From e1af37634b387e18361f15b2db1c7f7f93d37ebc Mon Sep 17 00:00:00 2001 From: Jan Tojnar Date: Wed, 23 Sep 2020 00:38:04 +0200 Subject: [PATCH] doc: Improve code listings By adding prompts and removing unnecessary indentation. --- doc/builders/images/dockertools.xml | 12 +- doc/builders/images/ocitools.xml | 3 +- doc/builders/packages/citrix.xml | 8 +- doc/builders/packages/urxvt.xml | 50 ++++--- doc/contributing/submitting-changes.xml | 12 +- doc/languages-frameworks/beam.xml | 6 +- doc/languages-frameworks/perl.xml | 186 ++++++++++++------------ doc/languages-frameworks/qt.xml | 2 +- doc/languages-frameworks/ruby.xml | 25 ++-- doc/languages-frameworks/texlive.xml | 10 +- doc/stdenv/multiple-output.xml | 2 +- doc/using/configuration.xml | 8 +- doc/using/overlays.xml | 10 +- 13 files changed, 173 insertions(+), 161 deletions(-) diff --git a/doc/builders/images/dockertools.xml b/doc/builders/images/dockertools.xml index 126698d0a9e..d881e712a04 100644 --- a/doc/builders/images/dockertools.xml +++ b/doc/builders/images/dockertools.xml @@ -132,11 +132,11 @@ buildImage { By default buildImage will use a static date of one second past the UNIX Epoch. This allows buildImage to produce binary reproducible images. When listing images with docker images, the newly created images will be listed like this: - +$ docker images REPOSITORY TAG IMAGE ID CREATED SIZE hello latest 08c791c7846e 48 years ago 25.2MB -]]> + You can break binary reproducibility but have a sorted, meaningful CREATED column by setting created to now. @@ -152,11 +152,11 @@ pkgs.dockerTools.buildImage { ]]> and now the Docker CLI will display a reasonable date and sort the images as expected: - +$ docker images REPOSITORY TAG IMAGE ID CREATED SIZE hello latest de2bf4786de6 About a minute ago 25.2MB -]]> + however, the produced images will not be binary reproducible. diff --git a/doc/builders/images/ocitools.xml b/doc/builders/images/ocitools.xml index e8cd3472f54..f26ed864427 100644 --- a/doc/builders/images/ocitools.xml +++ b/doc/builders/images/ocitools.xml @@ -38,8 +38,7 @@ buildContainer { readonly = false; } - - + diff --git a/doc/builders/packages/citrix.xml b/doc/builders/packages/citrix.xml index 16f1bc6f8f2..803eb2e4fc4 100644 --- a/doc/builders/packages/citrix.xml +++ b/doc/builders/packages/citrix.xml @@ -22,10 +22,10 @@ In order to set this up, you first have to download the .cr file from the Netscaler Gateway. After that you can configure the selfservice like this: - - $ storebrowse -C ~/Downloads/receiverconfig.cr - $ selfservice - + +$ storebrowse -C ~/Downloads/receiverconfig.cr +$ selfservice + diff --git a/doc/builders/packages/urxvt.xml b/doc/builders/packages/urxvt.xml index 135cc82a0b5..330e056b656 100644 --- a/doc/builders/packages/urxvt.xml +++ b/doc/builders/packages/urxvt.xml @@ -18,10 +18,13 @@ includes all available plugins. To make use of this functionality, use an overlay or directly install an expression that overrides its configuration, such as - rxvt-unicode.override { configure = { availablePlugins, ... }: { + +rxvt-unicode.override { + configure = { availablePlugins, ... }: { plugins = with availablePlugins; [ perls resize-font vtwheel ]; - } -} + }; +} + If the configure function returns an attrset without the plugins attribute, availablePlugins will be used automatically. @@ -30,18 +33,22 @@ In order to add plugins but also keep all default plugins installed, it is possible to use the following method: - rxvt-unicode.override { configure = { availablePlugins, ... }: { - plugins = (builtins.attrValues availablePlugins) ++ [ custom-plugin ]; - }; -} + +rxvt-unicode.override { + configure = { availablePlugins, ... }: { + plugins = (builtins.attrValues availablePlugins) ++ [ custom-plugin ]; + }; +} + To get a list of all the plugins available, open the Nix REPL and run - $ nix repl + +$ nix repl :l <nixpkgs> map (p: p.name) pkgs.rxvt-unicode.plugins - + Alternatively, if your shell is bash or zsh and have completion enabled, simply type nixpkgs.rxvt-unicode.plugins.<tab>. @@ -53,18 +60,24 @@ map (p: p.name) pkgs.rxvt-unicode.plugins extraDeps can be used, for example, to provide xsel (a clipboard manager) to the clipboard plugin, without installing it globally: - rxvt-unicode.override { configure = { availablePlugins, ... }: { - pluginsDeps = [ xsel ]; - } -} + +rxvt-unicode.override { + configure = { availablePlugins, ... }: { + pluginsDeps = [ xsel ]; + }; +} + perlDeps is a handy way to provide Perl packages to your custom plugins (in $HOME/.urxvt/ext). For example, if you need AnyEvent you can do: - rxvt-unicode.override { configure = { availablePlugins, ... }: { - perlDeps = with perlPackages; [ AnyEvent ]; - } -} + +rxvt-unicode.override { + configure = { availablePlugins, ... }: { + perlDeps = with perlPackages; [ AnyEvent ]; + }; +} + @@ -90,7 +103,8 @@ map (p: p.name) pkgs.rxvt-unicode.plugins If the plugin is itself a perl package that needs to be imported from other plugins or scripts, add the following passthrough: - passthru.perlPackages = [ "self" ]; + +passthru.perlPackages = [ "self" ]; This will make the urxvt wrapper pick up the dependency and set up the perl path accordingly. diff --git a/doc/contributing/submitting-changes.xml b/doc/contributing/submitting-changes.xml index a88965f5cc6..22389c24ea2 100644 --- a/doc/contributing/submitting-changes.xml +++ b/doc/contributing/submitting-changes.xml @@ -209,12 +209,12 @@ Additional information. - (fetchpatch { - name = "CVE-2019-11068.patch"; - url = "https://gitlab.gnome.org/GNOME/libxslt/commit/e03553605b45c88f0b4b2980adfbbb8f6fca2fd6.patch"; - sha256 = "0pkpb4837km15zgg6h57bncp66d5lwrlvkr73h0lanywq7zrwhj8"; - }) - +(fetchpatch { + name = "CVE-2019-11068.patch"; + url = "https://gitlab.gnome.org/GNOME/libxslt/commit/e03553605b45c88f0b4b2980adfbbb8f6fca2fd6.patch"; + sha256 = "0pkpb4837km15zgg6h57bncp66d5lwrlvkr73h0lanywq7zrwhj8"; +}) + If a security fix applies to both master and a stable release then, similar to regular changes, they are preferably delivered via master first and cherry-picked to the release branch. diff --git a/doc/languages-frameworks/beam.xml b/doc/languages-frameworks/beam.xml index 1d307e1d6dc..addab24f7f6 100644 --- a/doc/languages-frameworks/beam.xml +++ b/doc/languages-frameworks/beam.xml @@ -72,9 +72,9 @@ To install any of those builders into your profile, refer to them by their attribute path beamPackages.rebar3: - - $ nix-env -f "<nixpkgs>" -iA beamPackages.rebar3 - + +$ nix-env -f "<nixpkgs>" -iA beamPackages.rebar3 +
diff --git a/doc/languages-frameworks/perl.xml b/doc/languages-frameworks/perl.xml index ff0f350e99c..b017c028f64 100644 --- a/doc/languages-frameworks/perl.xml +++ b/doc/languages-frameworks/perl.xml @@ -8,28 +8,28 @@ When executing a Perl script, it is possible you get an error such as ./myscript.pl: bad interpreter: /usr/bin/perl: no such file or directory. This happens when the script expects Perl to be installed at /usr/bin/perl, which is not the case when using Perl from nixpkgs. You can fix the script by changing the first line to: - - #!/usr/bin/env perl - + +#!/usr/bin/env perl + to take the Perl installation from the PATH environment variable, or invoke Perl directly with: - - $ perl ./myscript.pl - + +$ perl ./myscript.pl + When the script is using a Perl library that is not installed globally, you might get an error such as Can't locate DB_File.pm in @INC (you may need to install the DB_File module). In that case, you can use nix-shell to start an ad-hoc shell with that library installed, for instance: - - $ nix-shell -p perl perlPackages.DBFile --run ./myscript.pl - + +$ nix-shell -p perl perlPackages.DBFile --run ./myscript.pl + If you are always using the script in places where nix-shell is available, you can embed the nix-shell invocation in the shebang like this: - - #!/usr/bin/env nix-shell - #! nix-shell -i perl -p perl perlPackages.DBFile - + +#!/usr/bin/env nix-shell +#! nix-shell -i perl -p perl perlPackages.DBFile +
@@ -44,30 +44,30 @@ Perl packages from CPAN are defined in pkgs/top-level/perl-packages.nix, rather than pkgs/all-packages.nix. Most Perl packages are so straight-forward to build that they are defined here directly, rather than having a separate function for each package called from perl-packages.nix. However, more complicated packages should be put in a separate file, typically in pkgs/development/perl-modules. Here is an example of the former: - - ClassC3 = buildPerlPackage rec { - name = "Class-C3-0.21"; - src = fetchurl { - url = "mirror://cpan/authors/id/F/FL/FLORA/${name}.tar.gz"; - sha256 = "1bl8z095y4js66pwxnm7s853pi9czala4sqc743fdlnk27kq94gz"; - }; - }; - + +ClassC3 = buildPerlPackage rec { + name = "Class-C3-0.21"; + src = fetchurl { + url = "mirror://cpan/authors/id/F/FL/FLORA/${name}.tar.gz"; + sha256 = "1bl8z095y4js66pwxnm7s853pi9czala4sqc743fdlnk27kq94gz"; + }; +}; + Note the use of mirror://cpan/, and the ${name} in the URL definition to ensure that the name attribute is consistent with the source that we’re actually downloading. Perl packages are made available in all-packages.nix through the variable perlPackages. For instance, if you have a package that needs ClassC3, you would typically write - - foo = import ../path/to/foo.nix { - inherit stdenv fetchurl ...; - inherit (perlPackages) ClassC3; - }; - + +foo = import ../path/to/foo.nix { + inherit stdenv fetchurl ...; + inherit (perlPackages) ClassC3; +}; + in all-packages.nix. You can test building a Perl package as follows: - - $ nix-build -A perlPackages.ClassC3 - + +$ nix-build -A perlPackages.ClassC3 + buildPerlPackage adds perl- to the start of the name attribute, so the package above is actually called perl-Class-C3-0.21. So to install it, you can say: - - $ nix-env -i perl-Class-C3 - + +$ nix-env -i perl-Class-C3 + (Of course you can also install using the attribute name: nix-env -i -A perlPackages.ClassC3.) @@ -94,61 +94,61 @@ buildPerlPackage is built on top of stdenv, so everything can be customised in the usual way. For instance, the BerkeleyDB module has a preConfigure hook to generate a configuration file used by Makefile.PL: - - { buildPerlPackage, fetchurl, db }: + +{ buildPerlPackage, fetchurl, db }: - buildPerlPackage rec { - name = "BerkeleyDB-0.36"; +buildPerlPackage rec { + name = "BerkeleyDB-0.36"; - src = fetchurl { - url = "mirror://cpan/authors/id/P/PM/PMQS/${name}.tar.gz"; - sha256 = "07xf50riarb60l1h6m2dqmql8q5dij619712fsgw7ach04d8g3z1"; - }; + src = fetchurl { + url = "mirror://cpan/authors/id/P/PM/PMQS/${name}.tar.gz"; + sha256 = "07xf50riarb60l1h6m2dqmql8q5dij619712fsgw7ach04d8g3z1"; + }; - preConfigure = '' - echo "LIB = ${db.out}/lib" > config.in - echo "INCLUDE = ${db.dev}/include" >> config.in - ''; - } - + preConfigure = '' + echo "LIB = ${db.out}/lib" > config.in + echo "INCLUDE = ${db.dev}/include" >> config.in + ''; +} + Dependencies on other Perl packages can be specified in the buildInputs and propagatedBuildInputs attributes. If something is exclusively a build-time dependency, use buildInputs; if it’s (also) a runtime dependency, use propagatedBuildInputs. For instance, this builds a Perl module that has runtime dependencies on a bunch of other modules: - - ClassC3Componentised = buildPerlPackage rec { - name = "Class-C3-Componentised-1.0004"; - src = fetchurl { - url = "mirror://cpan/authors/id/A/AS/ASH/${name}.tar.gz"; - sha256 = "0xql73jkcdbq4q9m0b0rnca6nrlvf5hyzy8is0crdk65bynvs8q1"; - }; - propagatedBuildInputs = [ - ClassC3 ClassInspector TestException MROCompat - ]; - }; - + +ClassC3Componentised = buildPerlPackage rec { + name = "Class-C3-Componentised-1.0004"; + src = fetchurl { + url = "mirror://cpan/authors/id/A/AS/ASH/${name}.tar.gz"; + sha256 = "0xql73jkcdbq4q9m0b0rnca6nrlvf5hyzy8is0crdk65bynvs8q1"; + }; + propagatedBuildInputs = [ + ClassC3 ClassInspector TestException MROCompat + ]; +}; + On Darwin, if a script has too many -Idir flags in its first line (its “shebang line”), it will not run. This can be worked around by calling the shortenPerlShebang function from the postInstall phase: - - { stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }: + +{ stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }: - ImageExifTool = buildPerlPackage { - pname = "Image-ExifTool"; - version = "11.50"; +ImageExifTool = buildPerlPackage { + pname = "Image-ExifTool"; + version = "11.50"; - src = fetchurl { - url = "https://www.sno.phy.queensu.ca/~phil/exiftool/Image-ExifTool-11.50.tar.gz"; - sha256 = "0d8v48y94z8maxkmw1rv7v9m0jg2dc8xbp581njb6yhr7abwqdv3"; - }; + src = fetchurl { + url = "https://www.sno.phy.queensu.ca/~phil/exiftool/Image-ExifTool-11.50.tar.gz"; + sha256 = "0d8v48y94z8maxkmw1rv7v9m0jg2dc8xbp581njb6yhr7abwqdv3"; + }; - buildInputs = stdenv.lib.optional stdenv.isDarwin shortenPerlShebang; - postInstall = stdenv.lib.optional stdenv.isDarwin '' - shortenPerlShebang $out/bin/exiftool - ''; - }; - + buildInputs = stdenv.lib.optional stdenv.isDarwin shortenPerlShebang; + postInstall = stdenv.lib.optional stdenv.isDarwin '' + shortenPerlShebang $out/bin/exiftool + ''; +}; + This will remove the -I flags from the shebang line, rewrite them in the use lib form, and put them on the next line instead. This function can be given any number of Perl scripts as arguments; it will modify them in-place. @@ -159,27 +159,27 @@ Nix expressions for Perl packages can be generated (almost) automatically from CPAN. This is done by the program nix-generate-from-cpan, which can be installed as follows: - - $ nix-env -i nix-generate-from-cpan - + +$ nix-env -i nix-generate-from-cpan + This program takes a Perl module name, looks it up on CPAN, fetches and unpacks the corresponding package, and prints a Nix expression on standard output. For example: - - $ nix-generate-from-cpan XML::Simple - XMLSimple = buildPerlPackage rec { - name = "XML-Simple-2.22"; - src = fetchurl { - url = "mirror://cpan/authors/id/G/GR/GRANTM/${name}.tar.gz"; - sha256 = "b9450ef22ea9644ae5d6ada086dc4300fa105be050a2030ebd4efd28c198eb49"; - }; - propagatedBuildInputs = [ XMLNamespaceSupport XMLSAX XMLSAXExpat ]; - meta = { - description = "An API for simple XML files"; - license = with stdenv.lib.licenses; [ artistic1 gpl1Plus ]; - }; - }; - + +$ nix-generate-from-cpan XML::Simple + XMLSimple = buildPerlPackage rec { + name = "XML-Simple-2.22"; + src = fetchurl { + url = "mirror://cpan/authors/id/G/GR/GRANTM/${name}.tar.gz"; + sha256 = "b9450ef22ea9644ae5d6ada086dc4300fa105be050a2030ebd4efd28c198eb49"; + }; + propagatedBuildInputs = [ XMLNamespaceSupport XMLSAX XMLSAXExpat ]; + meta = { + description = "An API for simple XML files"; + license = with stdenv.lib.licenses; [ artistic1 gpl1Plus ]; + }; + }; + The output can be pasted into pkgs/top-level/perl-packages.nix or wherever else you need it. diff --git a/doc/languages-frameworks/qt.xml b/doc/languages-frameworks/qt.xml index 8d97de504ad..ec95621d8ff 100644 --- a/doc/languages-frameworks/qt.xml +++ b/doc/languages-frameworks/qt.xml @@ -18,7 +18,7 @@ mkDerivation { buildInputs = [ qtbase ]; } - + diff --git a/doc/languages-frameworks/ruby.xml b/doc/languages-frameworks/ruby.xml index 9b36801fb96..9b579d6804f 100644 --- a/doc/languages-frameworks/ruby.xml +++ b/doc/languages-frameworks/ruby.xml @@ -12,14 +12,14 @@ - Gemfile +$ cd pkgs/servers/monitoring +$ mkdir sensu +$ cd sensu +$ cat > Gemfile source 'https://rubygems.org' gem 'sensu' -$ $(nix-build '' -A bundix --no-out-link)/bin/bundix --magic -$ cat > default.nix +$ $(nix-build '<nixpkgs>' -A bundix --no-out-link)/bin/bundix --magic +$ cat > default.nix { lib, bundlerEnv, ruby }: bundlerEnv rec { @@ -37,7 +37,7 @@ bundlerEnv rec { maintainers = with maintainers; [ theuni ]; platforms = platforms.unix; }; -}]]> +} @@ -49,17 +49,16 @@ bundlerEnv rec { - +$ cd pkgs/servers/monitoring/sensu +$ nix-shell -p bundler --run 'bundle lock --update' +$ nix-shell -p bundix --run 'bundix' For tools written in Ruby - i.e. where the desire is to install a package and then execute e.g. rake at the command line, there is an alternative builder called bundlerApp. Set up the gemset.nix the same way, and then, for example: - + - + The chief advantage of bundlerApp over bundlerEnv is the executables introduced in the environment are precisely those selected in the exes list, as opposed to bundlerEnv which adds all the executables made available by gems in the gemset, which can mean e.g. rspec or rake in unpredictable versions available from various packages. diff --git a/doc/languages-frameworks/texlive.xml b/doc/languages-frameworks/texlive.xml index a581ec5911c..141c46e5a62 100644 --- a/doc/languages-frameworks/texlive.xml +++ b/doc/languages-frameworks/texlive.xml @@ -44,11 +44,11 @@ texlive.combine { You can list packages e.g. by nix repl. - :l -nix-repl> texlive.collection- -]]> + +$ nix repl +nix-repl> :l <nixpkgs> +nix-repl> texlive.collection- + diff --git a/doc/stdenv/multiple-output.xml b/doc/stdenv/multiple-output.xml index 0f177ec719f..20658918db7 100644 --- a/doc/stdenv/multiple-output.xml +++ b/doc/stdenv/multiple-output.xml @@ -67,7 +67,7 @@ nix-env silenty disregards the outputs selected by the user, and instead installs the outputs from meta.outputsToInstall. For example, -$ nix-env -iA nixpkgs.coreutils.info +$ nix-env -iA nixpkgs.coreutils.info installs the "out" output (coreutils.meta.outputsToInstall is [ "out" ]) instead of the requested "info". diff --git a/doc/using/configuration.xml b/doc/using/configuration.xml index b670f78f28b..3e21b0e2284 100644 --- a/doc/using/configuration.xml +++ b/doc/using/configuration.xml @@ -66,7 +66,7 @@ For allowing the build of a broken package once, you can use an environment variable for a single invocation of the nix tools: -$ export NIXPKGS_ALLOW_BROKEN=1 +$ export NIXPKGS_ALLOW_BROKEN=1 @@ -92,7 +92,7 @@ For allowing the build of an unsupported package once, you can use an environment variable for a single invocation of the nix tools: -$ export NIXPKGS_ALLOW_UNSUPPORTED_SYSTEM=1 +$ export NIXPKGS_ALLOW_UNSUPPORTED_SYSTEM=1 @@ -122,7 +122,7 @@ To temporarily allow all unfree packages, you can use an environment variable for a single invocation of the nix tools: -$ export NIXPKGS_ALLOW_UNFREE=1 +$ export NIXPKGS_ALLOW_UNFREE=1 @@ -187,7 +187,7 @@ To temporarily allow all insecure packages, you can use an environment variable for a single invocation of the nix tools: -$ export NIXPKGS_ALLOW_INSECURE=1 +$ export NIXPKGS_ALLOW_INSECURE=1 diff --git a/doc/using/overlays.xml b/doc/using/overlays.xml index f6e02b969ea..4937e950885 100644 --- a/doc/using/overlays.xml +++ b/doc/using/overlays.xml @@ -240,7 +240,7 @@ self: super: lapackProvider = self.mkl; } } - + This overlay uses Intel’s MKL library for both BLAS and LAPACK interfaces. Note that the same can be accomplished at runtime @@ -248,9 +248,9 @@ self: super: libblas.so.3 and liblapack.so.3. For instance: - -$ LD_LIBRARY_PATH=$(nix-build -A mkl)/lib:$LD_LIBRARY_PATH nix-shell -p octave --run octave - + +$ LD_LIBRARY_PATH=$(nix-build -A mkl)/lib:$LD_LIBRARY_PATH nix-shell -p octave --run octave + Intel MKL requires an openmp implementation when running with multiple processors. By default, @@ -288,7 +288,7 @@ assert (!blas.isILP64) && (!lapack.isILP64); stdenv.mkDerivation { ... } - +