commit 409934a6e5f29ea9b9ac0ffc186b9a4772c4145a · pyrox.dev/nixpkgs

+1 -1

nixos/doc/manual/development/development.xml

···

       9
       9
        
          This chapter describes how you can modify and extend NixOS.

     

       10
       10
        
         </para>

     

       11
       11
        
        </partintro>

     

       12
       12
       -
        <xi:include href="sources.xml" />

     

       12
       12
       +
        <xi:include href="../from_md/development/sources.chapter.xml" />

     

       13
       13
        
        <xi:include href="writing-modules.xml" />

     

       14
       14
        
        <xi:include href="building-parts.xml" />

     

       15
       15
        
        <xi:include href="writing-documentation.xml" />

+77

nixos/doc/manual/development/sources.chapter.md

···

       1
       1
       +
       # Getting the Sources {#sec-getting-sources}

     

       2
       2
       +
       

     

       3
       3
       +
       By default, NixOS's `nixos-rebuild` command uses the NixOS and Nixpkgs

     

       4
       4
       +
       sources provided by the `nixos` channel (kept in

     

       5
       5
       +
       `/nix/var/nix/profiles/per-user/root/channels/nixos`). To modify NixOS,

     

       6
       6
       +
       however, you should check out the latest sources from Git. This is as

     

       7
       7
       +
       follows:

     

       8
       8
       +
       

     

       9
       9
       +
       ```ShellSession

     

       10
       10
       +
       $ git clone https://github.com/NixOS/nixpkgs

     

       11
       11
       +
       $ cd nixpkgs

     

       12
       12
       +
       $ git remote update origin

     

       13
       13
       +
       ```

     

       14
       14
       +
       

     

       15
       15
       +
       This will check out the latest Nixpkgs sources to `./nixpkgs` the NixOS

     

       16
       16
       +
       sources to `./nixpkgs/nixos`. (The NixOS source tree lives in a

     

       17
       17
       +
       subdirectory of the Nixpkgs repository.) The `nixpkgs` repository has

     

       18
       18
       +
       branches that correspond to each Nixpkgs/NixOS channel (see

     

       19
       19
       +
       [](#sec-upgrading) for more information about channels). Thus, the

     

       20
       20
       +
       Git branch `origin/nixos-17.03` will contain the latest built and tested

     

       21
       21
       +
       version available in the `nixos-17.03` channel.

     

       22
       22
       +
       

     

       23
       23
       +
       It's often inconvenient to develop directly on the master branch, since

     

       24
       24
       +
       if somebody has just committed (say) a change to GCC, then the binary

     

       25
       25
       +
       cache may not have caught up yet and you'll have to rebuild everything

     

       26
       26
       +
       from source. So you may want to create a local branch based on your

     

       27
       27
       +
       current NixOS version:

     

       28
       28
       +
       

     

       29
       29
       +
       ```ShellSession

     

       30
       30
       +
       $ nixos-version

     

       31
       31
       +
       17.09pre104379.6e0b727 (Hummingbird)

     

       32
       32
       +
       

     

       33
       33
       +
       $ git checkout -b local 6e0b727

     

       34
       34
       +
       ```

     

       35
       35
       +
       

     

       36
       36
       +
       Or, to base your local branch on the latest version available in a NixOS

     

       37
       37
       +
       channel:

     

       38
       38
       +
       

     

       39
       39
       +
       ```ShellSession

     

       40
       40
       +
       $ git remote update origin

     

       41
       41
       +
       $ git checkout -b local origin/nixos-17.03

     

       42
       42
       +
       ```

     

       43
       43
       +
       

     

       44
       44
       +
       (Replace `nixos-17.03` with the name of the channel you want to use.)

     

       45
       45
       +
       You can use `git merge` or `git

     

       46
       46
       +
         rebase` to keep your local branch in sync with the channel, e.g.

     

       47
       47
       +
       

     

       48
       48
       +
       ```ShellSession

     

       49
       49
       +
       $ git remote update origin

     

       50
       50
       +
       $ git merge origin/nixos-17.03

     

       51
       51
       +
       ```

     

       52
       52
       +
       

     

       53
       53
       +
       You can use `git cherry-pick` to copy commits from your local branch to

     

       54
       54
       +
       the upstream branch.

     

       55
       55
       +
       

     

       56
       56
       +
       If you want to rebuild your system using your (modified) sources, you

     

       57
       57
       +
       need to tell `nixos-rebuild` about them using the `-I` flag:

     

       58
       58
       +
       

     

       59
       59
       +
       ```ShellSession

     

       60
       60
       +
       # nixos-rebuild switch -I nixpkgs=/my/sources/nixpkgs

     

       61
       61
       +
       ```

     

       62
       62
       +
       

     

       63
       63
       +
       If you want `nix-env` to use the expressions in `/my/sources`, use

     

       64
       64
       +
       `nix-env -f

     

       65
       65
       +
         /my/sources/nixpkgs`, or change the default by adding a symlink in

     

       66
       66
       +
       `~/.nix-defexpr`:

     

       67
       67
       +
       

     

       68
       68
       +
       ```ShellSession

     

       69
       69
       +
       $ ln -s /my/sources/nixpkgs ~/.nix-defexpr/nixpkgs

     

       70
       70
       +
       ```

     

       71
       71
       +
       

     

       72
       72
       +
       You may want to delete the symlink `~/.nix-defexpr/channels_root` to

     

       73
       73
       +
       prevent root's NixOS channel from clashing with your own tree (this may

     

       74
       74
       +
       break the command-not-found utility though). If you want to go back to

     

       75
       75
       +
       the default state, you may just remove the `~/.nix-defexpr` directory

     

       76
       76
       +
       completely, log out and log in again and it should have been recreated

     

       77
       77
       +
       with a link to the root channels.

-85

nixos/doc/manual/development/sources.xml

···

       1
       1
       -
       <chapter xmlns="http://docbook.org/ns/docbook"

     

       2
       2
       -
               xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       3
       -
               xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       4
       -
               version="5.0"

     

       5
       5
       -
               xml:id="sec-getting-sources">

     

       6
       6
       -
        <title>Getting the Sources</title>

     

       7
       7
       -
        <para>

     

       8
       8
       -
         By default, NixOS’s <command>nixos-rebuild</command> command uses the NixOS

     

       9
       9
       -
         and Nixpkgs sources provided by the <literal>nixos</literal> channel (kept in

     

       10
       10
       -
         <filename>/nix/var/nix/profiles/per-user/root/channels/nixos</filename>). To

     

       11
       11
       -
         modify NixOS, however, you should check out the latest sources from Git. This

     

       12
       12
       -
         is as follows:

     

       13
       13
       -
       <screen>

     

       14
       14
       -
       <prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs

     

       15
       15
       -
       <prompt>$ </prompt>cd nixpkgs

     

       16
       16
       -
       <prompt>$ </prompt>git remote update origin

     

       17
       17
       -
       </screen>

     

       18
       18
       -
         This will check out the latest Nixpkgs sources to

     

       19
       19
       -
         <filename>./nixpkgs</filename> the NixOS sources to

     

       20
       20
       -
         <filename>./nixpkgs/nixos</filename>. (The NixOS source tree lives in a

     

       21
       21
       -
         subdirectory of the Nixpkgs repository.) The

     

       22
       22
       -
         <literal>nixpkgs</literal> repository has branches that correspond

     

       23
       23
       -
         to each Nixpkgs/NixOS channel (see <xref linkend="sec-upgrading"/> for more

     

       24
       24
       -
         information about channels). Thus, the Git branch

     

       25
       25
       -
         <literal>origin/nixos-17.03</literal> will contain the latest built and

     

       26
       26
       -
         tested version available in the <literal>nixos-17.03</literal> channel.

     

       27
       27
       -
        </para>

     

       28
       28
       -
        <para>

     

       29
       29
       -
         It’s often inconvenient to develop directly on the master branch, since if

     

       30
       30
       -
         somebody has just committed (say) a change to GCC, then the binary cache may

     

       31
       31
       -
         not have caught up yet and you’ll have to rebuild everything from source.

     

       32
       32
       -
         So you may want to create a local branch based on your current NixOS version:

     

       33
       33
       -
       <screen>

     

       34
       34
       -
       <prompt>$ </prompt>nixos-version

     

       35
       35
       -
       17.09pre104379.6e0b727 (Hummingbird)

     

       36
       36
       -
       

     

       37
       37
       -
       <prompt>$ </prompt>git checkout -b local 6e0b727

     

       38
       38
       -
       </screen>

     

       39
       39
       -
         Or, to base your local branch on the latest version available in a NixOS

     

       40
       40
       -
         channel:

     

       41
       41
       -
       <screen>

     

       42
       42
       -
       <prompt>$ </prompt>git remote update origin

     

       43
       43
       -
       <prompt>$ </prompt>git checkout -b local origin/nixos-17.03

     

       44
       44
       -
       </screen>

     

       45
       45
       -
         (Replace <literal>nixos-17.03</literal> with the name of the channel you want

     

       46
       46
       -
         to use.) You can use <command>git merge</command> or <command>git

     

       47
       47
       -
         rebase</command> to keep your local branch in sync with the channel, e.g.

     

       48
       48
       -
       <screen>

     

       49
       49
       -
       <prompt>$ </prompt>git remote update origin

     

       50
       50
       -
       <prompt>$ </prompt>git merge origin/nixos-17.03

     

       51
       51
       -
       </screen>

     

       52
       52
       -
         You can use <command>git cherry-pick</command> to copy commits from your

     

       53
       53
       -
         local branch to the upstream branch.

     

       54
       54
       -
        </para>

     

       55
       55
       -
        <para>

     

       56
       56
       -
         If you want to rebuild your system using your (modified) sources, you need to

     

       57
       57
       -
         tell <command>nixos-rebuild</command> about them using the

     

       58
       58
       -
         <option>-I</option> flag:

     

       59
       59
       -
       <screen>

     

       60
       60
       -
       <prompt># </prompt>nixos-rebuild switch -I nixpkgs=<replaceable>/my/sources</replaceable>/nixpkgs

     

       61
       61
       -
       </screen>

     

       62
       62
       -
        </para>

     

       63
       63
       -
        <para>

     

       64
       64
       -
         If you want <command>nix-env</command> to use the expressions in

     

       65
       65
       -
         <replaceable>/my/sources</replaceable>, use <command>nix-env -f

     

       66
       66
       -
         <replaceable>/my/sources</replaceable>/nixpkgs</command>, or change the

     

       67
       67
       -
         default by adding a symlink in <filename>~/.nix-defexpr</filename>:

     

       68
       68
       -
       <screen>

     

       69
       69
       -
       <prompt>$ </prompt>ln -s <replaceable>/my/sources</replaceable>/nixpkgs ~/.nix-defexpr/nixpkgs

     

       70
       70
       -
       </screen>

     

       71
       71
       -
         You may want to delete the symlink

     

       72
       72
       -
         <filename>~/.nix-defexpr/channels_root</filename> to prevent root’s NixOS

     

       73
       73
       -
         channel from clashing with your own tree (this may break the

     

       74
       74
       -
         command-not-found utility though). If you want to go back to the default

     

       75
       75
       -
         state, you may just remove the <filename>~/.nix-defexpr</filename> directory

     

       76
       76
       -
         completely, log out and log in again and it should have been recreated with a

     

       77
       77
       -
         link to the root channels.

     

       78
       78
       -
        </para>

     

       79
       79
       -
       <!-- FIXME: not sure what this means.

     

       80
       80
       -
       <para>You should not pass the base directory

     

       81
       81
       -
       <filename><replaceable>/my/sources</replaceable></filename>

     

       82
       82
       -
       to <command>nix-env</command>, as it will break after interpreting expressions

     

       83
       83
       -
       in <filename>nixos/</filename> as packages.</para>

     

       84
       84
       -
       -->

     

       85
       85
       -
       </chapter>

+90

nixos/doc/manual/from_md/development/sources.chapter.xml

···

       1
       1
       +
       <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-getting-sources">

     

       2
       2
       +
         <title>Getting the Sources</title>

     

       3
       3
       +
         <para>

     

       4
       4
       +
           By default, NixOS’s <literal>nixos-rebuild</literal> command uses

     

       5
       5
       +
           the NixOS and Nixpkgs sources provided by the

     

       6
       6
       +
           <literal>nixos</literal> channel (kept in

     

       7
       7
       +
           <literal>/nix/var/nix/profiles/per-user/root/channels/nixos</literal>).

     

       8
       8
       +
           To modify NixOS, however, you should check out the latest sources

     

       9
       9
       +
           from Git. This is as follows:

     

       10
       10
       +
         </para>

     

       11
       11
       +
         <programlisting>

     

       12
       12
       +
       $ git clone https://github.com/NixOS/nixpkgs

     

       13
       13
       +
       $ cd nixpkgs

     

       14
       14
       +
       $ git remote update origin

     

       15
       15
       +
       </programlisting>

     

       16
       16
       +
         <para>

     

       17
       17
       +
           This will check out the latest Nixpkgs sources to

     

       18
       18
       +
           <literal>./nixpkgs</literal> the NixOS sources to

     

       19
       19
       +
           <literal>./nixpkgs/nixos</literal>. (The NixOS source tree lives in

     

       20
       20
       +
           a subdirectory of the Nixpkgs repository.) The

     

       21
       21
       +
           <literal>nixpkgs</literal> repository has branches that correspond

     

       22
       22
       +
           to each Nixpkgs/NixOS channel (see <xref linkend="sec-upgrading" />

     

       23
       23
       +
           for more information about channels). Thus, the Git branch

     

       24
       24
       +
           <literal>origin/nixos-17.03</literal> will contain the latest built

     

       25
       25
       +
           and tested version available in the <literal>nixos-17.03</literal>

     

       26
       26
       +
           channel.

     

       27
       27
       +
         </para>

     

       28
       28
       +
         <para>

     

       29
       29
       +
           It’s often inconvenient to develop directly on the master branch,

     

       30
       30
       +
           since if somebody has just committed (say) a change to GCC, then the

     

       31
       31
       +
           binary cache may not have caught up yet and you’ll have to rebuild

     

       32
       32
       +
           everything from source. So you may want to create a local branch

     

       33
       33
       +
           based on your current NixOS version:

     

       34
       34
       +
         </para>

     

       35
       35
       +
         <programlisting>

     

       36
       36
       +
       $ nixos-version

     

       37
       37
       +
       17.09pre104379.6e0b727 (Hummingbird)

     

       38
       38
       +
       

     

       39
       39
       +
       $ git checkout -b local 6e0b727

     

       40
       40
       +
       </programlisting>

     

       41
       41
       +
         <para>

     

       42
       42
       +
           Or, to base your local branch on the latest version available in a

     

       43
       43
       +
           NixOS channel:

     

       44
       44
       +
         </para>

     

       45
       45
       +
         <programlisting>

     

       46
       46
       +
       $ git remote update origin

     

       47
       47
       +
       $ git checkout -b local origin/nixos-17.03

     

       48
       48
       +
       </programlisting>

     

       49
       49
       +
         <para>

     

       50
       50
       +
           (Replace <literal>nixos-17.03</literal> with the name of the channel

     

       51
       51
       +
           you want to use.) You can use <literal>git merge</literal> or

     

       52
       52
       +
           <literal>git rebase</literal> to keep your local branch in sync with

     

       53
       53
       +
           the channel, e.g.

     

       54
       54
       +
         </para>

     

       55
       55
       +
         <programlisting>

     

       56
       56
       +
       $ git remote update origin

     

       57
       57
       +
       $ git merge origin/nixos-17.03

     

       58
       58
       +
       </programlisting>

     

       59
       59
       +
         <para>

     

       60
       60
       +
           You can use <literal>git cherry-pick</literal> to copy commits from

     

       61
       61
       +
           your local branch to the upstream branch.

     

       62
       62
       +
         </para>

     

       63
       63
       +
         <para>

     

       64
       64
       +
           If you want to rebuild your system using your (modified) sources,

     

       65
       65
       +
           you need to tell <literal>nixos-rebuild</literal> about them using

     

       66
       66
       +
           the <literal>-I</literal> flag:

     

       67
       67
       +
         </para>

     

       68
       68
       +
         <programlisting>

     

       69
       69
       +
       # nixos-rebuild switch -I nixpkgs=/my/sources/nixpkgs

     

       70
       70
       +
       </programlisting>

     

       71
       71
       +
         <para>

     

       72
       72
       +
           If you want <literal>nix-env</literal> to use the expressions in

     

       73
       73
       +
           <literal>/my/sources</literal>, use

     

       74
       74
       +
           <literal>nix-env -f /my/sources/nixpkgs</literal>, or change the

     

       75
       75
       +
           default by adding a symlink in <literal>~/.nix-defexpr</literal>:

     

       76
       76
       +
         </para>

     

       77
       77
       +
         <programlisting>

     

       78
       78
       +
       $ ln -s /my/sources/nixpkgs ~/.nix-defexpr/nixpkgs

     

       79
       79
       +
       </programlisting>

     

       80
       80
       +
         <para>

     

       81
       81
       +
           You may want to delete the symlink

     

       82
       82
       +
           <literal>~/.nix-defexpr/channels_root</literal> to prevent root’s

     

       83
       83
       +
           NixOS channel from clashing with your own tree (this may break the

     

       84
       84
       +
           command-not-found utility though). If you want to go back to the

     

       85
       85
       +
           default state, you may just remove the

     

       86
       86
       +
           <literal>~/.nix-defexpr</literal> directory completely, log out and

     

       87
       87
       +
           log in again and it should have been recreated with a link to the

     

       88
       88
       +
           root channels.

     

       89
       89
       +
         </para>

     

       90
       90
       +
       </chapter>