List Of Common Folders In Output Derivation
Goal of this page
IMPORTANT: this page is under development, and was created to support this thread.
When creating a package, one need to copy stuff in various subfolders in the $out
directory. The most useful subfolder is certainly $out/bin
in which all executable must stay. However, there is many more such folders: $out/share
, $out/lib
... and some folders are also quite specific to some programs (python, emacs, ...).
This page is an attempt to give a (a non-exhaustive) list of these "special" folders: they could be here either because they receive a special treatment by nix or by any famous program, or because the name is a well used convention.
How to add a new entry
To add a new entry, you can start by copy pasting an existing entry. Ideally, each folder in this page would come with
- a very short description that says who consider this folder as special (nix, python, or just a convention), what kind of people can be interested by that folder (everybody, kernel developpers, python developpers...), how popular this folder is among these users (let's say 3 is "much nix packager will need to write into that folder at some point", 2 is "quite useful, but only if you create special derivations, like graphical programs, python...", 1 is "used in very specialized application", 0 is "very rare and specialized") and if we usually expect the user to directly write manually into that folder or if it will be done automatically by some helpers.
- a description of why it is useful
- an example of a file that could be put here (for instance, one can put a library in
$out/lib/mylib.so
) - a description of the special treatment they receive by nix or by the software, and if possible a link to the code that is doing this treatment. The treatment could be to be linked in some
/run/
folders, if the files are read recursively or not (for example can I put an executable in$out/bin/myprogram/myexec
), and if the files are expected to live in$out/subfolder
directly or in some sub-subfolders like$out/subfolder/myprogram
(or if it does not matter)... - typical way to populate that folder (copy or helpers LIKE
makeWrapper
,makeDesktopItem
... Put most common first.) - a simple example or a link to a (if possible simple) derivation in nixpkgs that uses this folder.
In order to keep the list ordered, we try to put the group these folder in different sections. If you add a folder, try to put it in a meaningful section, and put the most important ones first. If you describe a folder and its children, like $out/share
and $out/share/applications
, put the two next to each other.
Folder $out/bin
- Name of the folder:
$out/bin
- Handled by: nix, Concerning: everybody, Popularity: 3, How to populate: manually (often) or via helpers (often)
- Description: It contains all the executables of a given software that will be included in the
PATH
. Executables are put directly at the root of the$out/bin
folder. - Example of a filename:
$out/bin/mysoftware
wheremysoftware
is usually a script (bash...) or a binary. - Treatment: Nix will add the
$out/bin
folder of the installed packaged in thePATH
variable environment. TODO: check Nix is not doing anything else, and link to code. - How to populate:
- Manually: after a build succeed, you can usually just copy the executables via
cp yourbinary $out/yourbinary
(or using theinstall -Dm755 -t $out/bin yourbinary
program; if you use thecp
version, just ensure the program is executable. Nix should automatically setup the permission propertly for read and write part.). Note that if you choose to follow the more standardconfigure
/make install
scheme, then theconfigure
file will be run with--prefix=$out
by default. You can read how to change the default flags in configure and Makefile here. -
writeShellScriptBin "my-file" echo 'my bash code';
to create quickly a whole derivation with a simple bash script. See more in the manual, and see variants/source/examples here (you have for examplewriteCBin
if you want to compile a C code). -
wrapProgram $out/bin/MYPROGRAM --set FOOBAR baz
ormakeWrapper
to wrap a given binary in order to add some environment variables. See more here and in the source code. symlinkJoin { name = "myexample"; paths = [ pkgs.hello pkgs.stack ];}
will merge both derivationspkgs.hello
andpkgs.stack
into a single derivation using symlinks (practical to combine it withwriteShellScriptBin
in order to quickly add a script to an existing derivation). See more in the manual or longer description and examples in the source.- Usual bash commands, like
can be useful to add a script to an existing derivation.
cat > $out/yourcode <<EOF your code EOF
- Manually: after a build succeed, you can usually just copy the executables via
- Example of use:
To create a simple derivation with a bash script in
$out/myprogram
:{ pkgs ? import <nixpkgs> {} }: pkgs.writeShellScriptBin "myprogram" '' echo "Hello world" ''
To see example of use with
install
, see for instance the qcad derivation.