pyrox.dev
+672
-532
doc/coding-conventions.xml
+672
-532
doc/coding-conventions.xml
···············<replaceable>...</replaceable> if doCoverageAnalysis then "bla" else "" <replaceable>...</replaceable>···<replaceable>...</replaceable> if args ? doCoverageAnalysis && args.doCoverageAnalysis then "bla" else "" <replaceable>...</replaceable>-<filename>pkgs/<replaceable>category</replaceable>/<replaceable>subcategory</replaceable>/<replaceable>...</replaceable>/<replaceable>pkgname</replaceable></filename>.-<para><filename>development/tools/parsing</filename> (e.g. <filename>bison</filename>, <filename>flex</filename>)</para>-<para><filename>development/tools/build-managers</filename> (e.g. <filename>gnumake</filename>)</para>-<para><filename>tools/archivers</filename> (e.g. <filename>zip</filename>, <filename>tar</filename>)</para>-<para><filename>tools/compression</filename> (e.g. <filename>gzip</filename>, <filename>bzip2</filename>)</para>-<para><filename>tools/security</filename> (e.g. <filename>nmap</filename>, <filename>gnupg</filename>)</para>-<para><filename>servers/x11</filename> (e.g. <filename>xorg</filename> — this includes the client libraries and programs)</para>-<para><filename>desktops</filename> (e.g. <filename>kde</filename>, <filename>gnome</filename>, <filename>enlightenment</filename>)</para>-<para><filename>applications/window-managers</filename> (e.g. <filename>awesome</filename>, <filename>stumpwm</filename>)</para>-<para><filename>applications/version-management</filename> (e.g. <filename>subversion</filename>)</para>-<para><filename>applications/networking/mailreaders</filename> (e.g. <filename>thunderbird</filename>)</para>-<para><filename>applications/networking/newsreaders</filename> (e.g. <filename>pan</filename>)</para>-<para><filename>applications/networking/browsers</filename> (e.g. <filename>firefox</filename>)</para>-<para><filename>data/sgml+xml/schemas/xml-dtd</filename> (e.g. <filename>docbook</filename>)</para>-<para><filename>data/sgml+xml/stylesheets/xslt</filename> (e.g. <filename>docbook-xsl</filename>)</para>+<filename>pkgs/<replaceable>category</replaceable>/<replaceable>subcategory</replaceable>/<replaceable>...</replaceable>/<replaceable>pkgname</replaceable></filename>.············
+283
-276
doc/configuration.xml
+283
-276
doc/configuration.xml
···-<listitem><para>The package isn't intended to run on the given system, as none of its <literal>meta.platforms</literal> match the given system.</para></listitem>···-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:-For permanently allowing broken packages to be built, you may add <literal>allowUnsupportedSystem = true;</literal> to your user's configuration file, like this:-The difference between an a package being unsupported on some system and being broken is admittedly a bit fuzzy.-If a program <emphasis>ought</emphasis> to work on a certain platform, but doesn't, the platform should be included in <literal>meta.platforms</literal>, but marked as broken with e.g. <literal>meta.broken = !hostPlatform.isWindows</literal>.allowUnfreePredicate = (pkg: elem (builtins.parseDrvName pkg.name).name [ "flashplayer" "vscode" ]);···allowInsecurePredicate = (pkg: (builtins.stringLength (builtins.parseDrvName pkg.name).name) <= 5);·····················
+19
-19
doc/contributing.xml
+19
-19
doc/contributing.xml
···
+425
-264
doc/cross-compilation.xml
+425
-264
doc/cross-compilation.xml
···-One might think that cross-compilation is a fairly niche concern, but there are advantages to being rigorous about distinguishing build-time vs run-time environments even when one is developing and deploying on the same machine.-Nixpkgs is increasingly adopting the opinion that packages should be written with cross-compilation in mind, and nixpkgs should evaluate in a similar way (by minimizing cross-compilation-specific special cases) whether or not one is cross-compiling.-First, it will describe the basics of how to package software in a way that supports cross-compilation.-Nixpkgs follows the <link xlink:href="https://gcc.gnu.org/onlinedocs/gccint/Configure-Terms.html">common historical convention of GNU autoconf</link> of distinguishing between 3 types of platform: <wordasword>build</wordasword>, <wordasword>host</wordasword>, and <wordasword>target</wordasword>.+<programlisting>{ stdenv, buildPlatform, hostPlatform, fooDep, barDep, .. }: ...buildPlatform...</programlisting>-In summary, <wordasword>build</wordasword> is the platform on which a package is being built, <wordasword>host</wordasword> is the platform on which it is to run. The third attribute, <wordasword>target</wordasword>, is relevant only for certain specific compilers and build tools.-In Nixpkgs, these three platforms are defined as attribute sets under the names <literal>buildPlatform</literal>, <literal>hostPlatform</literal>, and <literal>targetPlatform</literal>.-All three are always defined as attributes in the standard environment, and at the top level. That means one can get at them just like a dependency in a function that is imported with <literal>callPackage</literal>:-<programlisting>{ stdenv, buildPlatform, hostPlatform, fooDep, barDep, .. }: ...buildPlatform...</programlisting>, or just off <varname>stdenv</varname>:-Once someone has a built package, or pre-built binary package, the build platform should not matter and be safe to ignore.-The "target platform" attribute is, unlike the other two attributes, not actually fundamental to the process of building software.-Instead, it is only relevant for compatibility with building certain specific compilers and build tools.-The build process of certain compilers is written in such a way that the compiler resulting from a single build can itself only produce binaries for a single platform.-The task specifying this single "target platform" is thus pushed to build time of the compiler.-The root cause of this mistake is often that the compiler (which will be run on the host) and the the standard library/runtime (which will be run on the target) are built by a single build process.-If the tool supports modular or pluggable backends, both the need to specify the target at build time and the constraint of having only a single target disappear.-Although the existence of a "target platfom" is arguably a historical mistake, it is a common one: examples of tools that suffer from it are GCC, Binutils, GHC and Autoconf.-Still, because the concept of a target platform is so ingrained, it is best to support it as is.-The exact schema these fields follow is a bit ill-defined due to a long and convoluted evolution, but this is slowly being cleaned up.-You can see examples of ones used in practice in <literal>lib.systems.examples</literal>; note how they are not all very consistent.-Examples of this would be "x86_64-darwin" and "i686-linux"; see <literal>lib.systems.doubles</literal> for more.-This format isn't very standard, but has built-in support in Nix, such as the <varname>builtins.currentSystem</varname> impure string.-This is a standard format called the "LLVM target triple", as they are pioneered by LLVM and traditionally just used for the <varname>targetPlatform</varname>.-This format is strictly more informative than the "Nix host double", as the previous format could analogously be termed.-[Technically, only one need be specified and the others can be inferred, though the precision of inference may not be very good.]-Valid identifiers include "glibc" for GNU libc, "libSystem" for Darwin's Libsystem, and "uclibc" for µClibc.-These predicates are defined in <literal>lib.systems.inspect</literal>, and slapped on every platform.-They are superior to the ones in <varname>stdenv</varname> as they force the user to be explicit about which platform they are inspecting.-See <literal>lib.systems.platforms</literal> for examples—there's hopefully one in there that will work verbatim for each platform that is working.-In this section we explore the relationship between both runtime and buildtime dependencies and the 3 Autoconf platforms.-A runtime dependency between 2 packages implies that between them both the host and target platforms match.-A build time dependency, however, implies a shift in platforms between the depending package and the depended-on package.-The meaning of a build time dependency is that to build the depending package we need to be able to run the depended-on's package.-The depending package's build platform is therefore equal to the depended-on package's host platform.-Analogously, the depending package's host platform is equal to the depended-on package's target platform.-In this manner, given the 3 platforms for one package, we can determine the three platforms for all its transitive dependencies.-This is the most important guiding principle behind cross-compilation with Nixpkgs, and will be called the <wordasword>sliding window principle</wordasword>.-If a package is being built with a <literal>(build, host, target)</literal> platform triple of <literal>(foo, bar, bar)</literal>, then its build-time dependencies would have a triple of <literal>(foo, foo, bar)</literal>, and <emphasis>those packages'</emphasis> build-time dependencies would have triple of <literal>(foo, foo, foo)</literal>.-In other words, it should take two "rounds" of following build-time dependency edges before one reaches a fixed point where, by the sliding window principle, the platform triple no longer changes.-Indeed, this happens with cross compilation, where only rounds of native dependencies starting with the second necessarily coincide with native packages.-The depending package's target platform is unconstrained by the sliding window principle, which makes sense in that one can in principle build cross compilers targeting arbitrary platforms.-How does this work in practice? Nixpkgs is now structured so that build-time dependencies are taken from <varname>buildPackages</varname>, whereas run-time dependencies are taken from the top level attribute set.-For example, <varname>buildPackages.gcc</varname> should be used at build time, while <varname>gcc</varname> should be used at run time.-Now, for most of Nixpkgs's history, there was no <varname>buildPackages</varname>, and most packages have not been refactored to use it explicitly.-Instead, one can use the six (<emphasis>gasp</emphasis>) attributes used for specifying dependencies as documented in <xref linkend="ssec-stdenv-dependencies"/>.-We "splice" together the run-time and build-time package sets with <varname>callPackage</varname>, and then <varname>mkDerivation</varname> for each of four attributes pulls the right derivation out.-This splicing can be skipped when not cross compiling as the package sets are the same, but is a bit slow for cross compiling.-Because of this, a best-of-both-worlds solution is in the works with no splicing or explicit access of <varname>buildPackages</varname> needed.-There is also a "backlink" <varname>targetPackages</varname>, yielding a package set whose <varname>buildPackages</varname> is the current package set.-Please do not use this unless you are absolutely sure you are packaging such a compiler and there is no other way.-Some frequently problems when packaging for cross compilation are good to just spell and answer.-Ideally the information above is exhaustive, so this section cannot provide any new information,-but its ludicrous and cruel to expect everyone to spend effort working through the interaction of many features just to figure out the same answer to the same common problem.-What if my package's build system needs to build a C program to be run under the build environment?-Many packages assume that an unprefixed <command>ar</command> is available, but Nix doesn't provide one.-More information needs to moved from the old wiki, especially <link xlink:href="https://nixos.org/wiki/CrossCompiling" />, for this section.-Nixpkgs can be instantiated with <varname>localSystem</varname> alone, in which case there is no cross compiling and everything is built by and for that system,-or also with <varname>crossSystem</varname>, in which case packages run on the latter, but all building happens on the former.-Both parameters take the same schema as the 3 (build, host, and target) platforms defined in the previous section.-As mentioned above, <literal>lib.systems.examples</literal> has some platforms which are used as arguments for these parameters in practice.nix-build <nixpkgs> --arg crossSystem '(import <nixpkgs/lib>).systems.examples.fooBarBaz' -A whatever</programlisting>-Eventually we would like to make these platform examples an unnecessary convenience so that <programlisting>nix-build <nixpkgs> --arg crossSystem.config '<arch>-<os>-<vendor>-<abi>' -A whatever</programlisting>-The problem today is dependencies on other sorts of configuration which aren't given proper defaults.-We rely on the examples to crudely to set those configuration parameters in some vaguely sane manner on the users behalf.-Issue <link xlink:href="https://github.com/NixOS/nixpkgs/issues/34274">#34274</link> tracks this inconvenience along with its root cause in crufty configuration options.-While one is free to pass both parameters in full, there's a lot of logic to fill in missing fields.-As discussed in the previous section, only one of <varname>system</varname>, <varname>config</varname>, and <varname>parsed</varname> is needed to infer the other two.-Finally, <literal>localSystem.system</literal> is also <emphasis>impurely</emphasis> inferred based on the platform evaluation occurs.-This means it is often not necessary to pass <varname>localSystem</varname> at all, as in the command-line example in the previous paragraph.-Many sources (manual, wiki, etc) probably mention passing <varname>system</varname>, <varname>platform</varname>, along with the optional <varname>crossSystem</varname> to nixpkgs:-Passing those two instead of <varname>localSystem</varname> is still supported for compatibility, but is discouraged.-Indeed, much of the inference we do for these parameters is motivated by compatibility as much as convenience.-One would think that <varname>localSystem</varname> and <varname>crossSystem</varname> overlap horribly with the three <varname>*Platforms</varname> (<varname>buildPlatform</varname>, <varname>hostPlatform,</varname> and <varname>targetPlatform</varname>; see <varname>stage.nix</varname> or the manual).-Actually, those identifiers are purposefully not used here to draw a subtle but important distinction:-While the granularity of having 3 platforms is necessary to properly *build* packages, it is overkill for specifying the user's *intent* when making a build plan or package set.-A simple "build vs deploy" dichotomy is adequate: the sliding window principle described in the previous section shows how to interpolate between the these two "end points" to get the 3 platform triple for each bootstrapping stage.-That means for any package a given package set, even those not bound on the top level but only reachable via dependencies or <varname>buildPackages</varname>, the three platforms will be defined as one of <varname>localSystem</varname> or <varname>crossSystem</varname>, with the former replacing the latter as one traverses build-time dependencies.-A last simple difference then is <varname>crossSystem</varname> should be null when one doesn't want to cross-compile, while the <varname>*Platform</varname>s are always non-null.-If one explores nixpkgs, they will see derivations with names like <literal>gccCross</literal>.-Such <literal>*Cross</literal> derivations is a holdover from before we properly distinguished between the host and target platforms-—the derivation with "Cross" in the name covered the <literal>build = host != target</literal> case, while the other covered the <literal>host = target</literal>, with build platform the same or not based on whether one was using its <literal>.nativeDrv</literal> or <literal>.crossDrv</literal>.
+538
-532
doc/functions.xml
+538
-532
doc/functions.xml
···············-<link xlink:href="https://github.com/moby/moby/blob/master/image/spec/v1.2.md#docker-image-specification-v120">+<link xlink:href="https://github.com/moby/moby/blob/master/image/spec/v1.2.md#docker-image-specification-v120">···+<link xlink:href="https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions">-<link xlink:href="https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions">-If you see errors similar to <literal>getProtocolByName: does not exist (no such protocol name: tcp)</literal>-If you see errors similar to <literal>Error_Protocol ("certificate has unknown CA",True,UnknownCa)</literal>······-<varname>runAsRoot</varname> <xref linkend='ex-dockerTools-buildImage-runAsRoot'/> script for cases like···
+277
-223
doc/languages-frameworks/beam.xml
+277
-223
doc/languages-frameworks/beam.xml
··················Erlang/OTP 18 [erts-7.0] [source] [64-bit] [smp:4:4] [async-threads:10] [hipe] [kernel-poll:false]·········
+130
-145
doc/languages-frameworks/bower.xml
+130
-145
doc/languages-frameworks/bower.xml
·········(fetchbower "jquery" "2.2.2" "1.9.1 - 2" "10sp5h98sqwk90y4k6hbdviwqzvzwqf47r3r51pakch5ii2y7js1")-<section xml:id="ssec-build-bower-components"><title><varname>buildBowerComponents</varname> function</title>-The function is implemented in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/bower-modules/generic/default.nix">+<link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/bower-modules/generic/default.nix">···-<varname>generated</varname> specifies the file which was created by <command>bower2nix</command>.-<example xml:id="ex-bowerGulpFile"><title>Example build script (<filename>gulpfile.js</filename>)</title>······
+31
-29
doc/languages-frameworks/coq.xml
+31
-29
doc/languages-frameworks/coq.xml
···
+79
-85
doc/languages-frameworks/go.xml
+79
-85
doc/languages-frameworks/go.xml
·········-<varname>fetch type</varname> that needs to be used to get package source. If <varname>git</varname>-is used there should be <varname>url</varname>, <varname>rev</varname> and <varname>sha256</varname>-<para>To extract dependency information from a Go package in automated way use <link xlink:href="https://github.com/kamilchm/go2nix">go2nix</link>.-<varname>buildGoPackage</varname> produces <xref linkend='chap-multiple-output' xrefstyle="select: title" />-where <varname>bin</varname> includes program binaries. You can test build a Go binary as follows:
+27
-32
doc/languages-frameworks/index.xml
+27
-32
doc/languages-frameworks/index.xml
···
+36
-40
doc/languages-frameworks/java.xml
+36
-40
doc/languages-frameworks/java.xml
·········
+20
-23
doc/languages-frameworks/lua.xml
+20
-23
doc/languages-frameworks/lua.xml
···-in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/lua-modules/generic/default.nix">+<link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/lua-modules/generic/default.nix">-in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/lua-packages.nix"><filename>pkgs/top-level/lua-packages.nix</filename></link>.+<link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/lua-packages.nix"><filename>pkgs/top-level/lua-packages.nix</filename></link>.···xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/lua-modules"><filename>pkgs/development/lua-modules</filename></link>.
+108
-111
doc/languages-frameworks/perl.xml
+108
-111
doc/languages-frameworks/perl.xml
···-xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/perl-modules/generic"><filename>pkgs/development/perl-modules/generic</filename></link>.</para>+xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/perl-modules/generic"><filename>pkgs/development/perl-modules/generic</filename></link>.xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link>,············
+62
-46
doc/languages-frameworks/qt.xml
+62
-46
doc/languages-frameworks/qt.xml
···-The most important consideration in packaging Qt-based software is ensuring that each package and all its dependencies use the same version of Qt 5;-Packages providing libraries should be added to the top-level function <varname>mkLibsForQt5</varname>,-A special <varname>callPackage</varname> function is used in this scope to ensure that the entire dependency tree uses the same Qt 5 version.-Import dependencies unqualified, i.e., <literal>qtbase</literal> not <literal>qt5.qtbase</literal>.-<emphasis>Do not</emphasis> import a package set such as <literal>qt5</literal> or <literal>libsForQt5</literal>.-If a library does not support a particular version of Qt 5, it is best to mark it as broken by setting its <literal>meta.broken</literal> attribute.-A package may be marked broken for certain versions by testing the <literal>qtbase.version</literal> attribute, which will always give the current Qt 5 version.-Call your application expression using <literal>libsForQt5.callPackage</literal> instead of <literal>callPackage</literal>.-Import dependencies unqualified, i.e., <literal>qtbase</literal> not <literal>qt5.qtbase</literal>.-<emphasis>Do not</emphasis> import a package set such as <literal>qt5</literal> or <literal>libsForQt5</literal>.-Qt 5 maintains strict backward compatibility, so it is generally best to build an application package against the latest version using the <varname>libsForQt5</varname> library set.-In case a package does not build with the latest Qt version, it is possible to pick a set pinned to a particular version, e.g. <varname>libsForQt55</varname> for Qt 5.5, if that is the latest version the package supports.-because Qt is strictly backwards-compatible, any incompatibility is by definition a bug in the application.-When testing applications in Nixpkgs, it is a common practice to build the package with <literal>nix-build</literal> and run it using the created symbolic link.-This will not work with Qt applications, however, because they have many hard runtime requirements that can only be guaranteed if the package is actually installed.-To test a Qt application, install it with <literal>nix-env</literal> or run it inside <literal>nix-shell</literal>.
+46
-44
doc/languages-frameworks/ruby.xml
+46
-44
doc/languages-frameworks/ruby.xml
············
+72
-36
doc/languages-frameworks/texlive.xml
+72
-36
doc/languages-frameworks/texlive.xml
···-<para>Since release 15.09 there is a new TeX Live packaging that lives entirely under attribute <varname>texlive</varname>.</para>-For basic usage just pull <varname>texlive.combined.scheme-basic</varname> for an environment with basic LaTeX support.</para></listitem>-There are all the schemes, collections and a few thousand packages, as defined upstream (perhaps with tiny differences).-By default you only get executables and files needed during runtime, and a little documentation for the core packages. To change that, you need to add <varname>pkgFilter</varname> function to <varname>combine</varname>.···-Note that the wrapper assumes that the result has a chance to be useful. For example, the core executables should be present, as well as some core data files. The supported way of ensuring this is by including some scheme, for example <varname>scheme-basic</varname>, into the combination.-feature/bug: when a package is rejected by <varname>pkgFilter</varname>, its dependencies are still propagated;</para></listitem>-in case of any bugs or feature requests, file a github issue or better a pull request and /cc @vcunat.</para></listitem>
+21
-26
doc/manual.xml
+21
-26
doc/manual.xml
···
+290
-246
doc/meta.xml
+290
-246
doc/meta.xml
·········-<para>Wrong: <literal>"libpng is a library that allows you to decode PNG images."</literal></para>-<listitem><para>Multiple licenses referenced as a space delimited string of attribute shortNames (frowned upon)xlink:href="https://github.com/NixOS/nixpkgs/blob/master/maintainers/maintainer-list.nix"><filename>nixpkgs/maintainers/maintainer-list.nix</filename></link>
+293
-79
doc/multiple-output.xml
+293
-79
doc/multiple-output.xml
···-<para>The Nix language allows a derivation to produce multiple outputs, which is similar to what is utilized by other Linux distribution packaging systems. The outputs reside in separate nix store paths, so they can be mostly handled independently of each other, including passing to build inputs, garbage collection or binary substitution. The exception is that building from source always produces all the outputs.</para>-<para>The main motivation is to save disk space by reducing runtime closure sizes; consequently also sizes of substituted binaries get reduced. Splitting can be used to have more granular runtime dependencies, for example the typical reduction is to split away development-only files, as those are typically not needed during runtime. As a result, closure sizes of many packages can get reduced to a half or even much less.</para>-<note><para>The reduction effects could be instead achieved by building the parts in completely separate derivations. That would often additionally reduce build-time closures, but it tends to be much harder to write such derivations, as build systems typically assume all parts are being built at once. This compromise approach of single source package producing multiple binary packages is also utilized often by rpm and deb.</para></note>-<para>When installing a package via <varname>systemPackages</varname> or <command>nix-env</command> you have several options:</para>-<listitem><para>You can install particular outputs explicitly, as each is available in the Nix language as an attribute of the package. The <varname>outputs</varname> attribute contains a list of output names.</para></listitem>-<listitem><para>You can let it use the default outputs. These are handled by <varname>meta.outputsToInstall</varname> attribute that contains a list of output names.</para>-<listitem><para>NixOS provides configuration option <varname>environment.extraOutputsToInstall</varname> that allows adding extra outputs of <varname>environment.systemPackages</varname> atop the default ones. It's mainly meant for documentation and debug symbols, and it's also modified by specific options.</para>-<note><para>At this moment there is no similar configurability for packages installed by <command>nix-env</command>. You can still use approach from <xref linkend="sec-modify-via-packageOverrides" /> to override <varname>meta.outputsToInstall</varname> attributes, but that's a rather inconvenient way.</para></note>-<para>In the Nix language the individual outputs can be reached explicitly as attributes, e.g. <varname>coreutils.info</varname>, but the typical case is just using packages as build inputs.</para>-<para>When a multiple-output derivation gets into a build input of another derivation, the <varname>dev</varname> output is added if it exists, otherwise the first output is added. In addition to that, <varname>propagatedBuildOutputs</varname> of that package which by default contain <varname>$outputBin</varname> and <varname>$outputLib</varname> are also added. (See <xref linkend="multiple-output-file-type-groups" />.)</para>-<para>In nixpkgs there is a framework supporting multiple-output derivations. It tries to cover most cases by default behavior. You can find the source separated in <<filename>nixpkgs/pkgs/build-support/setup-hooks/multiple-outputs.sh</filename>>; it's relatively well-readable. The whole machinery is triggered by defining the <varname>outputs</varname> attribute to contain the list of desired output names (strings).</para>-<para>Often such a single line is enough. For each output an equally named environment variable is passed to the builder and contains the path in nix store for that output. Typically you also want to have the main <varname>out</varname> output, as it catches any files that didn't get elsewhere.</para>-<note><para>There is a special handling of the <varname>debug</varname> output, described at <xref linkend="stdenv-separateDebugInfo" />.</para></note>-<para>A commonly adopted convention in <literal>nixpkgs</literal> is that executables provided by the package are contained within its first output. This convention allows the dependent packages to reference the executables provided by packages in a uniform manner. For instance, provided with the knowledge that the <literal>perl</literal> package contains a <literal>perl</literal> executable it can be referenced as <literal>${pkgs.perl}/bin/perl</literal> within a Nix derivation that needs to execute a Perl script.</para>-<para>The <literal>glibc</literal> package is a deliberate single exception to the <quote>binaries first</quote> convention. The <literal>glibc</literal> has <literal>libs</literal> as its first output allowing the libraries provided by <literal>glibc</literal> to be referenced directly (e.g. <literal>${stdenv.glibc}/lib/ld-linux-x86-64.so.2</literal>). The executables provided by <literal>glibc</literal> can be accessed via its <literal>bin</literal> attribute (e.g. <literal>${stdenv.glibc.bin}/bin/ldd</literal>).</para>-<para>The reason for why <literal>glibc</literal> deviates from the convention is because referencing a library provided by <literal>glibc</literal> is a very common operation among Nix packages. For instance, third-party executables packaged by Nix are typically patched and relinked with the relevant version of <literal>glibc</literal> libraries from Nix packages (please see the documentation on <link xlink:href="https://nixos.org/patchelf.html">patchelf</link> for more details).</para>-<para>The support code currently recognizes some particular kinds of outputs and either instructs the build system of the package to put files into their desired outputs or it moves the files during the fixup phase. Each group of file types has an <varname>outputFoo</varname> variable specifying the output name where they should go. If that variable isn't defined by the derivation writer, it is guessed – a default output name is defined, falling back to other possibilities if the output isn't defined.</para>-is for development-only files. These include C(++) headers, pkg-config, cmake and aclocal files. They go to <varname>dev</varname> or <varname>out</varname> by default.-is meant for user-facing binaries, typically residing in bin/. They go to <varname>bin</varname> or <varname>out</varname> by default.-is meant for libraries, typically residing in <filename>lib/</filename> and <filename>libexec/</filename>. They go to <varname>lib</varname> or <varname>out</varname> by default.-is for user documentation, typically residing in <filename>share/doc/</filename>. It goes to <varname>doc</varname> or <varname>out</varname> by default.-is for <emphasis>developer</emphasis> documentation. Currently we count gtk-doc and devhelp books in there. It goes to <varname>devdoc</varname> or is removed (!) by default. This is because e.g. gtk-doc tends to be rather large and completely unused by nixpkgs users.-is for man pages (except for section 3). They go to <varname>man</varname> or <varname>$outputBin</varname> by default.-is for section 3 man pages. They go to <varname>devman</varname> or <varname>$outputMan</varname> by default.-is for info pages. They go to <varname>info</varname> or <varname>$outputBin</varname> by default.-<listitem><para>Some configure scripts don't like some of the parameters passed by default by the framework, e.g. <literal>--docdir=/foo/bar</literal>. You can disable this by setting <literal>setOutputFlags = false;</literal>.</para></listitem>-<listitem><para>The outputs of a single derivation can retain references to each other, but note that circular references are not allowed. (And each strongly-connected component would act as a single output anyway.)</para></listitem>-<listitem><para>Most of split packages contain their core functionality in libraries. These libraries tend to refer to various kind of data that typically gets into <varname>out</varname>, e.g. locale strings, so there is often no advantage in separating the libraries into <varname>lib</varname>, as keeping them in <varname>out</varname> is easier.</para></listitem>-<listitem><para>Some packages have hidden assumptions on install paths, which complicates splitting.</para></listitem>
+135
-105
doc/overlays.xml
+135
-105
doc/overlays.xml
···-<para>If the <varname>overlays</varname> argument is not provided explicitly, we look for overlays in a path. The path-<para>First, if an <varname>overlays</varname> argument to the nixpkgs function itself is given,-<para>Otherwise, if the Nix path entry <literal><nixpkgs-overlays></literal> exists, we look for overlays-<para>See the section on <literal>NIX_PATH</literal> in the Nix manual for more details on how to-<filename>~/.config/nixpkgs/overlays/</filename> exists, then we look for overlays at that path, as-<para>If the path is a file, then the file is imported as a Nix expression and used as the list of-<para>Importing a top-level <filename>default.nix</filename> file, if it is a directory.</para>-<para>On a NixOS system the value of the <literal>nixpkgs.overlays</literal> option, if present,-is passed to the system Nixpkgs directly as an argument. Note that this does not affect the overlays for-non-NixOS operations (e.g. <literal>nix-env</literal>), which are looked up independently.</para>-<para>The <filename>overlays.nix</filename> option therefore provides a convenient way to use the same-as <filename>overlays.nix</filename> and imported as the value of <literal>nixpkgs.overlays</literal>.</para>···-the <literal>packageOverrides</literal> attribute described in <xref linkend="sec-modify-via-packageOverrides"/>.
+434
-467
doc/package-notes.xml
+434
-467
doc/package-notes.xml
···+xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/os-specific/linux/kernel"><filename>pkgs/os-specific/linux/kernel</filename></link>.-xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/os-specific/linux/kernel"><filename>pkgs/os-specific/linux/kernel</filename></link>.</para>| perl -e 'while (<>) { if (/(href|HREF)="([^"]*.bz2)"/) { print "$ENV{'i'}$2\n"; }; }' \···-<link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/eclipse"><filename>pkgs/applications/editors/eclipse</filename></link>.+<link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/eclipse"><filename>pkgs/applications/editors/eclipse</filename></link>.······+<link xlink:href="http://sandervanderburg.blogspot.nl/2013/09/composing-fhs-compatible-chroot.html">here</link>.-<link xlink:href="http://sandervanderburg.blogspot.nl/2013/09/composing-fhs-compatible-chroot.html">here</link>.-have a look at <link xlink:href="https://github.com/NixOS/nixpkgs/pull/20269">this pull request</link>.-<programlisting>/home/foo/.local/share/Steam/SteamApps/common/towns/towns.sh: line 1: java: command not found</programlisting>+<programlisting>/home/foo/.local/share/Steam/SteamApps/common/towns/towns.sh: line 1: java: command not found</programlisting>············
+38
-46
doc/platform-notes.xml
+38
-46
doc/platform-notes.xml
······makeFlags = stdenv.lib.optional stdenv.isDarwin "LDFLAGS=-Wl,-install_name,$(out)/lib/libfoo.dylib";-This causes errors like <code>xcode-select: error: no developer tools were found at '/Applications/Xcode.app'</code>···
+184
-188
doc/quick-start.xml
+184
-188
doc/quick-start.xml
···xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/hello/default.nix"><filename>pkgs/applications/misc/hello/default.nix</filename></link>.xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/archivers/cpio/default.nix"><filename>pkgs/tools/archivers/cpio/default.nix</filename></link>.xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/libraries/gmp/5.1.x.nix"><filename>pkgs/development/libraries/gmp/5.1.x.nix</filename></link>.xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/newsreaders/pan/default.nix"><filename>pkgs/applications/networking/newsreaders/pan/default.nix</filename></link>.xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/http/apache-httpd/2.4.nix"><filename>pkgs/servers/http/apache-httpd/2.4.nix</filename></link>.xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/mailreaders/thunderbird/default.nix"><filename>pkgs/applications/networking/mailreaders/thunderbird/default.nix</filename></link>.xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/misc/jdiskreport/default.nix"><filename>pkgs/tools/misc/jdiskreport/default.nix</filename></link>xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/misc/jdiskreport/builder.sh">builder</link>).xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link>xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/adobe-reader/default.nix"><filename>pkgs/applications/misc/adobe-reader/default.nix</filename></link>.xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/adobe-reader/builder.sh">builder</link>-<command>nix-prefetch-hg</command> available in <literal>nix-prefetch-scripts</literal> package.</para>-xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/fetchurl/mirrors.nix"><filename>pkgs/build-support/fetchurl/mirrors.nix</filename></link>.</para>+xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/fetchurl/mirrors.nix"><filename>pkgs/build-support/fetchurl/mirrors.nix</filename></link>.xlink:href="http://hydra.nixos.org/job/nix/trunk/tarball/latest/download-by-type/doc/manual/#chap-writing-nix-expressions">chapterxlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/all-packages.nix"><filename>pkgs/top-level/all-packages.nix</filename></link>
+703
-636
doc/release-notes.xml
+703
-636
doc/release-notes.xml
······url = http://releases.mozilla.org/<replaceable>...</replaceable>/firefox-2.0.0.6-source.tar.bz2;-<replaceable>mirror</replaceable><literal>/</literal><replaceable>hash-type</replaceable><literal>/</literal><replaceable>hash</replaceable>.+<replaceable>mirror</replaceable><literal>/</literal><replaceable>hash-type</replaceable><literal>/</literal><replaceable>hash</replaceable>.······
+456
-243
doc/reviewing-contributions.xml
+456
-243
doc/reviewing-contributions.xml
···xlink:href="https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc">mostxlink:href="https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-asc">least-We highly encourage looking at <link xlink:href="https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+review%3Anone+status%3Asuccess+-label%3A%222.status%3A+work-in-progress%22+no%3Aproject+no%3Aassignee+no%3Amilestone">+<link xlink:href="https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+review%3Anone+status%3Asuccess+-label%3A%222.status%3A+work-in-progress%22+no%3Aproject+no%3Aassignee+no%3Amilestone">··················
+2237
-1764
doc/stdenv.xml
+2237
-1764
doc/stdenv.xml
············-As described in the Nix manual, almost any <filename>*.drv</filename> store path in a derivation's attribute set will induce a dependency on that derivation.-<varname>mkDerivation</varname>, however, takes a few attributes intended to, between them, include all the dependencies of a package.-This is done both for structure and consistency, but also so that certain other setup can take place.-For example, certain dependencies need their bin directories added to the <envar>PATH</envar>.-That is built-in, but other setup is done via a pluggable mechanism that works in conjunction with these dependency attributes.-Dependencies can be broken down along three axes: their host and target platforms relative to the new derivation's, and whether they are propagated.-The platform distinctions are motivated by cross compilation; see <xref linkend="chap-cross"/> for exactly what each platform means.-The build platform is ignored because it is a mere implementation detail of the package satisfying the dependency:-As a general programming principle, dependencies are always <emphasis>specified</emphasis> as interfaces, not concrete implementation.-But even if one is not cross compiling, the platforms imply whether or not the dependency is needed at run-time or build-time, a concept that makes perfect sense outside of cross compilation.-For now, the run-time/build-time distinction is just a hint for mental clarity, but in the future it perhaps could be enforced.-The extension of <envar>PATH</envar> with dependencies, alluded to above, proceeds according to the relative platforms alone.-The process is carried out only for dependencies whose host platform matches the new derivation's build platform–i.e. which run on the platform where the new derivation will be built.-the platforms would be assumed to be unique for native and cross builds alike, so only the <varname>depsBuild*</varname> and <varname>nativeBuildDependencies</varname> dependencies would affect the <envar>PATH</envar>.-For each dependency <replaceable>dep</replaceable> of those dependencies, <filename><replaceable>dep</replaceable>/bin</filename>, if present, is added to the <envar>PATH</envar> environment variable.-The dependency is propagated when it forces some of its other-transitive (non-immediate) downstream dependencies to also take it on as an immediate dependency.-Nix itself already takes a package's transitive dependencies into account, but this propagation ensures nixpkgs-specific infrastructure like setup hooks (mentioned above) also are run as if the propagated dependency.-It is important to note dependencies are not necessary propagated as the same sort of dependency that they were before, but rather as the corresponding sort so that the platform rules still line up.-The exact rules for dependency propagation can be given by assigning each sort of dependency two integers based one how it's host and target platforms are offset from the depending derivation's platforms.-Those offsets are given are given below in the descriptions of each dependency list attribute.-Algorithmically, we traverse propagated inputs, accumulating every propagated dep's propagated deps and adjusting them to account for the "shift in perspective" described by the current dep's platform offsets.-This results in sort a transitive closure of the dependency relation, with the offsets being approximately summed when two dependency links are combined.-We also prune transitive deps whose combined offsets go out-of-bounds, which can be viewed as a filter over that transitive closure removing dependencies that are blatantly absurd.-We can define the process precisely with <link xlink:href="https://en.wikipedia.org/wiki/Natural_deduction">Natural Deduction</link> using the inference rules.-The <function>findInputs</function> function, currently residing in <filename>pkgs/stdenv/generic/setup.sh</filename>, implements the propagation logic.-They're confusing in very different ways so...hopefully if something doesn't make sense in one presentation, it does in the other!······-In the common case, the target offset of a dependency is the successor to the target offset: <literal>t = h + 1</literal>.-The target offset is the transitive dep is simply the host offset + 1, just as it was with the dependencies composed to make this transitive one;-Because of the bounds checks, the uncommon cases are <literal>h = t</literal> and <literal>h + 2 = t</literal>.-In the former case, the motivation for <function>mapOffset</function> is that since its host and target platforms are the same, no transitive dep of it should be able to "discover" an offset greater than its reduced target offsets.-<function>mapOffset</function> effectively "squashes" all its transitive dependencies' offsets so that none will ever be greater than the target offset of the original <literal>h = t</literal> package.-In the other case, <literal>h + 1</literal> is skipped over between the host and target offsets.-Instead of squashing the offsets, we need to "rip" them apart so no transitive dependencies' offset is that one.-Overall, the unifying theme here is that propagation shouldn't be introducing transitive dependencies involving platforms the needing package is unaware of.-The offset bounds checking and definition of <function>mapOffset</function> together ensure that this is the case.-Discovering a new offset is discovering a new platform, and since those platforms weren't in the derivation "spec" of the needing package, they cannot be relevant.-From a capability perspective, we can imagine that the host and target platforms of a package are the capabilities a package requires, and the depending package must provide the capability to the dependency.-A list of dependencies whose host and target platforms are the new derivation's build platform.-This means a <literal>-1</literal> host and <literal>-1</literal> target offset from the new derivation's platforms.-They are programs/libraries used at build time that furthermore produce programs/libraries also used at build time.-If the dependency doesn't care about the target platform (i.e. isn't a compiler or similar tool), put it in <varname>nativeBuildInputs</varname>instead.-The most common use for this <literal>buildPackages.stdenv.cc</literal>, the default C compiler for this role.-Since these packages are able to be run at build time, that are always added to the <envar>PATH</envar>, as described above.-But since these packages are only guaranteed to be able to run then, they shouldn't persist as run-time dependencies.-A list of dependencies whose host platform is the new derivation's build platform, and target platform is the new derivation's host platform.-This means a <literal>-1</literal> host offset and <literal>0</literal> target offset from the new derivation's platforms.-They are programs/libraries used at build time that, if they are a compiler or similar tool, produce code to run at run time—i.e. tools used to build the new derivation.-If the dependency doesn't care about the target platform (i.e. isn't a compiler or similar tool), put it here, rather than in <varname>depsBuildBuild</varname> or <varname>depsBuildTarget</varname>.-Since these packages are able to be run at build time, that are added to the <envar>PATH</envar>, as described above.-But since these packages only are guaranteed to be able to run then, they shouldn't persist as run-time dependencies.-A list of dependencies whose host platform is the new derivation's build platform, and target platform is the new derivation's target platform.-This means a <literal>-1</literal> host offset and <literal>1</literal> target offset from the new derivation's platforms.-They are programs used at build time that produce code to run at run with code produced by the depending package.-Most commonly, these would tools used to build the runtime or standard library the currently-being-built compiler will inject into any code it compiles.-In many cases, the currently-being built compiler is itself employed for that task, but when that compiler won't run (i.e. its build and host platform differ) this is not possible.-Other times, the compiler relies on some other tool, like binutils, that is always built separately so the dependency is unconditional.-As the only one where the platform offsets are not adjacent integers, it requires thinking of a bootstrapping stage <emphasis>two</emphasis> away from the current one.-try not to need this sort dependency, and try not avoid building standard libraries / runtimes in the same derivation as the compiler produces code using them.-Instead strive to build those like a normal library, using the newly-built compiler just as a normal library would.-In short, do not use this attribute unless you are packaging a compiler and are sure it is needed.-Since these packages are able to be run at build time, that are added to the <envar>PATH</envar>, as described above.-But since these packages only are guaranteed to be able to run then, they shouldn't persist as run-time dependencies.-A list of dependencies whose host and target platforms match the new derivation's host platform.-This means a both <literal>0</literal> host offset and <literal>0</literal> target offset from the new derivation's host platform.-In practice, that would usually be tools used by compilers for metaprogramming/macro systems, or libraries used by the macros/metaprogramming code itself.-It's always preferable to use a <varname>depsBuildBuild</varname> dependency in the derivation being built than a <varname>depsHostHost</varname> on the tool doing the building for this purpose.-This means a <literal>0</literal> host offset and <literal>1</literal> target offset from the new derivation's host platform.-If the dependency doesn't care about the target platform (i.e. isn't a compiler or similar tool), put it here, rather than in <varname>depsBuildBuild</varname>.-These often are programs/libraries used by the new derivation at <emphasis>run</emphasis>-time, but that isn't always the case.-For example, the machine code in a statically linked library is only used at run time, but the derivation containing the library is only needed at build time.-These are packages that run on the target platform, e.g. the standard library or run-time deps of standard library that a compiler insists on knowing about.-It's poor form in almost all cases for a package to depend on another from a future stage [future stage corresponding to positive offset].-This perhaps never ought to be used, but it is included for consistency [see below for the others].-This would be called <varname>depsBuildHostPropagated</varname> but for historical continuity.-For example, if package <varname>Y</varname> has <literal>propagatedNativeBuildInputs = [X]</literal>, and package <varname>Z</varname> has <literal>buildInputs = [Y]</literal>, then package <varname>Z</varname> will be built as if it included package <varname>X</varname> in its <varname>nativeBuildInputs</varname>.-If instead, package <varname>Z</varname> has <literal>nativeBuildInputs = [Y]</literal>, then <varname>Z</varname> will be built as if it included <varname>X</varname> in the <varname>depsBuildBuild</varname> of package <varname>Z</varname>, because of the sum of the two <literal>-1</literal> host offsets.-This would be called <varname>depsHostTargetPropagated</varname> but for historical continuity.-If set to 1 or higher, <literal>stdenv</literal> will print moderate debug information during the build.-In particular, the <command>gcc</command> and <command>ld</command> wrapper scripts will print out the complete command line passed to the wrapped tools.-If set to 6 or higher, the <literal>stdenv</literal> setup script will be run with <literal>set -x</literal> tracing.-If set to 7 or higher, the <command>gcc</command> and <command>ld</command> wrapper scripts will also be run with <literal>set -x</literal> tracing.-By default, when cross compiling, the configure script has <option>--build=...</option> and <option>--host=...</option> passed.-Packages can instead pass <literal>[ "build" "host" "target" ]</literal> or a subset to control exactly which platform flags are passed.-<footnote><para>Eventually these will be passed when in native builds too, to improve determinism: build-time guessing, as is done today, is a risk of impurity.</para></footnote>-By default it is skipped, but if <varname>doCheck</varname> is set to true, the check phase is usually executed.-Thus you should set <programlisting>doCheck = true;</programlisting> in the derivation to enable checks.-Like <varname>dontStripHost</varname>, but only affects the <command>strip</command> command targetting the package's host platform.-Like <varname>dontStripHost</varname>, but only affects the <command>strip</command> command targetting the packages' target platform.-<filename><replaceable>debug</replaceable>/lib/debug/.build-id/<replaceable>XX</replaceable>/<replaceable>YYYY…</replaceable></filename>,+<filename><replaceable>debug</replaceable>/lib/debug/.build-id/<replaceable>XX</replaceable>/<replaceable>YYYY…</replaceable></filename>,-By default it is skipped, but if <varname>doInstallCheck</varname> is set to true, the installCheck phase is usually executed.-Thus you should set <programlisting>doInstallCheck = true;</programlisting> in the derivation to enable install checks.-Cross compiled builds never run tests, no matter how <varname>doInstallCheck</varname> is set,+<term><function>makeWrapper</function><replaceable>executable</replaceable><replaceable>wrapperfile</replaceable><replaceable>args</replaceable>···+<term><function>substitute</function><replaceable>infile</replaceable><replaceable>outfile</replaceable><replaceable>subs</replaceable>+<term><option>--subst-var-by</option><replaceable>varName</replaceable><replaceable>s</replaceable>+<term><function>substituteInPlace</function><replaceable>file</replaceable><replaceable>subs</replaceable>+<term><function>substituteAll</function><replaceable>infile</replaceable><replaceable>outfile</replaceable>+<term><function>wrapProgram</function><replaceable>executable</replaceable><replaceable>makeWrapperArgs</replaceable>-Nix itself considers a build-time dependency merely something that should previously be built and accessible at build time—packages themselves are on their own to perform any additional setup.-In most cases, that is fine, and the downstream derivation can deal with it's own dependencies.-But for a few common tasks, that would result in almost every package doing the same sort of setup work---depending not on the package itself, but entirely on which dependencies were used.-In order to alleviate this burden, the <firstterm>setup hook></firstterm>mechanism was written, where any package can include a shell script that [by convention rather than enforcement by Nix], any downstream reverse-dependency will source as part of its build process.-That allows the downstream dependency to merely specify its dependencies, and lets those dependencies effectively initialize themselves.-The Setup hook mechanism is a bit of a sledgehammer though: a powerful feature with a broad and indiscriminate area of effect.-Nix itself is unchanged, but the spirit of adding dependencies being effect-free is violated even if the letter isn't.-For example, if a derivation path is mentioned more than once, Nix itself doesn't care and simply makes sure the dependency derivation is already built just the same—depending is just needing something to exist, and needing is idempotent.-However, a dependency specified twice will have its setup hook run twice, and that could easily change the build environment (though a well-written setup hook will therefore strive to be idempotent so this is in fact not observable).-More broadly, setup hooks are anti-modular in that multiple dependencies, whether the same or different, should not interfere and yet their setup hooks may well do so.-The most typical use of the setup hook is actually to add other hooks which are then run (i.e. after all the setup hooks) on each dependency.-For example, the C compiler wrapper's setup hook feeds itself flags for each dependency that contains relevant libaries and headers.-These 6 bash variables correspond to the 6 sorts of dependencies by platform (there's 12 total but we ignore the propagated/non-propagated axis).-Packages adding a hook should not hard code a specific hook, but rather choose a variable <emphasis>relative</emphasis> to how they are included.-Returning to the C compiler wrapper example, if it itself is an <literal>n</literal> dependency, then it only wants to accumulate flags from <literal>n + 1</literal> dependencies, as only those ones match the compiler's target platform.-The <envar>hostOffset</envar> variable is defined with the current dependency's host offset <envar>targetOffset</envar> with its target offset, before it's setup hook is sourced.-The <emphasis>existence</emphasis> of setups hooks has long been documented and packages inside Nixpkgs are free to use these mechanism.-Other packages, however, should not rely on these mechanisms not changing between Nixpkgs versions.-Because of the existing issues with this system, there's little benefit from mandating it be stable for any period of time.-These are GNU Binutils when targetting Linux, and a mix of cctools and GNU binutils for Darwin.-[The "Bintools" name is supposed to be a compromise between "Binutils" and "cctools" not denoting any specific implementation.]-Specifically, the underlying bintools package, and a C standard library (glibc or Darwin's libSystem, just for the dynamic loader) are all fed in, and dependency finding, hardening (see below), and purity checks for each are handled by Bintools Wrapper.-Packages typically depend on CC Wrapper, which in turn (at run time) depends on Bintools Wrapper.-Bintools Wrapper was only just recently split off from CC Wrapper, so the division of labor is still being worked out.-For example, it shouldn't care about about the C standard library, but just take a derivation with the dynamic loader (which happens to be the glibc on linux).-Dependency finding however is a task both wrappers will continue to need to share, and probably the most important to understand.-It is currently accomplished by collecting directories of host-platform dependencies (i.e. <varname>buildInputs</varname> and <varname>nativeBuildInputs</varname>) in environment variables.-Bintools Wrapper's setup hook causes any <filename>lib</filename> and <filename>lib64</filename> subdirectories to be added to <envar>NIX_LDFLAGS</envar>.-Since CC Wrapper and Bintools Wrapper use the same strategy, most of the Bintools Wrapper code is sparsely commented and refers to CC Wrapper.-Bintools Wrapper merely cites those, rather than repeating them, to avoid falling out of sync.-A final task of the setup hook is defining a number of standard environment variables to tell build systems which executables full-fill which purpose.-They are defined to just be the base name of the tools, under the assumption that Bintools Wrapper's binaries will be on the path.-Firstly, this helps poorly-written packages, e.g. ones that look for just <command>gcc</command> when <envar>CC</envar> isn't defined yet <command>clang</command> is to be used.-Secondly, this helps packages not get confused when cross-compiling, in which case multiple Bintools Wrappers may simultaneously be in use.-Each wrapper targets a single platform, so if binaries for multiple platforms are needed, the underlying binaries must be wrapped multiple times.-As this is a property of the wrapper itself, the multiple wrappings are needed whether or not the same underlying binaries can target multiple platforms.-<envar>BUILD_</envar>- and <envar>TARGET_</envar>-prefixed versions of the normal environment variable are defined for the additional Bintools Wrappers, properly disambiguating them.-A problem with this final task is that Bintools Wrapper is honest and defines <envar>LD</envar> as <command>ld</command>.-Most packages, however, firstly use the C compiler for linking, secondly use <envar>LD</envar> anyways, defining it as the C compiler, and thirdly, only so define <envar>LD</envar> when it is undefined as a fallback.-This triple-threat means Bintools Wrapper will break those packages, as LD is already defined as the actual linker which the package won't override yet doesn't want to use.-The workaround is to define, just for the problematic package, <envar>LD</envar> as the C compiler.-Specifically, a C compiler (GCC or Clang), wrapped binary tools, and a C standard library (glibc or Darwin's libSystem, just for the dynamic loader) are all fed in, and dependency finding, hardening (see below), and purity checks for each are handled by CC Wrapper.-Packages typically depend on CC Wrapper, which in turn (at run time) depends on Bintools Wrapper.-This works just like Bintools Wrapper, except that any <filename>include</filename> subdirectory of any relevant dependency is added to <envar>NIX_CFLAGS_COMPILE</envar>.-The setup hook itself contains some lengthy comments describing the exact convoluted mechanism by which this is accomplished.-CC Wrapper also like Bintools Wrapper defines standard environment variables with the names of the tools it wraps, for the same reasons described above.-Importantly, while it includes a <command>cc</command> symlink to the c compiler for portability, the <envar>CC</envar> will be defined using the compiler's "real name" (i.e. <command>gcc</command> or <command>clang</command>).-Adds the <filename>lib/site_perl</filename> subdirectory of each build input to the <envar>PERL5LIB</envar> environment variable.-For instance, if <varname>buildInputs</varname> contains Perl, then the <filename>lib/site_perl</filename> subdirectory of each input is added to the <envar>PERL5LIB</envar> environment variable./tmp/nix-build-zynaddsubfx-2.5.2.drv-0/zynaddsubfx-2.5.2/src/UI/guimain.cpp:571:28: error: format not a string literal and no format arguments [-Werror=format-security]/tmp/nix-build-ipxe-20141124-5cbdc41.drv-0/ipxe-5cbdc41/src/arch/i386/firmware/pcbios/bios_console.c:86: undefined reference to `__stack_chk_fail'fcntl2.h:50:4: error: call to '__open_missing_mode' declared with attribute error: open with O_CREAT or O_TMPFILE in second argument needs 3 arguments
+457
-393
doc/submitting-changes.xml
+457
-393
doc/submitting-changes.xml
···-<para>Read <link xlink:href="https://nixos.org/nixpkgs/manual/">Manual (How to write packages for Nix)</link>.</para>-<para>You can make branch from a commit of your local <command>nixos-version</command>. That will help you to avoid additional local compilations. Because you will receive packages from binary cache.-<para>For example: <command>nixos-version</command> returns <command>15.05.git.0998212 (Dingo)</command>. So you can do:</para>-<para>If you removed pkgs, made some major NixOS changes etc., write about them in <command>nixos/doc/manual/release-notes/rl-unstable.xml</command>.</para>-<para>Check for unnecessary whitespace with <command>git diff --check</command> before committing.</para>-<command>nix-build -A pkg-attribute-name <path to your local nixpkgs folder>/default.nix</command> and check results in the folder <command>result</command>. It will appear in the same directory where you did <command>nix-build</command>.</para>-<para>If you did <command>nix-env -i pkg-name</command> you can do <command>nix-env -e pkg-name</command> to uninstall it from your system.</para>-<para>You can add new module to your NixOS configuration file (usually it's <command>/etc/nixos/configuration.nix</command>).-And do <command>sudo nixos-rebuild test -I nixpkgs=<path to your local nixpkgs folder> --fast</command>.</para>-<para>If you have commits <command>pkg-name: oh, forgot to insert whitespace</command>: squash commits in this case. Use <command>git rebase -i</command>.</para>+<title>Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)</title>+<title>Tested compilation of all pkgs that depend on this change using <command>nox-review</command></title>-<para>Write the title in format <command>(pkg-name | nixos/<module>): improvement</command>.-<para>Write in comment if you have tested your patch. Do not rely much on <command>TravisCI</command>.</para>+<title>Tested execution of all binary files (usually in <filename>./result/bin/</filename>)</title>-<para>Notify maintainers of the package. For example add to the message: <command>cc @jagajaga @domenkozar</command>.</para>+xlink:href="https://github.com/NixOS/nixpkgs/blob/master/.github/CONTRIBUTING.md">CONTRIBUTING.md</link>.-following methods to enable sandboxing <emphasis role="bold">before</emphasis> building the package:-<title>Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)</title>-<title>Tested compilation of all pkgs that depend on this change using <command>nox-review</command></title>-<title>Tested execution of all binary files (usually in <filename>./result/bin/</filename>)</title>-xlink:href="https://github.com/NixOS/nixpkgs/blob/master/.github/CONTRIBUTING.md">CONTRIBUTING.md</link>.-<para>Commits must be sufficiently tested before being merged, both for the master and staging branches.</para>-<para>Hydra builds for master and staging should not be used as testing platform, it's a build farm for changes that have been already tested.</para>-<para>When changing the bootloader installation process, extra care must be taken. Grub installations cannot be rolled back, hence changes may break people's installations forever. For any non-trivial change to the bootloader please file a PR asking for review, especially from @edolstra.</para>-<link xlink:href="http://comments.gmane.org/gmane.linux.distributions.nixos/13447">Read policy here</link>.-<link xlink:href="http://hydra.nixos.org/jobset/nixpkgs/staging#tabs-evaluations">Keep an eye on the staging evaluations here</link>.···