mirror of
https://github.com/privatevoid-net/nix-super.git
synced 2024-11-21 21:46:15 +02:00
manual: Contributing -> Development, Hacking -> Building (#9014)
* manual: Contributing -> Development, Hacking -> Building 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.
This commit is contained in:
parent
dba1142c01
commit
a2fed6db9e
40 changed files with 214 additions and 201 deletions
|
@ -41,9 +41,9 @@ Check out the [security policy](https://github.com/NixOS/nix/security/policy).
|
|||
There are many open pull requests that might already do what you intend to work on.
|
||||
You can use [labels](https://github.com/NixOS/nix/labels) to filter for relevant topics.
|
||||
|
||||
3. Check the [Nix reference manual](https://nixos.org/manual/nix/unstable/contributing/hacking.html) for information on building Nix and running its tests.
|
||||
3. Check the [Nix reference manual](https://nix.dev/manual/nix/development/development/building.html) for information on building Nix and running its tests.
|
||||
|
||||
For contributions to the command line interface, please check the [CLI guidelines](https://nixos.org/manual/nix/unstable/contributing/cli-guideline.html).
|
||||
For contributions to the command line interface, please check the [CLI guidelines](https://nix.dev/manual/nix/development/development/cli-guideline.html).
|
||||
|
||||
4. Make your change!
|
||||
|
||||
|
@ -69,7 +69,7 @@ Check out the [security policy](https://github.com/NixOS/nix/security/policy).
|
|||
- [ ] API documentation in header files
|
||||
- [ ] Code and comments are self-explanatory
|
||||
- [ ] Commit message explains **why** the change was made
|
||||
- [ ] New feature or incompatible change: [add a release note](https://nixos.org/manual/nix/stable/contributing/hacking#add-a-release-note)
|
||||
- [ ] New feature or incompatible change: [add a release note](https://nix.dev/manual/nix/development/development/contributing.html#add-a-release-note)
|
||||
|
||||
7. If you need additional feedback or help to getting pull request into shape, ask other contributors using [@mentions](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams).
|
||||
|
||||
|
@ -78,7 +78,7 @@ Check out the [security policy](https://github.com/NixOS/nix/security/policy).
|
|||
The Nix reference manual is hosted on https://nixos.org/manual/nix.
|
||||
The underlying source files are located in [`doc/manual/src`](./doc/manual/src).
|
||||
For small changes you can [use GitHub to edit these files](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files)
|
||||
For larger changes see the [Nix reference manual](https://nixos.org/manual/nix/unstable/contributing/hacking.html).
|
||||
For larger changes see the [Nix reference manual](https://nix.dev/manual/nix/development/development/contributing.html).
|
||||
|
||||
## Getting help
|
||||
|
||||
|
|
|
@ -4,19 +4,18 @@
|
|||
[![Test](https://github.com/NixOS/nix/workflows/Test/badge.svg)](https://github.com/NixOS/nix/actions)
|
||||
|
||||
Nix is a powerful package manager for Linux and other Unix systems that makes package
|
||||
management reliable and reproducible. Please refer to the [Nix manual](https://nixos.org/nix/manual)
|
||||
management reliable and reproducible. Please refer to the [Nix manual](https://nix.dev/reference/nix-manual)
|
||||
for more details.
|
||||
|
||||
## Installation and first steps
|
||||
|
||||
Visit [nix.dev](https://nix.dev) for [installation instructions](https://nix.dev/tutorials/install-nix) and [beginner tutorials](https://nix.dev/tutorials/first-steps).
|
||||
|
||||
Full reference documentation can be found in the [Nix manual](https://nixos.org/nix/manual).
|
||||
Full reference documentation can be found in the [Nix manual](https://nix.dev/reference/nix-manual).
|
||||
|
||||
## Building and developing
|
||||
|
||||
See our [Hacking guide](https://nixos.org/manual/nix/unstable/contributing/hacking.html) in our manual for instruction on how to
|
||||
set up a development environment and build Nix from source.
|
||||
Follow instructions in the Nix reference manual to [set up a development environment and build Nix from source](https://nix.dev/manual/nix/development/development/building.html).
|
||||
|
||||
## Contributing
|
||||
|
||||
|
|
|
@ -12,7 +12,7 @@ let
|
|||
experimentalNotice = optionalString (experimental-feature != null) ''
|
||||
> **Note**
|
||||
>
|
||||
> This function is only available if the [`${experimental-feature}` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-${experimental-feature}) is enabled.
|
||||
> This function is only available if the [`${experimental-feature}` experimental feature](@docroot@/development/experimental-features.md#xp-feature-${experimental-feature}) is enabled.
|
||||
>
|
||||
> For example, include the following in [`nix.conf`](@docroot@/command-ref/conf-file.md):
|
||||
>
|
||||
|
|
|
@ -38,7 +38,7 @@ let
|
|||
result = ''
|
||||
> **Warning** \
|
||||
> This program is
|
||||
> [**experimental**](@docroot@/contributing/experimental-features.md#xp-feature-nix-command)
|
||||
> [**experimental**](@docroot@/development/experimental-features.md#xp-feature-nix-command)
|
||||
> and its interface is subject to change.
|
||||
|
||||
# Name
|
||||
|
|
|
@ -33,10 +33,10 @@ let
|
|||
> **Warning**
|
||||
>
|
||||
> This setting is part of an
|
||||
> [experimental feature](@docroot@/contributing/experimental-features.md).
|
||||
> [experimental feature](@docroot@/development/experimental-features.md).
|
||||
>
|
||||
> To change this setting, make sure the
|
||||
> [`${experimentalFeature}` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-${experimentalFeature})
|
||||
> [`${experimentalFeature}` experimental feature](@docroot@/development/experimental-features.md#xp-feature-${experimentalFeature})
|
||||
> is enabled.
|
||||
> For example, include the following in [`nix.conf`](@docroot@/command-ref/conf-file.md):
|
||||
>
|
||||
|
|
|
@ -32,10 +32,10 @@ let
|
|||
> **Warning**
|
||||
>
|
||||
> This store is part of an
|
||||
> [experimental feature](@docroot@/contributing/experimental-features.md).
|
||||
> [experimental feature](@docroot@/development/experimental-features.md).
|
||||
>
|
||||
> To use this store, make sure the
|
||||
> [`${experimentalFeature}` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-${experimentalFeature})
|
||||
> [`${experimentalFeature}` experimental feature](@docroot@/development/experimental-features.md#xp-feature-${experimentalFeature})
|
||||
> is enabled.
|
||||
> For example, include the following in [`nix.conf`](@docroot@/command-ref/conf-file.md):
|
||||
>
|
||||
|
|
|
@ -4,6 +4,6 @@ with import <nix/utils.nix>;
|
|||
let
|
||||
showExperimentalFeature = name: doc:
|
||||
''
|
||||
- [`${name}`](@docroot@/contributing/experimental-features.md#xp-feature-${name})
|
||||
- [`${name}`](@docroot@/development/experimental-features.md#xp-feature-${name})
|
||||
'';
|
||||
in xps: indent " " (concatStrings (attrValues (mapAttrs showExperimentalFeature xps)))
|
||||
|
|
|
@ -95,7 +95,7 @@ $(d)/nix-profiles.5: $(d)/src/command-ref/files/profiles.md
|
|||
$(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@
|
||||
@rm $^.tmp
|
||||
|
||||
$(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/SUMMARY-rl-next.md $(d)/src/store/types $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md
|
||||
$(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/SUMMARY-rl-next.md $(d)/src/store/types $(d)/src/command-ref/new-cli $(d)/src/development/experimental-feature-descriptions.md
|
||||
@cp $< $@
|
||||
@$(call process-includes,$@,$@)
|
||||
|
||||
|
@ -124,7 +124,7 @@ $(d)/conf-file.json: $(doc_nix)
|
|||
$(trace-gen) $(dummy-env) $(doc_nix) config show --json --experimental-features nix-command > $@.tmp
|
||||
@mv $@.tmp $@
|
||||
|
||||
$(d)/src/contributing/experimental-feature-descriptions.md: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features.nix $(doc_nix)
|
||||
$(d)/src/development/experimental-feature-descriptions.md: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features.nix $(doc_nix)
|
||||
@rm -rf $@ $@.tmp
|
||||
$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-xp-features.nix (builtins.fromJSON (builtins.readFile $<))'
|
||||
@mv $@.tmp $@
|
||||
|
@ -207,11 +207,11 @@ doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
|
|||
done
|
||||
@touch $@
|
||||
|
||||
# the `! -name 'contributing.md'` filter excludes the one place where
|
||||
# the `! -name 'documentation.md'` filter excludes the one place where
|
||||
# `@docroot@` is to be preserved for documenting the mechanism
|
||||
# FIXME: maybe contributing guides should live right next to the code
|
||||
# instead of in the manual
|
||||
$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/store/types $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md $(d)/src/release-notes/rl-next.md $(d)/src/figures $(d)/src/favicon.png $(d)/src/favicon.svg
|
||||
$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/store/types $(d)/src/command-ref/new-cli $(d)/src/development/experimental-feature-descriptions.md $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md $(d)/src/release-notes/rl-next.md $(d)/src/figures $(d)/src/favicon.png $(d)/src/favicon.svg
|
||||
$(trace-gen) \
|
||||
tmp="$$(mktemp -d)"; \
|
||||
cp -r doc/manual "$$tmp"; \
|
||||
|
|
|
@ -143,7 +143,7 @@ const redirects = {
|
|||
"opt-timeout": "command-ref/opt-common.html#opt-timeout",
|
||||
"sec-common-options": "command-ref/opt-common.html",
|
||||
"ch-utilities": "command-ref/utilities.html",
|
||||
"chap-hacking": "contributing/hacking.html",
|
||||
"chap-hacking": "development/building.html",
|
||||
"adv-attr-allowSubstitutes": "language/advanced-attributes.html#adv-attr-allowSubstitutes",
|
||||
"adv-attr-allowedReferences": "language/advanced-attributes.html#adv-attr-allowedReferences",
|
||||
"adv-attr-allowedRequisites": "language/advanced-attributes.html#adv-attr-allowedRequisites",
|
||||
|
@ -350,7 +350,7 @@ const redirects = {
|
|||
"macos": "uninstall.html#macos",
|
||||
"uninstalling": "uninstall.html",
|
||||
},
|
||||
"contributing/hacking.html": {
|
||||
"development/building.html": {
|
||||
"nix-with-flakes": "#building-nix-with-flakes",
|
||||
"classic-nix": "#building-nix",
|
||||
"running-tests": "testing.html#running-tests",
|
||||
|
@ -361,7 +361,12 @@ const redirects = {
|
|||
"installer-tests": "testing.html#installer-tests",
|
||||
"one-time-setup": "testing.html#one-time-setup",
|
||||
"using-the-ci-generated-installer-for-manual-testing": "testing.html#using-the-ci-generated-installer-for-manual-testing",
|
||||
"characterization-testing": "#characterisation-testing-unit",
|
||||
"characterization-testing": "testing.html#characterisation-testing-unit",
|
||||
"add-a-release-note": "contributing.html#add-a-release-note",
|
||||
"add-an-entry": "contributing.html#add-an-entry",
|
||||
"build-process": "contributing.html#build-process",
|
||||
"reverting": "contributing.html#reverting",
|
||||
"branches": "contributing.html#branches",
|
||||
},
|
||||
"glossary.html": {
|
||||
"gloss-local-store": "store/types/local-store.html",
|
||||
|
|
|
@ -116,14 +116,15 @@
|
|||
- [Derivation "ATerm" file format](protocols/derivation-aterm.md)
|
||||
- [C API](c-api.md)
|
||||
- [Glossary](glossary.md)
|
||||
- [Contributing](contributing/index.md)
|
||||
- [Hacking](contributing/hacking.md)
|
||||
- [Testing](contributing/testing.md)
|
||||
- [Documentation](contributing/documentation.md)
|
||||
- [Experimental Features](contributing/experimental-features.md)
|
||||
- [CLI guideline](contributing/cli-guideline.md)
|
||||
- [JSON guideline](contributing/json-guideline.md)
|
||||
- [C++ style guide](contributing/cxx.md)
|
||||
- [Development](development/index.md)
|
||||
- [Building](development/building.md)
|
||||
- [Testing](development/testing.md)
|
||||
- [Documentation](development/documentation.md)
|
||||
- [CLI guideline](development/cli-guideline.md)
|
||||
- [JSON guideline](development/json-guideline.md)
|
||||
- [C++ style guide](development/cxx.md)
|
||||
- [Experimental Features](development/experimental-features.md)
|
||||
- [Contributing](development/contributing.md)
|
||||
- [Releases](release-notes/index.md)
|
||||
{{#include ./SUMMARY-rl-next.md}}
|
||||
- [Release 2.23 (2024-06-03)](release-notes/rl-2.23.md)
|
||||
|
|
|
@ -20,7 +20,15 @@
|
|||
|
||||
/command-ref/command-ref /command-ref 301!
|
||||
|
||||
/contributing/contributing /contributing 301!
|
||||
/contributing/contributing /development 301!
|
||||
/contributing /development 301!
|
||||
/contributing/hacking /development/building 301!
|
||||
/contributing/testing /development/testing 301!
|
||||
/contributing/documentation /development/documentation 301!
|
||||
/contributing/experimental-features /development/experimental-features 301!
|
||||
/contributing/cli-guideline /development/cli-guideline 301!
|
||||
/contributing/json-guideline /development/json-guideline 301!
|
||||
/contributing/cxx /development/cxx 301!
|
||||
|
||||
/expressions/expression-language /language/ 301!
|
||||
/expressions/language-constructs /language/constructs 301!
|
||||
|
|
|
@ -10,7 +10,7 @@ See:
|
|||
- [Matrix Room *Nix Bindings*](https://matrix.to/#/#nix-bindings:nixos.org) for discussion and questions.
|
||||
- [Stabilisation Milestone](https://github.com/NixOS/nix/milestone/52)
|
||||
- [Other C API PRs and issues](https://github.com/NixOS/nix/labels/c%20api)
|
||||
- [Contributing C API Documentation](contributing/documentation.md#c-api-documentation), including how to build it locally.
|
||||
- [Contributing C API Documentation](development/documentation.md#c-api-documentation), including how to build it locally.
|
||||
|
||||
[Getting Started]: https://hydra.nixos.org/job/nix/master/external-api-docs/latest/download-by-type/doc/external-api-docs
|
||||
[Index]: https://hydra.nixos.org/job/nix/master/external-api-docs/latest/download-by-type/doc/external-api-docs/globals.html
|
||||
|
|
|
@ -1,6 +1,6 @@
|
|||
# Experimental Commands
|
||||
|
||||
This section lists [experimental commands](@docroot@/contributing/experimental-features.md#xp-feature-nix-command).
|
||||
This section lists [experimental commands](@docroot@/development/experimental-features.md#xp-feature-nix-command).
|
||||
|
||||
> **Warning**
|
||||
>
|
||||
|
|
|
@ -32,7 +32,7 @@ If no substitutes are available and no store derivation is given, realisation fa
|
|||
[store objects]: @docroot@/store/store-object.md
|
||||
[closure]: @docroot@/glossary.md#gloss-closure
|
||||
[substituters]: @docroot@/command-ref/conf-file.md#conf-substituters
|
||||
[content-addressed derivations]: @docroot@/contributing/experimental-features.md#xp-feature-ca-derivations
|
||||
[content-addressed derivations]: @docroot@/development/experimental-features.md#xp-feature-ca-derivations
|
||||
[Nix database]: @docroot@/glossary.md#gloss-nix-database
|
||||
|
||||
The resulting paths are printed on standard output.
|
||||
|
|
|
@ -1,24 +1,67 @@
|
|||
# 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].
|
||||
> **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/index.md).
|
||||
|
||||
[installation instructions]: ../installation/index.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-shell
|
||||
```
|
||||
|
||||
To get a shell with one of the other [supported compilation environments](#compilation-environments):
|
||||
|
||||
```console
|
||||
$ nix-shell --attr devShells.x86_64-linux.native-clangStdenvPackages
|
||||
```
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> 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:
|
||||
|
||||
```console
|
||||
[nix-shell]$ autoreconfPhase
|
||||
[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]$ ./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
|
||||
```
|
||||
|
||||
You can also build Nix for one of the [supported platforms](#platforms).
|
||||
|
||||
## 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
|
||||
[`flakes`]: @docroot@/development/experimental-features.md#xp-feature-flakes
|
||||
[`nix-command`]: @docroot@/development/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:
|
||||
|
||||
|
@ -67,50 +110,6 @@ $ nix build
|
|||
|
||||
You can also build Nix for one of the [supported platforms](#platforms).
|
||||
|
||||
## Building Nix
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
To get a shell with one of the other [supported compilation environments](#compilation-environments):
|
||||
|
||||
```console
|
||||
$ nix-shell --attr devShells.x86_64-linux.native-clangStdenvPackages
|
||||
```
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> 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:
|
||||
|
||||
```console
|
||||
[nix-shell]$ autoreconfPhase
|
||||
[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]$ ./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
|
||||
```
|
||||
|
||||
You can also build Nix for one of the [supported platforms](#platforms).
|
||||
|
||||
## Makefile variables
|
||||
|
||||
You may need `profiledir=$out/etc/profile.d` and `sysconfdir=$out/etc` to run `make install`.
|
||||
|
@ -294,81 +293,3 @@ If it fails, run `git add --patch` to approve the suggestions _and commit again_
|
|||
To refresh pre-commit hook's config file, do the following:
|
||||
1. Exit the development shell and start it again by running `nix develop`.
|
||||
2. If you also use the pre-commit hook, also run `pre-commit-hooks-install` again.
|
||||
|
||||
## Add a release note
|
||||
|
||||
`doc/manual/rl-next` contains release notes entries for all unreleased changes.
|
||||
|
||||
User-visible changes should come with a release note.
|
||||
|
||||
### Add an entry
|
||||
|
||||
Here's what a complete entry looks like. The file name is not incorporated in the document.
|
||||
|
||||
```
|
||||
---
|
||||
synopsis: Basically a title
|
||||
issues: 1234
|
||||
prs: 1238
|
||||
---
|
||||
|
||||
Here's one or more paragraphs that describe the change.
|
||||
|
||||
- It's markdown
|
||||
- Add references to the manual using @docroot@
|
||||
```
|
||||
|
||||
Significant changes should add the following header, which moves them to the top.
|
||||
|
||||
```
|
||||
significance: significant
|
||||
```
|
||||
|
||||
<!-- Keep an eye on https://codeberg.org/fgaz/changelog-d/issues/1 -->
|
||||
See also the [format documentation](https://github.com/haskell/cabal/blob/master/CONTRIBUTING.md#changelog).
|
||||
|
||||
### Build process
|
||||
|
||||
Releases have a precomputed `rl-MAJOR.MINOR.md`, and no `rl-next.md`.
|
||||
|
||||
## Branches
|
||||
|
||||
- [`master`](https://github.com/NixOS/nix/commits/master)
|
||||
|
||||
The main development branch. All changes are approved and merged here.
|
||||
When developing a change, create a branch based on the latest `master`.
|
||||
|
||||
Maintainers try to [keep it in a release-worthy state](#reverting).
|
||||
|
||||
- [`maintenance-*.*`](https://github.com/NixOS/nix/branches/all?query=maintenance)
|
||||
|
||||
These branches are the subject of backports only, and are
|
||||
also [kept](#reverting) in a release-worthy state.
|
||||
|
||||
See [`maintainers/backporting.md`](https://github.com/NixOS/nix/blob/master/maintainers/backporting.md)
|
||||
|
||||
- [`latest-release`](https://github.com/NixOS/nix/tree/latest-release)
|
||||
|
||||
The latest patch release of the latest minor version.
|
||||
|
||||
See [`maintainers/release-process.md`](https://github.com/NixOS/nix/blob/master/maintainers/release-process.md)
|
||||
|
||||
- [`backport-*-to-*`](https://github.com/NixOS/nix/branches/all?query=backport)
|
||||
|
||||
Generally branches created by the backport action.
|
||||
|
||||
See [`maintainers/backporting.md`](https://github.com/NixOS/nix/blob/master/maintainers/backporting.md)
|
||||
|
||||
- [_other_](https://github.com/NixOS/nix/branches/all)
|
||||
|
||||
Branches that do not conform to the above patterns should be feature branches.
|
||||
|
||||
## Reverting
|
||||
|
||||
If a change turns out to be merged by mistake, or contain a regression, it may be reverted.
|
||||
A revert is not a rejection of the contribution, but merely part of an effective development process.
|
||||
It makes sure that development keeps running smoothly, with minimal uncertainty, and less overhead.
|
||||
If maintainers have to worry too much about avoiding reverts, they would not be able to merge as much.
|
||||
By embracing reverts as a good part of the development process, everyone wins.
|
||||
|
||||
However, taking a step back may be frustrating, so maintainers will be extra supportive on the next try.
|
79
doc/manual/src/development/contributing.md
Normal file
79
doc/manual/src/development/contributing.md
Normal file
|
@ -0,0 +1,79 @@
|
|||
# Contributing
|
||||
|
||||
## Add a release note
|
||||
|
||||
`doc/manual/rl-next` contains release notes entries for all unreleased changes.
|
||||
|
||||
User-visible changes should come with a release note.
|
||||
|
||||
### Add an entry
|
||||
|
||||
Here's what a complete entry looks like. The file name is not incorporated in the document.
|
||||
|
||||
```
|
||||
---
|
||||
synopsis: Basically a title
|
||||
issues: 1234
|
||||
prs: 1238
|
||||
---
|
||||
|
||||
Here's one or more paragraphs that describe the change.
|
||||
|
||||
- It's markdown
|
||||
- Add references to the manual using @docroot@
|
||||
```
|
||||
|
||||
Significant changes should add the following header, which moves them to the top.
|
||||
|
||||
```
|
||||
significance: significant
|
||||
```
|
||||
|
||||
<!-- Keep an eye on https://codeberg.org/fgaz/changelog-d/issues/1 -->
|
||||
See also the [format documentation](https://github.com/haskell/cabal/blob/master/CONTRIBUTING.md#changelog).
|
||||
|
||||
### Build process
|
||||
|
||||
Releases have a precomputed `rl-MAJOR.MINOR.md`, and no `rl-next.md`.
|
||||
|
||||
## Branches
|
||||
|
||||
- [`master`](https://github.com/NixOS/nix/commits/master)
|
||||
|
||||
The main development branch. All changes are approved and merged here.
|
||||
When developing a change, create a branch based on the latest `master`.
|
||||
|
||||
Maintainers try to [keep it in a release-worthy state](#reverting).
|
||||
|
||||
- [`maintenance-*.*`](https://github.com/NixOS/nix/branches/all?query=maintenance)
|
||||
|
||||
These branches are the subject of backports only, and are
|
||||
also [kept](#reverting) in a release-worthy state.
|
||||
|
||||
See [`maintainers/backporting.md`](https://github.com/NixOS/nix/blob/master/maintainers/backporting.md)
|
||||
|
||||
- [`latest-release`](https://github.com/NixOS/nix/tree/latest-release)
|
||||
|
||||
The latest patch release of the latest minor version.
|
||||
|
||||
See [`maintainers/release-process.md`](https://github.com/NixOS/nix/blob/master/maintainers/release-process.md)
|
||||
|
||||
- [`backport-*-to-*`](https://github.com/NixOS/nix/branches/all?query=backport)
|
||||
|
||||
Generally branches created by the backport action.
|
||||
|
||||
See [`maintainers/backporting.md`](https://github.com/NixOS/nix/blob/master/maintainers/backporting.md)
|
||||
|
||||
- [_other_](https://github.com/NixOS/nix/branches/all)
|
||||
|
||||
Branches that do not conform to the above patterns should be feature branches.
|
||||
|
||||
## Reverting
|
||||
|
||||
If a change turns out to be merged by mistake, or contain a regression, it may be reverted.
|
||||
A revert is not a rejection of the contribution, but merely part of an effective development process.
|
||||
It makes sure that development keeps running smoothly, with minimal uncertainty, and less overhead.
|
||||
If maintainers have to worry too much about avoiding reverts, they would not be able to merge as much.
|
||||
By embracing reverts as a good part of the development process, everyone wins.
|
||||
|
||||
However, taking a step back may be frustrating, so maintainers will be extra supportive on the next try.
|
|
@ -24,7 +24,7 @@ nix build .#^doc
|
|||
|
||||
and open `./result-doc/share/doc/nix/manual/index.html`.
|
||||
|
||||
To build the manual incrementally, [enter the development shell](./hacking.md) and run:
|
||||
To build the manual incrementally, [enter the development shell](./building.md) and run:
|
||||
|
||||
```console
|
||||
make manual-html-open -j $NIX_BUILD_CORES
|
|
@ -5,4 +5,4 @@ Check the [contributing guide](https://github.com/NixOS/nix/blob/master/CONTRIBU
|
|||
|
||||
This chapter is a collection of guides for making changes to the code and documentation.
|
||||
|
||||
If you're not sure where to start, try to [compile Nix from source](./hacking.md) and consider [making improvements to documentation](./documentation.md).
|
||||
If you're not sure where to start, try to [compile Nix from source](./building.md) and consider [making improvements to documentation](./documentation.md).
|
|
@ -168,7 +168,7 @@
|
|||
|
||||
- [impure derivation]{#gloss-impure-derivation}
|
||||
|
||||
[An experimental feature](#@docroot@/contributing/experimental-features.md#xp-feature-impure-derivations) that allows derivations to be explicitly marked as impure,
|
||||
[An experimental feature](#@docroot@/development/experimental-features.md#xp-feature-impure-derivations) that allows derivations to be explicitly marked as impure,
|
||||
so that they are always rebuilt, and their outputs not reused by subsequent calls to realise them.
|
||||
|
||||
- [Nix database]{#gloss-nix-database}
|
||||
|
@ -353,7 +353,7 @@
|
|||
Not yet stabilized functionality guarded by named experimental feature flags.
|
||||
These flags are enabled or disabled with the [`experimental-features`](./command-ref/conf-file.html#conf-experimental-features) setting.
|
||||
|
||||
See the contribution guide on the [purpose and lifecycle of experimental feaures](@docroot@/contributing/experimental-features.md).
|
||||
See the contribution guide on the [purpose and lifecycle of experimental feaures](@docroot@/development/experimental-features.md).
|
||||
|
||||
|
||||
[Nix language]: ./language/index.md
|
||||
|
|
|
@ -77,7 +77,7 @@ $ su root
|
|||
# Installing from a binary tarball
|
||||
|
||||
You can also download a binary tarball that contains Nix and all its dependencies:
|
||||
- Choose a [version](https://releases.nixos.org/?prefix=nix/) and [system type](../contributing/hacking.md#platforms)
|
||||
- Choose a [version](https://releases.nixos.org/?prefix=nix/) and [system type](../development/building.md#platforms)
|
||||
- Download and unpack the tarball
|
||||
- Run the installer
|
||||
|
||||
|
|
|
@ -113,7 +113,7 @@ Derivations can declare some infrequently used optional attributes.
|
|||
> `nix-build`.
|
||||
|
||||
If the [`configurable-impure-env` experimental
|
||||
feature](@docroot@/contributing/experimental-features.md#xp-feature-configurable-impure-env)
|
||||
feature](@docroot@/development/experimental-features.md#xp-feature-configurable-impure-env)
|
||||
is enabled, these environment variables can also be controlled
|
||||
through the
|
||||
[`impure-env`](@docroot@/command-ref/conf-file.md#conf-impure-env)
|
||||
|
@ -226,7 +226,7 @@ Derivations can declare some infrequently used optional attributes.
|
|||
- [`__contentAddressed`]{#adv-attr-__contentAddressed}
|
||||
|
||||
> **Warning**
|
||||
> This attribute is part of an [experimental feature](@docroot@/contributing/experimental-features.md).
|
||||
> This attribute is part of an [experimental feature](@docroot@/development/experimental-features.md).
|
||||
>
|
||||
> To use this attribute, you must enable the
|
||||
> [`ca-derivations`][xp-feature-ca-derivations] experimental feature.
|
||||
|
@ -370,6 +370,6 @@ Derivations can declare some infrequently used optional attributes.
|
|||
|
||||
ensures that the derivation can only be built on a machine with the `kvm` feature.
|
||||
|
||||
[xp-feature-ca-derivations]: @docroot@/contributing/experimental-features.md#xp-feature-ca-derivations
|
||||
[xp-feature-dynamic-derivations]: @docroot@/contributing/experimental-features.md#xp-feature-dynamic-derivations
|
||||
[xp-feature-git-hashing]: @docroot@/contributing/experimental-features.md#xp-feature-git-hashing
|
||||
[xp-feature-ca-derivations]: @docroot@/development/experimental-features.md#xp-feature-ca-derivations
|
||||
[xp-feature-dynamic-derivations]: @docroot@/development/experimental-features.md#xp-feature-dynamic-derivations
|
||||
[xp-feature-git-hashing]: @docroot@/development/experimental-features.md#xp-feature-git-hashing
|
||||
|
|
|
@ -14,6 +14,6 @@ Derivations are serialised in one of the following formats:
|
|||
DrvWithVersion(<version-string>, ...)
|
||||
```
|
||||
|
||||
The only `version-string`s that are in use today are for [experimental features](@docroot@/contributing/experimental-features.md):
|
||||
The only `version-string`s that are in use today are for [experimental features](@docroot@/development/experimental-features.md):
|
||||
|
||||
- `"xp-dyn-drv"` for the [`dynamic-derivations`](@docroot@/contributing/experimental-features.md#xp-feature-dynamic-derivations) experimental feature.
|
||||
- `"xp-dyn-drv"` for the [`dynamic-derivations`](@docroot@/development/experimental-features.md#xp-feature-dynamic-derivations) experimental feature.
|
||||
|
|
|
@ -3,7 +3,7 @@
|
|||
> **Warning**
|
||||
>
|
||||
> This JSON format is currently
|
||||
> [**experimental**](@docroot@/contributing/experimental-features.md#xp-feature-nix-command)
|
||||
> [**experimental**](@docroot@/development/experimental-features.md#xp-feature-nix-command)
|
||||
> and subject to change.
|
||||
|
||||
The JSON serialization of a
|
||||
|
|
|
@ -3,7 +3,7 @@
|
|||
> **Warning**
|
||||
>
|
||||
> This JSON format is currently
|
||||
> [**experimental**](@docroot@/contributing/experimental-features.md#xp-feature-nix-command)
|
||||
> [**experimental**](@docroot@/development/experimental-features.md#xp-feature-nix-command)
|
||||
> and subject to change.
|
||||
|
||||
Info about a [store object].
|
||||
|
|
|
@ -13,7 +13,7 @@
|
|||
|
||||
- The `discard-references` feature has been stabilized.
|
||||
This means that the
|
||||
[unsafeDiscardReferences](@docroot@/contributing/experimental-features.md#xp-feature-discard-references)
|
||||
[unsafeDiscardReferences](@docroot@/development/experimental-features.md#xp-feature-discard-references)
|
||||
attribute is no longer guarded by an experimental flag and can be used
|
||||
freely.
|
||||
|
||||
|
@ -21,7 +21,7 @@
|
|||
This only affects `nix-build --json` when "building" non-derivation things like fetched sources, which is a no-op.
|
||||
|
||||
- A new builtin [`outputOf`](@docroot@/language/builtins.md#builtins-outputOf) has been added.
|
||||
It is part of the [`dynamic-derivations`](@docroot@/contributing/experimental-features.md#xp-feature-dynamic-derivations) experimental feature.
|
||||
It is part of the [`dynamic-derivations`](@docroot@/development/experimental-features.md#xp-feature-dynamic-derivations) experimental feature.
|
||||
|
||||
- Flake follow paths at depths greater than 2 are now handled correctly, preventing "follows a non-existent input" errors.
|
||||
|
||||
|
|
|
@ -17,8 +17,8 @@
|
|||
|
||||
- `nix-shell` shebang lines now support single-quoted arguments.
|
||||
|
||||
- `builtins.fetchTree` is now its own experimental feature, [`fetch-tree`](@docroot@/contributing/experimental-features.md#xp-fetch-tree).
|
||||
This allows stabilising it independently of the rest of what is encompassed by [`flakes`](@docroot@/contributing/experimental-features.md#xp-fetch-tree).
|
||||
- `builtins.fetchTree` is now its own experimental feature, [`fetch-tree`](@docroot@/development/experimental-features.md#xp-fetch-tree).
|
||||
This allows stabilising it independently of the rest of what is encompassed by [`flakes`](@docroot@/development/experimental-features.md#xp-fetch-tree).
|
||||
|
||||
- The interface for creating and updating lock files has been overhauled:
|
||||
|
||||
|
@ -33,7 +33,7 @@
|
|||
- The flake-specific flags `--recreate-lock-file` and `--update-input` have been removed from all commands operating on installables.
|
||||
They are superceded by `nix flake update`.
|
||||
|
||||
- Commit signature verification for the [`builtins.fetchGit`](@docroot@/language/builtins.md#builtins-fetchGit) is added as the new [`verified-fetches` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-verified-fetches).
|
||||
- Commit signature verification for the [`builtins.fetchGit`](@docroot@/language/builtins.md#builtins-fetchGit) is added as the new [`verified-fetches` experimental feature](@docroot@/development/experimental-features.md#xp-feature-verified-fetches).
|
||||
|
||||
- [`nix path-info --json`](@docroot@/command-ref/new-cli/nix3-path-info.md)
|
||||
(experimental) now returns a JSON map rather than JSON list.
|
||||
|
|
|
@ -14,7 +14,7 @@
|
|||
|
||||
- Modify `nix derivation {add,show}` JSON format [#9866](https://github.com/NixOS/nix/issues/9866) [#10722](https://github.com/NixOS/nix/pull/10722)
|
||||
|
||||
The JSON format for derivations has been slightly revised to better conform to our [JSON guidelines](@docroot@/contributing/cli-guideline.md#returning-future-proof-json).
|
||||
The JSON format for derivations has been slightly revised to better conform to our [JSON guidelines](@docroot@/development/cli-guideline.md#returning-future-proof-json).
|
||||
In particular, the hash algorithm and content addressing method of content-addresed derivation outputs are now separated into two fields `hashAlgo` and `method`,
|
||||
rather than one field with an arcane `:`-separated format.
|
||||
|
||||
|
@ -89,7 +89,7 @@
|
|||
This makes records of this sort more self-describing, and easier to consume programmatically.
|
||||
|
||||
We will follow this design principle going forward;
|
||||
the [JSON guidelines](@docroot@/contributing/json-guideline.md) in the contributing section have been updated accordingly.
|
||||
the [JSON guidelines](@docroot@/development/json-guideline.md) in the contributing section have been updated accordingly.
|
||||
|
||||
- Large path warnings [#10661](https://github.com/NixOS/nix/pull/10661)
|
||||
|
||||
|
|
|
@ -23,7 +23,7 @@ more than 2800 commits from 195 contributors since release 2.3.
|
|||
* The **`nix` command** has seen a lot of work and is now almost at
|
||||
feature parity with the old command-line interface (the `nix-*`
|
||||
commands). It aims to be [more modern, consistent and pleasant to
|
||||
use](../contributing/cli-guideline.md) than the old CLI. It is still
|
||||
use](../development/cli-guideline.md) than the old CLI. It is still
|
||||
marked as experimental but its interface should not change much
|
||||
anymore in future releases.
|
||||
|
||||
|
|
|
@ -82,4 +82,4 @@ In the future, we may support a Git-like hash for such file system objects, or w
|
|||
|
||||
[file system object]: ../file-system-object.md
|
||||
[store object]: ../store-object.md
|
||||
[xp-feature-git-hashing]: @docroot@/contributing/experimental-features.md#xp-feature-git-hashing
|
||||
[xp-feature-git-hashing]: @docroot@/development/experimental-features.md#xp-feature-git-hashing
|
||||
|
|
|
@ -92,4 +92,4 @@ becomes more widespread, this restriction will be revisited.
|
|||
|
||||
[fso-ca]: ../file-system-object/content-address.md
|
||||
[sp-spec]: @docroot@/protocols/store-path.md
|
||||
[xp-feature-git-hashing]: @docroot@/contributing/experimental-features.md#xp-feature-git-hashing
|
||||
[xp-feature-git-hashing]: @docroot@/development/experimental-features.md#xp-feature-git-hashing
|
||||
|
|
|
@ -65,7 +65,7 @@ struct EvalSettings : Config
|
|||
extern "C" typedef void (*ValueInitialiser) (EvalState & state, Value & v);
|
||||
```
|
||||
|
||||
The [Nix C++ API documentation](@docroot@/contributing/documentation.md#api-documentation) has more details on evaluator internals.
|
||||
The [Nix C++ API documentation](@docroot@/development/documentation.md#api-documentation) has more details on evaluator internals.
|
||||
|
||||
- `builtins.exec` *arguments*
|
||||
|
||||
|
|
|
@ -383,7 +383,7 @@ static RegisterPrimOp primop_fetchTree({
|
|||
- `"mercurial"`
|
||||
|
||||
*input* can also be a [URL-like reference](@docroot@/command-ref/new-cli/nix3-flake.md#flake-references).
|
||||
The additional input types and the URL-like syntax requires the [`flakes` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-flakes) to be enabled.
|
||||
The additional input types and the URL-like syntax requires the [`flakes` experimental feature](@docroot@/development/experimental-features.md#xp-feature-flakes) to be enabled.
|
||||
|
||||
> **Example**
|
||||
>
|
||||
|
@ -670,12 +670,12 @@ static RegisterPrimOp primop_fetchGit({
|
|||
|
||||
Whether to check `rev` for a signature matching `publicKey` or `publicKeys`.
|
||||
If `verifyCommit` is enabled, then `fetchGit` cannot use a local repository with uncommitted changes.
|
||||
Requires the [`verified-fetches` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-verified-fetches).
|
||||
Requires the [`verified-fetches` experimental feature](@docroot@/development/experimental-features.md#xp-feature-verified-fetches).
|
||||
|
||||
- `publicKey`
|
||||
|
||||
The public key against which `rev` is verified if `verifyCommit` is enabled.
|
||||
Requires the [`verified-fetches` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-verified-fetches).
|
||||
Requires the [`verified-fetches` experimental feature](@docroot@/development/experimental-features.md#xp-feature-verified-fetches).
|
||||
|
||||
- `keytype` (default: `"ssh-ed25519"`)
|
||||
|
||||
|
@ -687,7 +687,7 @@ static RegisterPrimOp primop_fetchGit({
|
|||
- `"ssh-ed25519"`
|
||||
- `"ssh-ed25519-sk"`
|
||||
- `"ssh-rsa"`
|
||||
Requires the [`verified-fetches` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-verified-fetches).
|
||||
Requires the [`verified-fetches` experimental feature](@docroot@/development/experimental-features.md#xp-feature-verified-fetches).
|
||||
|
||||
- `publicKeys`
|
||||
|
||||
|
@ -701,7 +701,7 @@ static RegisterPrimOp primop_fetchGit({
|
|||
}
|
||||
```
|
||||
|
||||
Requires the [`verified-fetches` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-verified-fetches).
|
||||
Requires the [`verified-fetches` experimental feature](@docroot@/development/experimental-features.md#xp-feature-verified-fetches).
|
||||
|
||||
|
||||
Here are some examples of how to use `fetchGit`.
|
||||
|
|
|
@ -286,7 +286,7 @@ public:
|
|||
For backward compatibility, `ssh://` may be omitted.
|
||||
The hostname may be an alias defined in `~/.ssh/config`.
|
||||
|
||||
2. A comma-separated list of [Nix system types](@docroot@/contributing/hacking.md#system-type).
|
||||
2. A comma-separated list of [Nix system types](@docroot@/development/building.md#system-type).
|
||||
If omitted, this defaults to the local platform type.
|
||||
|
||||
> **Example**
|
||||
|
@ -866,13 +866,13 @@ public:
|
|||
|
||||
- `ca-derivations`
|
||||
|
||||
Included by default if the [`ca-derivations` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-ca-derivations) is enabled.
|
||||
Included by default if the [`ca-derivations` experimental feature](@docroot@/development/experimental-features.md#xp-feature-ca-derivations) is enabled.
|
||||
|
||||
This system feature is implicitly required by derivations with the [`__contentAddressed` attribute](@docroot@/language/advanced-attributes.md#adv-attr-__contentAddressed).
|
||||
|
||||
- `recursive-nix`
|
||||
|
||||
Included by default if the [`recursive-nix` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-recursive-nix) is enabled.
|
||||
Included by default if the [`recursive-nix` experimental feature](@docroot@/development/experimental-features.md#xp-feature-recursive-nix) is enabled.
|
||||
|
||||
- `uid-range`
|
||||
|
||||
|
|
|
@ -393,7 +393,7 @@ struct ExperimentalFeatureSettings : Config {
|
|||
|
||||
{{#include experimental-features-shortlist.md}}
|
||||
|
||||
Experimental features are [further documented in the manual](@docroot@/contributing/experimental-features.md).
|
||||
Experimental features are [further documented in the manual](@docroot@/development/experimental-features.md).
|
||||
)"};
|
||||
|
||||
/**
|
||||
|
|
|
@ -50,7 +50,7 @@ manual](https://nixos.org/manual/nix/stable/).
|
|||
|
||||
> **Warning** \
|
||||
> Installables are part of the unstable
|
||||
> [`nix-command` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-nix-command),
|
||||
> [`nix-command` experimental feature](@docroot@/development/experimental-features.md#xp-feature-nix-command),
|
||||
> and subject to change without notice.
|
||||
|
||||
Many `nix` subcommands operate on one or more *installables*.
|
||||
|
@ -70,9 +70,9 @@ That is, Nix will operate on the default flake output attribute of the flake in
|
|||
|
||||
> **Warning** \
|
||||
> Flake output attribute installables depend on both the
|
||||
> [`flakes`](@docroot@/contributing/experimental-features.md#xp-feature-flakes)
|
||||
> [`flakes`](@docroot@/development/experimental-features.md#xp-feature-flakes)
|
||||
> and
|
||||
> [`nix-command`](@docroot@/contributing/experimental-features.md#xp-feature-nix-command)
|
||||
> [`nix-command`](@docroot@/development/experimental-features.md#xp-feature-nix-command)
|
||||
> experimental features, and subject to change without notice.
|
||||
|
||||
Example: `nixpkgs#hello`
|
||||
|
|
Loading…
Reference in a new issue