Packaging/Tutorial

If you are a new Nix adept and want to package some new software, you will benefit from reading existing Nix package descriptions. The more you read, the faster you'll do your package. I've even based a "Generic Algorithm on Doing Packaging Using Existing Knowledge" on this fact.

NOTE3: If you definitely have lots of time, then read Nixpkgs manual

1. Detect package building category. It may be something simple, that requires gcc and make only, or it may be a python library, or it may be a python application, or it may be any other LANGUAGE library/application, or it may be Qt applications, or it may be a Gnome application, or it does uses Mono/wine under a hood, or it vendors it's dependencies, or it is closed source/binary redistributable, or it uses CMake/any other alternative build tool, or it actually is a compiler, ... There are lots of such build categories, and it often isn't reflected at hierarchy level in Nixpkgs source tree.

2. Try grepping for building category keywords in Nixpkgs source. Find some example packages, review them and copy one of them as a new expression for your package. Too bad if you didn't find anything, then you should read Nix Pills first and skim through several package expressions in Nixpkgs source to be able to write own one.

3. Build it without changes, just to test it builds

4. Modify source URL and sha256. Don't forget about that sha256 stuff! What I do, I change last symbol of sha256, let the package fail, and then paste correct sha256 again into expression. There are also various prefetch techniques

5. Run nix-shell on this expression (for example: nix-shell '<nixpkgs>' -A hello). Then run in order:

   $ unpackPhase
   $ cd DIR_AFTER_UNPACK
   $ patchPhase
   $ configurePhase
   $ buildPhase
   

   (visit stdenv-phases chapter to learn more about phases)

You may need to run $ eval "$configurePhase" sometimes if build expression overrides that phase.

It most likely will fail.

6. Try to find failure category. It may be headers not found, library not found, executable not found, compiler not found, wrong build system, empty result, and many many more... But solutions to these problems are a bit more controllable:

• 1. buildInput dependency missing
• 2. source requires patching
• 3. you should enter a subdir first
• 4. you should specify correct build parameters
• 5. patchShebangs should be run first
• ....

Don't hesitate to learn from other package manager expressions, like AUR.

7. Apply a fix, exit nix-shell and enter it again. Do steps 6-7 while there are problems.

8. After you got buildPhase to pass and produce correct binaries/libraries, time to installPhase. There are two ways: either you do package developement under root and have write access to Nix store inside nix-shell, or you simply run nix-build on you expression, so Nix will perform it's installPhase.

In first case, you can run

$ installPhase

directly and examine using tree $out your package files. If something is missing or too many, fix the postInstallPhase or preInstallPhase or installPhase in your expression.

9. At this point you should have something that is both buildable and packageable. It still may not be runnable. Run the binaries to find out hidden dependencies, or patches required, or wrapper required, or patchelf required, or ... In general, I use Google and search in Nixpkgs issue tracker related problems.

10. After all the modifications, package should be buildable, runnable and should be self-sufficient. You may add meta section, but it isn't strictly required if you don't plan to publish your result.