diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/functions.xml | 33 | ||||
| -rw-r--r-- | doc/languages-frameworks/haskell.section.md | 13 | ||||
| -rw-r--r-- | doc/languages-frameworks/java.xml | 23 | ||||
| -rw-r--r-- | doc/languages-frameworks/python.section.md | 15 | ||||
| -rw-r--r-- | doc/languages-frameworks/rust.section.md | 5 | ||||
| -rw-r--r-- | doc/old/cross.txt | 2 | ||||
| -rw-r--r-- | doc/package-notes.xml | 58 | ||||
| -rw-r--r-- | doc/platform-notes.xml | 30 | ||||
| -rw-r--r-- | doc/quick-start.xml | 2 | ||||
| -rw-r--r-- | doc/reviewing-contributions.xml | 48 | ||||
| -rw-r--r-- | doc/stdenv.xml | 7 |
11 files changed, 186 insertions, 50 deletions
diff --git a/doc/functions.xml b/doc/functions.xml index 2a9cc44d5c5b..ec188e234543 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -1,5 +1,6 @@ <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="chap-functions"> <title>Functions reference</title> <para> @@ -444,6 +445,7 @@ merge:"diff3" <filename>./bin/start.sh</filename> -- relative paths are supported. </para> </section> + <xi:include href="shell.section.xml" /> <section xml:id="sec-pkgs-dockerTools"> <title>pkgs.dockerTools</title> @@ -521,7 +523,8 @@ merge:"diff3" <callout arearefs='ex-dockerTools-buildImage-2'> <para> <varname>tag</varname> specifies the tag of the resulting image. By - default it's <literal>null</literal>, which indicates that the nix output hash will be used as tag. + default it's <literal>null</literal>, which indicates that the nix output + hash will be used as tag. </para> </callout> <callout arearefs='ex-dockerTools-buildImage-3'> @@ -667,12 +670,12 @@ merge:"diff3" <para> <varname>imageDigest</varname> specifies the digest of the image to be downloaded. Skopeo can be used to get the digest of an image, with its - <varname>inspect</varname> subcommand. Since a given <varname>imageName</varname> - may transparently refer to a manifest list of images which support - multiple architectures and/or operating systems, supply the `--override-os` - and `--override-arch` arguments to specify exactly which image you - want. By default it will match the OS and architecture of the host the - command is run on. + <varname>inspect</varname> subcommand. Since a given + <varname>imageName</varname> may transparently refer to a manifest list + of images which support multiple architectures and/or operating systems, + supply the `--override-os` and `--override-arch` arguments to specify + exactly which image you want. By default it will match the OS and + architecture of the host the command is run on. <programlisting> $ nix-shell --packages skopeo jq --command "skopeo --override-os linux --override-arch x86_64 inspect docker://docker.io/nixos/nix:1.11 | jq -r '.Digest'" sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b @@ -695,16 +698,16 @@ merge:"diff3" </para> </callout> <callout arearefs='ex-dockerTools-pullImage-5'> - <para> - <varname>os</varname>, if specified, is the operating system of the fetched image. - By default it's <literal>linux</literal>. - </para> + <para> + <varname>os</varname>, if specified, is the operating system of the + fetched image. By default it's <literal>linux</literal>. + </para> </callout> <callout arearefs='ex-dockerTools-pullImage-6'> - <para> - <varname>arch</varname>, if specified, is the cpu architecture of the fetched image. - By default it's <literal>x86_64</literal>. - </para> + <para> + <varname>arch</varname>, if specified, is the cpu architecture of the + fetched image. By default it's <literal>x86_64</literal>. + </para> </callout> </calloutlist> </section> diff --git a/doc/languages-frameworks/haskell.section.md b/doc/languages-frameworks/haskell.section.md index c0dc741eabca..7677c366191f 100644 --- a/doc/languages-frameworks/haskell.section.md +++ b/doc/languages-frameworks/haskell.section.md @@ -1047,6 +1047,19 @@ As you can see, `packunused` finds out that although the testsuite component has no redundant dependencies the library component of `scientific-0.3.5.1` depends on `ghc-prim` which is unused in the library. +### Using hackage2nix with nixpkgs + +Hackage package derivations are found in the +[`hackage-packages.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/haskell-modules/hackage-packages.nix) +file within `nixpkgs` and are used as the initial package set for +`haskellPackages`. The `hackage-packages.nix` file is not meant to be edited +by hand, but rather autogenerated by [`hackage2nix`](https://github.com/NixOS/cabal2nix/tree/master/hackage2nix), +which by default uses the [`configuration-hackage2nix.yaml`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/haskell-modules/configuration-hackage2nix.yaml) +file to generate all the derivations. + +To modify the contents `configuration-hackage2nix.yaml`, follow the +instructions on [`hackage2nix`](https://github.com/NixOS/cabal2nix/tree/master/hackage2nix). + ## Other resources - The Youtube video [Nix Loves Haskell](https://www.youtube.com/watch?v=BsBhi_r-OeE) diff --git a/doc/languages-frameworks/java.xml b/doc/languages-frameworks/java.xml index dcf4d17fa57d..667a795a8d3a 100644 --- a/doc/languages-frameworks/java.xml +++ b/doc/languages-frameworks/java.xml @@ -15,15 +15,18 @@ stdenv.mkDerivation { buildPhase = "ant"; } </programlisting> - Note that <varname>jdk</varname> is an alias for the OpenJDK. + Note that <varname>jdk</varname> is an alias for the OpenJDK (self-built + where available, or pre-built via Zulu). Platforms with OpenJDK not (yet) in + Nixpkgs (<literal>Aarch32</literal>, <literal>Aarch64</literal>) point to the + (unfree) <literal>oraclejdk</literal>. </para> <para> JAR files that are intended to be used by other packages should be installed - in <filename>$out/share/java</filename>. The OpenJDK has a stdenv setup hook - that adds any JARs in the <filename>share/java</filename> directories of the - build inputs to the <envar>CLASSPATH</envar> environment variable. For - instance, if the package <literal>libfoo</literal> installs a JAR named + in <filename>$out/share/java</filename>. JDKs have a stdenv setup hook that + add any JARs in the <filename>share/java</filename> directories of the build + inputs to the <envar>CLASSPATH</envar> environment variable. For instance, if + the package <literal>libfoo</literal> installs a JAR named <filename>foo.jar</filename> in its <filename>share/java</filename> directory, and another package declares the attribute <programlisting> @@ -60,6 +63,16 @@ installPhase = </para> <para> + Note all JDKs passthru <literal>home</literal>, so if your application + requires environment variables like <envar>JAVA_HOME</envar> being set, that + can be done in a generic fashion with the <literal>--set</literal> argument + of <literal>makeWrapper</literal>: +<programlisting> + --set JAVA_HOME ${jdk.home} +</programlisting> + </para> + + <para> It is possible to use a different Java compiler than <command>javac</command> from the OpenJDK. For instance, to use the GNU Java Compiler: <programlisting> diff --git a/doc/languages-frameworks/python.section.md b/doc/languages-frameworks/python.section.md index 93eb5af0f2cc..5eabb866654e 100644 --- a/doc/languages-frameworks/python.section.md +++ b/doc/languages-frameworks/python.section.md @@ -645,9 +645,15 @@ in python.withPackages(ps: [ps.blaze])).env #### `buildPythonApplication` function -The `buildPythonApplication` function is practically the same as `buildPythonPackage`. -The difference is that `buildPythonPackage` by default prefixes the names of the packages with the version of the interpreter. -Because this is irrelevant for applications, the prefix is omitted. +The `buildPythonApplication` function is practically the same as +`buildPythonPackage`. The main purpose of this function is to build a Python +package where one is interested only in the executables, and not importable +modules. For that reason, when adding this package to a `python.buildEnv`, the +modules won't be made available. + +Another difference is that `buildPythonPackage` by default prefixes the names of +the packages with the version of the interpreter. Because this is irrelevant for +applications, the prefix is omitted. #### `toPythonApplication` function @@ -1068,4 +1074,5 @@ Following rules are desired to be respected: * Make sure libraries build for all Python interpreters. * By default we enable tests. Make sure the tests are found and, in the case of libraries, are passing for all interpreters. If certain tests fail they can be disabled individually. Try to avoid disabling the tests altogether. In any case, when you disable tests, leave a comment explaining why. * Commit names of Python libraries should reflect that they are Python libraries, so write for example `pythonPackages.numpy: 1.11 -> 1.12`. - +* Attribute names in `python-packages.nix` should be normalized according to [PEP 0503](https://www.python.org/dev/peps/pep-0503/#normalized-names). + This means that characters should be converted to lowercase and `.` and `_` should be replaced by a single `-` (foo-bar-baz instead of Foo__Bar.baz ) diff --git a/doc/languages-frameworks/rust.section.md b/doc/languages-frameworks/rust.section.md index b77c41e9b229..eec982d4c90a 100644 --- a/doc/languages-frameworks/rust.section.md +++ b/doc/languages-frameworks/rust.section.md @@ -59,6 +59,11 @@ all crate sources of this package. Currently it is obtained by inserting a fake checksum into the expression and building the package once. The correct checksum can be then take from the failed build. +When the `Cargo.lock`, provided by upstream, is not in sync with the +`Cargo.toml`, it is possible to use `cargoPatches` to update it. All patches +added in `cargoPatches` will also be prepended to the patches in `patches` at +build-time. + To install crates with nix there is also an experimental project called [nixcrates](https://github.com/fractalide/nixcrates). diff --git a/doc/old/cross.txt b/doc/old/cross.txt index 73103ea0c6d9..c0885c08176e 100644 --- a/doc/old/cross.txt +++ b/doc/old/cross.txt @@ -64,7 +64,7 @@ stdenv.mkDerivation { sha256 = "1ian3kwh2vg6hr3ymrv48s04gijs539vzrq62xr76bxbhbwnz2np"; }; inherit noSysDirs; - configureFlags = "--target=arm-linux"; + configureFlags = [ "--target=arm-linux" ]; } --- diff --git a/doc/package-notes.xml b/doc/package-notes.xml index 68d8f18e75ac..8c7c63c8c8d7 100644 --- a/doc/package-notes.xml +++ b/doc/package-notes.xml @@ -705,4 +705,62 @@ overrides = super: self: rec { </programlisting> </para> </section> + <section xml:id="sec-citrix"> + <title>Citrix Receiver</title> + + <para> + The <link xlink:href="https://www.citrix.com/products/receiver/">Citrix + Receiver</link> is a remote desktop viewer which provides access to + <link xlink:href="https://www.citrix.com/products/xenapp-xendesktop/">XenDesktop</link> + installations. + </para> + + <section xml:id="sec-citrix-base"> + <title>Basic usage</title> + + <para> + The tarball archive needs to be downloaded manually as the licenses + agreements of the vendor need to be accepted first. This is available at + the + <link xlink:href="https://www.citrix.com/downloads/citrix-receiver/">download + page at citrix.com</link>. Then run <literal>nix-prefetch-url + file://$PWD/linuxx64-$version.tar.gz</literal>. With the archive available + in the store the package can be built and installed with Nix. + </para> + + <para> + <emphasis>Note: it's recommended to install <literal>Citrix + Receiver</literal> using <literal>nix-env -i</literal> or globally to + ensure that the <literal>.desktop</literal> files are installed properly + into <literal>$XDG_CONFIG_DIRS</literal>. Otherwise it won't be possible to + open <literal>.ica</literal> files automatically from the browser to start + a Citrix connection.</emphasis> + </para> + </section> + + <section xml:id="sec-citrix-custom-certs"> + <title>Custom certificates</title> + + <para> + The <literal>Citrix Receiver</literal> in <literal>nixpkgs</literal> trusts + several certificates + <link xlink:href="https://curl.haxx.se/docs/caextract.html">from the + Mozilla database</link> by default. However several companies using Citrix + might require their own corporate certificate. On distros with imperative + packaging these certs can be stored easily in + <link xlink:href="https://developer-docs.citrix.com/projects/receiver-for-linux-command-reference/en/13.7/"><literal>$ICAROOT</literal></link>, + however this directory is a store path in <literal>nixpkgs</literal>. In + order to work around this issue the package provides a simple mechanism to + add custom certificates without rebuilding the entire package using + <literal>symlinkJoin</literal>: +<programlisting> +<![CDATA[with import <nixpkgs> { config.allowUnfree = true; }; +let extraCerts = [ ./custom-cert-1.pem ./custom-cert-2.pem /* ... */ ]; in +citrix_receiver.override { + inherit extraCerts; +}]]> +</programlisting> + </para> + </section> + </section> </chapter> diff --git a/doc/platform-notes.xml b/doc/platform-notes.xml index b2c20c2d35c0..cde27b8a5edf 100644 --- a/doc/platform-notes.xml +++ b/doc/platform-notes.xml @@ -48,6 +48,36 @@ </listitem> <listitem> <para> + Even if the libraries are linked using absolute paths and resolved via + their <literal>install_name</literal> correctly, tests can sometimes fail + to run binaries. This happens because the <varname>checkPhase</varname> + runs before the libraries are installed. + </para> + <para> + This can usually be solved by running the tests after the + <varname>installPhase</varname> or alternatively by using + <varname>DYLD_LIBRARY_PATH</varname>. More information about this variable + can be found in the <citerefentry> + <refentrytitle>dyld</refentrytitle> + <manvolnum>1</manvolnum></citerefentry> manpage. + </para> +<programlisting> + dyld: Library not loaded: /nix/store/7hnmbscpayxzxrixrgxvvlifzlxdsdir-jq-1.5-lib/lib/libjq.1.dylib + Referenced from: /private/tmp/nix-build-jq-1.5.drv-0/jq-1.5/tests/../jq + Reason: image not found + ./tests/jqtest: line 5: 75779 Abort trap: 6 + </programlisting> +<programlisting> + stdenv.mkDerivation { + name = "libfoo-1.2.3"; + # ... + doInstallCheck = true; + installCheckTarget = "check"; + } + </programlisting> + </listitem> + <listitem> + <para> Some packages assume xcode is available and use <command>xcrun</command> to resolve build tools like <command>clang</command>, etc. This causes errors like <code>xcode-select: error: no developer tools were found at diff --git a/doc/quick-start.xml b/doc/quick-start.xml index 0cba3a4769c4..b9e6d789404a 100644 --- a/doc/quick-start.xml +++ b/doc/quick-start.xml @@ -9,7 +9,7 @@ <para> Checkout the Nixpkgs source tree: <screen> -$ git clone git://github.com/NixOS/nixpkgs.git +$ git clone https://github.com/NixOS/nixpkgs $ cd nixpkgs</screen> </para> </listitem> diff --git a/doc/reviewing-contributions.xml b/doc/reviewing-contributions.xml index 673ff92d2c8a..6b854e085549 100644 --- a/doc/reviewing-contributions.xml +++ b/doc/reviewing-contributions.xml @@ -6,18 +6,20 @@ <title>Reviewing contributions</title> <warning> <para> - The following section is a draft, and the policy for reviewing is still being - discussed in issues such as <link + The following section is a draft, and the policy for reviewing is still + being discussed in issues such as + <link xlink:href="https://github.com/NixOS/nixpkgs/issues/11166">#11166 - </link> and <link + </link> and + <link xlink:href="https://github.com/NixOS/nixpkgs/issues/20836">#20836 </link>. </para> </warning> <para> - The nixpkgs project receives a fairly high number of contributions via - GitHub pull-requests. Reviewing and approving these is an important task and - a way to contribute to the project. + The nixpkgs project receives a fairly high number of contributions via GitHub + pull-requests. Reviewing and approving these is an important task and a way + to contribute to the project. </para> <para> The high change rate of nixpkgs makes any pull request that remains open for @@ -40,10 +42,10 @@ to respect every community member and their work. </para> <para> - GitHub provides reactions as a simple and quick way to provide - feedback to pull-requests or any comments. The thumb-down reaction should be - used with care and if possible accompanied with some explanation so the - submitter has directions to improve their contribution. + GitHub provides reactions as a simple and quick way to provide feedback to + pull-requests or any comments. The thumb-down reaction should be used with + care and if possible accompanied with some explanation so the submitter has + directions to improve their contribution. </para> <para> Pull-request reviews should include a list of what has been reviewed in a @@ -103,8 +105,9 @@ <itemizedlist> <listitem> <para> - mention-bot usually notifies GitHub users based on the submitted changes, - but it can happen that it misses some of the package maintainers. + <link xlink:href="https://help.github.com/articles/about-codeowners/">CODEOWNERS</link> + will make GitHub notify users based on the submitted changes, but it can + happen that it misses some of the package maintainers. </para> </listitem> </itemizedlist> @@ -116,8 +119,8 @@ <itemizedlist> <listitem> <para> - License can change with version updates, so it should be checked to match - the upstream license. + License can change with version updates, so it should be checked to + match the upstream license. </para> </listitem> <listitem> @@ -142,8 +145,8 @@ <listitem> <para> Pull-requests are often targeted to the master or staging branch, and - building the pull-request locally when it is submitted can trigger - many source builds. + building the pull-request locally when it is submitted can trigger many + source builds. </para> <para> It is possible to rebase the changes on nixos-unstable or @@ -376,8 +379,9 @@ $ nix-shell -p nox --run "nox-review -k pr PRNUMBER" <itemizedlist> <listitem> <para> - Mention-bot notify GitHub users based on the submitted changes, but it - can happen that it miss some of the package maintainers. + <link xlink:href="https://help.github.com/articles/about-codeowners/">CODEOWNERS</link> + will make GitHub notify users based on the submitted changes, but it can + happen that it misses some of the package maintainers. </para> </listitem> </itemizedlist> @@ -604,9 +608,11 @@ policy. <para> In a case a contributor leaves definitively the Nix community, he should - create an issue or notify the mailing list with references of packages and - modules he maintains so the maintainership can be taken over by other - contributors. + create an issue or post on + <link + xlink:href="https://discourse.nixos.org">Discourse</link> with + references of packages and modules he maintains so the maintainership can be + taken over by other contributors. </para> </section> </chapter> diff --git a/doc/stdenv.xml b/doc/stdenv.xml index e7f52377e687..94bd7365dd9a 100644 --- a/doc/stdenv.xml +++ b/doc/stdenv.xml @@ -836,9 +836,10 @@ passthru = { These can optionally be compressed using <command>gzip</command> (<filename>.tar.gz</filename>, <filename>.tgz</filename> or <filename>.tar.Z</filename>), <command>bzip2</command> - (<filename>.tar.bz2</filename> or <filename>.tbz2</filename>) or - <command>xz</command> (<filename>.tar.xz</filename> or - <filename>.tar.lzma</filename>). + (<filename>.tar.bz2</filename>, <filename>.tbz2</filename> or + <filename>.tbz</filename>) or <command>xz</command> + (<filename>.tar.xz</filename>, <filename>.tar.lzma</filename> or + <filename>.txz</filename>). </para> </listitem> </varlistentry> |