From 409934a6e5f29ea9b9ac0ffc186b9a4772c4145a Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Sat, 3 Jul 2021 12:00:40 +0800 Subject: [PATCH] nixos: nixos/doc/manual/development/sources.xml to CommonMark --- nixos/doc/manual/development/development.xml | 2 +- .../doc/manual/development/sources.chapter.md | 77 ++++++++++++++++ nixos/doc/manual/development/sources.xml | 85 ------------------ .../from_md/development/sources.chapter.xml | 90 +++++++++++++++++++ 4 files changed, 168 insertions(+), 86 deletions(-) create mode 100644 nixos/doc/manual/development/sources.chapter.md delete mode 100644 nixos/doc/manual/development/sources.xml create mode 100644 nixos/doc/manual/from_md/development/sources.chapter.xml diff --git a/nixos/doc/manual/development/development.xml b/nixos/doc/manual/development/development.xml index eb505567962c..d536d877add7 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. - + diff --git a/nixos/doc/manual/development/sources.chapter.md b/nixos/doc/manual/development/sources.chapter.md new file mode 100644 index 000000000000..88173f7135bd --- /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 b333ccabb420..000000000000 --- a/nixos/doc/manual/development/sources.xml +++ /dev/null @@ -1,85 +0,0 @@ - - Getting the 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: - -$ 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 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: - -$ 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: - -$ 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. - -$ 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 - flag: - -# 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: - -$ 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/from_md/development/sources.chapter.xml b/nixos/doc/manual/from_md/development/sources.chapter.xml new file mode 100644 index 000000000000..aac18c9d06c8 --- /dev/null +++ b/nixos/doc/manual/from_md/development/sources.chapter.xml @@ -0,0 +1,90 @@ + + Getting the 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: + + +$ 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 + 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: + + +$ 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: + + +$ 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. + + +$ 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: + + +# 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: + + +$ 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. + +