git.iko.soy/nix-bundle
on master help sign in
nix-bundle/README.md
131 lines 4.2 kB history raw
1# nix-bundle
3nix-bundle is a way to package Nix attributes into single-file executables.
5## Benefits
7* Single-file output
8* Can be run by non-root users
9* No runtime
10* Distro agnostic
11* No installation
13## Getting started
15Make sure you have installed Nix already. See http://nixos.org/nix/ for more details.
17Once you have a working Nix install, you can run:
19```sh
20$ ./nix-bundle.sh hello /bin/hello
21```
23```hello``` indicates the Nix derivation from NixPkgs that you want to use, while ```/bin/hello``` indicates the path of the executable relative to ```hello``` that you want to run. This will create the file "hello". Running it:
25```sh
26$ ./hello
27Hello, world!
28```
30This is a standalone file that is completely portable! As long as you are running the same architecture Linux kernel and have a shell interpreter available it will run.
32Some others to try:
34```sh
35./nix-bundle.sh nano /bin/nano
36```
38```sh
39./nix-bundle.sh emacs /bin/emacs
40```
42Or if you want to try graphical applications:
44```sh
45# Simple X game. Very few dependencies. Quick to build and load. ~13MB
46./nix-bundle.sh xskat /bin/xskat
47```
49```sh
50./nix-bundle.sh firefox /bin/firefox
51```
53```sh
54# SDL-based game. ~228MB
55./nix-bundle.sh ivan /bin/ivan
56```
59## Self-bundling (meta)
61Starting with v0.1.3, you can bundle nix-bundle! To do this, just use nix-bundle normally:
63```sh
64NIX_PATH="nixpkgs=https://github.com/matthewbauer/nixpkgs/archive/nix-bundle.tar.gz" ./nix-bundle.sh nix-bundle /bin/nix-bundle
65```
67## [Experimental] Create AppImage executables from Nix expressions
69"nix-bundle.sh" tends to create fairly large outputs. This is largely because nix-bundle.sh "extracts" its payload up front. AppImage uses a different method where extraction only takes place when the file is accessed (through FUSE and SquashFS). You can now create a compliant "AppImage" using the "nix2appimage.sh" script:
71```sh
72./nix2appimage.sh emacs
73```
75This will create a file at Emacs-x86_64.AppImage which you can execute.
77Notice that there is only one argument for nix2appimage.sh. This is because the target executable will be detected from the .desktop file in ```/share/applications/*.desktop```. As a side-effect, AppImage requires your package to have a .desktop file, so packages like "hello", "coreutils", etc. will not work.
79Some other examples to try:
81```sh
82./nix2appimage.sh firefox
83```
85```sh
86./nix2appimage.sh vlc
87```
89```sh
90./nix2appimage.sh 0ad
91```
93```sh
94./nix2appimage.sh wireshark-gtk
95```
97These may take a while because of the large closure size.
99Note that these do not currently work out of the box with NixOS. Other Linux distros should work.
101## Comparison with AppImage, FlatPak, Snappy
103| Name | Distro-agnostic | Runtime required | Root required | Storage |
104| ---------- | --------------- | ---------------- | ------------- | ------- |
105| nix-bundle | yes | no | no | Arx tarball |
106| AppImage | yes | no | no | Squashfs w/ lzma compression |
107| FlatPak | yes | yes | no | ? |
108| Snappy | yes | yes | no | squashFS |
110## How it works
112Nix-bundle glues together four different projects to work correctly:
114* [Arx](https://github.com/solidsnack/arx) - an archive execution tool
115* Creates single-file archive executable that can unpack themselves and then run some command. nix-bundle calls nix-user-chroot to bootstrap the Nix environment. It outputs a "./nix" folder.
116* [nix-user-chroot](https://github.com/lethalman/nix-user-chroot) - a small bootstrap that uses Linux namespaces to call chroot
117 * This will create sub namespace and bind mount the "./nix" to "/nix" so that the Nix references function properly.
118* [Nix](https://nixos.org/nix/) - a functional package manager
119 * Used to build runtime closures that are self-contained.
120* [nixpkgs](https://nixos.org/nixpkgs/)
121 * Provides lots of different packages to choose from.
123## Drawbacks
125Nix-bundle has some drawbacks that need to be worked on:
127* Slow startup
128* Large files (Firefox 150MB)
129* Only compatible Linux
130* Outputs built on x86-64 will not run on i386
131* Requires Linux kernel with CAP_SYS_USER_NS on and permissions setup correctly