nixos: nixos/doc/manual/development/sources.xml to CommonMark
This commit is contained in:
Bobby Rong
parent
09c38c29f2
commit
409934a6e5
4 changed files with 168 additions and 86 deletions
|
|
@ -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" />
|
||||
|
|
|
|||
77
nixos/doc/manual/development/sources.chapter.md
Normal file
77
nixos/doc/manual/development/sources.chapter.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -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>
|
||||
90
nixos/doc/manual/from_md/development/sources.chapter.xml
Normal file
90
nixos/doc/manual/from_md/development/sources.chapter.xml
Normal file
|
|
@ -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>
|
||||
Loading…
Reference in a new issue