drv

A Nix .drv file parser. Can produce either an AST or a descriptive object, depending on usage.

License

WTFPL or CC0, whichever you prefer. A donation and/or attribution are appreciated, but not required.

Donate

Maintaining open-source projects takes a lot of time, and the more donations I receive, the more time I can dedicate to open-source. If this module is useful to you, consider making a donation!

You can donate using Bitcoin, PayPal, Flattr, cash-in-mail, SEPA transfers, and pretty much anything else. Thank you!

Contributing

Pull requests welcome. Please make sure your modifications are in line with the overall code style, and ensure that you're editing the files in src/, not those in lib/.

Build tool of choice is gulp; simply run gulp while developing, and it will watch for changes.

Be aware that by making a pull request, you agree to release your modifications under the licenses stated above.

Usage

A basic example of parsing a derivation into a descriptive object:

'use strict';

const Promise = require("bluebird");
const fs = Promise.promisifyAll(require("fs"));
const util = require("util");

const drv = require("drv");

Promise.try(() => {
	return fs.readFileAsync("/nix/store/path/to/derivation.drv");
}).then((contents) => {
	let parsedContents = drv(contents.toString());

	console.log(util.inspect(parsedContents, {colors: true, depth: null}));
});

The default parsing method is to interpret the parsed data, in the same way that Nix would interpret it; each field in a derivation has a pre-defined meaning based on its position.

The above code will therefore produce output that looks something like this:

{ outputs:
   [ { name: 'dev',
       path: '/nix/store/lpwm4gcsda53g26jp6rxz4x13l8lywzg-libXdmcp-1.1.2-dev',
       hashAlgorithm: '',
       hash: '' },
     /* ... snipped ... */
     { name: 'out',
       path: '/nix/store/3iq0cd1ll0c7hss8xxgalxqn0jm0b2mi-libXdmcp-1.1.2',
       hashAlgorithm: '',
       hash: '' } ],
  inputDerivations:
   [ { path: '/nix/store/3l3gnqvlwrmiqdma5vg3zibkabv4d6wh-pkg-config-0.29.drv',
       inputDerivations: [ 'out' ] },
     /* ... snipped ... */
     { path: '/nix/store/w3qvvackybwaq6d2sw58yacsrbbrxa4b-xproto-7.0.29.drv',
       inputDerivations: [ 'out' ] } ],
  inputSources: [ '/nix/store/zsi9kk33hj7kvjfw0zahpdsiggg58nn4-builder.sh' ],
  platform: 'x86_64-linux',
  builder: '/nix/store/gabjbkwga2dhhp2wzyaxl83r8hjjfc37-bash-4.3-p48/bin/bash',
  builderArguments:
   [ '-e',
     '/nix/store/zsi9kk33hj7kvjfw0zahpdsiggg58nn4-builder.sh' ],
  environmentVariables:
   [ { name: 'buildInputs', value: '' },
     { name: 'builder',
       value: '/nix/store/gabjbkwga2dhhp2wzyaxl83r8hjjfc37-bash-4.3-p48/bin/bash' },
     /* ... snipped ... */
     { name: 'src',
       value: '/nix/store/djf171kmvws6891q2nzd2icdjd5bgj4r-libXdmcp-1.1.2.tar.bz2' },
     { name: 'stdenv',
       value: '/nix/store/985d95clq0216a6pcp3qzw4igp84ajvr-stdenv' },
     { name: 'system', value: 'x86_64-linux' } ] }

Sometimes, you'll only be interested in the AST, eg. because you're writing a pretty-printer. In that case, you'll want to use the drv.ast method instead.

For example:

'use strict';

const Promise = require("bluebird");
const fs = Promise.promisifyAll(require("fs"));
const util = require("util");

const drv = require("drv");

Promise.try(() => {
	return fs.readFileAsync("/nix/store/path/to/derivation.drv");
}).then((contents) => {
	let parsedContents = drv.ast(contents.toString()); // Note that we're using `drv.ast` now, instead of just `drv`!

	console.log(util.inspect(parsedContents, {colors: true, depth: null}));
});

That will produce output like this:

{ type: 'deriveTag',
  items:
   [ { type: 'array',
       items:
        [ { type: 'tuple',
            items:
             [ 'dev',
               '/nix/store/lpwm4gcsda53g26jp6rxz4x13l8lywzg-libXdmcp-1.1.2-dev',
               '',
               '' ] },
          /* ... snipped ... */
          { type: 'tuple',
            items:
             [ 'out',
               '/nix/store/3iq0cd1ll0c7hss8xxgalxqn0jm0b2mi-libXdmcp-1.1.2',
               '',
               '' ] } ] },
     { type: 'array',
       items:
        [ { type: 'tuple',
            items:
             [ '/nix/store/3l3gnqvlwrmiqdma5vg3zibkabv4d6wh-pkg-config-0.29.drv',
               { type: 'array', items: [ 'out' ] } ] },
          /* ... snipped ... */
          { type: 'tuple',
            items:
             [ '/nix/store/w3qvvackybwaq6d2sw58yacsrbbrxa4b-xproto-7.0.29.drv',
               { type: 'array', items: [ 'out' ] } ] } ] },
     { type: 'array',
       items: [ '/nix/store/zsi9kk33hj7kvjfw0zahpdsiggg58nn4-builder.sh' ] },
     'x86_64-linux',
     '/nix/store/gabjbkwga2dhhp2wzyaxl83r8hjjfc37-bash-4.3-p48/bin/bash',
     { type: 'array',
       items:
        [ '-e',
          '/nix/store/zsi9kk33hj7kvjfw0zahpdsiggg58nn4-builder.sh' ] },
     { type: 'array',
       items:
        [ { type: 'tuple', items: [ 'buildInputs', '' ] },
          /* ... snipped ... */
          { type: 'tuple',
            items:
             [ 'stdenv',
               '/nix/store/985d95clq0216a6pcp3qzw4igp84ajvr-stdenv' ] },
          { type: 'tuple', items: [ 'system', 'x86_64-linux' ] } ] } ] }

API

drv(contents)

Parses the specified contents and produces a descriptive object.

• contents: The derivation contents to parse. This must be a string; if you're reading from a file in Node.js, you'll want to .toString() it first.

The descriptive object that's returned is structured as follows:

• outputs: Array of objects. An array of derivation outputs; these are the store objects that are built from the derivation. Each item in the array contains the following properties:
  • name: String. The name of the derivation output.
  • path: String. The store path of the derivation output.
  • expectedHashAlgorithm: String, may be empty. The hashing algorithm used for the expected hash.
  • expectedHash: String, may be empty. The hash that the output is expected to have; if not, it will be considered a build failure. The hash is stored as a hexadecimal string.
• inputDerivations: Array of objects. An array of input derivations; these are the derivations that are a dependency of this derivation. They must have completed building before this derivation can be built. Each item in the array contains the following properties:
  • path: The path of the input derivation, as a string. Note that this is a path to the derivation, and not to the derivation output!
  • wantedOutputs: Array of strings. The names of the outputs of the input derivation that are required as a dependency of this derivation. These refer to the items in the outputs section of the input derivation.
• inputSources: Array of strings. An array of input sources; these are objects in the store that are copied from elsewhere, and that do not have their own derivation. Typical examples of this include builder scripts and source tarballs. Each item is a string containing the store path.
• platform: String. Describes the platform this derivation is meant to be built against. The platform strings used here are the same as those used throughout Nix and nixpkgs.
• builder: String. The builder to use for building ("realizing") this derivation.
• builderArguments: Array of strings. The arguments to pass to the builder.
• environmentVariables Array of objects. An array of environment variables in key/value format. These are the environment variables that are set when the builder is executed. Each item in the array contains the following properties:
  • name: String. The name of the environment variable.
  • value: String, may be empty. The value of the environment variable. It may contain variable interpolations.

drv.ast(contents)

Parses the specified contents and produces an AST (Abstract Syntax Tree).

• contents: The derivation contents to parse. This must be a string; if you're reading from a file in Node.js, you'll want to .toString() it first.

Each AST node has the following properties:

• type: String. The type of node. Possible options are:
  • "deriveTag": The root Derive tag (eg. Derive(contents)).
  • "array": An array (eg. [contents]).
  • "tuple": A tuple (eg. (contents)).
• items: Array. An array of items contained within this node. Each item is either an AST node or a string literal.

The root of the AST is always a deriveTag. String literals in the derivation are represented as string literals in the AST as well; all other syntactic constructs are represented as AST nodes.