diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/manual/expressions/builtins.xml | 119 | ||||
| -rw-r--r-- | doc/manual/packages/copy-closure.xml | 2 | ||||
| -rw-r--r-- | doc/manual/packages/s3-substituter.xml | 25 | ||||
| -rw-r--r-- | doc/manual/src/expressions/builtins.md | 126 | ||||
| -rw-r--r-- | doc/manual/src/package-management/copy-closure.md | 2 | ||||
| -rw-r--r-- | doc/manual/src/package-management/s3-substituter.md | 18 |
6 files changed, 157 insertions, 135 deletions
diff --git a/doc/manual/expressions/builtins.xml b/doc/manual/expressions/builtins.xml index 478b67ce8..877fd3a1b 100644 --- a/doc/manual/expressions/builtins.xml +++ b/doc/manual/expressions/builtins.xml @@ -434,88 +434,93 @@ stdenv.mkDerivation { … } </varlistentry> </variablelist> - <example> - <title>Fetching a private repository over SSH</title> - <programlisting>builtins.fetchGit { + <para>Here are some examples of how to use + <literal>fetchGit</literal>.</para> + + <itemizedlist> + + <listitem> + <para>To fetch a private repository over SSH:</para> + + <programlisting>builtins.fetchGit { url = "git@github.com:my-secret/repository.git"; ref = "master"; rev = "adab8b916a45068c044658c4158d81878f9ed1c3"; }</programlisting> - </example> - <example> - <title>Fetching an arbitrary ref</title> - <programlisting>builtins.fetchGit { + </listitem> + + <listitem> + <para>To fetch an arbitrary reference:</para> + + <programlisting>builtins.fetchGit { url = "https://github.com/NixOS/nix.git"; ref = "refs/heads/0.5-release"; }</programlisting> - </example> - - <example> - <title>Fetching a repository's specific commit on an arbitrary branch</title> - <para> - If the revision you're looking for is in the default branch - of the git repository you don't strictly need to specify - the branch name in the <varname>ref</varname> attribute. - </para> - <para> - However, if the revision you're looking for is in a future - branch for the non-default branch you will need to specify - the the <varname>ref</varname> attribute as well. - </para> - <programlisting>builtins.fetchGit { + </listitem> + + <listitem> + <para> + If the revision you're looking for is in the default branch + of the git repository you don't strictly need to specify + the branch name in the <varname>ref</varname> attribute. + </para> + <para> + However, if the revision you're looking for is in a future + branch for the non-default branch you will need to specify + the the <varname>ref</varname> attribute as well. + </para> + + <programlisting>builtins.fetchGit { url = "https://github.com/nixos/nix.git"; rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; ref = "1.11-maintenance"; }</programlisting> - <note> + + <note> + <para> + It is nice to always specify the branch which a revision + belongs to. Without the branch being specified, the + fetcher might fail if the default branch changes. + Additionally, it can be confusing to try a commit from a + non-default branch and see the fetch fail. If the branch + is specified the fault is much more obvious. + </para> + </note> + </listitem> + + <listitem> <para> - It is nice to always specify the branch which a revision - belongs to. Without the branch being specified, the - fetcher might fail if the default branch changes. - Additionally, it can be confusing to try a commit from a - non-default branch and see the fetch fail. If the branch - is specified the fault is much more obvious. + If the revision you're looking for is in the default branch + of the git repository you may omit the + <varname>ref</varname> attribute. </para> - </note> - </example> - - <example> - <title>Fetching a repository's specific commit on the default branch</title> - <para> - If the revision you're looking for is in the default branch - of the git repository you may omit the - <varname>ref</varname> attribute. - </para> - <programlisting>builtins.fetchGit { + <programlisting>builtins.fetchGit { url = "https://github.com/nixos/nix.git"; rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; }</programlisting> - </example> + </listitem> - <example> - <title>Fetching a tag</title> - <programlisting>builtins.fetchGit { + <listitem> + <para>To fetch a specific tag:</para> + <programlisting>builtins.fetchGit { url = "https://github.com/nixos/nix.git"; ref = "refs/tags/1.9"; }</programlisting> - </example> - - <example> - <title>Fetching the latest version of a remote branch</title> - <para> - <function>builtins.fetchGit</function> can behave impurely - fetch the latest version of a remote branch. - </para> - <note><para>Nix will refetch the branch in accordance to - <xref linkend="conf-tarball-ttl" />.</para></note> - <note><para>This behavior is disabled in - <emphasis>Pure evaluation mode</emphasis>.</para></note> + </listitem> + + <listitem> + <para>To fetch the latest version of a remote branch:</para> <programlisting>builtins.fetchGit { url = "ssh://git@github.com/nixos/nix.git"; ref = "master"; }</programlisting> - </example> + <note><para>Nix will refetch the branch in accordance to + <xref linkend="conf-tarball-ttl" />.</para></note> + <note><para>This behavior is disabled in <emphasis>Pure + evaluation mode</emphasis>.</para></note> + </listitem> + </itemizedlist> </listitem> </varlistentry> diff --git a/doc/manual/packages/copy-closure.xml b/doc/manual/packages/copy-closure.xml index 012030e3e..a336fb293 100644 --- a/doc/manual/packages/copy-closure.xml +++ b/doc/manual/packages/copy-closure.xml @@ -4,7 +4,7 @@ version="5.0" xml:id="ssec-copy-closure"> -<title>Copying Closures Via SSH</title> +<title>Copying Closures via SSH</title> <para>The command <command linkend="sec-nix-copy-closure">nix-copy-closure</command> copies a Nix diff --git a/doc/manual/packages/s3-substituter.xml b/doc/manual/packages/s3-substituter.xml index 868b5a66d..aa5df2026 100644 --- a/doc/manual/packages/s3-substituter.xml +++ b/doc/manual/packages/s3-substituter.xml @@ -5,10 +5,10 @@ version="5.0" xml:id="ssec-s3-substituter"> -<title>Serving a Nix store via AWS S3 or S3-compatible Service</title> +<title>Serving a Nix store via S3</title> <para>Nix has built-in support for storing and fetching store paths -from Amazon S3 and S3 compatible services. This uses the same +from Amazon S3 and S3-compatible services. This uses the same <emphasis>binary</emphasis> cache mechanism that Nix usually uses to fetch prebuilt binaries from <uri>cache.nixos.org</uri>.</para> @@ -170,13 +170,22 @@ the S3 URL:</para> } ]]></programlisting> +</section> + +<section><title>Examples</title> + +<para>To upload with a specific credential profile for Amazon S3:</para> - <example><title>Uploading with a specific credential profile for Amazon S3</title> - <para><command>nix copy --to 's3://example-nix-cache?profile=cache-upload&region=eu-west-2' nixpkgs.hello</command></para> - </example> +<screen> +nix copy --to 's3://example-nix-cache?profile=cache-upload&region=eu-west-2' nixpkgs.hello +</screen> + +<para>To upload to an S3-compatible binary cache:</para> + +<screen> +nix copy --to 's3://example-nix-cache?profile=cache-upload&scheme=https&endpoint=minio.example.com' nixpkgs.hello +</screen> - <example><title>Uploading to an S3-Compatible Binary Cache</title> - <para><command>nix copy --to 's3://example-nix-cache?profile=cache-upload&scheme=https&endpoint=minio.example.com' nixpkgs.hello</command></para> - </example> </section> + </section> diff --git a/doc/manual/src/expressions/builtins.md b/doc/manual/src/expressions/builtins.md index f60af9d24..8faf4b939 100644 --- a/doc/manual/src/expressions/builtins.md +++ b/doc/manual/src/expressions/builtins.md @@ -169,70 +169,76 @@ For instance, `derivation` is also available as `builtins.derivation`. A Boolean parameter that specifies whether submodules should be checked out. Defaults to `false`. - <!-- end list --> + Here are some examples of how to use `fetchGit`. - builtins.fetchGit { - url = "git@github.com:my-secret/repository.git"; - ref = "master"; - rev = "adab8b916a45068c044658c4158d81878f9ed1c3"; - } - - builtins.fetchGit { - url = "https://github.com/NixOS/nix.git"; - ref = "refs/heads/0.5-release"; - } - - If the revision you're looking for is in the default branch of the - git repository you don't strictly need to specify the branch name in - the `ref` attribute. - - However, if the revision you're looking for is in a future branch - for the non-default branch you will need to specify the the `ref` - attribute as well. - - builtins.fetchGit { - url = "https://github.com/nixos/nix.git"; - rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; - ref = "1.11-maintenance"; - } - - > **Note** - > - > It is nice to always specify the branch which a revision belongs - > to. Without the branch being specified, the fetcher might fail if - > the default branch changes. Additionally, it can be confusing to - > try a commit from a non-default branch and see the fetch fail. If - > the branch is specified the fault is much more obvious. - - If the revision you're looking for is in the default branch of the - git repository you may omit the `ref` attribute. - - builtins.fetchGit { - url = "https://github.com/nixos/nix.git"; - rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; - } - - builtins.fetchGit { - url = "https://github.com/nixos/nix.git"; - ref = "refs/tags/1.9"; - } - - `builtins.fetchGit` can behave impurely fetch the latest version of - a remote branch. + - To fetch a private repository over SSH: + + builtins.fetchGit { + url = "git@github.com:my-secret/repository.git"; + ref = "master"; + rev = "adab8b916a45068c044658c4158d81878f9ed1c3"; + } - > **Note** - > - > Nix will refetch the branch in accordance to - > [???](#conf-tarball-ttl). + - To fetch an arbitrary reference: + + builtins.fetchGit { + url = "https://github.com/NixOS/nix.git"; + ref = "refs/heads/0.5-release"; + } + + - If the revision you're looking for is in the default branch of + the git repository you don't strictly need to specify the branch + name in the `ref` attribute. + + However, if the revision you're looking for is in a future + branch for the non-default branch you will need to specify the + the `ref` attribute as well. + + builtins.fetchGit { + url = "https://github.com/nixos/nix.git"; + rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; + ref = "1.11-maintenance"; + } + + > **Note** + > + > It is nice to always specify the branch which a revision + > belongs to. Without the branch being specified, the fetcher + > might fail if the default branch changes. Additionally, it can + > be confusing to try a commit from a non-default branch and see + > the fetch fail. If the branch is specified the fault is much + > more obvious. + + - If the revision you're looking for is in the default branch of + the git repository you may omit the `ref` attribute. + + builtins.fetchGit { + url = "https://github.com/nixos/nix.git"; + rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; + } - > **Note** - > - > This behavior is disabled in *Pure evaluation mode*. + - To fetch a specific tag: + + builtins.fetchGit { + url = "https://github.com/nixos/nix.git"; + ref = "refs/tags/1.9"; + } - builtins.fetchGit { - url = "ssh://git@github.com/nixos/nix.git"; - ref = "master"; - } + - To fetch the latest version of a remote branch: + + builtins.fetchGit { + url = "ssh://git@github.com/nixos/nix.git"; + ref = "master"; + } + + > **Note** + > + > Nix will refetch the branch in accordance to + > [???](#conf-tarball-ttl). + + > **Note** + > + > This behavior is disabled in *Pure evaluation mode*. - `builtins.filter` f xs Return a list consisting of the elements of xs for which the diff --git a/doc/manual/src/package-management/copy-closure.md b/doc/manual/src/package-management/copy-closure.md index 6573862c0..d78b77e36 100644 --- a/doc/manual/src/package-management/copy-closure.md +++ b/doc/manual/src/package-management/copy-closure.md @@ -1,4 +1,4 @@ -# Copying Closures Via SSH +# Copying Closures via SSH The command `nix-copy-closure` copies a Nix store path along with all its dependencies to or from another machine via the SSH protocol. It diff --git a/doc/manual/src/package-management/s3-substituter.md b/doc/manual/src/package-management/s3-substituter.md index 4740b8b1c..d96114e3c 100644 --- a/doc/manual/src/package-management/s3-substituter.md +++ b/doc/manual/src/package-management/s3-substituter.md @@ -1,7 +1,7 @@ -# Serving a Nix store via AWS S3 or S3-compatible Service +# Serving a Nix store via S3 Nix has built-in support for storing and fetching store paths from -Amazon S3 and S3 compatible services. This uses the same *binary* cache +Amazon S3 and S3-compatible services. This uses the same *binary* cache mechanism that Nix usually uses to fetch prebuilt binaries from [cache.nixos.org](cache.nixos.org). @@ -124,10 +124,12 @@ Your account will need the following IAM policy to upload to the cache: ] } -`nix copy --to -'s3://example-nix-cache?profile=cache-upload®ion=eu-west-2' -nixpkgs.hello` +## Examples -`nix copy --to -'s3://example-nix-cache?profile=cache-upload&scheme=https&endpoint=minio.example.com' -nixpkgs.hello` +To upload with a specific credential profile for Amazon S3: + + nix copy --to 's3://example-nix-cache?profile=cache-upload®ion=eu-west-2' nixpkgs.hello + +To upload to an S3-compatible binary cache: + + nix copy --to 's3://example-nix-cache?profile=cache-upload&scheme=https&endpoint=minio.example.com' nixpkgs.hello |