mirror of
https://github.com/NixOS/nix.git
synced 2025-11-14 22:42:41 +01:00
ddc3fba9fb
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`)
55 lines
2.3 KiB
Markdown
55 lines
2.3 KiB
Markdown
# 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.
|
||
|
||
[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive
|
||
[file system object]: @docroot@/store/file-system-object.md
|
||
|
||
The format of this specification is close to [Extended Backus–Naur form](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_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.
|
||
|
||
```ebnf
|
||
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](https://kaitai.io/), 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).
|
||
|
||
```yaml
|
||
{{#include nar.ksy}}
|
||
```
|
||
|
||
The source of the spec can be found [here](https://github.com/nixos/nix/blob/master/src/nix-manual/source/protocols/nix-archive/nar.ksy). Contributions and improvements to the spec are welcomed.
|