doc: format the documentation (#57102)
This commit is contained in:
Wael Nasreddine
@@ -5,11 +5,11 @@
|
||||
<title>pkgs.appimageTools</title>
|
||||
|
||||
<para>
|
||||
<varname>pkgs.appimageTools</varname> is a set of functions for extracting and wrapping
|
||||
<link xlink:href="https://appimage.org/">AppImage</link> files.
|
||||
|
||||
They are meant to be used if traditional packaging from source is infeasible, or it would take too long.
|
||||
To quickly run an AppImage file, <literal>pkgs.appimage-run</literal> can be used as well.
|
||||
<varname>pkgs.appimageTools</varname> is a set of functions for extracting
|
||||
and wrapping <link xlink:href="https://appimage.org/">AppImage</link> files.
|
||||
They are meant to be used if traditional packaging from source is infeasible,
|
||||
or it would take too long. To quickly run an AppImage file,
|
||||
<literal>pkgs.appimage-run</literal> can be used as well.
|
||||
</para>
|
||||
|
||||
<warning>
|
||||
@@ -19,13 +19,13 @@
|
||||
</para>
|
||||
</warning>
|
||||
|
||||
|
||||
<section xml:id="ssec-pkgs-appimageTools-formats">
|
||||
<title>AppImage formats</title>
|
||||
|
||||
<para>
|
||||
There are different formats for AppImages, see
|
||||
<link xlink:href="https://github.com/AppImage/AppImageSpec/blob/74ad9ca2f94bf864a4a0dac1f369dd4f00bd1c28/draft.md#image-format">the specification</link> for details.
|
||||
<link xlink:href="https://github.com/AppImage/AppImageSpec/blob/74ad9ca2f94bf864a4a0dac1f369dd4f00bd1c28/draft.md#image-format">the
|
||||
specification</link> for details.
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
@@ -34,7 +34,6 @@
|
||||
Type 1 images are ISO 9660 files that are also ELF executables.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Type 2 images are ELF executables with an appended filesystem.
|
||||
@@ -46,7 +45,7 @@
|
||||
They can be told apart with <command>file -k</command>:
|
||||
</para>
|
||||
|
||||
<screen>
|
||||
<screen>
|
||||
<prompt>$ </prompt>file -k type1.AppImage
|
||||
type1.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) ISO 9660 CD-ROM filesystem data 'AppImage' (Lepton 3.x), scale 0-0,
|
||||
spot sensor temperature 0.000000, unit celsius, color scheme 0, calibration: offset 0.000000, slope 0.000000, dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 2.6.18, BuildID[sha1]=d629f6099d2344ad82818172add1d38c5e11bc6d, stripped\012- data
|
||||
@@ -56,7 +55,8 @@ type2.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) (Lepton 3.x)
|
||||
</screen>
|
||||
|
||||
<para>
|
||||
Note how the type 1 AppImage is described as an <literal>ISO 9660 CD-ROM filesystem</literal>, and the type 2 AppImage is not.
|
||||
Note how the type 1 AppImage is described as an <literal>ISO 9660 CD-ROM
|
||||
filesystem</literal>, and the type 2 AppImage is not.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
@@ -64,12 +64,11 @@ type2.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) (Lepton 3.x)
|
||||
<title>Wrapping</title>
|
||||
|
||||
<para>
|
||||
Depending on the type of AppImage you're wrapping, you'll have to use
|
||||
<varname>wrapType1</varname> or <varname>wrapType2</varname>.
|
||||
Depending on the type of AppImage you're wrapping, you'll have to use
|
||||
<varname>wrapType1</varname> or <varname>wrapType2</varname>.
|
||||
</para>
|
||||
|
||||
|
||||
<programlisting>
|
||||
<programlisting>
|
||||
appimageTools.wrapType2 { # or wrapType1
|
||||
name = "patchwork"; <co xml:id='ex-appimageTools-wrapping-1' />
|
||||
src = fetchurl { <co xml:id='ex-appimageTools-wrapping-2' />
|
||||
@@ -79,7 +78,6 @@ appimageTools.wrapType2 { # or wrapType1
|
||||
extraPkgs = pkgs: with pkgs; [ ]; <co xml:id='ex-appimageTools-wrapping-3' />
|
||||
}</programlisting>
|
||||
|
||||
|
||||
<calloutlist>
|
||||
<callout arearefs='ex-appimageTools-wrapping-1'>
|
||||
<para>
|
||||
@@ -93,29 +91,28 @@ appimageTools.wrapType2 { # or wrapType1
|
||||
</callout>
|
||||
<callout arearefs='ex-appimageTools-wrapping-2'>
|
||||
<para>
|
||||
<varname>extraPkgs</varname> allows you to pass a function to include additional packages
|
||||
inside the FHS environment your AppImage is going to run in.
|
||||
|
||||
There are a few ways to learn which dependencies an application needs:
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Looking through the extracted AppImage files, reading its scripts and running <command>patchelf</command> and <command>ldd</command> on its executables.
|
||||
This can also be done in <command>appimage-run</command>, by setting <command>APPIMAGE_DEBUG_EXEC=bash</command>.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Running <command>strace -vfefile</command> on the wrapped executable, looking for libraries that can't be found.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<varname>extraPkgs</varname> allows you to pass a function to include
|
||||
additional packages inside the FHS environment your AppImage is going to
|
||||
run in. There are a few ways to learn which dependencies an application
|
||||
needs:
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Looking through the extracted AppImage files, reading its scripts and
|
||||
running <command>patchelf</command> and <command>ldd</command> on its
|
||||
executables. This can also be done in <command>appimage-run</command>,
|
||||
by setting <command>APPIMAGE_DEBUG_EXEC=bash</command>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Running <command>strace -vfefile</command> on the wrapped executable,
|
||||
looking for libraries that can't be found.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</callout>
|
||||
</calloutlist>
|
||||
|
||||
</section>
|
||||
</section>
|
||||
|
||||
@@ -24,9 +24,9 @@
|
||||
|
||||
<para>
|
||||
This function is analogous to the <command>docker build</command> command,
|
||||
in that it can be used to build a Docker-compatible repository tarball containing
|
||||
a single image with one or multiple layers. As such, the result is suitable
|
||||
for being loaded in Docker with <command>docker load</command>.
|
||||
in that it can be used to build a Docker-compatible repository tarball
|
||||
containing a single image with one or multiple layers. As such, the result
|
||||
is suitable for being loaded in Docker with <command>docker load</command>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@@ -190,8 +190,8 @@ buildImage {
|
||||
By default <function>buildImage</function> will use a static date of one
|
||||
second past the UNIX Epoch. This allows <function>buildImage</function> to
|
||||
produce binary reproducible images. When listing images with
|
||||
<command>docker images</command>, the newly created images will be
|
||||
listed like this:
|
||||
<command>docker images</command>, the newly created images will be listed
|
||||
like this:
|
||||
</para>
|
||||
<screen><![CDATA[
|
||||
$ docker images
|
||||
@@ -402,9 +402,9 @@ pkgs.dockerTools.buildLayeredImage {
|
||||
|
||||
<para>
|
||||
This function is analogous to the <command>docker pull</command> command, in
|
||||
that it can be used to pull a Docker image from a Docker registry. By default
|
||||
<link xlink:href="https://hub.docker.com/">Docker Hub</link> is used to pull
|
||||
images.
|
||||
that it can be used to pull a Docker image from a Docker registry. By
|
||||
default <link xlink:href="https://hub.docker.com/">Docker Hub</link> is used
|
||||
to pull images.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@@ -484,10 +484,10 @@ sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b
|
||||
|
||||
<para>
|
||||
This function is analogous to the <command>docker export</command> command,
|
||||
in that it can be used to flatten a Docker image that contains multiple layers. It
|
||||
is in fact the result of the merge of all the layers of the image. As such,
|
||||
the result is suitable for being imported in Docker with <command>docker
|
||||
import</command>.
|
||||
in that it can be used to flatten a Docker image that contains multiple
|
||||
layers. It is in fact the result of the merge of all the layers of the
|
||||
image. As such, the result is suitable for being imported in Docker with
|
||||
<command>docker import</command>.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
|
||||
+153
-165
@@ -5,24 +5,21 @@
|
||||
<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.
|
||||
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.
|
||||
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[
|
||||
<programlisting><![CDATA[
|
||||
{ stdenv, fetchurl }:
|
||||
|
||||
stdenv.mkDerivation {
|
||||
@@ -35,172 +32,163 @@ stdenv.mkDerivation {
|
||||
]]></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.
|
||||
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.
|
||||
<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>.
|
||||
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>
|
||||
<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.
|
||||
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>
|
||||
<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>
|
||||
|
||||
@@ -13,12 +13,17 @@
|
||||
|
||||
<xi:include href="./library/attrsets.xml" />
|
||||
|
||||
<!-- These docs are generated via nixdoc. To add another generated
|
||||
<!-- These docs are generated via nixdoc. To add another generated
|
||||
library function file to this list, the file
|
||||
`lib-function-docs.nix` must also be updated. -->
|
||||
|
||||
<xi:include href="./library/generated/strings.xml" />
|
||||
|
||||
<xi:include href="./library/generated/trivial.xml" />
|
||||
|
||||
<xi:include href="./library/generated/lists.xml" />
|
||||
|
||||
<xi:include href="./library/generated/debug.xml" />
|
||||
|
||||
<xi:include href="./library/generated/options.xml" />
|
||||
</section>
|
||||
|
||||
@@ -14,15 +14,15 @@
|
||||
<title>Usage</title>
|
||||
|
||||
<para>
|
||||
<literal>pkgs.nix-gitignore</literal> exports a number of functions, but
|
||||
you'll most likely need either <literal>gitignoreSource</literal> or
|
||||
<literal>gitignoreSourcePure</literal>. As their first argument, they both
|
||||
accept either 1. a file with gitignore lines or 2. a string
|
||||
with gitignore lines, or 3. a list of either of the two. They will be
|
||||
concatenated into a single big string.
|
||||
<literal>pkgs.nix-gitignore</literal> exports a number of functions, but
|
||||
you'll most likely need either <literal>gitignoreSource</literal> or
|
||||
<literal>gitignoreSourcePure</literal>. As their first argument, they both
|
||||
accept either 1. a file with gitignore lines or 2. a string with gitignore
|
||||
lines, or 3. a list of either of the two. They will be concatenated into a
|
||||
single big string.
|
||||
</para>
|
||||
|
||||
<programlisting><![CDATA[
|
||||
<programlisting><![CDATA[
|
||||
{ pkgs ? import <nixpkgs> {} }:
|
||||
|
||||
nix-gitignore.gitignoreSource [] ./source
|
||||
@@ -40,24 +40,29 @@
|
||||
]]></programlisting>
|
||||
|
||||
<para>
|
||||
These functions are derived from the <literal>Filter</literal> functions
|
||||
by setting the first filter argument to <literal>(_: _: true)</literal>:
|
||||
These functions are derived from the <literal>Filter</literal> functions by
|
||||
setting the first filter argument to <literal>(_: _: true)</literal>:
|
||||
</para>
|
||||
|
||||
<programlisting><![CDATA[
|
||||
<programlisting><![CDATA[
|
||||
gitignoreSourcePure = gitignoreFilterSourcePure (_: _: true);
|
||||
gitignoreSource = gitignoreFilterSource (_: _: true);
|
||||
]]></programlisting>
|
||||
|
||||
<para>
|
||||
Those filter functions accept the same arguments the <literal>builtins.filterSource</literal> function would pass to its filters, thus <literal>fn: gitignoreFilterSourcePure fn ""</literal> should be extensionally equivalent to <literal>filterSource</literal>. The file is blacklisted iff it's blacklisted by either your filter or the gitignoreFilter.
|
||||
Those filter functions accept the same arguments the
|
||||
<literal>builtins.filterSource</literal> function would pass to its filters,
|
||||
thus <literal>fn: gitignoreFilterSourcePure fn ""</literal> should be
|
||||
extensionally equivalent to <literal>filterSource</literal>. The file is
|
||||
blacklisted iff it's blacklisted by either your filter or the
|
||||
gitignoreFilter.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you want to make your own filter from scratch, you may use
|
||||
</para>
|
||||
If you want to make your own filter from scratch, you may use
|
||||
</para>
|
||||
|
||||
<programlisting><![CDATA[
|
||||
<programlisting><![CDATA[
|
||||
gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root;
|
||||
]]></programlisting>
|
||||
</section>
|
||||
@@ -66,10 +71,11 @@ gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root;
|
||||
<title>gitignore files in subdirectories</title>
|
||||
|
||||
<para>
|
||||
If you wish to use a filter that would search for .gitignore files in subdirectories, just like git does by default, use this function:
|
||||
</para>
|
||||
If you wish to use a filter that would search for .gitignore files in
|
||||
subdirectories, just like git does by default, use this function:
|
||||
</para>
|
||||
|
||||
<programlisting><![CDATA[
|
||||
<programlisting><![CDATA[
|
||||
gitignoreFilterRecursiveSource = filter: patterns: root:
|
||||
# OR
|
||||
gitignoreRecursiveSource = gitignoreFilterSourcePure (_: _: true);
|
||||
|
||||
@@ -7,17 +7,15 @@
|
||||
<para>
|
||||
<function>prefer-remote-fetch</function> is an overlay that download sources
|
||||
on remote builder. This is useful when the evaluating machine has a slow
|
||||
upload while the builder can fetch faster directly from the source.
|
||||
To use it, put the following snippet as a new overlay:
|
||||
<programlisting>
|
||||
upload while the builder can fetch faster directly from the source. To use
|
||||
it, put the following snippet as a new overlay:
|
||||
<programlisting>
|
||||
self: super:
|
||||
(super.prefer-remote-fetch self super)
|
||||
</programlisting>
|
||||
|
||||
A full configuration example for that sets the overlay up for your own account,
|
||||
could look like this
|
||||
|
||||
<programlisting>
|
||||
A full configuration example for that sets the overlay up for your own
|
||||
account, could look like this
|
||||
<programlisting>
|
||||
$ mkdir ~/.config/nixpkgs/overlays/
|
||||
$ cat > ~/.config/nixpkgs/overlays/prefer-remote-fetch.nix <<EOF
|
||||
self: super: super.prefer-remote-fetch self super
|
||||
|
||||
@@ -5,12 +5,11 @@
|
||||
<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.
|
||||
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>
|
||||
@@ -19,26 +18,23 @@
|
||||
<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>
|
||||
<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 <nixpkgs> {}).runCommand "my-example" {} ''
|
||||
echo My example command is running
|
||||
|
||||
@@ -65,41 +61,35 @@
|
||||
<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>
|
||||
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>
|
||||
<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>
|
||||
<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>
|
||||
@@ -109,16 +99,15 @@
|
||||
<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,
|
||||
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.
|
||||
<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>
|
||||
|
||||
Reference in New Issue
Block a user