From 77171b60560dc8d218ea606738525751cf3a3182 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Thu, 21 Sep 2023 02:52:44 +0200 Subject: [PATCH] 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. --- README.md | 3 +- doc/manual/src/SUMMARY.md.in | 6 +-- doc/manual/src/contributing/hacking.md | 53 +++++++++++++------------- 3 files changed, 30 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index dbca7a80f487..a044bc78d410 100644 --- 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 index 2e631058ff7b..5ed365312158 100644 --- 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 index db393942c27a..c70179b672f2 100644 --- 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).