diff --git a/doc/functions/fetchers.xml b/doc/functions/fetchers.xml index 96937ca7182e..b3bd2fe0f45e 100644 --- a/doc/functions/fetchers.xml +++ b/doc/functions/fetchers.xml @@ -6,8 +6,8 @@ When using Nix, you will frequently need to download source code - and other file from the internet. Nixpkgs comes with a few helper - functions that allow you to fetch fixed-output derivations in + 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. @@ -48,7 +48,11 @@ stdenv.mkDerivation { fetchpatch works very similarly to - fetchurl with the same arguments expected. + fetchurl 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. @@ -80,6 +84,9 @@ stdenv.mkDerivation { Used with Git. Expects url to a Git repo, rev, and sha256. + rev in this case can be full the git commit + id (SHA1 hash) or a tag name like + refs/tags/v1.0. @@ -141,9 +148,10 @@ stdenv.mkDerivation { GitHub HTML page as owner/repo. rev corresponds to the Git commit hash or - tag that will be downloaded from Git. Finally, - sha256. Again, other hash algorithms are - also available but sha256 is currently + tag (e.g v1.0) that will be downloaded from + Git. Finally, sha256 corresponds to the + hash of the extracted directory. Again, other hash algorithms + are also available but sha256 is currently preferred. diff --git a/doc/functions/trivial-builders.xml b/doc/functions/trivial-builders.xml index 4fbe88836100..c5972d3ea908 100644 --- a/doc/functions/trivial-builders.xml +++ b/doc/functions/trivial-builders.xml @@ -5,10 +5,10 @@ Trivial builders - There are a couple of functions provide in Nixpkgs that help with - building derivations. The most important one, + Nixpkgs provides a couple of functions that help with building + derivations. The most important one, stdenv.mkDerivation, has already been - documented above. These wrap + documented above. The following functions wrap stdenv.mkDerivation, making it easier to use in certain cases. @@ -22,14 +22,42 @@ This takes three arguments, name, env, and buildCommand. - name is just the name that Nix will use to - refer to the derivation. env is an attribute - set specifying environment variables that will be set for this - derivation. buildCommand specifies the - commands that will be run to create this derivation. Note that - you will need to create $out for Nix to - register the command as successful. - + name is just the name that Nix will append + to the store path in the same way that + stdenv.mkDerivation uses its + name attribute. env is an + attribute set specifying environment variables that will be set + for this derivation. These attributes are then passed to the + wrapped stdenv.mkDerivation. + buildCommand specifies the commands that + will be run to create this derivation. Note that you will need + to create $out for Nix to register the + command as successful. + + + An example of using runCommand is provided + below. + + + (import <nixpkgs> {}).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 + '' + @@ -47,19 +75,30 @@ - writeTextFile + writeTextFile, writeText, + writeTextDir, writeScript, + writeScriptBin - This writes text to the Nix store. This is - useful for creating scripts from Nix expressions. This takes an - attribute set and expects two arguments, - name and text. - name corresponds to the name used in the Nix - store path. text will be the contents of the - file. You can also set executable to true to - make this file have the executable bit set. - + These functions write text to the Nix store. + This is useful for creating scripts from Nix expressions. + writeTextFile takes an attribute set and + expects two arguments, name and + text. name corresponds to + the name used in the Nix store path. text + will be the contents of the file. You can also set + executable to true to make this file have + the executable bit set. + + + Many more commands wrap writeTextFile + including writeText, + writeTextDir, + writeScript, and + writeScriptBin. These are convenience + functions over writeTextFile. + @@ -75,7 +114,7 @@ name is the name used in the Nix store path for the created derivation. paths is a list of paths that will be symlinked. These paths can be to Nix store - derivations or any other directory. + derivations or any other subdirectory contained within. diff --git a/doc/stdenv.xml b/doc/stdenv.xml index 21667252ad00..3a51907eb8a6 100644 --- a/doc/stdenv.xml +++ b/doc/stdenv.xml @@ -2207,7 +2207,8 @@ addEnvHooks "$hostOffset" myBashFunction This setup hook moves any installed documentation to the /share subdirectory directory. This includes the man, doc and info directories. This is needed for legacy - programs that do not know use the share subdirectory. + programs that do not know how to use the + share subdirectory. @@ -2219,7 +2220,7 @@ addEnvHooks "$hostOffset" myBashFunction This setup hook compresses any man pages that have been installed. The compression is done using the gzip program. This - helps to reduce installed size of packages. + helps to reduce the installed size of packages. @@ -2230,9 +2231,9 @@ addEnvHooks "$hostOffset" myBashFunction This runs the strip command on installed binaries and - libraries. This removed things like debug symbols when they are - not needed. This also helps to reduce installed size of - packages. + libraries. This removes unnecessary information like debug + symbols when they are not needed. This also helps to reduce the + installed size of packages. @@ -2244,10 +2245,11 @@ addEnvHooks "$hostOffset" myBashFunction 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 - what to use to run this script. In Nix, we want an exact path - to that interpreter to be used. This often replcaes - /bin/sh with a path in the Nix store. + commented line of a script telling the operating system which + program will run the script (e.g #!/bin/bash). In + Nix, we want an exact path to that interpreter to be used. This + often replaces /bin/sh with a path in the + Nix store. @@ -2260,7 +2262,7 @@ addEnvHooks "$hostOffset" myBashFunction 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 currently Linux only. + store. This is currently supported in Linux only. @@ -2425,9 +2427,9 @@ addEnvHooks "$hostOffset" myBashFunction Here are some more 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. + 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.