List Of Common Folders In Output Derivation

Goal of this page

IMPORTANT: this page is under development.

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,.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.

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 TODO: explain what Nix is precisely doing and link to code.
• How to populate:
• Manually: you can usually just copy the executables via cp yourbinary $out/yourbinary (or using the install -D -t $out/bin yourbinary program
(juste ensure they are executable). Note that you can put that kind of code in a makefile if you use $PREFIX instead of $out since the default installPhase will call make install with the environment variable PREFIX=$(out).
• 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"
''