JakeHillion/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #54659 from matthewbauer/doc-fixes

Browse Source 
Nixpkgs documentation additions for 19.03
This commit is contained in:
Matthew Bauer 2019-01-27 13:54:06 -05:00 committed by GitHub
commit 14ecdbefd4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 544 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/functions.xml
View File

@ -11,6 +11,8 @@
<xi:include href="functions/overrides.xml" />
<xi:include href="functions/generators.xml" />
<xi:include href="functions/debug.xml" />
<xi:include href="functions/fetchers.xml" />
<xi:include href="functions/trivial-builders.xml" />
<xi:include href="functions/fhs-environments.xml" />
<xi:include href="functions/shell.xml" />
<xi:include href="functions/dockertools.xml" />

206
doc/functions/fetchers.xml Normal file
View File

@ -0,0 +1,206 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="sec-pkgs-fetchers">
<title>Fetcher functions</title>
<para>
When using Nix, you will frequently need to download source code
and other files from the internet. Nixpkgs comes with a few helper
functions that allow you to fetch fixed-output derivations in a
structured way.
</para>
<para>
The two fetcher primitives are <function>fetchurl</function> and
<function>fetchzip</function>. Both of these have two required
arguments, a URL and a hash. The hash is typically
<literal>sha256</literal>, although many more hash algorithms are
supported. Nixpkgs contributors are currently recommended to use
<literal>sha256</literal>. This hash will be used by Nix to
identify your source. A typical usage of fetchurl is provided
below.
</para>
<programlisting><![CDATA[
{ stdenv, fetchurl }:
stdenv.mkDerivation {
name = "hello";
src = fetchurl {
url = "http://www.example.org/hello.tar.gz";
sha256 = "1111111111111111111111111111111111111111111111111111";
};
}
]]></programlisting>
<para>
The main difference between <function>fetchurl</function> and
<function>fetchzip</function> is in how they store the contents.
<function>fetchurl</function> will store the unaltered contents of
the URL within the Nix store. <function>fetchzip</function> on the
other hand will decompress the archive for you, making files and
directories directly accessible in the future.
<function>fetchzip</function> can only be used with archives.
Despite the name, <function>fetchzip</function> is not limited to
.zip files and can also be used with any tarball.
</para>
<para>
<function>fetchpatch</function> works very similarly to
<function>fetchurl</function> with the same arguments expected. It
expects patch files as a source and and performs normalization on
them before computing the checksum. For example it will remove
comments or other unstable parts that are sometimes added by
version control systems and can change over time.
</para>
<para>
Other fetcher functions allow you to add source code directly from
a VCS such as subversion or git. These are mostly straightforward
names based on the name of the command used with the VCS system.
Because they give you a working repository, they act most like
<function>fetchzip</function>.
</para>
<variablelist>
<varlistentry>
<term>
<literal>fetchsvn</literal>
</term>
<listitem>
<para>
Used with Subversion. Expects <literal>url</literal> to a
Subversion directory, <literal>rev</literal>, and
<literal>sha256</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>fetchgit</literal>
</term>
<listitem>
<para>
Used with Git. Expects <literal>url</literal> to a Git repo,
<literal>rev</literal>, and <literal>sha256</literal>.
<literal>rev</literal> in this case can be full the git commit
id (SHA1 hash) or a tag name like
<literal>refs/tags/v1.0</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>fetchfossil</literal>
</term>
<listitem>
<para>
Used with Fossil. Expects <literal>url</literal> to a Fossil
archive, <literal>rev</literal>, and <literal>sha256</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>fetchcvs</literal>
</term>
<listitem>
<para>
Used with CVS. Expects <literal>cvsRoot</literal>,
<literal>tag</literal>, and <literal>sha256</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>fetchhg</literal>
</term>
<listitem>
<para>
Used with Mercurial. Expects <literal>url</literal>,
<literal>rev</literal>, and <literal>sha256</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
A number of fetcher functions wrap part of
<function>fetchurl</function> and <function>fetchzip</function>.
They are mainly convenience functions intended for commonly used
destinations of source code in Nixpkgs. These wrapper fetchers are
listed below.
</para>
<variablelist>
<varlistentry>
<term>
<literal>fetchFromGitHub</literal>
</term>
<listitem>
<para>
<function>fetchFromGitHub</function> expects four arguments.
<literal>owner</literal> is a string corresponding to the
GitHub user or organization that controls this repository.
<literal>repo</literal> corresponds to the name of the
software repository. These are located at the top of every
GitHub HTML page as
<literal>owner</literal>/<literal>repo</literal>.
<literal>rev</literal> corresponds to the Git commit hash or
tag (e.g <literal>v1.0</literal>) that will be downloaded from
Git. Finally, <literal>sha256</literal> corresponds to the
hash of the extracted directory. Again, other hash algorithms
are also available but <literal>sha256</literal> is currently
preferred.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>fetchFromGitLab</literal>
</term>
<listitem>
<para>
This is used with GitLab repositories. The arguments expected
are very similar to fetchFromGitHub above.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>fetchFromBitbucket</literal>
</term>
<listitem>
<para>
This is used with BitBucket repositories. The arguments expected
are very similar to fetchFromGitHub above.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>fetchFromSavannah</literal>
</term>
<listitem>
<para>
This is used with Savannah repositories. The arguments expected
are very similar to fetchFromGitHub above.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>fetchFromRepoOrCz</literal>
</term>
<listitem>
<para>
This is used with repo.or.cz repositories. The arguments
expected are very similar to fetchFromGitHub above.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>

124
doc/functions/trivial-builders.xml Normal file
View File

@ -0,0 +1,124 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="sec-trivial-builders">
<title>Trivial builders</title>
<para>
Nixpkgs provides a couple of functions that help with building
derivations. The most important one,
<function>stdenv.mkDerivation</function>, has already been
documented above. The following functions wrap
<function>stdenv.mkDerivation</function>, making it easier to use
in certain cases.
</para>
<variablelist>
<varlistentry>
<term>
<literal>runCommand</literal>
</term>
<listitem>
<para>
This takes three arguments, <literal>name</literal>,
<literal>env</literal>, and <literal>buildCommand</literal>.
<literal>name</literal> is just the name that Nix will append
to the store path in the same way that
<literal>stdenv.mkDerivation</literal> uses its
<literal>name</literal> attribute. <literal>env</literal> is an
attribute set specifying environment variables that will be set
for this derivation. These attributes are then passed to the
wrapped <literal>stdenv.mkDerivation</literal>.
<literal>buildCommand</literal> specifies the commands that
will be run to create this derivation. Note that you will need
to create <literal>$out</literal> for Nix to register the
command as successful.
</para>
<para>
An example of using <literal>runCommand</literal> is provided
below.
</para>
<programlisting>
(import &lt;nixpkgs&gt; {}).runCommand "my-example" {} ''
echo My example command is running
mkdir $out
echo I can write data to the Nix store > $out/message
echo I can also run basic commands like:
echo ls
ls
echo whoami
whoami
echo date
date
''
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>runCommandCC</literal>
</term>
<listitem>
<para>
This works just like <literal>runCommand</literal>. The only
difference is that it also provides a C compiler in
<literal>buildCommand</literal>’s environment. To minimize your
dependencies, you should only use this if you are sure you will
need a C compiler as part of running your command.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>writeTextFile</literal>, <literal>writeText</literal>,
<literal>writeTextDir</literal>, <literal>writeScript</literal>,
<literal>writeScriptBin</literal>
</term>
<listitem>
<para>
These functions write <literal>text</literal> to the Nix store.
This is useful for creating scripts from Nix expressions.
<literal>writeTextFile</literal> takes an attribute set and
expects two arguments, <literal>name</literal> and
<literal>text</literal>. <literal>name</literal> corresponds to
the name used in the Nix store path. <literal>text</literal>
will be the contents of the file. You can also set
<literal>executable</literal> to true to make this file have
the executable bit set.
</para>
<para>
Many more commands wrap <literal>writeTextFile</literal>
including <literal>writeText</literal>,
<literal>writeTextDir</literal>,
<literal>writeScript</literal>, and
<literal>writeScriptBin</literal>. These are convenience
functions over <literal>writeTextFile</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>symlinkJoin</literal>
</term>
<listitem>
<para>
This can be used to put many derivations into the same directory
structure. It works by creating a new derivation and adding
symlinks to each of the paths listed. It expects two arguments,
<literal>name</literal>, and <literal>paths</literal>.
<literal>name</literal> is the name used in the Nix store path
for the created derivation. <literal>paths</literal> is a list of
paths that will be symlinked. These paths can be to Nix store
derivations or any other subdirectory contained within.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>

137
doc/stdenv.xml
View File

@ -2192,10 +2192,130 @@ addEnvHooks "$hostOffset" myBashFunction
</para>
<para>
Here are some packages that provide a setup hook. Since the mechanism is
modular, this probably isn't an exhaustive list. Then again, since the
mechanism is only to be used as a last resort, it might be.
<variablelist>
First, let’s cover some setup hooks that are part of Nixpkgs
default stdenv. This means that they are run for every package
built using <function>stdenv.mkDerivation</function>. Some of
these are platform specific, so they may run on Linux but not
Darwin or vice-versa.
<variablelist>
<varlistentry>
<term>
<literal>move-docs.sh</literal>
</term>
<listitem>
<para>
This setup hook moves any installed documentation to the
<literal>/share</literal> subdirectory directory. This includes
the man, doc and info directories. This is needed for legacy
programs that do not know how to use the
<literal>share</literal> subdirectory.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>compress-man-pages.sh</literal>
</term>
<listitem>
<para>
This setup hook compresses any man pages that have been
installed. The compression is done using the gzip program. This
helps to reduce the installed size of packages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>strip.sh</literal>
</term>
<listitem>
<para>
This runs the strip command on installed binaries and
libraries. This removes unnecessary information like debug
symbols when they are not needed. This also helps to reduce the
installed size of packages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>patch-shebangs.sh</literal>
</term>
<listitem>
<para>
This setup hook patches installed scripts to use the full path
to the shebang interpreter. A shebang interpreter is the first
commented line of a script telling the operating system which
program will run the script (e.g <literal>#!/bin/bash</literal>). In
Nix, we want an exact path to that interpreter to be used. This
often replaces <literal>/bin/sh</literal> with a path in the
Nix store.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>audit-tmpdir.sh</literal>
</term>
<listitem>
<para>
This verifies that no references are left from the install
binaries to the directory used to build those binaries. This
ensures that the binaries do not need things outside the Nix
store. This is currently supported in Linux only.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>multiple-outputs.sh</literal>
</term>
<listitem>
<para>
This setup hook adds configure flags that tell packages to
install files into any one of the proper outputs listed in
<literal>outputs</literal>. This behavior can be turned off by setting
<literal>setOutputFlags</literal> to false in the derivation
environment. See <xref linkend="chap-multiple-output"/> for
more information.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>move-sbin.sh</literal>
</term>
<listitem>
<para>
This setup hook moves any binaries installed in the sbin
subdirectory into bin. In addition, a link is provided from
sbin to bin for compatibility.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>move-lib64.sh</literal>
</term>
<listitem>
<para>
This setup hook moves any libraries installed in the lib64
subdirectory into lib. In addition, a link is provided from
lib64 to lib for compatibility.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>set-source-date-epoch-to-latest.sh</literal>
</term>
<listitem>
<para>
This sets <literal>SOURCE_DATE_EPOCH</literal> to the
modification time of the most recent file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
Bintools Wrapper
@ -2302,6 +2422,15 @@ addEnvHooks "$hostOffset" myBashFunction
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
Here are some more packages that provide a setup hook. Since the
list of hooks is extensible, this is not an exhaustive list the
mechanism is only to be used as a last resort, it might cover most
uses.
<variablelist>
<varlistentry>
<term>
Perl

2
nixos/doc/manual/installation/installing-usb.xml
View File

@ -23,7 +23,7 @@ $ diskutil list
[..]
$ diskutil unmountDisk diskN
Unmount of all volumes on diskN was successful
$ sudo dd bs=1000000 if=nix.iso of=/dev/rdiskN
$ sudo dd if=nix.iso of=/dev/rdiskN
</programlisting>
Using the 'raw' <command>rdiskN</command> device instead of
<command>diskN</command> completes in minutes instead of hours. After

10
pkgs/build-support/fetchbitbucket/default.nix Normal file
View File

@ -0,0 +1,10 @@
{ fetchzip }:
{ owner, repo, rev, name ? "source"
, ... # For hash agility
}@args: fetchzip ({
inherit name;
url = "https://bitbucket.org/${owner}/${repo}/get/${rev}.tar.gz";
meta.homepage = "https://bitbucket.org/${owner}/${repo}/";
extraPostFetch = ''rm -f "$out"/.hg_archival.txt''; # impure file; see #12002
} // removeAttrs args [ "owner" "repo" "rev" ]) // { inherit rev; }

33
pkgs/build-support/fetchgithub/default.nix Normal file
View File

@ -0,0 +1,33 @@
{ lib, fetchgit, fetchzip }:
{ owner, repo, rev, name ? "source"
, fetchSubmodules ? false, private ? false
, githubBase ? "github.com", varPrefix ? null
, ... # For hash agility
}@args: assert private -> !fetchSubmodules;
let
baseUrl = "https://${githubBase}/${owner}/${repo}";
passthruAttrs = removeAttrs args [ "owner" "repo" "rev" "fetchSubmodules" "private" "githubBase" "varPrefix" ];
varBase = "NIX${if varPrefix == null then "" else "_${varPrefix}"}_GITHUB_PRIVATE_";
# We prefer fetchzip in cases we don't need submodules as the hash
# is more stable in that case.
fetcher = if fetchSubmodules then fetchgit else fetchzip;
privateAttrs = lib.optionalAttrs private {
netrcPhase = ''
if [ -z "''$${varBase}USERNAME" -o -z "''$${varBase}PASSWORD" ]; then
echo "Error: Private fetchFromGitHub requires the nix building process (nix-daemon in multi user mode) to have the ${varBase}USERNAME and ${varBase}PASSWORD env vars set." >&2
exit 1
fi
cat > netrc <<EOF
machine ${githubBase}
login ''$${varBase}USERNAME
password ''$${varBase}PASSWORD
EOF
'';
netrcImpureEnvVars = [ "${varBase}USERNAME" "${varBase}PASSWORD" ];
};
fetcherArgs = (if fetchSubmodules
then { inherit rev fetchSubmodules; url = "${baseUrl}.git"; }
else ({ url = "${baseUrl}/archive/${rev}.tar.gz"; } // privateAttrs)
) // passthruAttrs // { inherit name; };
in fetcher fetcherArgs // { meta.homepage = baseUrl; inherit rev; }

10
pkgs/build-support/fetchgitlab/default.nix Normal file
View File

@ -0,0 +1,10 @@
{ fetchzip, lib }:
# gitlab example
{ owner, repo, rev, domain ? "gitlab.com", name ? "source", group ? null
, ... # For hash agility
}@args: fetchzip ({
inherit name;
url = "https://${domain}/api/v4/projects/${lib.optionalString (group != null) "${lib.replaceStrings ["."] ["%2E"] group}%2F"}${lib.replaceStrings ["."] ["%2E"] owner}%2F${lib.replaceStrings ["."] ["%2E"] repo}/repository/archive.tar.gz?sha=${rev}";
meta.homepage = "https://${domain}/${lib.optionalString (group != null) "${group}/"}${owner}/${repo}/";
} // removeAttrs args [ "domain" "owner" "group" "repo" "rev" ]) // { inherit rev; }

10
pkgs/build-support/fetchrepoorcz/default.nix Normal file
View File

@ -0,0 +1,10 @@
{ fetchzip }:
# gitweb example, snapshot support is optional in gitweb
{ repo, rev, name ? "source"
, ... # For hash agility
}@args: fetchzip ({
inherit name;
url = "https://repo.or.cz/${repo}.git/snapshot/${rev}.tar.gz";
meta.homepage = "https://repo.or.cz/${repo}.git/";
} // removeAttrs args [ "repo" "rev" ]) // { inherit rev; }

10
pkgs/build-support/fetchsavannah/default.nix Normal file
View File

@ -0,0 +1,10 @@
{ fetchzip }:
# cgit example, snapshot support is optional in cgit
{ repo, rev, name ? "source"
, ... # For hash agility
}@args: fetchzip ({
inherit name;
url = "https://git.savannah.gnu.org/cgit/${repo}.git/snapshot/${repo}-${rev}.tar.gz";
meta.homepage = "https://git.savannah.gnu.org/cgit/${repo}.git/";
} // removeAttrs args [ "repo" "rev" ]) // { inherit rev; }

73
pkgs/top-level/all-packages.nix
View File

@ -261,78 +261,15 @@ in
fetchCrate = callPackage ../build-support/rust/fetchcrate.nix { };
fetchFromGitHub = {
owner, repo, rev, name ? "source",
fetchSubmodules ? false, private ? false,
githubBase ? "github.com", varPrefix ? null,
... # For hash agility
}@args: assert private -> !fetchSubmodules;
let
baseUrl = "https://${githubBase}/${owner}/${repo}";
passthruAttrs = removeAttrs args [ "owner" "repo" "rev" "fetchSubmodules" "private" "githubBase" "varPrefix" ];
varBase = "NIX${if varPrefix == null then "" else "_${varPrefix}"}_GITHUB_PRIVATE_";
# We prefer fetchzip in cases we don't need submodules as the hash
# is more stable in that case.
fetcher = if fetchSubmodules then fetchgit else fetchzip;
privateAttrs = lib.optionalAttrs private {
netrcPhase = ''
if [ -z "''$${varBase}USERNAME" -o -z "''$${varBase}PASSWORD" ]; then
echo "Error: Private fetchFromGitHub requires the nix building process (nix-daemon in multi user mode) to have the ${varBase}USERNAME and ${varBase}PASSWORD env vars set." >&2
exit 1
fi
cat > netrc <<EOF
machine ${githubBase}
login ''$${varBase}USERNAME
password ''$${varBase}PASSWORD
EOF
'';
netrcImpureEnvVars = [ "${varBase}USERNAME" "${varBase}PASSWORD" ];
};
fetcherArgs = (if fetchSubmodules
then { inherit rev fetchSubmodules; url = "${baseUrl}.git"; }
else ({ url = "${baseUrl}/archive/${rev}.tar.gz"; } // privateAttrs)
) // passthruAttrs // { inherit name; };
in fetcher fetcherArgs // { meta.homepage = baseUrl; inherit rev; };
fetchFromGitHub = callPackage ../build-support/fetchgithub {};
fetchFromBitbucket = {
owner, repo, rev, name ? "source",
... # For hash agility
}@args: fetchzip ({
inherit name;
url = "https://bitbucket.org/${owner}/${repo}/get/${rev}.tar.gz";
meta.homepage = "https://bitbucket.org/${owner}/${repo}/";
extraPostFetch = ''rm -f "$out"/.hg_archival.txt''; # impure file; see #12002
} // removeAttrs args [ "owner" "repo" "rev" ]) // { inherit rev; };
fetchFromBitbucket = callPackage ../build-support/fetchbitbucket {};
# cgit example, snapshot support is optional in cgit
fetchFromSavannah = {
repo, rev, name ? "source",
... # For hash agility
}@args: fetchzip ({
inherit name;
url = "https://git.savannah.gnu.org/cgit/${repo}.git/snapshot/${repo}-${rev}.tar.gz";
meta.homepage = "https://git.savannah.gnu.org/cgit/${repo}.git/";
} // removeAttrs args [ "repo" "rev" ]) // { inherit rev; };
fetchFromSavannah = callPackage ../build-support/fetchsavannah {};
# gitlab example
fetchFromGitLab = {
owner, repo, rev, domain ? "gitlab.com", name ? "source", group ? null,
... # For hash agility
}@args: fetchzip ({
inherit name;
url = "https://${domain}/api/v4/projects/${lib.optionalString (group != null) "${lib.replaceStrings ["."] ["%2E"] group}%2F"}${lib.replaceStrings ["."] ["%2E"] owner}%2F${lib.replaceStrings ["."] ["%2E"] repo}/repository/archive.tar.gz?sha=${rev}";
meta.homepage = "https://${domain}/${lib.optionalString (group != null) "${group}/"}${owner}/${repo}/";
} // removeAttrs args [ "domain" "owner" "group" "repo" "rev" ]) // { inherit rev; };
fetchFromGitLab = callPackage ../build-support/fetchgitlab {};
# gitweb example, snapshot support is optional in gitweb
fetchFromRepoOrCz = {
repo, rev, name ? "source",
... # For hash agility
}@args: fetchzip ({
inherit name;
url = "https://repo.or.cz/${repo}.git/snapshot/${rev}.tar.gz";
meta.homepage = "https://repo.or.cz/${repo}.git/";
} // removeAttrs args [ "repo" "rev" ]) // { inherit rev; };
fetchFromRepoOrCz = callPackage ../build-support/fetchrepoorcz {};
fetchNuGet = callPackage ../build-support/fetchnuget { };
buildDotnetPackage = callPackage ../build-support/build-dotnet-package { };