max/nix-super
1
0
Fork 0
mirror of https://github.com/privatevoid-net/nix-super.git synced 2024-11-22 05:56:15 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Improve hacking.md

Browse source 
- Refer to current version in readme
- Split into flakes and non-flakes section
- Change order to move nix-build to the end, since people often start
  with it in the beginning.
- Use proper "Note" syntax
- Add notes about editor integration
- Move information about target platforms and stdenvs into separate
  sections

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
Co-authored-by: Alexander Bantyev <alexander.bantyev@tweag.io>
Co-authored-by: Théophane Hufschmitt <theophane.hufschmitt@tweag.io>
This commit is contained in:
Yorick van Pelt 2022-11-25 14:47:05 +01:00 committed by Alexander Bantyev
parent 012ddaa322
commit f2e427942d
No known key found for this signature in database
GPG key ID: E081FF12ADCB4AD5
3 changed files with 139 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
README.md
View file

@ -20,8 +20,8 @@ Information on additional installation methods is available on the [Nix download
## Building And Developing ## Building And Developing
See our [Hacking guide](https://nixos.org/manual/nix/stable/contributing/hacking.html) in our manual for instruction on how to See our [Hacking guide](https://nixos.org/manual/nix/unstable/contributing/hacking.html) in our manual for instruction on how to
build nix from source with nix-build or how to get a development environment. to set up a development environment and build Nix from source.
## Additional Resources ## Additional Resources

163
doc/manual/src/contributing/hacking.md
View file

@ -8,25 +8,64 @@ $ git clone https://github.com/NixOS/nix.git
$ cd nix $ cd nix
``` ```
To build Nix for the current operating system/architecture use 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
## Nix with flakes
This section assumes you are using Nix with [flakes] enabled. See the [next section](#classic-nix) for equivalent instructions which don't require flakes.
[flakes]: ../command-ref/new-cli/nix3-flake.md#description
To build all dependencies and start a shell in which all environment
variables are set up so that those dependencies can be found:
```console ```console
$ nix-build $ nix develop
``` ```
or if you have a flake-enabled nix: 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 .#clang11Stdenv
```
> **Note**
>
> 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:
```console
[nix-shell]$ ./bootstrap.sh
[nix-shell]$ ./configure $configureFlags --prefix=$(pwd)/outputs/out
[nix-shell]$ make -j $NIX_BUILD_CORES
```
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 (Nix) 2.12
```
To build a release version of Nix:
```console ```console
$ nix build $ nix build
``` ```
This will build `defaultPackage` attribute defined in the `flake.nix` You can also build Nix for one of the [supported target platforms](#target-platforms).
file. To build for other platforms add one of the following suffixes to
it: aarch64-linux, i686-linux, x86\_64-darwin, x86\_64-linux. i.e.
```console ## Classic Nix
$ nix-build -A defaultPackage.x86_64-linux
``` This section is for Nix without [flakes].
To build all dependencies and start a shell in which all environment To build all dependencies and start a shell in which all environment
variables are set up so that those dependencies can be found: variables are set up so that those dependencies can be found:
@ -35,27 +74,16 @@ variables are set up so that those dependencies can be found:
$ nix-shell $ nix-shell
``` ```
or if you have a flake-enabled nix: To get a shell with one of the other [supported compilation environments](#compilation-environments):
```console
$ nix develop
```
To get a shell with a different compilation environment (e.g. stdenv,
gccStdenv, clangStdenv, clang11Stdenv, ccacheStdenv):
```console ```console
$ nix-shell -A devShells.x86_64-linux.clang11Stdenv $ nix-shell -A devShells.x86_64-linux.clang11Stdenv
``` ```
or if you have a flake-enabled nix: > **Note**
>
```console > You can use `ccacheStdenv` to drastically improve rebuild time.
$ nix develop .#clang11Stdenv > By default, [ccache](https://ccache.dev) keeps artifacts in `~/.cache/ccache/`.
```
Note: you can use `ccacheStdenv` to drastically improve rebuild
time. By default, ccache keeps artifacts in `~/.cache/ccache/`.
To build Nix itself in this shell: To build Nix itself in this shell:
@ -71,21 +99,96 @@ To install it in `$(pwd)/outputs` and test it:
[nix-shell]$ make install [nix-shell]$ make install
[nix-shell]$ make installcheck -j $NIX_BUILD_CORES [nix-shell]$ make installcheck -j $NIX_BUILD_CORES
[nix-shell]$ ./outputs/out/bin/nix --version [nix-shell]$ ./outputs/out/bin/nix --version
nix (Nix) 3.0 nix (Nix) 2.12
``` ```
If you have a flakes-enabled Nix you can replace: To build Nix for the current operating system and CPU architecture use
```console ```console
$ nix-shell $ nix-build
``` ```
by: You can also build Nix for one of the [supported target platforms](#target-platforms).
## Target platforms
As specified in [`flake.nix`], Nix can be built for various platforms:
- `aarch64-linux`
- `i686-linux`
- `x86_64-darwin`
- `x86_64-linux`
[`flake.nix`]: https://github.com/nixos/nix/blob/master/flake.nix
In order to build Nix for a different platform than the one you're currently
one, you need to have some way for your system Nix to build code for that
platform. Common solutions include [remote builders] and [binfmt emulation]
(only supported on NixOS).
[remote builders]: ../advanced-topics/distributed-builds.md
[binfmt emulation]: https://nixos.org/manual/nixos/stable/options.html#opt-boot.binfmt.emulatedSystems
Once you are able to build for different platforms, executing the build is as simple as
```console ```console
$ nix develop $ nix build .#packages.aarch64-linux.default
``` ```
for flake-enabled Nix, or
```console
$ nix-build -A packages.aarch64-linux.default
```
for classic Nix.
You can use any of the other supported platforms in place of `aarch64-linux`.
## Compilation environments
Nix can be compiled using multiple environments:
- `stdenv`: default;
- `gccStdenv`: force the use of `gcc` compiler;
- `clangStdenv`: force the use of `clang` compiler;
- `ccacheStdenv`: enable [ccache], a compiler cache to speed up compilation.
To build with one of those environments, you can use
```console
$ nix build .#nix-ccacheStdenv
```
for flake-enabled Nix, or
```console
$ nix-build -A nix-ccacheStdenv
```
for classic Nix.
You can use any of the other supported environments in place of `nix-ccacheStdenv`.
## Editor integration
The `clangd` LSP server is installed by default on the `clang`-based `devShell`s.
See [supported compilation environments](#compilation-environments) and instructions how to set up a shell [with flakes](#nix-with-flakes) or in [classic Nix](#classic-nix).
To use the LSP with your editor, you first need to [set up `clangd`](https://clangd.llvm.org/installation#project-setup) by running:
```console
make clean && bear -- make -j$NIX_BUILD_CORES install
```
Configure your editor to use the `clangd` from the shell, either by running it inside the development shell, or by using [nix-direnv](https://github.com/nix-community/nix-direnv) and [the appropriate editor plugin](https://github.com/direnv/direnv/wiki#editor-integration).
> **Note**
>
> For some editors (e.g. Visual Studio Code), you may need to install a [special extension](https://open-vsx.org/extension/llvm-vs-code-extensions/vscode-clangd) for the editor to interact with `clangd`.
> Some other editors (e.g. Emacs, Vim) need a plugin to support LSP servers in general (e.g. [lsp-mode](https://github.com/emacs-lsp/lsp-mode) for Emacs and [vim-lsp](https://github.com/prabirshrestha/vim-lsp) for vim).
> Editor-specific setup is typically opinionated, so we will not cover it here in more detail.
## Running tests ## Running tests
### Unit-tests ### Unit-tests

5
flake.nix
View file

@ -701,7 +701,10 @@
outputs = [ "out" "dev" "doc" ]; outputs = [ "out" "dev" "doc" ];
nativeBuildInputs = nativeBuildDeps ++ [ clang-tools bear ]; nativeBuildInputs = nativeBuildDeps
++ (lib.optionals
nixpkgsFor.${system}.${stdenv}.cc.isClang
[ bear clang-tools ]);
buildInputs = buildDeps ++ propagatedDeps ++ awsDeps; buildInputs = buildDeps ++ propagatedDeps ++ awsDeps;
inherit configureFlags; inherit configureFlags;