7. Coding conventions¶

7.1. Syntax¶

• Use 2 spaces of indentation per indentation level in Nix expressions, 4 spaces in shell scripts.

• Do not use tab characters, i.e. configure your editor to use soft tabs. For instance, use ``(setq-default

  indent-tabs-mode nil)`` in Emacs. Everybody has different tab

  settings so it’s asking for trouble.

• Use lowerCamelCase for variable names, not UpperCamelCase. TODO: naming of attributes in all-packages.nix?

• Function calls with attribute set arguments are written as

  foo {
    arg = ...;
  }
  

  not

  foo
  {
    arg = ...;
  }
  

  Also fine is

  foo { arg = ...; }
  

  if it’s a short call.

• In attribute sets or lists that span multiple lines, the attribute names or list elements should be aligned:

  # A long list.
  list =
    [ elem1
      elem2
      elem3
    ];
  
  # A long attribute set.
  attrs =
    { attr1 = short_expr;
      attr2 =
        if true then big_expr else big_expr;
    };
  
  # Alternatively:
  attrs = {
    attr1 = short_expr;
    attr2 =
      if true then big_expr else big_expr;
  };
  

• Short lists or attribute sets can be written on one line:

  # A short list.
  list = [ elem1 elem2 elem3 ];
  
  # A short set.
  attrs = { x = 1280; y = 1024; };
  

• Breaking in the middle of a function argument can give hard-to-read code, like

  someFunction { x = 1280;
    y = 1024; } otherArg
    yetAnotherArg
  

  (especially if the argument is very large, spanning multiple lines).

  Better:

  someFunction
    { x = 1280; y = 1024; }
    otherArg
    yetAnotherArg
  

  or

  let res = { x = 1280; y = 1024; };
  in someFunction res otherArg yetAnotherArg
  

• The bodies of functions, asserts, and withs are not indented to prevent a lot of superfluous indentation levels, i.e.

  { arg1, arg2 }:
  assert system == "i686-linux";
  stdenv.mkDerivation { ...
  

  not

  { arg1, arg2 }:
    assert system == "i686-linux";
      stdenv.mkDerivation { ...
  

• Function formal arguments are written as:

  { arg1, arg2, arg3 }:
  

  but if they don’t fit on one line they’re written as:

  { arg1, arg2, arg3
  , arg4, ...
  , # Some comment...
    argN
  }:
  

• Functions should list their expected arguments as precisely as possible. That is, write

  { stdenv, fetchurl, perl }:
  

  instead of

  args: with args;
  

  or

  { stdenv, fetchurl, perl, ... }:
  

  For functions that are truly generic in the number of arguments (such as wrappers around mkDerivation) that have some required arguments, you should write them using an @-pattern:

  { stdenv, doCoverageAnalysis ? false, ... } @ args:
  
  stdenv.mkDerivation (args // {
     if doCoverageAnalysis then "bla" else ""
  })
  

  instead of

  args:
  
  args.stdenv.mkDerivation (args // {
     if args ? doCoverageAnalysis && args.doCoverageAnalysis then "bla" else ""
  })
  

7.2. Package naming¶

In Nixpkgs, there are generally three different names associated with a package:

• The name attribute of the derivation (excluding the version part). This is what most users see, in particular when using nix-env.

• The variable name used for the instantiated package in all-packages.nix, and when passing it as a dependency to other functions. This is what Nix expression authors see. It can also be used when installing using ``nix-env

  -iA``.

• The filename for (the directory containing) the Nix expression.

Most of the time, these are the same. For instance, the package e2fsprogs has a name attribute "e2fsprogs-", is bound to the variable name e2fsprogs in all-packages.nix, and the Nix expression is in pkgs/os-specific/linux/e2fsprogs/default.nix. However, identifiers in the Nix language don’t allow certain characters (e.g. dashes), so sometimes a different variable name should be used. For instance, the module-init-tools package is bound to the module_init_tools variable in all-packages.nix.

There are a few naming guidelines:

• Generally, try to stick to the upstream package name.
• Don’t use uppercase letters in the name attribute — e.g., "mplayer-1.0rc2" instead of "MPlayer-1.0rc2".
• The version part of the name attribute must start with a digit (following a dash) — e.g., "hello-0.3-pre-r3910" instead of "hello-svn-r3910", as the latter would be seen as a package named hello-svn by nix-env.
• Dashes in the package name should be changed to underscores in variable names, rather than to camel case — e.g., module_init_tools instead of moduleInitTools.
• If there are multiple versions of a package, this should be reflected in the variable names in all-packages.nix, e.g. hello_0_3 and hello_0_4. If there is an obvious “default” version, make an attribute like hello = hello_0_4;.

7.3. File naming and organisation¶

Names of files and directories should be in lowercase, with dashes between words — not in camel case. For instance, it should be all-packages.nix, not allPackages.nix or AllPackages.nix.