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

   1 # Getting the Sources {#sec-getting-sources}
   2
   3 By default, NixOS's `nixos-rebuild` command uses the NixOS and Nixpkgs
   4 sources provided by the `nixos` channel (kept in
   5 `/nix/var/nix/profiles/per-user/root/channels/nixos`). To modify NixOS,
   6 however, you should check out the latest sources from Git. This is as
   7 follows:
   8
   9 ```ShellSession
  10 $ git clone https://github.com/NixOS/nixpkgs
  11 $ cd nixpkgs
  12 $ git remote update origin
  13 ```
  14
  15 This will check out the latest Nixpkgs sources to `./nixpkgs` the NixOS
  16 sources to `./nixpkgs/nixos`. (The NixOS source tree lives in a
  17 subdirectory of the Nixpkgs repository.) The `nixpkgs` repository has
  18 branches that correspond to each Nixpkgs/NixOS channel (see
  19 [](#sec-upgrading) for more information about channels). Thus, the
  20 Git branch `origin/nixos-17.03` will contain the latest built and tested
  21 version available in the `nixos-17.03` channel.
  22
  23 It's often inconvenient to develop directly on the master branch, since
  24 if somebody has just committed (say) a change to GCC, then the binary
  25 cache may not have caught up yet and you'll have to rebuild everything
  26 from source. So you may want to create a local branch based on your
  27 current NixOS version:
  28
  29 ```ShellSession
  30 $ nixos-version
  31 17.09pre104379.6e0b727 (Hummingbird)
  32
  33 $ git checkout -b local 6e0b727
  34 ```
  35
  36 Or, to base your local branch on the latest version available in a NixOS
  37 channel:
  38
  39 ```ShellSession
  40 $ git remote update origin
  41 $ git checkout -b local origin/nixos-17.03
  42 ```
  43
  44 (Replace `nixos-17.03` with the name of the channel you want to use.)
  45 You can use `git merge` or `git
  46   rebase` to keep your local branch in sync with the channel, e.g.
  47
  48 ```ShellSession
  49 $ git remote update origin
  50 $ git merge origin/nixos-17.03
  51 ```
  52
  53 You can use `git cherry-pick` to copy commits from your local branch to
  54 the upstream branch.
  55
  56 If you want to rebuild your system using your (modified) sources, you
  57 need to tell `nixos-rebuild` about them using the `-I` flag:
  58
  59 ```ShellSession
  60 # nixos-rebuild switch -I nixpkgs=/my/sources/nixpkgs
  61 ```
  62
  63 If you want `nix-env` to use the expressions in `/my/sources`, use
  64 `nix-env -f
  65   /my/sources/nixpkgs`, or change the default by adding a symlink in
  66 `~/.nix-defexpr`:
  67
  68 ```ShellSession
  69 $ ln -s /my/sources/nixpkgs ~/.nix-defexpr/nixpkgs
  70 ```
  71
  72 You may want to delete the symlink `~/.nix-defexpr/channels_root` to
  73 prevent root's NixOS channel from clashing with your own tree (this may
  74 break the command-not-found utility though). If you want to go back to
  75 the default state, you may just remove the `~/.nix-defexpr` directory
  76 completely, log out and log in again and it should have been recreated
  77 with a link to the root channels.