commit 360f420ac7df37e8987473f49e00175ef70732b8 · pyrox.dev/nixpkgs

+16 -15

doc/functions.xml

···

       523
        
           <callout arearefs='ex-dockerTools-buildImage-2'>

     

       524
        
            <para>

     

       525
        
             <varname>tag</varname> specifies the tag of the resulting image. By

     

       526
       -
             default it's <literal>null</literal>, which indicates that the nix output hash will be used as tag.

     

       0
        
       
     

       527
        
            </para>

     

       528
        
           </callout>

     

       529
        
           <callout arearefs='ex-dockerTools-buildImage-3'>

     
···

       669
        
            <para>

     

       670
        
             <varname>imageDigest</varname> specifies the digest of the image to be

     

       671
        
             downloaded. Skopeo can be used to get the digest of an image, with its

     

       672
       -
             <varname>inspect</varname> subcommand.  Since a given <varname>imageName</varname>

     

       673
       -
             may transparently refer to a manifest list of images which support

     

       674
       -
             multiple architectures and/or operating systems, supply the `--override-os`

     

       675
       -
             and `--override-arch` arguments to specify exactly which image you

     

       676
       -
             want.  By default it will match the OS and architecture of the host the

     

       677
       -
             command is run on.

     

       678
        
       <programlisting>

     

       679
        
         $ nix-shell --packages skopeo jq --command "skopeo --override-os linux --override-arch x86_64 inspect docker://docker.io/nixos/nix:1.11 | jq -r '.Digest'"

     

       680
        
         sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b

     
···

       697
        
            </para>

     

       698
        
           </callout>

     

       699
        
           <callout arearefs='ex-dockerTools-pullImage-5'>

     

       700
       -
             <para>

     

       701
       -
               <varname>os</varname>, if specified, is the operating system of the fetched image.

     

       702
       -
               By default it's <literal>linux</literal>.

     

       703
       -
             </para>

     

       704
        
           </callout>

     

       705
        
           <callout arearefs='ex-dockerTools-pullImage-6'>

     

       706
       -
             <para>

     

       707
       -
               <varname>arch</varname>, if specified, is the cpu architecture of the fetched image.

     

       708
       -
               By default it's <literal>x86_64</literal>.

     

       709
       -
             </para>

     

       710
        
           </callout>

     

       711
        
          </calloutlist>

     

       712
        
         </section>

···

       523
        
           <callout arearefs='ex-dockerTools-buildImage-2'>

     

       524
        
            <para>

     

       525
        
             <varname>tag</varname> specifies the tag of the resulting image. By

     

       526
       +
             default it's <literal>null</literal>, which indicates that the nix output

     

       527
       +
             hash will be used as tag.

     

       528
        
            </para>

     

       529
        
           </callout>

     

       530
        
           <callout arearefs='ex-dockerTools-buildImage-3'>

     
···

       670
        
            <para>

     

       671
        
             <varname>imageDigest</varname> specifies the digest of the image to be

     

       672
        
             downloaded. Skopeo can be used to get the digest of an image, with its

     

       673
       +
             <varname>inspect</varname> subcommand. Since a given

     

       674
       +
             <varname>imageName</varname> may transparently refer to a manifest list

     

       675
       +
             of images which support multiple architectures and/or operating systems,

     

       676
       +
             supply the `--override-os` and `--override-arch` arguments to specify

     

       677
       +
             exactly which image you want. By default it will match the OS and

     

       678
       +
             architecture of the host the command is run on.

     

       679
        
       <programlisting>

     

       680
        
         $ nix-shell --packages skopeo jq --command "skopeo --override-os linux --override-arch x86_64 inspect docker://docker.io/nixos/nix:1.11 | jq -r '.Digest'"

     

       681
        
         sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b

     
···

       698
        
            </para>

     

       699
        
           </callout>

     

       700
        
           <callout arearefs='ex-dockerTools-pullImage-5'>

     

       701
       +
            <para>

     

       702
       +
             <varname>os</varname>, if specified, is the operating system of the

     

       703
       +
             fetched image. By default it's <literal>linux</literal>.

     

       704
       +
            </para>

     

       705
        
           </callout>

     

       706
        
           <callout arearefs='ex-dockerTools-pullImage-6'>

     

       707
       +
            <para>

     

       708
       +
             <varname>arch</varname>, if specified, is the cpu architecture of the

     

       709
       +
             fetched image. By default it's <literal>x86_64</literal>.

     

       710
       +
            </para>

     

       711
        
           </callout>

     

       712
        
          </calloutlist>

     

       713
        
         </section>

+11 -13

doc/languages-frameworks/java.xml

···

       16
        
       }

     

       17
        
       </programlisting>

     

       18
        
         Note that <varname>jdk</varname> is an alias for the OpenJDK (self-built

     

       19
       -
         where available, or pre-built via Zulu).

     

       20
       -
         Platforms with OpenJDK not (yet) in Nixpkgs (<literal>Aarch32</literal>,

     

       21
       -
         <literal>Aarch64</literal>) point to the (unfree)

     

       22
       -
         <literal>oraclejdk</literal>.

     

       23
       -
       </para>

     

       24
        
       

     

       25
        
        <para>

     

       26
        
         JAR files that are intended to be used by other packages should be installed

     

       27
       -
         in <filename>$out/share/java</filename>. JDKs have a stdenv setup hook

     

       28
       -
         that add any JARs in the <filename>share/java</filename> directories of the

     

       29
       -
         build inputs to the <envar>CLASSPATH</envar> environment variable. For

     

       30
       -
         instance, if the package <literal>libfoo</literal> installs a JAR named

     

       31
        
         <filename>foo.jar</filename> in its <filename>share/java</filename>

     

       32
        
         directory, and another package declares the attribute

     

       33
        
       <programlisting>

     
···

       61
        
         <literal>${jre}/bin/java</literal> instead of

     

       62
        
         <literal>${jdk}/bin/java</literal>, you prevent your package from depending

     

       63
        
         on the JDK at runtime.

     

       64
       -
       </para>

     

       65
        
       

     

       66
       -
       <para>

     

       67
        
         Note all JDKs passthru <literal>home</literal>, so if your application

     

       68
        
         requires environment variables like <envar>JAVA_HOME</envar> being set, that

     

       69
        
         can be done in a generic fashion with the <literal>--set</literal> argument

     

       70
        
         of <literal>makeWrapper</literal>:

     

       71
       -
       

     

       72
        
       <programlisting>

     

       73
        
         --set JAVA_HOME ${jdk.home}

     

       74
        
       </programlisting>

     

       75
       -
       </para>

     

       76
        
       

     

       77
        
        <para>

     

       78
        
         It is possible to use a different Java compiler than <command>javac</command>

···

       16
        
       }

     

       17
        
       </programlisting>

     

       18
        
         Note that <varname>jdk</varname> is an alias for the OpenJDK (self-built

     

       19
       +
         where available, or pre-built via Zulu). Platforms with OpenJDK not (yet) in

     

       20
       +
         Nixpkgs (<literal>Aarch32</literal>, <literal>Aarch64</literal>) point to the

     

       21
       +
         (unfree) <literal>oraclejdk</literal>.

     

       22
       +
        </para>

     

       0
        
       
     

       23
        
       

     

       24
        
        <para>

     

       25
        
         JAR files that are intended to be used by other packages should be installed

     

       26
       +
         in <filename>$out/share/java</filename>. JDKs have a stdenv setup hook that

     

       27
       +
         add any JARs in the <filename>share/java</filename> directories of the build

     

       28
       +
         inputs to the <envar>CLASSPATH</envar> environment variable. For instance, if

     

       29
       +
         the package <literal>libfoo</literal> installs a JAR named

     

       30
        
         <filename>foo.jar</filename> in its <filename>share/java</filename>

     

       31
        
         directory, and another package declares the attribute

     

       32
        
       <programlisting>

     
···

       60
        
         <literal>${jre}/bin/java</literal> instead of

     

       61
        
         <literal>${jdk}/bin/java</literal>, you prevent your package from depending

     

       62
        
         on the JDK at runtime.

     

       63
       +
        </para>

     

       64
        
       

     

       65
       +
        <para>

     

       66
        
         Note all JDKs passthru <literal>home</literal>, so if your application

     

       67
        
         requires environment variables like <envar>JAVA_HOME</envar> being set, that

     

       68
        
         can be done in a generic fashion with the <literal>--set</literal> argument

     

       69
        
         of <literal>makeWrapper</literal>:

     

       0
        
       
     

       70
        
       <programlisting>

     

       71
        
         --set JAVA_HOME ${jdk.home}

     

       72
        
       </programlisting>

     

       73
       +
        </para>

     

       74
        
       

     

       75
        
        <para>

     

       76
        
         It is possible to use a different Java compiler than <command>javac</command>

+29 -19

doc/package-notes.xml

···

       709
        
         <title>Citrix Receiver</title>

     

       710
        
       

     

       711
        
         <para>

     

       712
       -
          The <link xlink:href="https://www.citrix.com/products/receiver/">Citrix Receiver</link> is a remote

     

       713
       -
          desktop viewer which provides access to

     

       714
       -
          <link xlink:href="https://www.citrix.com/products/xenapp-xendesktop/">XenDesktop</link> installations.

     

       0
        
       
     

       715
        
         </para>

     

       716
        
       

     

       717
        
         <section xml:id="sec-citrix-base">

     

       718
        
          <title>Basic usage</title>

     

       0
        
       
     

       719
        
          <para>

     

       720
       -
           The tarball archive needs to be downloaded manually as the licenses agreements of the vendor

     

       721
       -
           need to be accepted first. This is available at the

     

       722
       -
           <link xlink:href="https://www.citrix.com/downloads/citrix-receiver/">download page at citrix.com</link>.

     

       723
       -
           Then run <literal>nix-prefetch-url file://$PWD/linuxx64-$version.tar.gz</literal>.

     

       724
       -
           With the archive available in the store the package can be built and installed with Nix.

     

       0
        
       
     

       0
        
       
     

       725
        
          </para>

     

       726
        
       

     

       727
        
          <para>

     

       728
       -
           <emphasis>Note: it's recommended to install <literal>Citrix Receiver</literal> using

     

       729
       -
           <literal>nix-env -i</literal> or globally to ensure that the <literal>.desktop</literal> files

     

       730
       -
           are installed properly into <literal>$XDG_CONFIG_DIRS</literal>. Otherwise it won't

     

       731
       -
           be possible to open <literal>.ica</literal> files

     

       732
       -
           automatically from the browser to start a Citrix connection.</emphasis>

     

       0
        
       
     

       733
        
          </para>

     

       734
        
         </section>

     

       0
        
       
     

       735
        
         <section xml:id="sec-citrix-custom-certs">

     

       736
        
          <title>Custom certificates</title>

     

       0
        
       
     

       737
        
          <para>

     

       738
       -
           The <literal>Citrix Receiver</literal> in <literal>nixpkgs</literal> trusts several certificates

     

       739
       -
           <link xlink:href="https://curl.haxx.se/docs/caextract.html">from the Mozilla database</link> by default.

     

       740
       -
           However several companies using Citrix might require their own corporate certificate. On distros with imperative

     

       0
        
       
     

       0
        
       
     

       741
        
           packaging these certs can be stored easily in

     

       742
        
           <link xlink:href="https://developer-docs.citrix.com/projects/receiver-for-linux-command-reference/en/13.7/"><literal>$ICAROOT</literal></link>,

     

       743
       -
           however this directory is a store path in <literal>nixpkgs</literal>. In order to work around this issue the package provides a simple

     

       744
       -
           mechanism to add custom certificates without rebuilding the entire package using <literal>symlinkJoin</literal>:

     

       745
       -
       

     

       0
        
       
     

       746
        
       <programlisting>

     

       747
        
       <![CDATA[with import <nixpkgs> { config.allowUnfree = true; };

     

       748
        
       let extraCerts = [ ./custom-cert-1.pem ./custom-cert-2.pem /* ... */ ]; in

···

       709
        
         <title>Citrix Receiver</title>

     

       710
        
       

     

       711
        
         <para>

     

       712
       +
          The <link xlink:href="https://www.citrix.com/products/receiver/">Citrix

     

       713
       +
          Receiver</link> is a remote desktop viewer which provides access to

     

       714
       +
          <link xlink:href="https://www.citrix.com/products/xenapp-xendesktop/">XenDesktop</link>

     

       715
       +
          installations.

     

       716
        
         </para>

     

       717
        
       

     

       718
        
         <section xml:id="sec-citrix-base">

     

       719
        
          <title>Basic usage</title>

     

       720
       +
       

     

       721
        
          <para>

     

       722
       +
           The tarball archive needs to be downloaded manually as the licenses

     

       723
       +
           agreements of the vendor need to be accepted first. This is available at

     

       724
       +
           the

     

       725
       +
           <link xlink:href="https://www.citrix.com/downloads/citrix-receiver/">download

     

       726
       +
           page at citrix.com</link>. Then run <literal>nix-prefetch-url

     

       727
       +
           file://$PWD/linuxx64-$version.tar.gz</literal>. With the archive available

     

       728
       +
           in the store the package can be built and installed with Nix.

     

       729
        
          </para>

     

       730
        
       

     

       731
        
          <para>

     

       732
       +
           <emphasis>Note: it's recommended to install <literal>Citrix

     

       733
       +
           Receiver</literal> using <literal>nix-env -i</literal> or globally to

     

       734
       +
           ensure that the <literal>.desktop</literal> files are installed properly

     

       735
       +
           into <literal>$XDG_CONFIG_DIRS</literal>. Otherwise it won't be possible to

     

       736
       +
           open <literal>.ica</literal> files automatically from the browser to start

     

       737
       +
           a Citrix connection.</emphasis>

     

       738
        
          </para>

     

       739
        
         </section>

     

       740
       +
       

     

       741
        
         <section xml:id="sec-citrix-custom-certs">

     

       742
        
          <title>Custom certificates</title>

     

       743
       +
       

     

       744
        
          <para>

     

       745
       +
           The <literal>Citrix Receiver</literal> in <literal>nixpkgs</literal> trusts

     

       746
       +
           several certificates

     

       747
       +
           <link xlink:href="https://curl.haxx.se/docs/caextract.html">from the

     

       748
       +
           Mozilla database</link> by default. However several companies using Citrix

     

       749
       +
           might require their own corporate certificate. On distros with imperative

     

       750
        
           packaging these certs can be stored easily in

     

       751
        
           <link xlink:href="https://developer-docs.citrix.com/projects/receiver-for-linux-command-reference/en/13.7/"><literal>$ICAROOT</literal></link>,

     

       752
       +
           however this directory is a store path in <literal>nixpkgs</literal>. In

     

       753
       +
           order to work around this issue the package provides a simple mechanism to

     

       754
       +
           add custom certificates without rebuilding the entire package using

     

       755
       +
           <literal>symlinkJoin</literal>:

     

       756
        
       <programlisting>

     

       757
        
       <![CDATA[with import <nixpkgs> { config.allowUnfree = true; };

     

       758
        
       let extraCerts = [ ./custom-cert-1.pem ./custom-cert-2.pem /* ... */ ]; in

+3 -5

doc/platform-notes.xml

···

       29
        
             }

     

       30
        
           </programlisting>

     

       31
        
          </listitem>

     

       32
       -
       

     

       33
        
          <listitem>

     

       34
        
           <para>

     

       35
        
            On darwin libraries are linked using absolute paths, libraries are

     
···

       47
        
             }

     

       48
        
           </programlisting>

     

       49
        
          </listitem>

     

       50
       -
       

     

       51
        
          <listitem>

     

       52
        
           <para>

     

       53
        
            Even if the libraries are linked using absolute paths and resolved via

     

       54
        
            their <literal>install_name</literal> correctly, tests can sometimes fail

     

       55
       -
            to run binaries.  This happens because the <varname>checkPhase</varname>

     

       56
        
            runs before the libraries are installed.

     

       57
        
           </para>

     

       58
        
           <para>

     

       59
        
            This can usually be solved by running the tests after the

     

       60
        
            <varname>installPhase</varname> or alternatively by using

     

       61
        
            <varname>DYLD_LIBRARY_PATH</varname>. More information about this variable

     

       62
       -
            can be found in the <citerefentry><refentrytitle>dyld</refentrytitle>

     

       0
        
       
     

       63
        
            <manvolnum>1</manvolnum></citerefentry> manpage.

     

       64
        
           </para>

     

       65
        
       <programlisting>

     
···

       77
        
             }

     

       78
        
           </programlisting>

     

       79
        
          </listitem>

     

       80
       -
       

     

       81
        
          <listitem>

     

       82
        
           <para>

     

       83
        
            Some packages assume xcode is available and use <command>xcrun</command>

···

       29
        
             }

     

       30
        
           </programlisting>

     

       31
        
          </listitem>

     

       0
        
       
     

       32
        
          <listitem>

     

       33
        
           <para>

     

       34
        
            On darwin libraries are linked using absolute paths, libraries are

     
···

       46
        
             }

     

       47
        
           </programlisting>

     

       48
        
          </listitem>

     

       0
        
       
     

       49
        
          <listitem>

     

       50
        
           <para>

     

       51
        
            Even if the libraries are linked using absolute paths and resolved via

     

       52
        
            their <literal>install_name</literal> correctly, tests can sometimes fail

     

       53
       +
            to run binaries. This happens because the <varname>checkPhase</varname>

     

       54
        
            runs before the libraries are installed.

     

       55
        
           </para>

     

       56
        
           <para>

     

       57
        
            This can usually be solved by running the tests after the

     

       58
        
            <varname>installPhase</varname> or alternatively by using

     

       59
        
            <varname>DYLD_LIBRARY_PATH</varname>. More information about this variable

     

       60
       +
            can be found in the <citerefentry>

     

       61
       +
            <refentrytitle>dyld</refentrytitle>

     

       62
        
            <manvolnum>1</manvolnum></citerefentry> manpage.

     

       63
        
           </para>

     

       64
        
       <programlisting>

     
···

       76
        
             }

     

       77
        
           </programlisting>

     

       78
        
          </listitem>

     

       0
        
       
     

       79
        
          <listitem>

     

       80
        
           <para>

     

       81
        
            Some packages assume xcode is available and use <command>xcrun</command>

+21 -18

doc/reviewing-contributions.xml

···

       6
        
        <title>Reviewing contributions</title>

     

       7
        
        <warning>

     

       8
        
         <para>

     

       9
       -
          The following section is a draft, and the policy for reviewing is still being

     

       10
       -
          discussed in issues such as <link

     

       0
        
       
     

       11
        
       	   xlink:href="https://github.com/NixOS/nixpkgs/issues/11166">#11166

     

       12
       -
          </link> and <link

     

       0
        
       
     

       13
        
       	   xlink:href="https://github.com/NixOS/nixpkgs/issues/20836">#20836

     

       14
        
          </link>.

     

       15
        
         </para>

     

       16
        
        </warning>

     

       17
        
        <para>

     

       18
       -
         The nixpkgs project receives a fairly high number of contributions via

     

       19
       -
         GitHub pull-requests. Reviewing and approving these is an important task and

     

       20
       -
         a way to contribute to the project.

     

       21
        
        </para>

     

       22
        
        <para>

     

       23
        
         The high change rate of nixpkgs makes any pull request that remains open for

     
···

       40
        
         to respect every community member and their work.

     

       41
        
        </para>

     

       42
        
        <para>

     

       43
       -
         GitHub provides reactions as a simple and quick way to provide

     

       44
       -
         feedback to pull-requests or any comments. The thumb-down reaction should be

     

       45
       -
         used with care and if possible accompanied with some explanation so the

     

       46
       -
         submitter has directions to improve their contribution.

     

       47
        
        </para>

     

       48
        
        <para>

     

       49
        
         Pull-request reviews should include a list of what has been reviewed in a

     
···

       117
        
           <itemizedlist>

     

       118
        
            <listitem>

     

       119
        
             <para>

     

       120
       -
              License can change with version updates, so it should be checked to match

     

       121
       -
              the upstream license.

     

       122
        
             </para>

     

       123
        
            </listitem>

     

       124
        
            <listitem>

     
···

       143
        
            <listitem>

     

       144
        
             <para>

     

       145
        
              Pull-requests are often targeted to the master or staging branch, and

     

       146
       -
              building the pull-request locally when it is submitted can trigger

     

       147
       -
              many source builds.

     

       148
        
             </para>

     

       149
        
             <para>

     

       150
        
              It is possible to rebase the changes on nixos-unstable or

     
···

       605
        
       -->

     

       606
        
       

     

       607
        
         <para>

     

       608
       -
          In a case a contributor leaves definitively the Nix community, he

     

       609
       -
          should create an issue or post on <link

     

       0
        
       
     

       610
        
          xlink:href="https://discourse.nixos.org">Discourse</link> with

     

       611
       -
          references of packages and modules he maintains so the

     

       612
       -
          maintainership can be taken over by other contributors.

     

       613
        
         </para>

     

       614
        
        </section>

     

       615
        
       </chapter>

···

       6
        
        <title>Reviewing contributions</title>

     

       7
        
        <warning>

     

       8
        
         <para>

     

       9
       +
          The following section is a draft, and the policy for reviewing is still

     

       10
       +
          being discussed in issues such as

     

       11
       +
          <link

     

       12
        
       	   xlink:href="https://github.com/NixOS/nixpkgs/issues/11166">#11166

     

       13
       +
          </link> and

     

       14
       +
          <link

     

       15
        
       	   xlink:href="https://github.com/NixOS/nixpkgs/issues/20836">#20836

     

       16
        
          </link>.

     

       17
        
         </para>

     

       18
        
        </warning>

     

       19
        
        <para>

     

       20
       +
         The nixpkgs project receives a fairly high number of contributions via GitHub

     

       21
       +
         pull-requests. Reviewing and approving these is an important task and a way

     

       22
       +
         to contribute to the project.

     

       23
        
        </para>

     

       24
        
        <para>

     

       25
        
         The high change rate of nixpkgs makes any pull request that remains open for

     
···

       42
        
         to respect every community member and their work.

     

       43
        
        </para>

     

       44
        
        <para>

     

       45
       +
         GitHub provides reactions as a simple and quick way to provide feedback to

     

       46
       +
         pull-requests or any comments. The thumb-down reaction should be used with

     

       47
       +
         care and if possible accompanied with some explanation so the submitter has

     

       48
       +
         directions to improve their contribution.

     

       49
        
        </para>

     

       50
        
        <para>

     

       51
        
         Pull-request reviews should include a list of what has been reviewed in a

     
···

       119
        
           <itemizedlist>

     

       120
        
            <listitem>

     

       121
        
             <para>

     

       122
       +
              License can change with version updates, so it should be checked to

     

       123
       +
              match the upstream license.

     

       124
        
             </para>

     

       125
        
            </listitem>

     

       126
        
            <listitem>

     
···

       145
        
            <listitem>

     

       146
        
             <para>

     

       147
        
              Pull-requests are often targeted to the master or staging branch, and

     

       148
       +
              building the pull-request locally when it is submitted can trigger many

     

       149
       +
              source builds.

     

       150
        
             </para>

     

       151
        
             <para>

     

       152
        
              It is possible to rebase the changes on nixos-unstable or

     
···

       607
        
       -->

     

       608
        
       

     

       609
        
         <para>

     

       610
       +
          In a case a contributor leaves definitively the Nix community, he should

     

       611
       +
          create an issue or post on

     

       612
       +
          <link

     

       613
        
          xlink:href="https://discourse.nixos.org">Discourse</link> with

     

       614
       +
          references of packages and modules he maintains so the maintainership can be

     

       615
       +
          taken over by other contributors.

     

       616
        
         </para>

     

       617
        
        </section>

     

       618
        
       </chapter>