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.

Generic Nix-related folders

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 where mysoftware is usually a script (bash...) or a binary.
• Treatment: Nix will add the $out/bin folder of the installed packaged in the PATH 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 the install -D -t $out/bin yourbinary program); juste ensure the program is executable). Note that if you choose to follow the more standard configure/make install scheme, then the configure 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 example writeCBin if you want to compile a C code).
  • wrapProgram $out/bin/MYPROGRAM --set FOOBAR baz or makeWrapperto wrap a given binary in order to add some environment variables. See more here.
  • symlinkJoin { name = "myexample"; paths = [ pkgs.hello pkgs.stack ];} will merge both derivations pkgs.hello and pkgs.stack into a single derivation using symlinks (practical to combine it with writeShellScriptBin 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

    cat > $out/yourcode <<EOF
    your code
    EOF
    

    can be useful to add a script to an existing derivation.
• Example of use: To create a simple derivation with a bash script in $out/myprogram:

  { pkgs ? import <nixpkgs> {} }:
  pkgs.writeShellScriptBin "myprogram" ''
    echo "Hello world"
  ''