diff options
author | Bobby Rong <rjl931189261@126.com> | 2021-07-03 12:00:40 +0800 |
---|---|---|
committer | Bobby Rong <rjl931189261@126.com> | 2021-07-03 12:00:40 +0800 |
commit | 409934a6e5f29ea9b9ac0ffc186b9a4772c4145a (patch) | |
tree | 65f0290365b432c3736a2e880d9b8f135d603c70 /nixos/doc | |
parent | 09c38c29f2c719cd76ca17a596c2fdac9e186ceb (diff) | |
download | nixpkgs-409934a6e5f29ea9b9ac0ffc186b9a4772c4145a.tar nixpkgs-409934a6e5f29ea9b9ac0ffc186b9a4772c4145a.tar.gz nixpkgs-409934a6e5f29ea9b9ac0ffc186b9a4772c4145a.tar.bz2 nixpkgs-409934a6e5f29ea9b9ac0ffc186b9a4772c4145a.tar.lz nixpkgs-409934a6e5f29ea9b9ac0ffc186b9a4772c4145a.tar.xz nixpkgs-409934a6e5f29ea9b9ac0ffc186b9a4772c4145a.tar.zst nixpkgs-409934a6e5f29ea9b9ac0ffc186b9a4772c4145a.zip |
nixos: nixos/doc/manual/development/sources.xml to CommonMark
Diffstat (limited to 'nixos/doc')
-rw-r--r-- | nixos/doc/manual/development/development.xml | 2 | ||||
-rw-r--r-- | nixos/doc/manual/development/sources.chapter.md | 77 | ||||
-rw-r--r-- | nixos/doc/manual/development/sources.xml | 85 | ||||
-rw-r--r-- | nixos/doc/manual/from_md/development/sources.chapter.xml | 90 |
4 files changed, 168 insertions, 86 deletions
diff --git a/nixos/doc/manual/development/development.xml b/nixos/doc/manual/development/development.xml index eb505567962..d536d877add 100644 --- a/nixos/doc/manual/development/development.xml +++ b/nixos/doc/manual/development/development.xml @@ -9,7 +9,7 @@ This chapter describes how you can modify and extend NixOS. </para> </partintro> - <xi:include href="sources.xml" /> + <xi:include href="../from_md/development/sources.chapter.xml" /> <xi:include href="writing-modules.xml" /> <xi:include href="building-parts.xml" /> <xi:include href="writing-documentation.xml" /> diff --git a/nixos/doc/manual/development/sources.chapter.md b/nixos/doc/manual/development/sources.chapter.md new file mode 100644 index 00000000000..88173f7135b --- /dev/null +++ b/nixos/doc/manual/development/sources.chapter.md @@ -0,0 +1,77 @@ +# Getting the Sources {#sec-getting-sources} + +By default, NixOS's `nixos-rebuild` command uses the NixOS and Nixpkgs +sources provided by the `nixos` channel (kept in +`/nix/var/nix/profiles/per-user/root/channels/nixos`). To modify NixOS, +however, you should check out the latest sources from Git. This is as +follows: + +```ShellSession +$ git clone https://github.com/NixOS/nixpkgs +$ cd nixpkgs +$ git remote update origin +``` + +This will check out the latest Nixpkgs sources to `./nixpkgs` the NixOS +sources to `./nixpkgs/nixos`. (The NixOS source tree lives in a +subdirectory of the Nixpkgs repository.) The `nixpkgs` repository has +branches that correspond to each Nixpkgs/NixOS channel (see +[](#sec-upgrading) for more information about channels). Thus, the +Git branch `origin/nixos-17.03` will contain the latest built and tested +version available in the `nixos-17.03` channel. + +It's often inconvenient to develop directly on the master branch, since +if somebody has just committed (say) a change to GCC, then the binary +cache may not have caught up yet and you'll have to rebuild everything +from source. So you may want to create a local branch based on your +current NixOS version: + +```ShellSession +$ nixos-version +17.09pre104379.6e0b727 (Hummingbird) + +$ git checkout -b local 6e0b727 +``` + +Or, to base your local branch on the latest version available in a NixOS +channel: + +```ShellSession +$ git remote update origin +$ git checkout -b local origin/nixos-17.03 +``` + +(Replace `nixos-17.03` with the name of the channel you want to use.) +You can use `git merge` or `git + rebase` to keep your local branch in sync with the channel, e.g. + +```ShellSession +$ git remote update origin +$ git merge origin/nixos-17.03 +``` + +You can use `git cherry-pick` to copy commits from your local branch to +the upstream branch. + +If you want to rebuild your system using your (modified) sources, you +need to tell `nixos-rebuild` about them using the `-I` flag: + +```ShellSession +# nixos-rebuild switch -I nixpkgs=/my/sources/nixpkgs +``` + +If you want `nix-env` to use the expressions in `/my/sources`, use +`nix-env -f + /my/sources/nixpkgs`, or change the default by adding a symlink in +`~/.nix-defexpr`: + +```ShellSession +$ ln -s /my/sources/nixpkgs ~/.nix-defexpr/nixpkgs +``` + +You may want to delete the symlink `~/.nix-defexpr/channels_root` to +prevent root's NixOS channel from clashing with your own tree (this may +break the command-not-found utility though). If you want to go back to +the default state, you may just remove the `~/.nix-defexpr` directory +completely, log out and log in again and it should have been recreated +with a link to the root channels. diff --git a/nixos/doc/manual/development/sources.xml b/nixos/doc/manual/development/sources.xml deleted file mode 100644 index b333ccabb42..00000000000 --- a/nixos/doc/manual/development/sources.xml +++ /dev/null @@ -1,85 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-getting-sources"> - <title>Getting the Sources</title> - <para> - By default, NixOS’s <command>nixos-rebuild</command> command uses the NixOS - and Nixpkgs sources provided by the <literal>nixos</literal> channel (kept in - <filename>/nix/var/nix/profiles/per-user/root/channels/nixos</filename>). To - modify NixOS, however, you should check out the latest sources from Git. This - is as follows: -<screen> -<prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs -<prompt>$ </prompt>cd nixpkgs -<prompt>$ </prompt>git remote update origin -</screen> - This will check out the latest Nixpkgs sources to - <filename>./nixpkgs</filename> the NixOS sources to - <filename>./nixpkgs/nixos</filename>. (The NixOS source tree lives in a - subdirectory of the Nixpkgs repository.) The - <literal>nixpkgs</literal> repository has branches that correspond - to each Nixpkgs/NixOS channel (see <xref linkend="sec-upgrading"/> for more - information about channels). Thus, the Git branch - <literal>origin/nixos-17.03</literal> will contain the latest built and - tested version available in the <literal>nixos-17.03</literal> channel. - </para> - <para> - It’s often inconvenient to develop directly on the master branch, since if - somebody has just committed (say) a change to GCC, then the binary cache may - not have caught up yet and you’ll have to rebuild everything from source. - So you may want to create a local branch based on your current NixOS version: -<screen> -<prompt>$ </prompt>nixos-version -17.09pre104379.6e0b727 (Hummingbird) - -<prompt>$ </prompt>git checkout -b local 6e0b727 -</screen> - Or, to base your local branch on the latest version available in a NixOS - channel: -<screen> -<prompt>$ </prompt>git remote update origin -<prompt>$ </prompt>git checkout -b local origin/nixos-17.03 -</screen> - (Replace <literal>nixos-17.03</literal> with the name of the channel you want - to use.) You can use <command>git merge</command> or <command>git - rebase</command> to keep your local branch in sync with the channel, e.g. -<screen> -<prompt>$ </prompt>git remote update origin -<prompt>$ </prompt>git merge origin/nixos-17.03 -</screen> - You can use <command>git cherry-pick</command> to copy commits from your - local branch to the upstream branch. - </para> - <para> - If you want to rebuild your system using your (modified) sources, you need to - tell <command>nixos-rebuild</command> about them using the - <option>-I</option> flag: -<screen> -<prompt># </prompt>nixos-rebuild switch -I nixpkgs=<replaceable>/my/sources</replaceable>/nixpkgs -</screen> - </para> - <para> - If you want <command>nix-env</command> to use the expressions in - <replaceable>/my/sources</replaceable>, use <command>nix-env -f - <replaceable>/my/sources</replaceable>/nixpkgs</command>, or change the - default by adding a symlink in <filename>~/.nix-defexpr</filename>: -<screen> -<prompt>$ </prompt>ln -s <replaceable>/my/sources</replaceable>/nixpkgs ~/.nix-defexpr/nixpkgs -</screen> - You may want to delete the symlink - <filename>~/.nix-defexpr/channels_root</filename> to prevent root’s NixOS - channel from clashing with your own tree (this may break the - command-not-found utility though). If you want to go back to the default - state, you may just remove the <filename>~/.nix-defexpr</filename> directory - completely, log out and log in again and it should have been recreated with a - link to the root channels. - </para> -<!-- FIXME: not sure what this means. -<para>You should not pass the base directory -<filename><replaceable>/my/sources</replaceable></filename> -to <command>nix-env</command>, as it will break after interpreting expressions -in <filename>nixos/</filename> as packages.</para> ---> -</chapter> diff --git a/nixos/doc/manual/from_md/development/sources.chapter.xml b/nixos/doc/manual/from_md/development/sources.chapter.xml new file mode 100644 index 00000000000..aac18c9d06c --- /dev/null +++ b/nixos/doc/manual/from_md/development/sources.chapter.xml @@ -0,0 +1,90 @@ +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-getting-sources"> + <title>Getting the Sources</title> + <para> + By default, NixOS’s <literal>nixos-rebuild</literal> command uses + the NixOS and Nixpkgs sources provided by the + <literal>nixos</literal> channel (kept in + <literal>/nix/var/nix/profiles/per-user/root/channels/nixos</literal>). + To modify NixOS, however, you should check out the latest sources + from Git. This is as follows: + </para> + <programlisting> +$ git clone https://github.com/NixOS/nixpkgs +$ cd nixpkgs +$ git remote update origin +</programlisting> + <para> + This will check out the latest Nixpkgs sources to + <literal>./nixpkgs</literal> the NixOS sources to + <literal>./nixpkgs/nixos</literal>. (The NixOS source tree lives in + a subdirectory of the Nixpkgs repository.) The + <literal>nixpkgs</literal> repository has branches that correspond + to each Nixpkgs/NixOS channel (see <xref linkend="sec-upgrading" /> + for more information about channels). Thus, the Git branch + <literal>origin/nixos-17.03</literal> will contain the latest built + and tested version available in the <literal>nixos-17.03</literal> + channel. + </para> + <para> + It’s often inconvenient to develop directly on the master branch, + since if somebody has just committed (say) a change to GCC, then the + binary cache may not have caught up yet and you’ll have to rebuild + everything from source. So you may want to create a local branch + based on your current NixOS version: + </para> + <programlisting> +$ nixos-version +17.09pre104379.6e0b727 (Hummingbird) + +$ git checkout -b local 6e0b727 +</programlisting> + <para> + Or, to base your local branch on the latest version available in a + NixOS channel: + </para> + <programlisting> +$ git remote update origin +$ git checkout -b local origin/nixos-17.03 +</programlisting> + <para> + (Replace <literal>nixos-17.03</literal> with the name of the channel + you want to use.) You can use <literal>git merge</literal> or + <literal>git rebase</literal> to keep your local branch in sync with + the channel, e.g. + </para> + <programlisting> +$ git remote update origin +$ git merge origin/nixos-17.03 +</programlisting> + <para> + You can use <literal>git cherry-pick</literal> to copy commits from + your local branch to the upstream branch. + </para> + <para> + If you want to rebuild your system using your (modified) sources, + you need to tell <literal>nixos-rebuild</literal> about them using + the <literal>-I</literal> flag: + </para> + <programlisting> +# nixos-rebuild switch -I nixpkgs=/my/sources/nixpkgs +</programlisting> + <para> + If you want <literal>nix-env</literal> to use the expressions in + <literal>/my/sources</literal>, use + <literal>nix-env -f /my/sources/nixpkgs</literal>, or change the + default by adding a symlink in <literal>~/.nix-defexpr</literal>: + </para> + <programlisting> +$ ln -s /my/sources/nixpkgs ~/.nix-defexpr/nixpkgs +</programlisting> + <para> + You may want to delete the symlink + <literal>~/.nix-defexpr/channels_root</literal> to prevent root’s + NixOS channel from clashing with your own tree (this may break the + command-not-found utility though). If you want to go back to the + default state, you may just remove the + <literal>~/.nix-defexpr</literal> directory completely, log out and + log in again and it should have been recreated with a link to the + root channels. + </para> +</chapter> |