diff options
Diffstat (limited to 'doc')
26 files changed, 597 insertions, 64 deletions
diff --git a/doc/.gitignore b/doc/.gitignore index b5c58be03d150..e532ed0eb9c81 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -6,3 +6,5 @@ functions/library/locations.xml highlightjs manual-full.xml out +result +result-* diff --git a/doc/Makefile b/doc/Makefile index 1e54aef9bd122..ee98a3ee92137 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -3,7 +3,7 @@ MD_TARGETS=$(addsuffix .xml, $(basename $(shell find . -type f -regex '.*\.md$$' PANDOC ?= pandoc pandoc_media_dir = media -# NOTE: Keep in sync with NixOS manual (/nixos/doc/manual/md-to-db.sh) and conversion script (/maintainers/scripts/db-to-md.sh). +# NOTE: Keep in sync with conversion script (/maintainers/scripts/db-to-md.sh). # TODO: Remove raw-attribute when we can get rid of DocBook altogether. pandoc_commonmark_enabled_extensions = +attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute # Not needed: diff --git a/doc/build-aux/pandoc-filters/docbook-writer/html-elements.lua b/doc/build-aux/pandoc-filters/docbook-writer/html-elements.lua deleted file mode 100644 index 8f4de40ce5f88..0000000000000 --- a/doc/build-aux/pandoc-filters/docbook-writer/html-elements.lua +++ /dev/null @@ -1,11 +0,0 @@ ---[[ -Converts some HTML elements commonly used in Markdown to corresponding DocBook elements. -]] - -function RawInline(elem) - if elem.format == 'html' and elem.text == '<kbd>' then - return pandoc.RawInline('docbook', '<keycap>') - elseif elem.format == 'html' and elem.text == '</kbd>' then - return pandoc.RawInline('docbook', '</keycap>') - end -end diff --git a/doc/builders/fetchers.chapter.md b/doc/builders/fetchers.chapter.md index 773eb3028ddbe..551df86a58f40 100644 --- a/doc/builders/fetchers.chapter.md +++ b/doc/builders/fetchers.chapter.md @@ -163,3 +163,30 @@ or "hg"), `domain` and `fetchSubmodules`. If `fetchSubmodules` is `true`, `fetchFromSourcehut` uses `fetchgit` or `fetchhg` with `fetchSubmodules` or `fetchSubrepos` set to `true`, respectively. Otherwise, the fetcher uses `fetchzip`. + +## `requireFile` {#requirefile} + +`requireFile` allows requesting files that cannot be fetched automatically, but whose content is known. +This is a useful last-resort workaround for license restrictions that prohibit redistribution, or for downloads that are only accessible after authenticating interactively in a browser. +If the requested file is present in the Nix store, the resulting derivation will not be built, because its expected output is already available. +Otherwise, the builder will run, but fail with a message explaining to the user how to provide the file. The following code, for example: + +``` +requireFile { + name = "jdk-${version}_linux-x64_bin.tar.gz"; + url = "https://www.oracle.com/java/technologies/javase-jdk11-downloads.html"; + sha256 = "94bd34f85ee38d3ef59e5289ec7450b9443b924c55625661fffe66b03f2c8de2"; +} +``` +results in this error message: +``` +*** +Unfortunately, we cannot download file jdk-11.0.10_linux-x64_bin.tar.gz automatically. +Please go to https://www.oracle.com/java/technologies/javase-jdk11-downloads.html to download it yourself, and add it to the Nix store +using either + nix-store --add-fixed sha256 jdk-11.0.10_linux-x64_bin.tar.gz +or + nix-prefetch-url --type sha256 file:///path/to/jdk-11.0.10_linux-x64_bin.tar.gz + +*** +``` diff --git a/doc/builders/images.xml b/doc/builders/images.xml index 7d06130e3eca2..a4661ab5a7af7 100644 --- a/doc/builders/images.xml +++ b/doc/builders/images.xml @@ -11,4 +11,5 @@ <xi:include href="images/snaptools.section.xml" /> <xi:include href="images/portableservice.section.xml" /> <xi:include href="images/makediskimage.section.xml" /> + <xi:include href="images/binarycache.section.xml" /> </chapter> diff --git a/doc/builders/images/binarycache.section.md b/doc/builders/images/binarycache.section.md new file mode 100644 index 0000000000000..fe2772f33b4bb --- /dev/null +++ b/doc/builders/images/binarycache.section.md @@ -0,0 +1,49 @@ +# pkgs.mkBinaryCache {#sec-pkgs-binary-cache} + +`pkgs.mkBinaryCache` is a function for creating Nix flat-file binary caches. Such a cache exists as a directory on disk, and can be used as a Nix substituter by passing `--substituter file:///path/to/cache` to Nix commands. + +Nix packages are most commonly shared between machines using [HTTP, SSH, or S3](https://nixos.org/manual/nix/stable/package-management/sharing-packages.html), but a flat-file binary cache can still be useful in some situations. For example, you can copy it directly to another machine, or make it available on a network file system. It can also be a convenient way to make some Nix packages available inside a container via bind-mounting. + +Note that this function is meant for advanced use-cases. The more idiomatic way to work with flat-file binary caches is via the [nix-copy-closure](https://nixos.org/manual/nix/stable/command-ref/nix-copy-closure.html) command. You may also want to consider [dockerTools](#sec-pkgs-dockerTools) for your containerization needs. + +## Example + +The following derivation will construct a flat-file binary cache containing the closure of `hello`. + +```nix +mkBinaryCache { + rootPaths = [hello]; +} +``` + +- `rootPaths` specifies a list of root derivations. The transitive closure of these derivations' outputs will be copied into the cache. + +Here's an example of building and using the cache. + +Build the cache on one machine, `host1`: + +```shellSession +nix-build -E 'with import <nixpkgs> {}; mkBinaryCache { rootPaths = [hello]; }' +``` + +```shellSession +/nix/store/cc0562q828rnjqjyfj23d5q162gb424g-binary-cache +``` + +Copy the resulting directory to the other machine, `host2`: + +```shellSession +scp result host2:/tmp/hello-cache +``` + +Substitute the derivation using the flat-file binary cache on the other machine, `host2`: +```shellSession +nix-build -A hello '<nixpkgs>' \ + --option require-sigs false \ + --option trusted-substituters file:///tmp/hello-cache \ + --option substituters file:///tmp/hello-cache +``` + +```shellSession +/nix/store/gl5a41azbpsadfkfmbilh9yk40dh5dl0-hello-2.12.1 +``` diff --git a/doc/builders/images/dockertools.section.md b/doc/builders/images/dockertools.section.md index dfc012b80c5a7..2467739a1a5e2 100644 --- a/doc/builders/images/dockertools.section.md +++ b/doc/builders/images/dockertools.section.md @@ -145,7 +145,7 @@ Create a Docker image with many of the store paths being on their own layer to i `architecture` is _optional_ and used to specify the image architecture, this is useful for multi-architecture builds that don't need cross compiling. If not specified it will default to `hostPlatform`. -: Run-time configuration of the container. A full list of the options are available at in the [Docker Image Specification v1.2.0](https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions). +: Run-time configuration of the container. A full list of the options available is in the [Docker Image Specification v1.2.0](https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions). *Default:* `{}` diff --git a/doc/builders/special.xml b/doc/builders/special.xml index 525eb71abfe7e..c971134819818 100644 --- a/doc/builders/special.xml +++ b/doc/builders/special.xml @@ -6,6 +6,7 @@ This chapter describes several special builders. </para> <xi:include href="special/fhs-environments.section.xml" /> + <xi:include href="special/makesetuphook.section.xml" /> <xi:include href="special/mkshell.section.xml" /> <xi:include href="special/darwin-builder.section.xml" /> </chapter> diff --git a/doc/builders/special/makesetuphook.section.md b/doc/builders/special/makesetuphook.section.md new file mode 100644 index 0000000000000..90d75c5491cff --- /dev/null +++ b/doc/builders/special/makesetuphook.section.md @@ -0,0 +1,37 @@ +# pkgs.makeSetupHook {#sec-pkgs.makeSetupHook} + +`pkgs.makeSetupHook` is a builder that produces hooks that go in to `nativeBuildInputs` + +## Usage {#sec-pkgs.makeSetupHook-usage} + +```nix +pkgs.makeSetupHook { + name = "something-hook"; + propagatedBuildInputs = [ pkgs.commandsomething ]; + depsTargetTargetPropagated = [ pkgs.libsomething ]; +} ./script.sh +``` + +#### setup hook that depends on the hello package and runs hello and @shell@ is substituted with path to bash + +```nix +pkgs.makeSetupHook { + name = "run-hello-hook"; + propagatedBuildInputs = [ pkgs.hello ]; + substitutions = { shell = "${pkgs.bash}/bin/bash"; }; + passthru.tests.greeting = callPackage ./test { }; + meta.platforms = lib.platforms.linux; +} (writeScript "run-hello-hook.sh" '' + #!@shell@ + hello +'') +``` + +## Attributes + +* `name` Set the name of the hook. +* `propagatedBuildInputs` Runtime dependencies (such as binaries) of the hook. +* `depsTargetTargetPropagated` Non-binary dependencies. +* `meta` +* `passthru` +* `substitutions` Variables for `substituteAll` diff --git a/doc/builders/testers.chapter.md b/doc/builders/testers.chapter.md index 3d91f096051ee..a0f0f97f9d53f 100644 --- a/doc/builders/testers.chapter.md +++ b/doc/builders/testers.chapter.md @@ -1,6 +1,19 @@ # Testers {#chap-testers} This chapter describes several testing builders which are available in the <literal>testers</literal> namespace. +## `hasPkgConfigModule` {#tester-hasPkgConfigModule} + +Checks whether a package exposes a certain `pkg-config` module. + +Example: + +```nix +passthru.tests.pkg-config = testers.hasPkgConfigModule { + package = finalAttrs.finalPackage; + moduleName = "libfoo"; +} +``` + ## `testVersion` {#tester-testVersion} Checks the command output contains the specified version diff --git a/doc/contributing/coding-conventions.chapter.md b/doc/contributing/coding-conventions.chapter.md index f6a0970165f56..2530b14a2f7be 100644 --- a/doc/contributing/coding-conventions.chapter.md +++ b/doc/contributing/coding-conventions.chapter.md @@ -204,13 +204,13 @@ The key words _must_, _must not_, _required_, _shall_, _shall not_, _should_, _s 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 `pname` attribute of the derivation. 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`. +Most of the time, these are the same. For instance, the package `e2fsprogs` has a `pname` attribute `"e2fsprogs"`, 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: diff --git a/doc/contributing/contributing-to-documentation.chapter.md b/doc/contributing/contributing-to-documentation.chapter.md index 889b4114accaf..a732eee4b9627 100644 --- a/doc/contributing/contributing-to-documentation.chapter.md +++ b/doc/contributing/contributing-to-documentation.chapter.md @@ -27,7 +27,7 @@ If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual. As per [RFC 0072](https://github.com/NixOS/rfcs/pull/72), all new documentation content should be written in [CommonMark](https://commonmark.org/) Markdown dialect. -Additional syntax extensions are available, though not all extensions can be used in NixOS option documentation. The following extensions are currently used: +Additional syntax extensions are available, all of which can be used in NixOS option documentation. The following extensions are currently used: - []{#ssec-contributing-markup-anchors} Explicitly defined **anchors** on headings, to allow linking to sections. These should be always used, to ensure the anchors can be linked even when the heading text changes, and to prevent conflicts between [automatically assigned identifiers](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/auto_identifiers.md). @@ -38,6 +38,10 @@ Additional syntax extensions are available, though not all extensions can be use ## Syntax {#sec-contributing-markup} ``` + ::: {.note} + NixOS option documentation does not support headings in general. + ::: + - []{#ssec-contributing-markup-anchors-inline} **Inline anchors**, which allow linking arbitrary place in the text (e.g. individual list items, sentences…). @@ -67,10 +71,6 @@ Additional syntax extensions are available, though not all extensions can be use This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point). Though, the feature originates from [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage) with slightly different syntax. - ::: {.note} - Inline roles are available for option documentation. - ::: - - []{#ssec-contributing-markup-admonitions} **Admonitions**, set off from the text to bring attention to something. @@ -96,10 +96,6 @@ Additional syntax extensions are available, though not all extensions can be use - [`tip`](https://tdg.docbook.org/tdg/5.0/tip.html) - [`warning`](https://tdg.docbook.org/tdg/5.0/warning.html) - ::: {.note} - Admonitions are available for option documentation. - ::: - - []{#ssec-contributing-markup-definition-lists} [**Definition lists**](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/definition_lists.md), for defining a group of terms: diff --git a/doc/default.nix b/doc/default.nix index 1d5fa4811a369..ac405c3790380 100644 --- a/doc/default.nix +++ b/doc/default.nix @@ -1,6 +1,5 @@ { pkgs ? (import ./.. { }), nixpkgs ? { }}: let - lib = pkgs.lib; doc-support = import ./doc-support { inherit pkgs nixpkgs; }; in pkgs.stdenv.mkDerivation { name = "nixpkgs-manual"; @@ -15,7 +14,7 @@ in pkgs.stdenv.mkDerivation { xmlformat ]; - src = lib.cleanSource ./.; + src = pkgs.nix-gitignore.gitignoreSource [] ./.; postPatch = '' ln -s ${doc-support} ./doc-support/result diff --git a/doc/doc-support/default.nix b/doc/doc-support/default.nix index e9cb96e37fdd5..bea3e12a70b35 100644 --- a/doc/doc-support/default.nix +++ b/doc/doc-support/default.nix @@ -75,7 +75,7 @@ in pkgs.runCommand "doc-support" {} ln -s ${epub-xsl} ./epub.xsl ln -s ${xhtml-xsl} ./xhtml.xsl - ln -s ${../../nixos/doc/xmlformat.conf} ./xmlformat.conf + ln -s ${./xmlformat.conf} ./xmlformat.conf ln -s ${pkgs.documentation-highlighter} ./highlightjs echo -n "${version}" > ./version diff --git a/doc/doc-support/xmlformat.conf b/doc/doc-support/xmlformat.conf new file mode 100644 index 0000000000000..c3f39c7fd81b8 --- /dev/null +++ b/doc/doc-support/xmlformat.conf @@ -0,0 +1,72 @@ +# +# DocBook Configuration file for "xmlformat" +# see http://www.kitebird.com/software/xmlformat/ +# 10 Sept. 2004 +# + +# Only block elements +ackno address appendix article biblioentry bibliography bibliomixed \ +biblioset blockquote book bridgehead callout calloutlist caption caution \ +chapter chapterinfo classsynopsis cmdsynopsis colophon constraintdef \ +constructorsynopsis dedication destructorsynopsis entry epigraph equation example \ +figure formalpara funcsynopsis glossary glossdef glossdiv glossentry glosslist \ +glosssee glossseealso graphic graphicco highlights imageobjectco important \ +index indexdiv indexentry indexinfo info informalequation informalexample \ +informalfigure informaltable legalnotice literallayout lot lotentry mediaobject \ +mediaobjectco msgmain msgset note orderedlist para part preface primaryie \ +procedure qandadiv qandaentry qandaset refentry refentrytitle reference \ +refnamediv refsect1 refsect2 refsect3 refsection revhistory screenshot sect1 \ +sect2 sect3 sect4 sect5 section seglistitem set setindex sidebar simpara \ +simplesect step substeps synopfragment synopsis table term title \ +toc variablelist varlistentry warning itemizedlist listitem \ +footnote colspec partintro row simplelist subtitle tbody tgroup thead tip + format block + normalize no + + +#appendix bibliography chapter glossary preface reference +# element-break 3 + +sect1 section + element-break 2 + + +# +para abstract + format block + entry-break 1 + exit-break 1 + normalize yes + +title + format block + normalize = yes + entry-break = 0 + exit-break = 0 + +# Inline elements +abbrev accel acronym action application citation citebiblioid citerefentry citetitle \ +classname co code command computeroutput constant country database date email emphasis \ +envar errorcode errorname errortext errortype exceptionname fax filename \ +firstname firstterm footnoteref foreignphrase funcdef funcparams function \ +glossterm group guibutton guiicon guilabel guimenu guimenuitem guisubmenu \ +hardware holder honorific indexterm inlineequation inlinegraphic inlinemediaobject \ +interface interfacename \ +keycap keycode keycombo keysym lineage link literal manvolnum markup medialabel \ +menuchoice methodname methodparam modifier mousebutton olink ooclass ooexception \ +oointerface option optional otheraddr othername package paramdef parameter personname \ +phrase pob postcode productname prompt property quote refpurpose replaceable \ +returnvalue revnumber sgmltag state street structfield structname subscript \ +superscript surname symbol systemitem token trademark type ulink userinput \ +uri varargs varname void wordasword xref year mathphrase member tag + format inline + +programlisting screen + format verbatim + entry-break = 0 + exit-break = 0 + +# This is needed so that the spacing inside those tags is kept. +term cmdsynopsis arg + normalize yes + format block diff --git a/doc/hooks/breakpoint.section.md b/doc/hooks/breakpoint.section.md index 41e50653e91df..9600e06b79342 100644 --- a/doc/hooks/breakpoint.section.md +++ b/doc/hooks/breakpoint.section.md @@ -10,9 +10,7 @@ nativeBuildInputs = [ breakpointHook ]; When a build failure happens there will be an instruction printed that shows how to attach with `cntr` to the build sandbox. ::: {.note} -::: {.title} Caution with remote builds -::: This won’t work with remote builds as the build environment is on a different machine and can’t be accessed by `cntr`. Remote builds can be turned off by setting `--option builders ''` for `nix-build` or `--builders ''` for `nix build`. ::: diff --git a/doc/languages-frameworks/android.section.md b/doc/languages-frameworks/android.section.md index 15b8d3839b193..6f9717ca09cca 100644 --- a/doc/languages-frameworks/android.section.md +++ b/doc/languages-frameworks/android.section.md @@ -13,6 +13,7 @@ with import <nixpkgs> {}; let androidComposition = androidenv.composeAndroidPackages { + cmdLineToolsVersion = "8.0"; toolsVersion = "26.1.1"; platformToolsVersion = "30.0.5"; buildToolsVersions = [ "30.0.3" ]; @@ -42,7 +43,10 @@ exceptions are the tools, platform-tools and build-tools sub packages. The following parameters are supported: -* `toolsVersion`, specifies the version of the tools package to use +* `cmdLineToolsVersion `, specifies the version of the `cmdline-tools` package to use +* `toolsVersion`, specifies the version of the `tools` package. Notice `tools` is + obsolete, and currently only `26.1.1` is available, so there's not a lot of + options here, however, you can set it as `null` if you don't want it. * `platformsToolsVersion` specifies the version of the `platform-tools` plugin * `buildToolsVersions` specifies the versions of the `build-tools` plugins to use. diff --git a/doc/languages-frameworks/beam.section.md b/doc/languages-frameworks/beam.section.md index 6b3a369c291ff..707da43e9dd73 100644 --- a/doc/languages-frameworks/beam.section.md +++ b/doc/languages-frameworks/beam.section.md @@ -171,6 +171,7 @@ let inherit src version; # nix will complain and tell you the right value to replace this with hash = lib.fakeHash; + mixEnv = ""; # default is "prod", when empty includes all dependencies, such as "dev", "test". # if you have build time environment variables add them here MY_ENV_VAR="my_value"; }; diff --git a/doc/languages-frameworks/emscripten.section.md b/doc/languages-frameworks/emscripten.section.md index ff622cfb0b501..5f93dd5ff3159 100644 --- a/doc/languages-frameworks/emscripten.section.md +++ b/doc/languages-frameworks/emscripten.section.md @@ -56,11 +56,11 @@ See the `zlib` example: zlib = (pkgs.zlib.override { stdenv = pkgs.emscriptenStdenv; - }).overrideDerivation + }).overrideAttrs (old: rec { buildInputs = old.buildInputs ++ [ pkg-config ]; # we need to reset this setting! - NIX_CFLAGS_COMPILE=""; + env = (old.env or { }) // { NIX_CFLAGS_COMPILE = ""; }; configurePhase = '' # FIXME: Some tests require writing at $HOME HOME=$TMPDIR diff --git a/doc/languages-frameworks/haskell.section.md b/doc/languages-frameworks/haskell.section.md index f0b302bbc356f..c6d85a240a900 100644 --- a/doc/languages-frameworks/haskell.section.md +++ b/doc/languages-frameworks/haskell.section.md @@ -137,7 +137,12 @@ set the default version to a version older than the newest on Hackage. We do this to get them or their reverse dependencies to compile in our package set. 4. For all packages, for which the newest Hackage version is not the default version, there will also be a `haskellPackages.foo_x_y_z` package with the -newest version. +newest version. The `x_y_z` part encodes the version with dots replaced by +underscores. When the newest version changes by a new release to Hackage the +old package will disappear under that name and be replaced by a newer one under +the name with the new version. The package name including the version will +also disappear when the default version e.g. from Stackage catches up with the +newest version from Hackage. 5. For some packages, we also manually add other `haskellPackages.foo_x_y_z` versions, if they are required for a certain build. @@ -161,12 +166,14 @@ given in the `.cabal` file of your package and all its dependencies. The [Haskell builder in nixpkgs](#haskell-mkderivation) does no such thing. It will simply take as input packages with names off the desired dependencies -and just check whether they fulfill the version bounds and (by default, see -`jailbreak`) fail if they don’t. - -The package resolution is done by the `haskellPackages.callPackage` function -which will, e.g., use `haskellPackages.aeson` for a package input of name -`aeson`. +and just check whether they fulfill the version bounds and fail if they don’t +(by default, see `jailbreak` to circumvent this). + +The `haskellPackages.callPackage` function does the package resolution. +It will, e.g., use `haskellPackages.aeson`which has the default version as +described above for a package input of name `aeson`. (More general: +`<packages>.callPackage f` will call `f` with named inputs provided from the +package set `<packages>`.) While this is the default behavior, it is possible to override the dependencies for a specific package, see [`override` and `overrideScope`](#haskell-overriding-haskell-packages). @@ -195,7 +202,7 @@ maintenance work for `haskellPackages` is required. Besides that, it is not possible to get the dependencies of a legacy project from nixpkgs or to use a specific stack solver for compiling a project. -Even though we couldn‘t use them directly in nixpkgs, it would be desirable +Even though we couldn’t use them directly in nixpkgs, it would be desirable to have tooling to generate working Nix package sets from build plans generated by `cabal-install` or a specific Stackage snapshot via import-from-derivation. Sadly we currently don’t have tooling for this. For this you might be @@ -538,7 +545,7 @@ via [`shellFor`](#haskell-shellFor). When using `cabal-install` for dependency resolution you need to be a bit careful to achieve build purity. `cabal-install` will find and use all dependencies installed from the packages `env` via Nix, but it will also -consult Hackage to potentially download and compile dependencies if it can‘t +consult Hackage to potentially download and compile dependencies if it can’t find a valid build plan locally. To prevent this you can either never run `cabal update`, remove the cabal database from your `~/.cabal` folder or run `cabal` with `--offline`. Note though, that for some usecases `cabal2nix` needs diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml index 7d404643d3693..f089b99a0451b 100644 --- a/doc/languages-frameworks/index.xml +++ b/doc/languages-frameworks/index.xml @@ -32,11 +32,13 @@ <xi:include href="octave.section.xml" /> <xi:include href="perl.section.xml" /> <xi:include href="php.section.xml" /> + <xi:include href="pkg-config.section.xml" /> <xi:include href="python.section.xml" /> <xi:include href="qt.section.xml" /> <xi:include href="r.section.xml" /> <xi:include href="ruby.section.xml" /> <xi:include href="rust.section.xml" /> + <xi:include href="swift.section.xml" /> <xi:include href="texlive.section.xml" /> <xi:include href="titanium.section.xml" /> <xi:include href="vim.section.xml" /> diff --git a/doc/languages-frameworks/ocaml.section.md b/doc/languages-frameworks/ocaml.section.md index 347b2ea2ecabe..1e5a5cb4536fb 100644 --- a/doc/languages-frameworks/ocaml.section.md +++ b/doc/languages-frameworks/ocaml.section.md @@ -129,3 +129,8 @@ packaged libraries may still use the old spelling: maintainers are invited to fix this when updating packages. Massive renaming is strongly discouraged as it would be challenging to review, difficult to test, and will cause unnecessary rebuild. + +The build will automatically fail if two distinct versions of the same library +are added to `buildInputs` (which usually happens transitively because of +`propagatedBuildInputs`). Set `dontDetectOcamlConflicts` to true to disable this +behavior. diff --git a/doc/languages-frameworks/pkg-config.section.md b/doc/languages-frameworks/pkg-config.section.md new file mode 100644 index 0000000000000..fb6fee997d6f2 --- /dev/null +++ b/doc/languages-frameworks/pkg-config.section.md @@ -0,0 +1,51 @@ +# pkg-config {#sec-pkg-config} + +*pkg-config* is a unified interface for declaring and querying built C/C++ libraries. + +Nixpkgs provides a couple of facilities for working with this tool. + +## Writing packages providing pkg-config modules + +Packages should set `meta.pkgConfigModules` with the list of package config modules they provide. +They should also use `testers.testMetaPkgConfig` to check that the final built package matches that list. +Additionally, the [`validatePkgConfig` setup hook](https://nixos.org/manual/nixpkgs/stable/#validatepkgconfig), will do extra checks on to-be-installed pkg-config modules. + +A good example of all these things is zlib: + +``` +{ pkg-config, testers, ... }: + +stdenv.mkDerivation (finalAttrs: { + ... + + nativeBuildInputs = [ pkg-config validatePkgConfig ]; + + passthru.tests.pkg-config = testers.testMetaPkgConfig finalAttrs.finalPackage; + + meta = { + ... + pkgConfigModules = [ "zlib" ]; + }; +}) +``` + +## Accessing packages via pkg-config module name + +### Within Nixpkgs + +A [setup hook](#setup-hook-pkg-config) is bundled in the `pkg-config` package to bring a derivation's declared build inputs into the environment. +This will populate environment variables like `PKG_CONFIG_PATH`, `PKG_CONFIG_PATH_FOR_BUILD`, and `PKG_CONFIG_PATH_HOST` based on: + + - how `pkg-config` itself is depended upon + + - how other dependencies are depended upon + +For more details see the section on [specifying dependencies in general](#ssec-stdenv-dependencies). + +Normal pkg-config commands to look up dependencies by name will then work with those environment variables defined by the hook. + +### Externally + +The `defaultPkgConfigPackages` package set is a set of aliases, named after the modules they provide. +This is meant to be used by language-to-nix integrations. +Hand-written packages should use the normal Nixpkgs attribute name instead. diff --git a/doc/languages-frameworks/python.section.md b/doc/languages-frameworks/python.section.md index 7b8a804106af7..a65cea533bc05 100644 --- a/doc/languages-frameworks/python.section.md +++ b/doc/languages-frameworks/python.section.md @@ -58,7 +58,7 @@ with a nix-shell that has `numpy` and `toolz` in Python 3.9; then we will create a re-usable environment in a single-file Python script; then we will create a full Python environment for development with this same environment. -Philosphically, this should be familiar to users who are used to a `venv` style +Philosophically, this should be familiar to users who are used to a `venv` style of development: individual projects create their own Python environments without impacting the global environment or each other. @@ -744,17 +744,17 @@ work in any of the formats supported by `buildPythonPackage` currently, with the exception of `other` (see `format` in [`buildPythonPackage` parameters](#buildpythonpackage-parameters) for more details). -### Using unittestCheckHook {#using-unittestcheckhook} +#### Using unittestCheckHook {#using-unittestcheckhook} `unittestCheckHook` is a hook which will substitute the setuptools `test` command for a `checkPhase` which runs `python -m unittest discover`: ``` nativeCheckInputs = [ unittestCheckHook ]; - unittestFlags = [ "-s" "tests" "-v" ]; + unittestFlagsArray = [ "-s" "tests" "-v" ]; ``` -##### Using sphinxHook {#using-sphinxhook} +#### Using sphinxHook {#using-sphinxhook} The `sphinxHook` is a helpful tool to build documentation and manpages using the popular Sphinx documentation generator. @@ -1019,7 +1019,7 @@ buildPythonPackage rec { The `buildPythonPackage` mainly does four things: -* In the `buildPhase`, it calls `${python.interpreter} setup.py bdist_wheel` to +* In the `buildPhase`, it calls `${python.pythonForBuild.interpreter} setup.py bdist_wheel` to build a wheel binary zipfile. * In the `installPhase`, it installs the wheel file using `pip install *.whl`. * In the `postFixup` phase, the `wrapPythonPrograms` bash function is called to @@ -1546,7 +1546,7 @@ of such package using the feature is `pkgs/tools/X11/xpra/default.nix`. As workaround install it as an extra `preInstall` step: ```shell -${python.interpreter} setup.py install_data --install-dir=$out --root=$out +${python.pythonForBuild.interpreter} setup.py install_data --install-dir=$out --root=$out sed -i '/ = data\_files/d' setup.py ``` @@ -1821,6 +1821,11 @@ hosted on GitHub, exporting a `GITHUB_API_TOKEN` is highly recommended. Updating packages in bulk leads to lots of breakages, which is why a stabilization period on the `python-unstable` branch is required. +If a package is fragile and often breaks during these bulks updates, it +may be reasonable to set `passthru.skipBulkUpdate = true` in the +derivation. This decision should not be made on a whim and should +always be supported by a qualifying comment. + Once the branch is sufficiently stable it should normally be merged into the `staging` branch. diff --git a/doc/languages-frameworks/swift.section.md b/doc/languages-frameworks/swift.section.md new file mode 100644 index 0000000000000..1cc452cc9b9bf --- /dev/null +++ b/doc/languages-frameworks/swift.section.md @@ -0,0 +1,176 @@ +# Swift {#swift} + +The Swift compiler is provided by the `swift` package: + +```sh +# Compile and link a simple executable. +nix-shell -p swift --run 'swiftc -' <<< 'print("Hello world!")' +# Run it! +./main +``` + +The `swift` package also provides the `swift` command, with some caveats: + +- Swift Package Manager (SwiftPM) is packaged separately as `swiftpm`. If you + need functionality like `swift build`, `swift run`, `swift test`, you must + also add the `swiftpm` package to your closure. +- On Darwin, the `swift repl` command requires an Xcode installation. This is + because it uses the system LLDB debugserver, which has special entitlements. + +## Module search paths {#ssec-swift-module-search-paths} + +Like other toolchains in Nixpkgs, the Swift compiler executables are wrapped +to help Swift find your application's dependencies in the Nix store. These +wrappers scan the `buildInputs` of your package derivation for specific +directories where Swift modules are placed by convention, and automatically +add those directories to the Swift compiler search paths. + +Swift follows different conventions depending on the platform. The wrappers +look for the following directories: + +- On Darwin platforms: `lib/swift/macosx` + (If not targeting macOS, replace `macosx` with the Xcode platform name.) +- On other platforms: `lib/swift/linux/x86_64` + (Where `linux` and `x86_64` are from lowercase `uname -sm`.) +- For convenience, Nixpkgs also adds simply `lib/swift` to the search path. + This can save a bit of work packaging Swift modules, because many Nix builds + will produce output for just one target any way. + +## Core libraries {#ssec-swift-core-libraries} + +In addition to the standard library, the Swift toolchain contains some +additional 'core libraries' that, on Apple platforms, are normally distributed +as part of the OS or Xcode. These are packaged separately in Nixpkgs, and can +be found (for use in `buildInputs`) as: + +- `swiftPackages.Dispatch` +- `swiftPackages.Foundation` +- `swiftPackages.XCTest` + +## Packaging with SwiftPM {#ssec-swift-packaging-with-swiftpm} + +Nixpkgs includes a small helper `swiftpm2nix` that can fetch your SwiftPM +dependencies for you, when you need to write a Nix expression to package your +application. + +The first step is to run the generator: + +```sh +cd /path/to/my/project +# Enter a Nix shell with the required tools. +nix-shell -p swift swiftpm swiftpm2nix +# First, make sure the workspace is up-to-date. +swift package resolve +# Now generate the Nix code. +swiftpm2nix +``` + +This produces some files in a directory `nix`, which will be part of your Nix +expression. The next step is to write that expression: + +```nix +{ stdenv, swift, swiftpm, swiftpm2nix, fetchFromGitHub }: + +let + # Pass the generated files to the helper. + generated = swiftpm2nix.helpers ./nix; +in + +stdenv.mkDerivation rec { + pname = "myproject"; + version = "0.0.0"; + + src = fetchFromGitHub { + owner = "nixos"; + repo = pname; + rev = version; + hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="; + }; + + # Including SwiftPM as a nativeBuildInput provides a buildPhase for you. + # This by default performs a release build using SwiftPM, essentially: + # swift build -c release + nativeBuildInputs = [ swift swiftpm ]; + + # The helper provides a configure snippet that will prepare all dependencies + # in the correct place, where SwiftPM expects them. + configurePhase = generated.configure; + + installPhase = '' + # This is a special function that invokes swiftpm to find the location + # of the binaries it produced. + binPath="$(swiftpmBinPath)" + # Now perform any installation steps. + mkdir -p $out/bin + cp $binPath/myproject $out/bin/ + ''; +} +``` + +### Custom build flags {#ssec-swiftpm-custom-build-flags} + +If you'd like to build a different configuration than `release`: + +```nix +swiftpmBuildConfig = "debug"; +``` + +It is also possible to provide additional flags to `swift build`: + +```nix +swiftpmFlags = [ "--disable-dead-strip" ]; +``` + +The default `buildPhase` already passes `-j` for parallel building. + +If these two customization options are insufficient, simply provide your own +`buildPhase` that invokes `swift build`. + +### Running tests {#ssec-swiftpm-running-tests} + +Including `swiftpm` in your `nativeBuildInputs` also provides a default +`checkPhase`, but it must be enabled with: + +```nix +doCheck = true; +``` + +This essentially runs: `swift test -c release` + +### Patching dependencies {#ssec-swiftpm-patching-dependencies} + +In some cases, it may be necessary to patch a SwiftPM dependency. SwiftPM +dependencies are located in `.build/checkouts`, but the `swiftpm2nix` helper +provides these as symlinks to read-only `/nix/store` paths. In order to patch +them, we need to make them writable. + +A special function `swiftpmMakeMutable` is available to replace the symlink +with a writable copy: + +``` +configurePhase = generated.configure ++ '' + # Replace the dependency symlink with a writable copy. + swiftpmMakeMutable swift-crypto + # Now apply a patch. + patch -p1 -d .build/checkouts/swift-crypto -i ${./some-fix.patch} +''; +``` + +## Considerations for custom build tools {#ssec-swift-considerations-for-custom-build-tools} + +### Linking the standard library {#ssec-swift-linking-the-standard-library} + +The `swift` package has a separate `lib` output containing just the Swift +standard library, to prevent Swift applications needing a dependency on the +full Swift compiler at run-time. Linking with the Nixpkgs Swift toolchain +already ensures binaries correctly reference the `lib` output. + +Sometimes, Swift is used only to compile part of a mixed codebase, and the +link step is manual. Custom build tools often locate the standard library +relative to the `swift` compiler executable, and while the result will work, +when this path ends up in the binary, it will have the Swift compiler as an +unintended dependency. + +In this case, you should investigate how your build process discovers the +standard library, and override the path. The correct path will be something +like: `"${swift.swift.lib}/${swift.swiftModuleSubdir}"` diff --git a/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md index e66cc3476776b..b3f9f681da4c6 100644 --- a/doc/stdenv/stdenv.chapter.md +++ b/doc/stdenv/stdenv.chapter.md @@ -95,6 +95,27 @@ installPhase() { genericBuild ``` +### Building a `stdenv` package in `nix-shell` {#sec-building-stdenv-package-in-nix-shell} + +To build a `stdenv` package in a [`nix-shell`](https://nixos.org/manual/nix/unstable/command-ref/nix-shell.html), use + +```bash +nix-shell '<nixpkgs>' -A some_package +eval ${unpackPhase:-unpackPhase} +cd $sourceRoot +eval ${patchPhase:-patchPhase} +eval ${configurePhase:-configurePhase} +eval ${buildPhase:-buildPhase} +``` + +To modify a [phase](#sec-stdenv-phases), first print it with + +```bash +type buildPhase +``` + +then change it in a text editor, and paste it back to the terminal. + ## Tools provided by `stdenv` {#sec-tools-of-stdenv} The standard environment provides the following packages: @@ -116,6 +137,82 @@ On Linux, `stdenv` also includes the `patchelf` utility. ## Specifying dependencies {#ssec-stdenv-dependencies} +Build systems often require more dependencies than just what `stdenv` provides. This section describes attributes accepted by `stdenv.mkDerivation` that can be used to make these dependencies available to the build system. + +### Overview {#ssec-stdenv-dependencies-overview} + +A full reference of the different kinds of dependencies is provided in [](#ssec-stdenv-dependencies-reference), but here is an overview of the most common ones. +It should cover most use cases. + +Add dependencies to `nativeBuildInputs` if they are executed during the build: +- those which are needed on `$PATH` during the build, for example `cmake` and `pkg-config` +- [setup hooks](#ssec-setup-hooks), for example [`makeWrapper`](#fun-makeWrapper) +- interpreters needed by [`patchShebangs`](#patch-shebangs.sh) for build scripts (with the `--build` flag), which can be the case for e.g. `perl` + +Add dependencies to `buildInputs` if they will end up copied or linked into the final output or otherwise used at runtime: +- libraries used by compilers, for example `zlib`, +- interpreters needed by [`patchShebangs`](#patch-shebangs.sh) for scripts which are installed, which can be the case for e.g. `perl` + +::: {.note} +These criteria are independent. + +For example, software using Wayland usually needs the `wayland` library at runtime, so `wayland` should be added to `buildInputs`. +But it also executes the `wayland-scanner` program as part of the build to generate code, so `wayland` should also be added to `nativeBuildInputs`. +::: + +Dependencies needed only to run tests are similarly classified between native (executed during build) and non-native (executed at runtime): +- `nativeCheckInputs` for test tools needed on `$PATH` (such as `ctest`) and [setup hooks](#ssec-setup-hooks) (for example [`pytestCheckHook`](#python)) +- `checkInputs` for libraries linked into test executables (for example the `qcheck` OCaml package) + +These dependencies are only injected when [`doCheck`](#var-stdenv-doCheck) is set to `true`. + +#### Example {#ssec-stdenv-dependencies-overview-example} + +Consider for example this simplified derivation for `solo5`, a sandboxing tool: +```nix +stdenv.mkDerivation rec { + pname = "solo5"; + version = "0.7.5"; + + src = fetchurl { + url = "https://github.com/Solo5/solo5/releases/download/v${version}/solo5-v${version}.tar.gz"; + sha256 = "sha256-viwrS9lnaU8sTGuzK/+L/PlMM/xRRtgVuK5pixVeDEw="; + }; + + nativeBuildInputs = [ makeWrapper pkg-config ]; + buildInputs = [ libseccomp ]; + + postInstall = '' + substituteInPlace $out/bin/solo5-virtio-mkimage \ + --replace "/usr/lib/syslinux" "${syslinux}/share/syslinux" \ + --replace "/usr/share/syslinux" "${syslinux}/share/syslinux" \ + --replace "cp " "cp --no-preserve=mode " + + wrapProgram $out/bin/solo5-virtio-mkimage \ + --prefix PATH : ${lib.makeBinPath [ dosfstools mtools parted syslinux ]} + ''; + + doCheck = true; + nativeCheckInputs = [ util-linux qemu ]; + checkPhase = '' [elided] ''; +} +``` + +- `makeWrapper` is a setup hook, i.e., a shell script sourced by the generic builder of `stdenv`. + It is thus executed during the build and must be added to `nativeBuildInputs`. +- `pkg-config` is a build tool which the configure script of `solo5` expects to be on `$PATH` during the build: + therefore, it must be added to `nativeBuildInputs`. +- `libseccomp` is a library linked into `$out/bin/solo5-elftool`. + As it is used at runtime, it must be added to `buildInputs`. +- Tests need `qemu` and `getopt` (from `util-linux`) on `$PATH`, these must be added to `nativeCheckInputs`. +- Some dependencies are injected directly in the shell code of phases: `syslinux`, `dosfstools`, `mtools`, and `parted`. +In this specific case, they will end up in the output of the derivation (`$out` here). +As Nix marks dependencies whose absolute path is present in the output as runtime dependencies, adding them to `buildInputs` is not required. + +For more complex cases, like libraries linked into an executable which is then executed as part of the build system, see [](#ssec-stdenv-dependencies-reference). + +### Reference {#ssec-stdenv-dependencies-reference} + As described in the Nix manual, almost any `*.drv` store path in a derivation’s attribute set will induce a dependency on that derivation. `mkDerivation`, however, takes a few attributes intended to 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 `PATH`. That is built-in, but other setup is done via a pluggable mechanism that works in conjunction with these dependency attributes. See [](#ssec-setup-hooks) for details. 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 [](#chap-cross) for exactly what each platform means. [^footnote-stdenv-ignored-build-platform] 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. By default, the run-time/build-time distinction is just a hint for mental clarity, but with `strictDeps` set it is mostly enforced even in the native case. @@ -187,21 +284,21 @@ Because of the bounds checks, the uncommon cases are `h = t` and `h + 2 = t`. In Overall, the unifying theme here is that propagation shouldn’t be introducing transitive dependencies involving platforms the depending package is unaware of. \[One can imagine the dependending package asking for dependencies with the platforms it knows about; other platforms it doesn’t know how to ask for. The platform description in that scenario is a kind of unforagable capability.\] The offset bounds checking and definition of `mapOffset` 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. -### Variables specifying dependencies {#variables-specifying-dependencies} +#### Variables specifying dependencies {#variables-specifying-dependencies} -#### `depsBuildBuild` {#var-stdenv-depsBuildBuild} +##### `depsBuildBuild` {#var-stdenv-depsBuildBuild} A list of dependencies whose host and target platforms are the new derivation’s build platform. These are programs and libraries used at build time that produce programs and 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 `nativeBuildInputs` instead. The most common use of this `buildPackages.stdenv.cc`, the default C compiler for this role. That example crops up more than one might think in old commonly used C libraries. Since these packages are able to be run at build-time, they are always added to the `PATH`, as described above. But since these packages are only guaranteed to be able to run then, they shouldn’t persist as run-time dependencies. This isn’t currently enforced, but could be in the future. -#### `nativeBuildInputs` {#var-stdenv-nativeBuildInputs} +##### `nativeBuildInputs` {#var-stdenv-nativeBuildInputs} A list of dependencies whose host platform is the new derivation’s build platform, and target platform is the new derivation’s host platform. These are programs and 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 `depsBuildBuild` or `depsBuildTarget`. This could be called `depsBuildHost` but `nativeBuildInputs` is used for historical continuity. Since these packages are able to be run at build-time, they are added to the `PATH`, as described above. But since these packages are only guaranteed to be able to run then, they shouldn’t persist as run-time dependencies. This isn’t currently enforced, but could be in the future. -#### `depsBuildTarget` {#var-stdenv-depsBuildTarget} +##### `depsBuildTarget` {#var-stdenv-depsBuildTarget} A list of dependencies whose host platform is the new derivation’s build platform, and target platform is the new derivation’s target platform. These are programs used at build time that produce code to run with code produced by the depending package. Most commonly, these are tools used to build the runtime or standard library that 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 that the dependency is unconditional. @@ -209,41 +306,41 @@ This is a somewhat confusing concept to wrap one’s head around, and for good r Since these packages are able to run at build time, they are added to the `PATH`, as described above. But since these packages are only guaranteed to be able to run then, they shouldn’t persist as run-time dependencies. This isn’t currently enforced, but could be in the future. -#### `depsHostHost` {#var-stdenv-depsHostHost} +##### `depsHostHost` {#var-stdenv-depsHostHost} A list of dependencies whose host and target platforms match the new derivation’s host platform. In practice, this would usually be tools used by compilers for macros or a metaprogramming system, or libraries used by the macros or metaprogramming code itself. It’s always preferable to use a `depsBuildBuild` dependency in the derivation being built over a `depsHostHost` on the tool doing the building for this purpose. -#### `buildInputs` {#var-stdenv-buildInputs} +##### `buildInputs` {#var-stdenv-buildInputs} A list of dependencies whose host platform and target platform match the new derivation’s. This would be called `depsHostTarget` but for historical continuity. 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 `depsBuildBuild`. These are often programs and libraries used by the new derivation at *run*-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. Even in the dynamic case, the library may also be needed at build-time to appease the linker. -#### `depsTargetTarget` {#var-stdenv-depsTargetTarget} +##### `depsTargetTarget` {#var-stdenv-depsTargetTarget} A list of dependencies whose host platform matches the new derivation’s target platform. 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\]. Do not use this attribute unless you are packaging a compiler and are sure it is needed. -#### `depsBuildBuildPropagated` {#var-stdenv-depsBuildBuildPropagated} +##### `depsBuildBuildPropagated` {#var-stdenv-depsBuildBuildPropagated} The propagated equivalent of `depsBuildBuild`. This perhaps never ought to be used, but it is included for consistency \[see below for the others\]. -#### `propagatedNativeBuildInputs` {#var-stdenv-propagatedNativeBuildInputs} +##### `propagatedNativeBuildInputs` {#var-stdenv-propagatedNativeBuildInputs} The propagated equivalent of `nativeBuildInputs`. This would be called `depsBuildHostPropagated` but for historical continuity. For example, if package `Y` has `propagatedNativeBuildInputs = [X]`, and package `Z` has `buildInputs = [Y]`, then package `Z` will be built as if it included package `X` in its `nativeBuildInputs`. If instead, package `Z` has `nativeBuildInputs = [Y]`, then `Z` will be built as if it included `X` in the `depsBuildBuild` of package `Z`, because of the sum of the two `-1` host offsets. -#### `depsBuildTargetPropagated` {#var-stdenv-depsBuildTargetPropagated} +##### `depsBuildTargetPropagated` {#var-stdenv-depsBuildTargetPropagated} The propagated equivalent of `depsBuildTarget`. This is prefixed for the same reason of alerting potential users. -#### `depsHostHostPropagated` {#var-stdenv-depsHostHostPropagated} +##### `depsHostHostPropagated` {#var-stdenv-depsHostHostPropagated} The propagated equivalent of `depsHostHost`. -#### `propagatedBuildInputs` {#var-stdenv-propagatedBuildInputs} +##### `propagatedBuildInputs` {#var-stdenv-propagatedBuildInputs} The propagated equivalent of `buildInputs`. This would be called `depsHostTargetPropagated` but for historical continuity. -#### `depsTargetTargetPropagated` {#var-stdenv-depsTargetTargetPropagated} +##### `depsTargetTargetPropagated` {#var-stdenv-depsTargetTargetPropagated} The propagated equivalent of `depsTargetTarget`. This is prefixed for the same reason of alerting potential users. @@ -253,7 +350,7 @@ The propagated equivalent of `depsTargetTarget`. This is prefixed for the same r #### `NIX_DEBUG` {#var-stdenv-NIX_DEBUG} -A natural number indicating how much information to log. If set to 1 or higher, `stdenv` will print moderate debugging information during the build. In particular, the `gcc` and `ld` wrapper scripts will print out the complete command line passed to the wrapped tools. If set to 6 or higher, the `stdenv` setup script will be run with `set -x` tracing. If set to 7 or higher, the `gcc` and `ld` wrapper scripts will also be run with `set -x` tracing. +A number between 0 and 7 indicating how much information to log. If set to 1 or higher, `stdenv` will print moderate debugging information during the build. In particular, the `gcc` and `ld` wrapper scripts will print out the complete command line passed to the wrapped tools. If set to 6 or higher, the `stdenv` setup script will be run with `set -x` tracing. If set to 7 or higher, the `gcc` and `ld` wrapper scripts will also be run with `set -x` tracing. ### Attributes affecting build properties {#attributes-affecting-build-properties} @@ -626,7 +723,7 @@ Before and after running `make`, the hooks `preBuild` and `postBuild` are called ### The check phase {#ssec-check-phase} -The check phase checks whether the package was built correctly by running its test suite. The default `checkPhase` calls `make check`, but only if the `doCheck` variable is enabled. +The check phase checks whether the package was built correctly by running its test suite. The default `checkPhase` calls `make $checkTarget`, but only if the [`doCheck` variable](#var-stdenv-doCheck) is enabled. #### Variables controlling the check phase {#variables-controlling-the-check-phase} @@ -646,7 +743,8 @@ See the [build phase](#var-stdenv-makeFlags) for details. ##### `checkTarget` {#var-stdenv-checkTarget} -The make target that runs the tests. Defaults to `check`. +The `make` target that runs the tests. +If unset, use `check` if it exists, otherwise `test`; if neither is found, do nothing. ##### `checkFlags` / `checkFlagsArray` {#var-stdenv-checkFlags} @@ -1231,7 +1329,7 @@ bin/blib.a(bios_console.o): In function `bios_handle_cup': Adds the `-O2 -D_FORTIFY_SOURCE=2` compiler options. During code generation the compiler knows a great deal of information about buffer sizes (where possible), and attempts to replace insecure unlimited length buffer function calls with length-limited ones. This is especially useful for old, crufty code. Additionally, format strings in writable memory that contain `%n` are blocked. If an application depends on such a format string, it will need to be worked around. -Additionally, some warnings are enabled which might trigger build failures if compiler warnings are treated as errors in the package build. In this case, set `NIX_CFLAGS_COMPILE` to `-Wno-error=warning-type`. +Additionally, some warnings are enabled which might trigger build failures if compiler warnings are treated as errors in the package build. In this case, set `env.NIX_CFLAGS_COMPILE` to `-Wno-error=warning-type`. This needs to be turned off or fixed for errors similar to: |