diff options
author | Robert Helgesson <robert@rycee.net> | 2017-11-14 18:59:27 +0100 |
---|---|---|
committer | Robert Helgesson <robert@rycee.net> | 2017-11-14 19:17:35 +0100 |
commit | 91154416b650e7a09c44b0c0d97399bc5c849117 (patch) | |
tree | 33ed1fe4d742e24fa6e77f142679d76c6add44ec | |
parent | ea1724ba371ad7921323c5f07021f6ef4748258a (diff) |
docs: clarify package and module option naming
This attempts to briefly clarify the current naming conventions of
attribute names in `all-packages.nix` and module option names.
-rw-r--r-- | doc/coding-conventions.xml | 25 | ||||
-rw-r--r-- | nixos/doc/manual/development/option-declarations.xml | 9 |
2 files changed, 22 insertions, 12 deletions
diff --git a/doc/coding-conventions.xml b/doc/coding-conventions.xml index 0776e70f14e1..ec81c968e4a4 100644 --- a/doc/coding-conventions.xml +++ b/doc/coding-conventions.xml @@ -18,9 +18,9 @@ tab settings so it’s asking for trouble.</para></listitem> <listitem><para>Use <literal>lowerCamelCase</literal> for variable - names, not <literal>UpperCamelCase</literal>. TODO: naming of - attributes in - <filename>all-packages.nix</filename>?</para></listitem> + names, not <literal>UpperCamelCase</literal>. Note, this rule does + not apply to package attribute names, which instead follow the rules + in <xref linkend="sec-package-naming"/>.</para></listitem> <listitem><para>Function calls with attribute set arguments are written as @@ -220,9 +220,10 @@ args.stdenv.mkDerivation (args // { <listitem><para>The variable name used for the instantiated package in <filename>all-packages.nix</filename>, 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 <command>nix-env - -iA</command>.</para></listitem> + dependency to other functions. Typically this is called the + <emphasis>package attribute name</emphasis>. This is what Nix + expression authors see. It can also be used when installing using + <command>nix-env -iA</command>.</para></listitem> <listitem><para>The filename for (the directory containing) the Nix expression.</para></listitem> @@ -259,12 +260,12 @@ bound to the variable name <varname>e2fsprogs</varname> in Also append <literal>"unstable"</literal> to the name - e.g., <literal>"pkgname-unstable-2014-09-23"</literal>.</para></listitem> - <listitem><para>Dashes in the package name should be preserved - in new variable names, rather than converted to underscores - (which was convention up to around 2013 and most names - still have underscores instead of dashes) — e.g., - <varname>http-parser</varname> instead of - <varname>http_parser</varname>.</para></listitem> + <listitem><para>Dashes in the package name should be preserved in + new variable names, rather than converted to underscores or camel + cased — e.g., <varname>http-parser</varname> instead of + <varname>http_parser</varname> or <varname>httpParser</varname>. The + hyphenated style is preferred in all three package + names.</para></listitem> <listitem><para>If there are multiple versions of a package, this should be reflected in the variable names in diff --git a/nixos/doc/manual/development/option-declarations.xml b/nixos/doc/manual/development/option-declarations.xml index be793152f9ef..ed718c89eb77 100644 --- a/nixos/doc/manual/development/option-declarations.xml +++ b/nixos/doc/manual/development/option-declarations.xml @@ -22,6 +22,15 @@ options = { }; </programlisting> +The attribute names within the <replaceable>name</replaceable> +attribute path must be camel cased in general but should, as an +exception, match the +<link +xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming"> +package attribute name</link> when referencing a Nixpkgs package. For +example, the option <varname>services.nix-serve.bindAddress</varname> +references the <varname>nix-serve</varname> Nixpkgs package. + </para> <para>The function <varname>mkOption</varname> accepts the following arguments. |