Skip to content

docs: clarify package and module option naming #31668

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lukateras merged 1 commit into from
Dec 23, 2017
Merged

docs: clarify package and module option naming #31668

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 13 additions & 12 deletions doc/coding-conventions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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
Expand Down
9 changes: 9 additions & 0 deletions nixos/doc/manual/development/option-declarations.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down