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 +++++----- doc/configuration.xml | 569 ++--- doc/contributing.xml | 38 +- doc/cross-compilation.xml | 689 +++--- doc/functions.xml | 1110 ++++----- doc/languages-frameworks/beam.xml | 500 ++-- doc/languages-frameworks/bower.xml | 289 ++- doc/languages-frameworks/coq.xml | 60 +- doc/languages-frameworks/go.xml | 174 +- doc/languages-frameworks/index.xml | 59 +- doc/languages-frameworks/java.xml | 84 +- doc/languages-frameworks/lua.xml | 43 +- doc/languages-frameworks/perl.xml | 233 +- doc/languages-frameworks/qt.xml | 108 +- doc/languages-frameworks/ruby.xml | 92 +- doc/languages-frameworks/texlive.xml | 108 +- doc/manual.xml | 47 +- doc/meta.xml | 544 +++-- doc/multiple-output.xml | 382 +++- doc/overlays.xml | 256 ++- doc/package-notes.xml | 927 ++++---- doc/platform-notes.xml | 84 +- doc/quick-start.xml | 372 ++- doc/release-notes.xml | 1353 +++++------ doc/reviewing-contributions.xml | 739 +++--- doc/stdenv.xml | 4149 +++++++++++++++++++--------------- doc/submitting-changes.xml | 860 +++---- 27 files changed, 8263 insertions(+), 6820 deletions(-) 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 - - -
- + + + + +
diff --git a/doc/configuration.xml b/doc/configuration.xml index 5370265c53ad..4411b4844e99 100644 --- a/doc/configuration.xml +++ b/doc/configuration.xml @@ -1,42 +1,51 @@ - -Global configuration - -Nix comes with certain defaults about what packages can and -cannot be installed, based on a package's metadata. By default, Nix -will prevent installation if any of the following criteria are -true: - - - The package is thought to be broken, and has had - its meta.broken set to - true. - - The package isn't intended to run on the given system, as none of its meta.platforms match the given system. - - The package's meta.license is set - to a license which is considered to be unfree. - - The package has known security vulnerabilities but - has not or can not be updated for some reason, and a list of issues - has been entered in to the package's - meta.knownVulnerabilities. - - -Note that all this is checked during evaluation already, -and the check includes any package that is evaluated. -In particular, all build-time dependencies are checked. -nix-env -qa will (attempt to) hide any packages -that would be refused. - - -Each of these criteria can be altered in the nixpkgs -configuration. - -The nixpkgs configuration for a NixOS system is set in the -configuration.nix, as in the following example: + Global configuration + + Nix comes with certain defaults about what packages can and cannot be + installed, based on a package's metadata. By default, Nix will prevent + installation if any of the following criteria are true: + + + + + The package is thought to be broken, and has had its + meta.broken set to true. + + + + + The package isn't intended to run on the given system, as none of its + meta.platforms match the given system. + + + + + The package's meta.license is set to a license which is + considered to be unfree. + + + + + The package has known security vulnerabilities but has not or can not be + updated for some reason, and a list of issues has been entered in to the + package's meta.knownVulnerabilities. + + + + + Note that all this is checked during evaluation already, and the check + includes any package that is evaluated. In particular, all build-time + dependencies are checked. nix-env -qa will (attempt to) + hide any packages that would be refused. + + + Each of these criteria can be altered in the nixpkgs configuration. + + + The nixpkgs configuration for a NixOS system is set in the + configuration.nix, as in the following example: { nixpkgs.config = { @@ -44,187 +53,197 @@ configuration. }; } -However, this does not allow unfree software for individual users. -Their configurations are managed separately. - -A user's of nixpkgs configuration is stored in a user-specific -configuration file located at -~/.config/nixpkgs/config.nix. For example: + However, this does not allow unfree software for individual users. Their + configurations are managed separately. + + + A user's of nixpkgs configuration is stored in a user-specific configuration + file located at ~/.config/nixpkgs/config.nix. For + example: { allowUnfree = true; } - - -Note that we are not able to test or build unfree software on Hydra -due to policy. Most unfree licenses prohibit us from either executing or -distributing the software. - -
+ + + Note that we are not able to test or build unfree software on Hydra due to + policy. Most unfree licenses prohibit us from either executing or + distributing the software. + +
Installing broken packages - - There are two ways to try compiling a package which has been - marked as broken. + + There are two ways to try compiling a package which has been marked as + broken. + - - For allowing the build of a broken package once, you can use an - environment variable for a single invocation of the nix tools: - - $ export NIXPKGS_ALLOW_BROKEN=1 - - - - For permanently allowing broken packages to be built, you may - add allowBroken = true; to your user's - configuration file, like this: - + + + For allowing the build of a broken package once, you can use an + environment variable for a single invocation of the nix tools: +$ export NIXPKGS_ALLOW_BROKEN=1 + + + + + For permanently allowing broken packages to be built, you may add + allowBroken = true; to your user's configuration file, + like this: { allowBroken = true; } - + + -
- -
+
+
Installing packages on unsupported systems - - There are also two ways to try compiling a package which has been marked as unsuported for the given system. + There are also two ways to try compiling a package which has been marked as + unsuported for the given system. - - For allowing the build of a broken package once, you can use an environment variable for a single invocation of the nix tools: - - $ export NIXPKGS_ALLOW_UNSUPPORTED_SYSTEM=1 - - - - - For permanently allowing broken packages to be built, you may add allowUnsupportedSystem = true; to your user's configuration file, like this: - + + + For allowing the build of a broken package once, you can use an + environment variable for a single invocation of the nix tools: +$ export NIXPKGS_ALLOW_UNSUPPORTED_SYSTEM=1 + + + + + For permanently allowing broken packages to be built, you may add + allowUnsupportedSystem = true; to your user's + configuration file, like this: { allowUnsupportedSystem = true; } - - + + - The difference between an a package being unsupported on some system and being broken is admittedly a bit fuzzy. - If a program ought to work on a certain platform, but doesn't, the platform should be included in meta.platforms, but marked as broken with e.g. meta.broken = !hostPlatform.isWindows. - Of course, this begs the question of what "ought" means exactly. - That is left to the package maintainer. + The difference between an a package being unsupported on some system and + being broken is admittedly a bit fuzzy. If a program + ought to work on a certain platform, but doesn't, the + platform should be included in meta.platforms, but marked + as broken with e.g. meta.broken = + !hostPlatform.isWindows. Of course, this begs the question of what + "ought" means exactly. That is left to the package maintainer. -
- -
+
+
Installing unfree packages - There are several ways to tweak how Nix handles a package - which has been marked as unfree. + + There are several ways to tweak how Nix handles a package which has been + marked as unfree. + - - To temporarily allow all unfree packages, you can use an - environment variable for a single invocation of the nix tools: - - $ export NIXPKGS_ALLOW_UNFREE=1 - - - - It is possible to permanently allow individual unfree packages, - while still blocking unfree packages by default using the - allowUnfreePredicate configuration - option in the user configuration file. - - This option is a function which accepts a package as a - parameter, and returns a boolean. The following example - configuration accepts a package and always returns false: + + + To temporarily allow all unfree packages, you can use an environment + variable for a single invocation of the nix tools: +$ export NIXPKGS_ALLOW_UNFREE=1 + + + + + It is possible to permanently allow individual unfree packages, while + still blocking unfree packages by default using the + allowUnfreePredicate configuration option in the user + configuration file. + + + This option is a function which accepts a package as a parameter, and + returns a boolean. The following example configuration accepts a package + and always returns false: { allowUnfreePredicate = (pkg: false); } - - - A more useful example, the following configuration allows - only allows flash player and visual studio code: - + + + A more useful example, the following configuration allows only allows + flash player and visual studio code: { allowUnfreePredicate = (pkg: elem (builtins.parseDrvName pkg.name).name [ "flashplayer" "vscode" ]); } - - - - It is also possible to whitelist and blacklist licenses - that are specifically acceptable or not acceptable, using - whitelistedLicenses and - blacklistedLicenses, respectively. - - - The following example configuration whitelists the - licenses amd and wtfpl: - + + + + + It is also possible to whitelist and blacklist licenses that are + specifically acceptable or not acceptable, using + whitelistedLicenses and + blacklistedLicenses, respectively. + + + The following example configuration whitelists the licenses + amd and wtfpl: { whitelistedLicenses = with stdenv.lib.licenses; [ amd wtfpl ]; } - - - The following example configuration blacklists the - gpl3 and agpl3 licenses: - + + + The following example configuration blacklists the gpl3 + and agpl3 licenses: { blacklistedLicenses = with stdenv.lib.licenses; [ agpl3 gpl3 ]; } - - + + - A complete list of licenses can be found in the file - lib/licenses.nix of the nixpkgs tree. -
- - -
- - Installing insecure packages - + + A complete list of licenses can be found in the file + lib/licenses.nix of the nixpkgs tree. + +
+
+ Installing insecure packages - There are several ways to tweak how Nix handles a package - which has been marked as insecure. + + There are several ways to tweak how Nix handles a package which has been + marked as insecure. + - - To temporarily allow all insecure packages, you can use an - environment variable for a single invocation of the nix tools: - - $ export NIXPKGS_ALLOW_INSECURE=1 - - - - It is possible to permanently allow individual insecure - packages, while still blocking other insecure packages by - default using the permittedInsecurePackages - configuration option in the user configuration file. - - The following example configuration permits the - installation of the hypothetically insecure package - hello, version 1.2.3: + + + To temporarily allow all insecure packages, you can use an environment + variable for a single invocation of the nix tools: +$ export NIXPKGS_ALLOW_INSECURE=1 + + + + + It is possible to permanently allow individual insecure packages, while + still blocking other insecure packages by default using the + permittedInsecurePackages configuration option in the + user configuration file. + + + The following example configuration permits the installation of the + hypothetically insecure package hello, version + 1.2.3: { permittedInsecurePackages = [ @@ -232,47 +251,44 @@ distributing the software. ]; } - - - - - It is also possible to create a custom policy around which - insecure packages to allow and deny, by overriding the - allowInsecurePredicate configuration - option. - - The allowInsecurePredicate option is a - function which accepts a package and returns a boolean, much - like allowUnfreePredicate. - - The following configuration example only allows insecure - packages with very short names: - + + + + + It is also possible to create a custom policy around which insecure + packages to