nixos/nix
1
1
Fork 0
mirror of https://github.com/NixOS/nix.git synced 2025-11-14 14:32:42 +01:00
Code Activity
nix/doc/manual/source/protocols/nix-archive/index.md
Alex Auvolat ddc3fba9fb doc: fix "Nix Archive (NAR) format" specification 
For executable files in NAR archives, the `executable` tag is followed
by an empty string, which was not indicated correctly in the
specification.

Adding the empty string can be seen in `src/libutil/archive.cc:62`.

Here is an example of a hexdump of a NAR archives where this empty
string can be seen:

```
00000730  65 6e 74 72 79 00 00 00  01 00 00 00 00 00 00 00  |entry...........|
00000740  28 00 00 00 00 00 00 00  04 00 00 00 00 00 00 00  |(...............|
00000750  6e 61 6d 65 00 00 00 00  10 00 00 00 00 00 00 00  |name............|
00000760  6c 69 62 6d 70 66 72 2e  73 6f 2e 36 2e 32 2e 31  |libmpfr.so.6.2.1|
00000770  04 00 00 00 00 00 00 00  6e 6f 64 65 00 00 00 00  |........node....|
00000780  01 00 00 00 00 00 00 00  28 00 00 00 00 00 00 00  |........(.......|
00000790  04 00 00 00 00 00 00 00  74 79 70 65 00 00 00 00  |........type....|
000007a0  07 00 00 00 00 00 00 00  72 65 67 75 6c 61 72 00  |........regular.|
000007b0  0a 00 00 00 00 00 00 00  65 78 65 63 75 74 61 62  |........executab|
000007c0  6c 65 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |le..............|
000007d0  08 00 00 00 00 00 00 00  63 6f 6e 74 65 6e 74 73  |........contents|
000007e0  a0 16 0c 00 00 00 00 00  7f 45 4c 46 02 01 01 00  |.........ELF....|
000007f0  00 00 00 00 00 00 00 00  03 00 3e 00 01 00 00 00  |..........>.....|
00000800  00 00 00 00 00 00 00 00  40 00 00 00 00 00 00 00  |........@.......|
00000810  e0 0e 0c 00 00 00 00 00  00 00 00 00 40 00 38 00  |............@.8.|
00000820  0b 00 40 00 1f 00 1e 00  01 00 00 00 04 00 00 00  |..@.............|
00000830  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
```

(taken from `09zrxnn4j5hjxqj93xvxrl1dpmq4cyajas3yf7a7y0i7h81m6bd4.nar`,
available on `cache.nixos.org`)
2025-11-12 20:16:00 +01:00

2.3 KiB
Raw Blame History

Nix Archive (NAR) format

This is the complete specification of the Nix Archive format. The Nix Archive format closely follows the abstract specification of a file system object tree, because it is designed to serialize exactly that data structure.

The format of this specification is close to Extended Backus–Naur form, with the exception of the str(..) function / parameterized rule, which length-prefixes and pads strings. This makes the resulting binary format easier to parse.

Regular users do not need to know this information. But for those interested in exactly how Nix works, e.g. if they are reimplementing it, this information can be useful.

nar = str("nix-archive-1"), nar-obj;

nar-obj = str("("), nar-obj-inner, str(")");

nar-obj-inner
  = str("type"), str("regular") regular
  | str("type"), str("symlink") symlink
  | str("type"), str("directory") directory
  ;

regular = [ str("executable"), str("") ], str("contents"), str(contents);

symlink = str("target"), str(target);

(* side condition: directory entries must be ordered by their names *)
directory = { directory-entry };

directory-entry = str("entry"), str("("), str("name"), str(name), str("node"), nar-obj, str(")");

The str function / parameterized rule is defined as follows:

  • str(s) = int(|s|), pad(s);

  • int(n) = the 64-bit little endian representation of the number n

  • pad(s) = the byte sequence s, padded with 0s to a multiple of 8 byte

Kaitai Struct Specification

The Nix Archive (NAR) format is also formally described using Kaitai Struct, an Interface Description Language (IDL) for defining binary data structures.

Kaitai Struct provides a language-agnostic, machine-readable specification that can be compiled into parsers for various programming languages (e.g., C++, Python, Java, Rust).

{{#include nar.ksy}}

The source of the spec can be found here. Contributions and improvements to the spec are welcomed.