diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/builders/packages/citrix.xml | 30 | ||||
| -rw-r--r-- | doc/languages-frameworks/perl.xml | 318 | ||||
| -rw-r--r-- | doc/stdenv/stdenv.xml | 3 |
3 files changed, 195 insertions, 156 deletions
diff --git a/doc/builders/packages/citrix.xml b/doc/builders/packages/citrix.xml index c629dc9ee50..16f1bc6f8f2 100644 --- a/doc/builders/packages/citrix.xml +++ b/doc/builders/packages/citrix.xml @@ -4,34 +4,36 @@ <title>Citrix Workspace</title> <para> - <note> - <para> - Please note that the <literal>citrix_receiver</literal> package has been deprecated since its development was <link xlink:href="https://docs.citrix.com/en-us/citrix-workspace-app.html">discontinued by upstream</link> and has been replaced by <link xlink:href="https://www.citrix.com/products/workspace-app/">the citrix workspace app</link>. - </para> - </note> - <link xlink:href="https://www.citrix.com/products/receiver/">Citrix Receiver</link> and <link xlink:href="https://www.citrix.com/products/workspace-app/">Citrix Workspace App</link> are a remote desktop viewers which provide access to <link xlink:href="https://www.citrix.com/products/xenapp-xendesktop/">XenDesktop</link> installations. + The <link xlink:href="https://www.citrix.com/products/workspace-app/">Citrix Workspace App</link> is a remote desktop viewer which provides access to <link xlink:href="https://www.citrix.com/products/xenapp-xendesktop/">XenDesktop</link> installations. </para> <section xml:id="sec-citrix-base"> <title>Basic usage</title> <para> - The tarball archive needs to be downloaded manually as the license agreements of the vendor for <link xlink:href="https://www.citrix.com/downloads/citrix-receiver/">Citrix Receiver</link> or <link xlink:href="https://www.citrix.de/downloads/workspace-app/linux/workspace-app-for-linux-latest.html">Citrix Workspace</link> need to be accepted first. Then run <command>nix-prefetch-url file://$PWD/linuxx64-$version.tar.gz</command>. With the archive available in the store the package can be built and installed with Nix. + The tarball archive needs to be downloaded manually as the license agreements of the vendor for <link xlink:href="https://www.citrix.de/downloads/workspace-app/linux/workspace-app-for-linux-latest.html">Citrix Workspace</link> needs to be accepted first. Then run <command>nix-prefetch-url file://$PWD/linuxx64-$version.tar.gz</command>. With the archive available in the store the package can be built and installed with Nix. </para> + </section> - <warning> - <title>Caution with <command>nix-shell</command> installs</title> - <para> - It's recommended to install <literal>Citrix Receiver</literal> and/or <literal>Citrix Workspace</literal> using <literal>nix-env -i</literal> or globally to ensure that the <literal>.desktop</literal> files are installed properly into <literal>$XDG_CONFIG_DIRS</literal>. Otherwise it won't be possible to open <literal>.ica</literal> files automatically from the browser to start a Citrix connection. - </para> - </warning> + <section xml:id="sec-citrix-selfservice"> + <title>Citrix Selfservice</title> + <para> + The <link xlink:href="https://support.citrix.com/article/CTX200337">selfservice</link> is an application managing Citrix desktops and applications. Please note that this feature only works with at least <package>citrix_workspace_20_06_0</package> and later versions. + </para> + <para> + In order to set this up, you first have to <link xlink:href="https://its.uiowa.edu/support/article/102186">download the <literal>.cr</literal> file from the Netscaler Gateway</link>. After that you can configure the <command>selfservice</command> like this: + <screen> + <prompt>$ </prompt>storebrowse -C ~/Downloads/receiverconfig.cr + <prompt>$ </prompt>selfservice + </screen> + </para> </section> <section xml:id="sec-citrix-custom-certs"> <title>Custom certificates</title> <para> - The <literal>Citrix Workspace App</literal> in <literal>nixpkgs</literal> trust several certificates <link xlink:href="https://curl.haxx.se/docs/caextract.html">from the Mozilla database</link> by default. However several companies using Citrix might require their own corporate certificate. On distros with imperative packaging these certs can be stored easily in <link xlink:href="https://developer-docs.citrix.com/projects/receiver-for-linux-command-reference/en/13.7/"><literal>$ICAROOT</literal></link>, however this directory is a store path in <literal>nixpkgs</literal>. In order to work around this issue the package provides a simple mechanism to add custom certificates without rebuilding the entire package using <literal>symlinkJoin</literal>: + The <literal>Citrix Workspace App</literal> in <literal>nixpkgs</literal> trusts several certificates <link xlink:href="https://curl.haxx.se/docs/caextract.html">from the Mozilla database</link> by default. However several companies using Citrix might require their own corporate certificate. On distros with imperative packaging these certs can be stored easily in <link xlink:href="https://developer-docs.citrix.com/projects/receiver-for-linux-command-reference/en/13.7/"><literal>$ICAROOT</literal></link>, however this directory is a store path in <literal>nixpkgs</literal>. In order to work around this issue the package provides a simple mechanism to add custom certificates without rebuilding the entire package using <literal>symlinkJoin</literal>: <programlisting> <![CDATA[with import <nixpkgs> { config.allowUnfree = true; }; let extraCerts = [ ./custom-cert-1.pem ./custom-cert-2.pem /* ... */ ]; in diff --git a/doc/languages-frameworks/perl.xml b/doc/languages-frameworks/perl.xml index d9b6b2721c6..e661ba4e87c 100644 --- a/doc/languages-frameworks/perl.xml +++ b/doc/languages-frameworks/perl.xml @@ -3,159 +3,193 @@ xml:id="sec-language-perl"> <title>Perl</title> - <para> - Nixpkgs provides a function <varname>buildPerlPackage</varname>, a generic package builder function for any Perl package that has a standard <varname>Makefile.PL</varname>. It’s implemented in <link -xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/perl-modules/generic"><filename>pkgs/development/perl-modules/generic</filename></link>. - </para> - - <para> - Perl packages from CPAN are defined in <link -xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link>, rather than <filename>pkgs/all-packages.nix</filename>. 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 <filename>perl-packages.nix</filename>. However, more complicated packages should be put in a separate file, typically in <filename>pkgs/development/perl-modules</filename>. Here is an example of the former: -<programlisting> -ClassC3 = buildPerlPackage rec { - name = "Class-C3-0.21"; - src = fetchurl { - url = "mirror://cpan/authors/id/F/FL/FLORA/${name}.tar.gz"; - sha256 = "1bl8z095y4js66pwxnm7s853pi9czala4sqc743fdlnk27kq94gz"; - }; -}; -</programlisting> - Note the use of <literal>mirror://cpan/</literal>, and the <literal>${name}</literal> 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 <filename>all-packages.nix</filename> through the variable <varname>perlPackages</varname>. For instance, if you have a package that needs <varname>ClassC3</varname>, you would typically write -<programlisting> -foo = import ../path/to/foo.nix { - inherit stdenv fetchurl ...; - inherit (perlPackages) ClassC3; -}; -</programlisting> - in <filename>all-packages.nix</filename>. You can test building a Perl package as follows: -<screen> -<prompt>$ </prompt>nix-build -A perlPackages.ClassC3 -</screen> - <varname>buildPerlPackage</varname> adds <literal>perl-</literal> to the start of the name attribute, so the package above is actually called <literal>perl-Class-C3-0.21</literal>. So to install it, you can say: -<screen> -<prompt>$ </prompt>nix-env -i perl-Class-C3 -</screen> - (Of course you can also install using the attribute name: <literal>nix-env -i -A perlPackages.ClassC3</literal>.) - </para> - - <para> - So what does <varname>buildPerlPackage</varname> do? It does the following: - <orderedlist> - <listitem> - <para> - In the configure phase, it calls <literal>perl Makefile.PL</literal> to generate a Makefile. You can set the variable <varname>makeMakerFlags</varname> to pass flags to <filename>Makefile.PL</filename> - </para> - </listitem> - <listitem> - <para> - It adds the contents of the <envar>PERL5LIB</envar> environment variable to <literal>#! .../bin/perl</literal> line of Perl scripts as <literal>-I<replaceable>dir</replaceable></literal> flags. This ensures that a script can find its dependencies. (This can cause this shebang line to become too long for Darwin to handle; see the note below.) - </para> - </listitem> - <listitem> - <para> - In the fixup phase, it writes the propagated build inputs (<varname>propagatedBuildInputs</varname>) to the file <filename>$out/nix-support/propagated-user-env-packages</filename>. <command>nix-env</command> recursively installs all packages listed in this file when you install a package that has it. This ensures that a Perl package can find its dependencies. - </para> - </listitem> - </orderedlist> - </para> - - <para> - <varname>buildPerlPackage</varname> is built on top of <varname>stdenv</varname>, so everything can be customised in the usual way. For instance, the <literal>BerkeleyDB</literal> module has a <varname>preConfigure</varname> hook to generate a configuration file used by <filename>Makefile.PL</filename>: -<programlisting> -{ buildPerlPackage, fetchurl, db }: - -buildPerlPackage rec { - name = "BerkeleyDB-0.36"; - - 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 - ''; -} -</programlisting> - </para> - - <para> - Dependencies on other Perl packages can be specified in the <varname>buildInputs</varname> and <varname>propagatedBuildInputs</varname> attributes. If something is exclusively a build-time dependency, use <varname>buildInputs</varname>; if it’s (also) a runtime dependency, use <varname>propagatedBuildInputs</varname>. For instance, this builds a Perl module that has runtime dependencies on a bunch of other modules: -<programlisting> -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 - ]; -}; -</programlisting> - </para> - - <para> - On Darwin, if a script has too many <literal>-I<replaceable>dir</replaceable></literal> flags in its first line (its “shebang line”), it will not run. This can be worked around by calling the <literal>shortenPerlShebang</literal> function from the <literal>postInstall</literal> phase: -<programlisting> -{ stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }: - -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"; - }; - - buildInputs = stdenv.lib.optional stdenv.isDarwin shortenPerlShebang; - postInstall = stdenv.lib.optional stdenv.isDarwin '' - shortenPerlShebang $out/bin/exiftool - ''; -}; -</programlisting> - This will remove the <literal>-I</literal> flags from the shebang line, rewrite them in the <literal>use lib</literal> 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. - </para> - - <section xml:id="ssec-generation-from-CPAN"> - <title>Generation from CPAN</title> + <section xml:id="ssec-perl-running"> + <title>Running perl programs on the shell</title> <para> - Nix expressions for Perl packages can be generated (almost) automatically from CPAN. This is done by the program <command>nix-generate-from-cpan</command>, which can be installed as follows: + When executing a Perl script, it is possible you get an error such as <literal>./myscript.pl: bad interpreter: /usr/bin/perl: no such file or directory</literal>. This happens when the script expects Perl to be installed at <filename>/usr/bin/perl</filename>, which is not the case when using Perl from nixpkgs. You can fix the script by changing the first line to: + <programlisting> + #!/usr/bin/env perl + </programlisting> + to take the Perl installation from the <literal>PATH<literal> environment variable, or invoke Perl directly with: + <screen> + <prompt>$ </prompt>perl ./myscript.pl + </screen> </para> -<screen> -<prompt>$ </prompt>nix-env -i nix-generate-from-cpan -</screen> + <para> + When the script is using a Perl library that is not installed globally, you might get an error such as <literal>Can't locate DB_File.pm in @INC (you may need to install the DB_File module)</literal>. In that case, you can use <command>nix-shell</command> to start an ad-hoc shell with that library installed, for instance: + <screen> + <prompt>$ </prompt>nix-shell -p perl perlPackages.DBFile --run ./myscript.pl + </screen> + </para> <para> - 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: -<screen> -<prompt>$ </prompt>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 ]; - }; - }; -</screen> - The output can be pasted into <filename>pkgs/top-level/perl-packages.nix</filename> or wherever else you need it. + If you are always using the script in places where <command>nix-shell</command> is available, you can embed the <command>nix-shell</command> invocation in the shebang like this: + <programlisting> + #!/usr/bin/env nix-shell + #! nix-shell -i perl -p perl perlPackages.DBFile + </programlisting> </para> </section> - <section xml:id="ssec-perl-cross-compilation"> - <title>Cross-compiling modules</title> + <section xml:id="ssec-perl-packaging"> + <title>Packaging Perl programs</title> + + <para> + Nixpkgs provides a function <varname>buildPerlPackage</varname>, a generic package builder function for any Perl package that has a standard <varname>Makefile.PL</varname>. It’s implemented in <link + xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/perl-modules/generic"><filename>pkgs/development/perl-modules/generic</filename></link>. + </para> + + <para> + Perl packages from CPAN are defined in <link + xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link>, rather than <filename>pkgs/all-packages.nix</filename>. 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 <filename>perl-packages.nix</filename>. However, more complicated packages should be put in a separate file, typically in <filename>pkgs/development/perl-modules</filename>. Here is an example of the former: + <programlisting> + ClassC3 = buildPerlPackage rec { + name = "Class-C3-0.21"; + src = fetchurl { + url = "mirror://cpan/authors/id/F/FL/FLORA/${name}.tar.gz"; + sha256 = "1bl8z095y4js66pwxnm7s853pi9czala4sqc743fdlnk27kq94gz"; + }; + }; + </programlisting> + Note the use of <literal>mirror://cpan/</literal>, and the <literal>${name}</literal> 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 <filename>all-packages.nix</filename> through the variable <varname>perlPackages</varname>. For instance, if you have a package that needs <varname>ClassC3</varname>, you would typically write + <programlisting> + foo = import ../path/to/foo.nix { + inherit stdenv fetchurl ...; + inherit (perlPackages) ClassC3; + }; + </programlisting> + in <filename>all-packages.nix</filename>. You can test building a Perl package as follows: + <screen> + <prompt>$ </prompt>nix-build -A perlPackages.ClassC3 + </screen> + <varname>buildPerlPackage</varname> adds <literal>perl-</literal> to the start of the name attribute, so the package above is actually called <literal>perl-Class-C3-0.21</literal>. So to install it, you can say: + <screen> + <prompt>$ </prompt>nix-env -i perl-Class-C3 + </screen> + (Of course you can also install using the attribute name: <literal>nix-env -i -A perlPackages.ClassC3</literal>.) + </para> + + <para> + So what does <varname>buildPerlPackage</varname> do? It does the following: + <orderedlist> + <listitem> + <para> + In the configure phase, it calls <literal>perl Makefile.PL</literal> to generate a Makefile. You can set the variable <varname>makeMakerFlags</varname> to pass flags to <filename>Makefile.PL</filename> + </para> + </listitem> + <listitem> + <para> + It adds the contents of the <envar>PERL5LIB</envar> environment variable to <literal>#! .../bin/perl</literal> line of Perl scripts as <literal>-I<replaceable>dir</replaceable></literal> flags. This ensures that a script can find its dependencies. (This can cause this shebang line to become too long for Darwin to handle; see the note below.) + </para> + </listitem> + <listitem> + <para> + In the fixup phase, it writes the propagated build inputs (<varname>propagatedBuildInputs</varname>) to the file <filename>$out/nix-support/propagated-user-env-packages</filename>. <command>nix-env</command> recursively installs all packages listed in this file when you install a package that has it. This ensures that a Perl package can find its dependencies. + </para> + </listitem> + </orderedlist> + </para> + + <para> + <varname>buildPerlPackage</varname> is built on top of <varname>stdenv</varname>, so everything can be customised in the usual way. For instance, the <literal>BerkeleyDB</literal> module has a <varname>preConfigure</varname> hook to generate a configuration file used by <filename>Makefile.PL</filename>: + <programlisting> + { buildPerlPackage, fetchurl, db }: + + buildPerlPackage rec { + name = "BerkeleyDB-0.36"; + + 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 + ''; + } + </programlisting> + </para> <para> - Nixpkgs has experimental support for cross-compiling Perl modules. In many cases, it will just work out of the box, even for modules with native extensions. Sometimes, however, the Makefile.PL for a module may (indirectly) import a native module. In that case, you will need to make a stub for that module that will satisfy the Makefile.PL and install it into <filename>lib/perl5/site_perl/cross_perl/${perl.version}</filename>. See the <varname>postInstall</varname> for <varname>DBI</varname> for an example. + Dependencies on other Perl packages can be specified in the <varname>buildInputs</varname> and <varname>propagatedBuildInputs</varname> attributes. If something is exclusively a build-time dependency, use <varname>buildInputs</varname>; if it’s (also) a runtime dependency, use <varname>propagatedBuildInputs</varname>. For instance, this builds a Perl module that has runtime dependencies on a bunch of other modules: + <programlisting> + 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 + ]; + }; + </programlisting> </para> + + <para> + On Darwin, if a script has too many <literal>-I<replaceable>dir</replaceable></literal> flags in its first line (its “shebang line”), it will not run. This can be worked around by calling the <literal>shortenPerlShebang</literal> function from the <literal>postInstall</literal> phase: + <programlisting> + { stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }: + + 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"; + }; + + buildInputs = stdenv.lib.optional stdenv.isDarwin shortenPerlShebang; + postInstall = stdenv.lib.optional stdenv.isDarwin '' + shortenPerlShebang $out/bin/exiftool + ''; + }; + </programlisting> + This will remove the <literal>-I</literal> flags from the shebang line, rewrite them in the <literal>use lib</literal> 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. + </para> + + <section xml:id="ssec-generation-from-CPAN"> + <title>Generation from CPAN</title> + + <para> + Nix expressions for Perl packages can be generated (almost) automatically from CPAN. This is done by the program <command>nix-generate-from-cpan</command>, which can be installed as follows: + </para> + + <screen> + <prompt>$ </prompt>nix-env -i nix-generate-from-cpan + </screen> + + <para> + 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: + <screen> + <prompt>$ </prompt>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 ]; + }; + }; + </screen> + The output can be pasted into <filename>pkgs/top-level/perl-packages.nix</filename> or wherever else you need it. + </para> + </section> + + <section xml:id="ssec-perl-cross-compilation"> + <title>Cross-compiling modules</title> + + <para> + Nixpkgs has experimental support for cross-compiling Perl modules. In many cases, it will just work out of the box, even for modules with native extensions. Sometimes, however, the Makefile.PL for a module may (indirectly) import a native module. In that case, you will need to make a stub for that module that will satisfy the Makefile.PL and install it into <filename>lib/perl5/site_perl/cross_perl/${perl.version}</filename>. See the <varname>postInstall</varname> for <varname>DBI</varname> for an example. + </para> + </section> </section> </section> diff --git a/doc/stdenv/stdenv.xml b/doc/stdenv/stdenv.xml index ee93f39318b..818e6c5da00 100644 --- a/doc/stdenv/stdenv.xml +++ b/doc/stdenv/stdenv.xml @@ -2019,6 +2019,9 @@ addEnvHooks "$hostOffset" myBashFunction In certain situations you may want to run the main command (<command>autoPatchelf</command>) of the setup hook on a file or a set of directories instead of unconditionally patching all outputs. This can be done by setting the <varname>dontAutoPatchelf</varname> environment variable to a non-empty value. </para> <para> + By default <command>autoPatchelf</command> will fail as soon as any ELF file requires a dependency which cannot be resolved via the given build inputs. In some situations you might prefer to just leave missing dependencies unpatched and continue to patch the rest. This can be achieved by setting the <envar>autoPatchelfIgnoreMissingDeps</envar> environment variable to a non-empty value. + </para> + <para> The <command>autoPatchelf</command> command also recognizes a <parameter class="command">--no-recurse</parameter> command line flag, which prevents it from recursing into subdirectories. </para> </listitem> |