From 77161de4546697f9bf2da6d081eeba4c399b3313 Mon Sep 17 00:00:00 2001 From: Graham Christensen Date: Tue, 1 May 2018 19:54:21 -0400 Subject: nixpkgs docs: format =) --- doc/coding-conventions.xml | 1214 ++++++++++++++++++++++++-------------------- 1 file changed, 677 insertions(+), 537 deletions(-) (limited to 'doc/coding-conventions.xml') diff --git a/doc/coding-conventions.xml b/doc/coding-conventions.xml index d556c7ebe1ed..f244c11d4f20 100644 --- a/doc/coding-conventions.xml +++ b/doc/coding-conventions.xml @@ -1,56 +1,59 @@ - -Coding conventions - - -
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. Note, this rule does - not apply to package attribute names, which instead follow the rules - in . - - Function calls with attribute set arguments are - written as - + Coding conventions +
+ 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. Note, this rule does not apply to + package attribute names, which instead follow the rules in + . + + + + + Function calls with attribute set arguments are written as foo { arg = ...; } - - not - + not foo { arg = ...; } - - Also fine is - + 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: - + 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 = @@ -73,12 +76,11 @@ attrs = { if true then big_expr else big_expr; }; - - - - Short lists or attribute sets can be written on one - line: - + + + + + Short lists or attribute sets can be written on one line: # A short list. list = [ elem1 elem2 elem3 ]; @@ -86,66 +88,58 @@ 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 - + + + + + 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: - + (especially if the argument is very large, spanning multiple lines). + + + Better: someFunction { x = 1280; y = 1024; } otherArg yetAnotherArg - - or - + 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. - + + + + + 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 - + not { arg1, arg2 }: assert system == "i686-linux"; stdenv.mkDerivation { ... - - - - Function formal arguments are written as: - + + + + + Function formal arguments are written as: { arg1, arg2, arg3 }: - - but if they don't fit on one line they're written as: - + but if they don't fit on one line they're written as: { arg1, arg2, arg3 , arg4, ... @@ -153,35 +147,28 @@ stdenv.mkDerivation { ... argN }: - - - - Functions should list their expected arguments as - precisely as possible. That is, write - + + + + + Functions should list their expected arguments as precisely as possible. + That is, write { stdenv, fetchurl, perl }: ... - - instead of - + instead of args: with args; ... - - or - + 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: - + + + 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: @@ -189,9 +176,7 @@ stdenv.mkDerivation (args // { ... if doCoverageAnalysis then "bla" else "" ... }) - - instead of - + instead of args: @@ -199,432 +184,557 @@ args.stdenv.mkDerivation (args // { ... if args ? doCoverageAnalysis && args.doCoverageAnalysis then "bla" else "" ... }) + + + +
+
+ Package naming - - - - -
- - -
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. Typically this is called the - package attribute name. 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-version", is -bound to the variable name e2fsprogs in -all-packages.nix, and the Nix expression is in -pkgs/os-specific/linux/e2fsprogs/default.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.1rc2". - - If a package is not a release but a commit from a repository, then - the version part of the name must be the date of that - (fetched) commit. The date must be in "YYYY-MM-DD" format. - Also append "unstable" to the name - e.g., - "pkgname-unstable-2014-09-23". - - Dashes in the package name should be preserved in - new variable names, rather than converted to underscores or camel - cased — e.g., http-parser instead of - http_parser or httpParser. The - hyphenated style is preferred in all three package - names. - - If there are multiple versions of a package, this - should be reflected in the variable names in - all-packages.nix, - e.g. json-c-0-9 and json-c-0-11. - If there is an obvious “default” version, make an attribute like - json-c = json-c-0-9;. - See also - - - - - -
- - -
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. - -
Hierarchy - -Each package should be stored in its own directory somewhere in -the pkgs/ tree, i.e. in -pkgs/category/subcategory/.../pkgname. -Below are some rules for picking the right category for a package. -Many packages fall under several categories; what matters is the -primary purpose of a package. For example, the -libxml2 package builds both a library and some -tools; but it’s a library foremost, so it goes under -pkgs/development/libraries. - -When in doubt, consider refactoring the -pkgs/ tree, e.g. creating new categories or -splitting up an existing category. - - - - If it’s used to support software development: + + In Nixpkgs, there are generally three different names associated with a + package: + - - - If it’s a library used by other packages: - - development/libraries (e.g. libxml2) - - - - If it’s a compiler: - - development/compilers (e.g. gcc) - - - - If it’s an interpreter: - - development/interpreters (e.g. guile) - - - - If it’s a (set of) development tool(s): - - - - If it’s a parser generator (including lexers): - - development/tools/parsing (e.g. bison, flex) - - - - If it’s a build manager: - - development/tools/build-managers (e.g. gnumake) - - - - Else: - - development/tools/misc (e.g. binutils) - - - - - - - Else: - - development/misc - - - + + The name attribute of the derivation (excluding the + version part). This is what most users see, in particular when using + nix-env. + - - - If it’s a (set of) tool(s): - (A tool is a relatively small program, especially one intended - to be used non-interactively.) - - - If it’s for networking: - - tools/networking (e.g. wget) - - - - If it’s for text processing: - - tools/text (e.g. diffutils) - - - - If it’s a system utility, i.e., - something related or essential to the operation of a - system: - - tools/system (e.g. cron) - - - - If it’s an archiver (which may - include a compression function): - - tools/archivers (e.g. zip, tar) - - - - If it’s a compression program: - - tools/compression (e.g. gzip, bzip2) - - - - If it’s a security-related program: - - tools/security (e.g. nmap, gnupg) - - - - Else: - - tools/misc - - - + + The variable name used for the instantiated package in + all-packages.nix, and when passing it as a + dependency to other functions. Typically this is called the + package attribute name. This is what Nix expression + authors see. It can also be used when installing using nix-env + -iA. + - - - If it’s a shell: - shells (e.g. bash) + + The filename for (the directory containing) the Nix expression. + - - - If it’s a server: + + Most of the time, these are the same. For instance, the package + e2fsprogs has a name attribute + "e2fsprogs-version", is bound + to the variable name e2fsprogs in + all-packages.nix, and the Nix expression is in + pkgs/os-specific/linux/e2fsprogs/default.nix. + + + + There are a few naming guidelines: + - - - If it’s a web server: - - servers/http (e.g. apache-httpd) - - - - If it’s an implementation of the X Windowing System: - - servers/x11 (e.g. xorg — this includes the client libraries and programs) - - - - Else: - - servers/misc - - - + + Generally, try to stick to the upstream package name. + - - - If it’s a desktop environment: - desktops (e.g. kde, gnome, enlightenment) + + Don’t use uppercase letters in the name attribute + — e.g., "mplayer-1.0rc2" instead of + "MPlayer-1.0rc2". + - - - If it’s a window manager: - applications/window-managers (e.g. awesome, stumpwm) + + The version part of the name attribute + must start with a digit (following a dash) — e.g., + "hello-0.3.1rc2". + - - - If it’s an application: - A (typically large) program with a distinct user - interface, primarily used interactively. - - - If it’s a version management system: - - applications/version-management (e.g. subversion) - - - - If it’s for video playback / editing: - - applications/video (e.g. vlc) - - - - If it’s for graphics viewing / editing: - - applications/graphics (e.g. gimp) - - - - If it’s for networking: - - - - If it’s a mailreader: - - applications/networking/mailreaders (e.g. thunderbird) - - - - If it’s a newsreader: - - applications/networking/newsreaders (e.g. pan) - - - - If it’s a web browser: - - applications/networking/browsers (e.g. firefox) - - - - Else: - - applications/networking/misc - - - - - - - Else: - - applications/misc - - - + + If a package is not a release but a commit from a repository, then the + version part of the name must be the date of that + (fetched) commit. The date must be in "YYYY-MM-DD" + format. Also append "unstable" to the name - e.g., + "pkgname-unstable-2014-09-23". + - - - If it’s data (i.e., does not have a - straight-forward executable semantics): - - - If it’s a font: - - data/fonts - - - - If it’s related to SGML/XML processing: - - - - If it’s an XML DTD: - - data/sgml+xml/schemas/xml-dtd (e.g. docbook) - - - - If it’s an XSLT stylesheet: - - (Okay, these are executable...) - data/sgml+xml/stylesheets/xslt (e.g. docbook-xsl) - - - - - - + + Dashes in the package name should be preserved in new variable names, + rather than converted to underscores or camel cased — e.g., + http-parser instead of http_parser + or httpParser. The hyphenated style is preferred in + all three package names. + - - - If it’s a game: - games + + If there are multiple versions of a package, this should be reflected in + the variable names in all-packages.nix, e.g. + json-c-0-9 and json-c-0-11. If + there is an obvious “default” version, make an attribute like + json-c = json-c-0-9;. See also + + - - - Else: - - misc - - - - -
- -
Versioning - -Because every version of a package in Nixpkgs creates a -potential maintenance burden, old versions of a package should not be -kept unless there is a good reason to do so. For instance, Nixpkgs -contains several versions of GCC because other packages don’t build -with the latest version of GCC. Other examples are having both the -latest stable and latest pre-release version of a package, or to keep -several major releases of an application that differ significantly in -functionality. - -If there is only one version of a package, its Nix expression -should be named e2fsprogs/default.nix. If there -are multiple versions, this should be reflected in the filename, -e.g. e2fsprogs/1.41.8.nix and -e2fsprogs/1.41.9.nix. The version in the -filename should leave out unnecessary detail. For instance, if we -keep the latest Firefox 2.0.x and 3.5.x versions in Nixpkgs, they -should be named firefox/2.0.nix and -firefox/3.5.nix, respectively (which, at a given -point, might contain versions 2.0.0.20 and -3.5.4). If a version requires many auxiliary -files, you can use a subdirectory for each version, -e.g. firefox/2.0/default.nix and -firefox/3.5/default.nix. + + +
+
+ File naming and organisation -All versions of a package must be included -in all-packages.nix to make sure that they -evaluate correctly. + + 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. + -
+
+ Hierarchy + + + Each package should be stored in its own directory somewhere in the + pkgs/ tree, i.e. in + pkgs/category/subcategory/.../pkgname. + Below are some rules for picking the right category for a package. Many + packages fall under several categories; what matters is the + primary purpose of a package. For example, the + libxml2 package builds both a library and some tools; + but it’s a library foremost, so it goes under + pkgs/development/libraries. + + + + When in doubt, consider refactoring the pkgs/ tree, + e.g. creating new categories or splitting up an existing category. + + + + + If it’s used to support software development: + + + + If it’s a library used by other packages: + + + development/libraries (e.g. + libxml2) + + + + + If it’s a compiler: + + + development/compilers (e.g. + gcc) + + + + + If it’s an interpreter: + + + development/interpreters (e.g. + guile) + + + + + If it’s a (set of) development tool(s): + + + + If it’s a parser generator (including lexers): + + + development/tools/parsing (e.g. + bison, flex) + + + + + If it’s a build manager: + + + development/tools/build-managers (e.g. + gnumake) + + + + + Else: + + + development/tools/misc (e.g. + binutils) + + + + + + + + Else: + + + development/misc + + + + + + + + If it’s a (set of) tool(s): + + + (A tool is a relatively small program, especially one intended to be + used non-interactively.) + + + + If it’s for networking: + + + tools/networking (e.g. + wget) + + + + + If it’s for text processing: + + + tools/text (e.g. diffutils) + + + + + If it’s a system utility, i.e., + something related or essential to the operation of a + system: + + + tools/system (e.g. cron) + + + + + If it’s an archiver (which may + include a compression function): + + + tools/archivers (e.g. zip, + tar) + + + + + If it’s a compression program: + + + tools/compression (e.g. + gzip, bzip2) + + + + + If it’s a security-related program: + + + tools/security (e.g. nmap, + gnupg) + + + + + Else: + + + tools/misc + + + + + + + + If it’s a shell: + + + shells (e.g. bash) + + + + + If it’s a server: + + + + If it’s a web server: + + + servers/http (e.g. + apache-httpd) + + + + + If it’s an implementation of the X Windowing System: + + + servers/x11 (e.g. xorg — + this includes the client libraries and programs) + + + + + Else: + + + servers/misc + + + + + + + + If it’s a desktop environment: + + + desktops (e.g. kde, + gnome, enlightenment) + + + + + If it’s a window manager: + + + applications/window-managers (e.g. + awesome, stumpwm) + + + + + If it’s an application: + + + A (typically large) program with a distinct user interface, primarily + used interactively. + + + + If it’s a version management system: + + + applications/version-management (e.g. + subversion) + + + + + If it’s for video playback / editing: + + + applications/video (e.g. + vlc) + + + + + If it’s for graphics viewing / editing: + + + applications/graphics (e.g. + gimp) + + + + + If it’s for networking: + + + + If it’s a mailreader: + + + applications/networking/mailreaders (e.g. + thunderbird) + + + + + If it’s a newsreader: + + + applications/networking/newsreaders (e.g. + pan) + + + + + If it’s a web browser: + + + applications/networking/browsers (e.g. + firefox) + + + + + Else: + + + applications/networking/misc + + + + + + + + Else: + + + applications/misc + + + + + + + + If it’s data (i.e., does not have a + straight-forward executable semantics): + + + + If it’s a font: + + + data/fonts + + + + + If it’s related to SGML/XML processing: + + + + If it’s an XML DTD: + + + data/sgml+xml/schemas/xml-dtd (e.g. + docbook) + + + + + If it’s an XSLT stylesheet: + + + (Okay, these are executable...) + + + data/sgml+xml/stylesheets/xslt (e.g. + docbook-xsl) + + + + + + + + + + + If it’s a game: + + + games + + + + + Else: + + + misc + + + + +
+ +
+ Versioning + + + Because every version of a package in Nixpkgs creates a potential + maintenance burden, old versions of a package should not be kept unless + there is a good reason to do so. For instance, Nixpkgs contains several + versions of GCC because other packages don’t build with the latest + version of GCC. Other examples are having both the latest stable and latest + pre-release version of a package, or to keep several major releases of an + application that differ significantly in functionality. + + + + If there is only one version of a package, its Nix expression should be + named e2fsprogs/default.nix. If there are multiple + versions, this should be reflected in the filename, e.g. + e2fsprogs/1.41.8.nix and + e2fsprogs/1.41.9.nix. The version in the filename + should leave out unnecessary detail. For instance, if we keep the latest + Firefox 2.0.x and 3.5.x versions in Nixpkgs, they should be named + firefox/2.0.nix and + firefox/3.5.nix, respectively (which, at a given + point, might contain versions 2.0.0.20 and + 3.5.4). If a version requires many auxiliary files, you + can use a subdirectory for each version, e.g. + firefox/2.0/default.nix and + firefox/3.5/default.nix. + + + + All versions of a package must be included in + all-packages.nix to make sure that they evaluate + correctly. + +
+
+
+ Fetching Sources -
-
Fetching Sources - There are multiple ways to fetch a package source in nixpkgs. The - general guideline is that you should package sources with a high degree of - availability. Right now there is only one fetcher which has mirroring - support and that is fetchurl. Note that you should also - prefer protocols which have a corresponding proxy environment variable. + + There are multiple ways to fetch a package source in nixpkgs. The general + guideline is that you should package sources with a high degree of + availability. Right now there is only one fetcher which has mirroring + support and that is fetchurl. Note that you should also + prefer protocols which have a corresponding proxy environment variable. - You can find many source fetch helpers in pkgs/build-support/fetch*. + + + You can find many source fetch helpers in + pkgs/build-support/fetch*. - In the file pkgs/top-level/all-packages.nix you can - find fetch helpers, these have names on the form - fetchFrom*. The intention of these are to provide - snapshot fetches but using the same api as some of the version controlled - fetchers from pkgs/build-support/. As an example going - from bad to good: - - - Bad: Uses git:// which won't be proxied. + + + In the file pkgs/top-level/all-packages.nix you can find + fetch helpers, these have names on the form fetchFrom*. + The intention of these are to provide snapshot fetches but using the same + api as some of the version controlled fetchers from + pkgs/build-support/. As an example going from bad to + good: + + + + Bad: Uses git:// which won't be proxied. src = fetchgit { url = "git://github.com/NixOS/nix.git"; @@ -632,10 +742,11 @@ src = fetchgit { sha256 = "1cw5fszffl5pkpa6s6wjnkiv6lm5k618s32sp60kvmvpy7a2v9kg"; } - - - - Better: This is ok, but an archive fetch will still be faster. + + + + + Better: This is ok, but an archive fetch will still be faster. src = fetchgit { url = "https://github.com/NixOS/nix.git"; @@ -643,10 +754,11 @@ src = fetchgit { sha256 = "1cw5fszffl5pkpa6s6wjnkiv6lm5k618s32sp60kvmvpy7a2v9kg"; } - - - - Best: Fetches a snapshot archive and you get the rev you want. + + + + + Best: Fetches a snapshot archive and you get the rev you want. src = fetchFromGitHub { owner = "NixOS"; @@ -655,15 +767,19 @@ src = fetchFromGitHub { sha256 = "04yri911rj9j19qqqn6m82266fl05pz98inasni0vxr1cf1gdgv9"; } - - - + + + + +
+
+ Patches + + + Patches available online should be retrieved using + fetchpatch. -
-
Patches - Patches available online should be retrieved using - fetchpatch. patches = [ @@ -675,30 +791,54 @@ patches = [ ]; - Otherwise, you can add a .patch file to the - nixpkgs repository. In the interest of keeping our - maintenance burden to a minimum, only patches that are unique - to nixpkgs should be added in this way. - + + + Otherwise, you can add a .patch file to the + nixpkgs repository. In the interest of keeping our + maintenance burden to a minimum, only patches that are unique to + nixpkgs should be added in this way. + + + + patches = [ ./0001-changes.patch ]; - - If you do need to do create this sort of patch file, - one way to do so is with git: - - Move to the root directory of the source code - you're patching. -$ cd the/program/source - If a git repository is not already present, - create one and stage all of the source files. + + + + + If you do need to do create this sort of patch file, one way to do so is + with git: + + + + Move to the root directory of the source code you're patching. + +$ cd the/program/source + + + + + If a git repository is not already present, create one and stage all of + the source files. + $ git init -$ git add . - Edit some files to make whatever changes need - to be included in the patch. - Use git to create a diff, and pipe the output - to a patch file: +$ git add . + + + + + Edit some files to make whatever changes need to be included in the + patch. + + + + + Use git to create a diff, and pipe the output to a patch file: + $ git diff > nixpkgs/pkgs/the/package/0001-changes.patch - - -
- + + + + +
-- cgit v1.2.3