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 be able to build your package. I've even based a "Generic Algorithm on Doing Packaging Using Existing Knowledge" on this fact.
The nixpkgs manual describes the standard workflow to adding packages to nixpkgs. Be sure to read this one first.
Detect package building category. It may be something simple, that requires
makeonly, 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.
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 your own.
Build it without changes, just to test if it builds
Modify source URL and sha256. Don't forget about that sha256 stuff! What I do, I change the last symbol of the sha256, let the package fail, and then paste the correct sha256 again into expression. There are also various prefetch techniques
nix-shellon 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 the build expression overrides that phase.
It most likely will fail.
- Try to find the 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:
- source requires patching
- you should enter a subdir first
- you should specify correct build parameters
patchShebangsshould be run first
Don't hesitate to learn from other package manager expressions, like AUR.
Apply a fix, exit nix-shell and enter it again. Do steps 6-7 while there are problems.
After you get the
buildPhaseto pass and produce correct binaries/libraries, it's time for the
installPhase. There are two ways: either you do package development under root and have write access to Nix store inside nix-shell, or you simply run
nix-buildon you expression, so Nix will perform it's
In the first case, you can run
directly and examine using
tree $outin your package files. If something is missing or too many, fix the
installPhasein your expression.
At this point you should have something that is both buildable and packageable. It still may not be runnable. Run the binaries to find any 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.
After all the modifications, package should be buildable, runnable and should be self-sufficient. You may add
metasection, but it isn't strictly required if you don't plan to publish your result.