Packaging/Binaries
Downloading and attempting to run a binary on NixOS will almost never work. This is due to hard-coded paths in the executable. Unfortunately, almost all unfree and proprietary software comes in binary form - the main reason to include binaries is because no source code is available. This tutorial will guide you through packaging a binary executable.
If a downloaded binary is not packaged for NixOS then running the binary may fail like the following:
$ ~/.local/share/nvim/mason/packages/rust-analyzer/rust-analyzer-x86_64-unknown-linux-gnu --help
bash: /home/gdforj/.local/share/nvim/mason/packages/rust-analyzer/rust-analyzer-x86_64-unknown-linux-gnu: cannot execute: required file not found
Which indicates the interpreter, the dynamic loader in this case, could not be located.
Using AutoPatchelfHook
autoPatchelfHook is the current (as of 19.09) preferred way to package binaries.
{ stdenv, lib
, fetchurl
, alsaLib
, openssl
, zlib
, pulseaudio
, autoPatchelfHook
}:
stdenv.mkDerivation rec {
pname = "studio-link";
version = "21.07.0";
src = fetchurl {
url = "https://download.studio.link/releases/v${version}-stable/linux/studio-link-standalone-v${version}.tar.gz";
hash = "sha256-4CkijAlenhht8tyk3nBULaBPE0GBf6DVII699/RmmWI=";
};
nativeBuildInputs = [
autoPatchelfHook
];
buildInputs = [
alsaLib
openssl
zlib
pulseaudio
];
sourceRoot = ".";
installPhase = ''
runHook preInstall
install -m755 -D studio-link-standalone-v${version} $out/bin/studio-link
runHook postInstall
'';
meta = with lib; {
homepage = "https://studio-link.com";
description = "Voip transfer";
platforms = platforms.linux;
};
}
See this commit, or the example in method 5 of this answer, for more details.
Additional Library Paths
Some packages may put their library files somewhere other than $out/lib/ in the install phase, while autoPatchelfHook by default only looks in that one directory for every package in buildInputs. You can tell autoPatchelfHook to look in additional directories by passing it to the command addAutoPatchelfSearchPath in any phase before autoPatchelfHook is run.
For example,
preBuild = ''
addAutoPatchelfSearchPath ${jre8}/lib/openjdk/jre/lib/
'';
Manual Method
This sections describes the manual method of packaging a binary. It serves as a reference on the packaging issue with binaries and how these issues can be solved in nix derivations.
This tutorial is about how to patch the executable with patchelf which is sufficient for most cases. If no source is available for a program patchelf is the preferred way in nixpkgs to add support for the package.
However sometimes this is not enough, more hardcoded paths may be scattered all over the place. For this you may need to set up an FHSUserEnv, a Linux Standard Base style directory structure with a final chroot call to fixate all paths. For a tutorial on how to use this technique, check out Anders Papittos blog post on installing debian packages in nixos.
Starting Point
We want to package a tool called "MasterPDFEditor", the package for debian can be found at [1] (archive.org mirror).
This tutorial assumes you run nixos-17.09 or later (for nix-index to work).
Let's download the archive and unpack the archive in a nix shell for testing:
$ nix-shell -p binutils stdenv wget dpkg nix-index \
stdenv.cc # stdenv.cc is required for setting $NIX_CC env
$ wget https://web.archive.org/web/20170914112947/http://get.code-industry.net/public/master-pdf-editor-4.3.10_qt5.amd64.deb
$ # we extract data.tar.xz from the deb package and untar it
$ dpkg-deb -x master-pdf-editor-4.3.10_qt5.amd64.deb .
$ ls opt/master-pdf-editor-4/
fonts license.txt masterpdfeditor4.png templates
lang masterpdfeditor4 stamps
$ # running the executable does not `just work`
$ opt/master-pdf-editor-4/masterpdfeditor4
bash: opt/master-pdf-editor-4/masterpdfeditor4: No such file or directory
The Dynamic Loader
The binary has the dynamic loader ("ELF interpreter") set to a static path which is in general not available under NixOS: /lib64/ld-linux-x86-64.so.2
We can use patchelf to show and set the library path and dynamic linker appropriately:
$ cd opt/master-pdf-editor-4/
# the current interpreter
$ patchelf --print-interpreter masterpdfeditor4
# all the needed libraries
/lib64/ld-linux-x86-64.so.2
We start by patching the interpreter and see if the executable already starts:
$ patchelf \
--set-interpreter "$(cat $NIX_CC/nix-support/dynamic-linker)" \
masterpdfeditor4
$ ./masterpdfeditor4
./masterpdfeditor4: error while loading shared libraries: libsane.so.1: cannot open shared object file: No such file or directory
We went beyond the No such file or directory error, means that setting the interpreter worked! Unfortunately we have new errors which show that some shared objects cannot be found.
Extra Dynamic Libraries
Just like before, the executable simply expects libraries to be available in the Linux Standard Base(LSB) directories. Because Nix tries to avoid impurity and global directories we also have to explicitly set the libraries.
Patchelf can show the required libraries but we still have to set them manually.
$ patchelf --print-needed masterpdfeditor4
libdl.so.2
librt.so.1
libsane.so.1
libQt5Svg.so.5
libQt5PrintSupport.so.5
libQt5Widgets.so.5
libQt5Gui.so.5
libQt5Network.so.5
libQt5Core.so.5
libGL.so.1
libpthread.so.0
libstdc++.so.6
libm.so.6
libgcc_s.so.1
libc.so.6
$ # now that the interpreter path is patched we can use ldd to find the libraries which are currently not found (check '=> not found'):
$ ldd masterpdfeditor4 | grep 'not found'
libsane.so.1 => not found
libQt5Svg.so.5 => not found
libQt5PrintSupport.so.5 => not found
libQt5Widgets.so.5 => not found
libQt5Gui.so.5 => not found
libQt5Network.so.5 => not found
libQt5Core.so.5 => not found
libstdc++.so.6 => not found
All the libraries which are not yet found are the ones we need to add to the runtime search path of the executable (RPATH). Again we can use patchelf to do this. We will be using nix-index for finding the files we are looking for:
$ # we generate the database index of all files in our channel first
$ nix-index
+ querying available packages
+ generating index: 41977 paths found :: 15957 paths not in binary cache :: 00000 paths in queue
+ wrote index of 21,621,061 bytes
# we use the power of nix-locate to find the packages which contain the file:
$ nix-locate ---minimal --top-level -w lib/libsane.so.1
saneBackends.out
$ nix-locate --minimal --top-level -w lib/libQt5Svg.so.5
remarkable2-toolchain.out
remarkable-toolchain.out
libsForQt5.qt5.qtsvg.out
onlyoffice-bin.out
$ nix-locate --minimal --top-level -w lib/libQt5PrintSupport.so.5
robo3t.out
libsForQt5.qt5.qtbase.out
$ nix-locate --minimal --top-level -w lib/libstdc++.so.6
# ...
# libsdtc++.so.6 is `special`, it resides in stdenv.cc.cc.lib (see other packages)
The right package will usually have a name similar to the .so file you're missing, with some exceptions (e.g. libcrypto.so is provided by openssl).
 |
Tip
in case there are too many .so libraries, you may save time by automated approach, executing nix-de-generate for target application, which will produce list of nix packages (in nix expression) to satisfy dependencies of target application.
|
The next step is to create a library path for all these packages. We use nix-repl to resolve the paths:
$ nix repl '<nixpkgs>'
# .out can be omitted because this is the default output for all packages
# makeLibraryPath outputs the correct path for each package to use as rpath
nix-repl> with pkgs; lib.makeLibraryPath [ sane-backends libsForQt5.qt5.qtbase libsForQt5.qt5.qtsvg stdenv.cc.cc.lib ]
"/nix/store/7lbi3gn351j4hix3dqhis58adxbmvbxa-sane-backends-1.0.25/lib:/nix/store/0990ls1p2nnxq6605mr9lxpps8p7qvw7-qtbase-5.9.1/lib:/nix/store/qzhn2svk71886fz3a79vklps781ah0lb-qtsvg-5.9.1/lib:/nix/store/snc31f0alikhh3a835riyqhbsjm29vki-gcc-6.4.0-lib/lib"
Let's try out the path we generated:
$ patchelf --set-interpreter "$(cat $NIX_CC/nix-support/dynamic-linker)" --set-rpath /nix/store/7lbi3gn351j4hix3dqhis58adxbmvbxa-sane-backends-1.0.25/lib:/nix/store/0990ls1p2nnxq6605mr9lxpps8p7qvw7-qtbase-5.9.1/lib:/nix/store/qzhn2svk71886fz3a79vklps781ah0lb-qtsvg-5.9.1/lib:/nix/store/snc31f0alikhh3a835riyqhbsjm29vki-gcc-6.4.0-lib/lib masterpdfeditor4
$ ./masterpdfeditor4
# SUCCESS!!!
Creating the Derivation for upstream Packaging
Packaging is straight forward. We just have to add all the steps we did into a simple derivation file. We call it default.nix and store it in the checked out nixpkgs repository at pkgs/applications/office/master-pdf-editor
The content looks like this:
{ stdenv, lib, qt5, saneBackends, makeWrapper, fetchurl }:
stdenv.mkDerivation rec {
name = "master-pdf-editor-${version}";
version = "4.3.10";
src = fetchurl {
url = "http://get.code-industry.net/public/master-pdf-editor-${version}_qt5.amd64.deb";
hash = "sha256-1z26qjhbiyz33rm7mp8ycgl5ka0v3v5lv5i5v0b5mx35arvx2zzy";
};
sourceRoot = ".";
unpackCmd = "dpkg-deb -x master-pdf-editor-${version}_qt5.amd64.deb .";
dontConfigure = true;
dontBuild = true;
installPhase = ''
runHook preInstall
mkdir -p $out/bin
cp -R usr/share opt $out/
# fix the path in the desktop file
substituteInPlace \
$out/share/applications/masterpdfeditor4.desktop \
--replace /opt/ $out/opt/
# symlink the binary to bin/
ln -s $out/opt/master-pdf-editor-4/masterpdfeditor4 $out/bin/masterpdfeditor4
runHook postInstall
'';
preFixup = let
# we prepare our library path in the let clause to avoid it become part of the input of mkDerivation
libPath = lib.makeLibraryPath [
qt5.qtbase # libQt5PrintSupport.so.5
qt5.qtsvg # libQt5Svg.so.5
stdenv.cc.cc.lib # libstdc++.so.6
saneBackends # libsane.so.1
];
in ''
patchelf \
--set-interpreter "$(cat $NIX_CC/nix-support/dynamic-linker)" \
--set-rpath "${libPath}" \
$out/opt/master-pdf-editor-4/masterpdfeditor4
'';
meta = with lib; {
homepage = https://code-industry.net/masterpdfeditor/;
description = "a multifunctional PDF Editor";
license = licenses.unfree;
platforms = platforms.linux;
maintainers = [ your_name ];
};
}
Because we created a derivation which is meant to be called by callPackage we can build the package now only via:
nix-build -E '((import <nixpkgs> {}).callPackage (import ./default.nix) { })' --keep-failed --no-out-link
Add the package to nixpkgs
In order to add this new package to nixpkgs and be able to install it via nix-build -A pkgs.master-pdf-editor you need to add it to pkgs/top-level/all-packages.nix:
...
masscan = callPackage ../tools/security/masscan { };
master-pdf-editor = callPackage ../applications/office/master-pdf-editor {};
meson = ../development/tools/build-managers/meson { };
...
Creating a Pull Request
With this new package you can create a pull request for nixpkgs. Be aware that binary distributions are frowned upon if the source is available.
autoPatchelfHook
autoPatchelfHook can make the manual written patchelf invocations unnecessary.
Wrong file paths
Some programs will try to access hard-coded FHS file paths like /usr/lib or /opt. Mostly though, this will produce silent No such file errors, which can break the program.
To make these errors visible, we can use strace
strace --trace=file,process --follow-forks --string-limit=200 \
./result/bin/some-program 2>strace.log
cat strace.log | grep -e 'No such file' -e 'execve("' \
| grep -v -E -e '(open|stat|access)(at)?\(.*"/nix/store/' \
-e resumed -e '/etc/ld-nix.so.preload'
Example
[pid 357679] openat(AT_FDCWD, "/opt/brother/Printers/hll3210cw/inf/lut/0600-k_cache17.bin", O_RDONLY) = -1 ENOENT (No such file or directory) [pid 357679] openat(AT_FDCWD, "0600-k_cache17.bin", O_RDONLY) = -1 ENOENT (No such file or directory)
This means: process 357679 is trying to open file 0600-k_cache17.bin either from the hard-coded path in /opt/brother/Printers/hll3210cw/inf/lut or from the current workdir.
So, as a quick fix, we could change the working directory of the wrapped binary with makeWrapper:
makeWrapper <executable> <out_path> --run 'cd /nix/store/path/to/workdir'
Finding the failing process
How can we find which process is throwing the No such file error? Let's search for the process ID and the exec syscall:
cat strace.log | grep 357679 | grep exec
[pid 357679] execve("/nix/store/ybl1pacslmhci9zy5qv95hshdgz6ihjl-brother-hll3210cw-1.0.2-0/opt/brother/Printers/hll3210cw/lpd/brhll3210cwfilter", ["/nix/store/ybl1pacslmhci9zy5qv95"..., "-pi", "/nix/store/ybl1pacslmhci9zy5qv95"..., "-rc", "/nix/store/ybl1pacslmhci9zy5qv95"...], 0x8ba010 /* 132 vars */ <unfinished ...>
See also
- steam-run as a quick way to run binaries