manual: Contributing -> Development, Hacking -> Compiling

what's currently called "hacking" are really instructions for setting up a development environment and compiling from source. we have a contribution guide in the repo (which rightly focuses on GitHub workflows), and the material in the manual is more about working on the code itself. since we'd otherwise have three headings that amount to "Building Nix", this change also moves the "classic Nix" instructions to the top. we may want to reorganise this in the future, and bring contributor-oriented information closer to the code, but for now let's stick to more accurate names to ease navigation.
NixOS · Oct 5, 2023 · 77171b6 · 77171b6
1 parent d12fb4b
commit 77171b6
Show file tree

Hide file tree

Showing 3 changed files with 30 additions and 32 deletions.
diff --git a/README.md b/README.md
@@ -20,8 +20,7 @@ Information on additional installation methods is available on the [Nix download
 
 ## Building And Developing
 
-See our [Hacking guide](https://nixos.org/manual/nix/unstable/contributing/hacking.html) in our manual for instruction on how to
-to set up a development environment and build Nix from source.
+Follow instructions in the Nix manual to [set up a development environment and build Nix from source](https://nixos.org/manual/nix/unstable/contributing/hacking.html).
 
 ## Contributing
 

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
@@ -103,13 +103,13 @@
   - [Serving Tarball Flakes](protocols/tarball-fetcher.md)
   - [Derivation "ATerm" file format](protocols/derivation-aterm.md)
 - [Glossary](glossary.md)
-- [Contributing](contributing/contributing.md)
-  - [Hacking](contributing/hacking.md)
+- [Development](contributing/contributing.md)
+  - [Building](contributing/hacking.md)
   - [Testing](contributing/testing.md)
   - [Documentation](contributing/documentation.md)
-  - [Experimental Features](contributing/experimental-features.md)
   - [CLI guideline](contributing/cli-guideline.md)
   - [C++ style guide](contributing/cxx.md)
+  - [Experimental Features](contributing/experimental-features.md)
 - [Release Notes](release-notes/release-notes.md)
   - [Release X.Y (202?-??-??)](release-notes/rl-next.md)
   - [Release 2.18 (2023-09-20)](release-notes/rl-2.18.md)

diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
@@ -1,42 +1,33 @@
-# Hacking
+# Building Nix
 
-This section provides some notes on how to hack on Nix. To get the
-latest version of Nix from GitHub:
+This section provides some notes on how to start hacking on Nix.
+To get the latest version of Nix from GitHub:
 
 ```console
 $ git clone https://github.com/NixOS/nix.git
 $ cd nix
 ```
 
-The following instructions assume you already have some version of Nix installed locally, so that you can use it to set up the development environment. If you don't have it installed, follow the [installation instructions].
-
-[installation instructions]: ../installation/installation.md
-
-## Building Nix with flakes
-
-This section assumes you are using Nix with the [`flakes`] and [`nix-command`] experimental features enabled.
-See the [Building Nix](#building-nix) section for equivalent instructions using stable Nix interfaces.
-
-[`flakes`]: @docroot@/contributing/experimental-features.md#xp-feature-flakes
-[`nix-command`]: @docroot@/contributing/experimental-features.md#xp-nix-command
+> **Note**
+>
+> The following instructions assume you already have some version of Nix installed locally, so that you can use it to set up the development environment.
+> If you don't have it installed, follow the [installation instructions](../installation/installation.md).
 
 To build all dependencies and start a shell in which all environment variables are set up so that those dependencies can be found:
 
 ```console
-$ nix develop
+$ nix-shell
 ```
 
-This shell also adds `./outputs/bin/nix` to your `$PATH` so you can run `nix` immediately after building it.
-
 To get a shell with one of the other [supported compilation environments](#compilation-environments):
 
 ```console
-$ nix develop .#native-clang11StdenvPackages
+$ nix-shell --attr devShells.x86_64-linux.native-clang11StdenvPackages
 ```
 
 > **Note**
 >
-> Use `ccacheStdenv` to drastically improve rebuild time.
+> You can use `native-ccacheStdenvPackages` to drastically improve rebuild time.
 > By default, [ccache](https://ccache.dev) keeps artifacts in `~/.cache/ccache/`.
 
 To build Nix itself in this shell:
@@ -52,35 +43,43 @@ To install it in `$(pwd)/outputs` and test it:
 ```console
 [nix-shell]$ make install
 [nix-shell]$ make installcheck -j $NIX_BUILD_CORES
-[nix-shell]$ nix --version
+[nix-shell]$ ./outputs/out/bin/nix --version
 nix (Nix) 2.12
 ```
 
 To build a release version of Nix for the current operating system and CPU architecture:
 
 ```console
-$ nix build
+$ nix-build
 ```
 
 You can also build Nix for one of the [supported platforms](#platforms).
 
-## Building Nix
+## Building Nix with flakes
+
+This section assumes you are using Nix with the [`flakes`] and [`nix-command`] experimental features enabled.
+See the [Building Nix](#building-nix) section for equivalent instructions using stable Nix interfaces.
+
+[`flakes`]: @docroot@/contributing/experimental-features.md#xp-feature-flakes
+[`nix-command`]: @docroot@/contributing/experimental-features.md#xp-nix-command
 
 To build all dependencies and start a shell in which all environment variables are set up so that those dependencies can be found:
 
 ```console
-$ nix-shell
+$ nix develop
 ```
 
+This shell also adds `./outputs/bin/nix` to your `$PATH` so you can run `nix` immediately after building it.
+
 To get a shell with one of the other [supported compilation environments](#compilation-environments):
 
 ```console
-$ nix-shell --attr devShells.x86_64-linux.native-clang11StdenvPackages
+$ nix develop .#native-clang11StdenvPackages
 ```
 
 > **Note**
 >
-> You can use `native-ccacheStdenvPackages` to drastically improve rebuild time.
+> Use `ccacheStdenv` to drastically improve rebuild time.
 > By default, [ccache](https://ccache.dev) keeps artifacts in `~/.cache/ccache/`.
 
 To build Nix itself in this shell:
@@ -96,14 +95,14 @@ To install it in `$(pwd)/outputs` and test it:
 ```console
 [nix-shell]$ make install
 [nix-shell]$ make installcheck -j $NIX_BUILD_CORES
-[nix-shell]$ ./outputs/out/bin/nix --version
+[nix-shell]$ nix --version
 nix (Nix) 2.12
 ```
 
 To build a release version of Nix for the current operating system and CPU architecture:
 
 ```console
-$ nix-build
+$ nix build
 ```
 
 You can also build Nix for one of the [supported platforms](#platforms).