mirror of
https://github.com/NixOS/nix
synced 2025-07-09 03:43:54 +02:00
Tagging release 2.26.2
-----BEGIN PGP SIGNATURE----- iQFHBAABCAAxFiEEtUHVUwEnDgvPFcpdgXC0cm1xmN4FAmetA5oTHGVkb2xzdHJh QGdtYWlsLmNvbQAKCRCBcLRybXGY3g2pB/9JAFyjmaXuccbMTO/6x9qwsWuuXNLk OQWzfbdUekvsihZZSFZg1r7KqqXHCi64f0nxLPsJ/0oeDWZktJ5KnbV630nuUlDj ulLCpKdvhWFa8dVx9LiziGwQw4KLx8PjOfwThtQ4DqCWxWEmu6lKkijag9cE+ai4 3mw9YtUjBRxlXyhYLzWz3whLbv37c/m+R8iGS8xm8W260pmei6D0beOIPdfXYBQF PzPlPORyI08A06uqyA3z7bTxzmSMnzvu0QInCPCKSHzFUnTZPHUYuYStFl28NrZS fXKK59L0G7QEfdTRAmqQkdHdtPj2RlYFiMN0kQiNLflvKfGGWdi/kvdx =rRix -----END PGP SIGNATURE----- Merge tag '2.26.2' into sync-2.26.2 Tagging release 2.26.2
This commit is contained in:
commit
4055239936
1395 changed files with 24694 additions and 16040 deletions
1
doc/manual/.version
Symbolic link
1
doc/manual/.version
Symbolic link
|
@ -0,0 +1 @@
|
|||
../../.version
|
|
@ -1,5 +1,6 @@
|
|||
[book]
|
||||
title = "Determinate Nix Reference Manual"
|
||||
src = "source"
|
||||
|
||||
[output.html]
|
||||
additional-css = ["custom.css"]
|
||||
|
@ -7,9 +8,21 @@ additional-js = ["redirects.js"]
|
|||
edit-url-template = "https://github.com/NixOS/nix/tree/master/doc/manual/{path}"
|
||||
git-repository-url = "https://github.com/NixOS/nix"
|
||||
|
||||
# Handles replacing @docroot@ with a path to ./source relative to that markdown file,
|
||||
# {{#include handlebars}}, and the @generated@ syntax used within these. it mostly
|
||||
# but not entirely replaces the links preprocessor (which we cannot simply use due
|
||||
# to @generated@ files living in a different directory to make meson happy). we do
|
||||
# not want to disable the links preprocessor entirely though because that requires
|
||||
# disabling *all* built-in preprocessors and selectively reenabling those we want.
|
||||
[preprocessor.substitute]
|
||||
command = "python3 ./substitute.py"
|
||||
before = ["anchors", "links"]
|
||||
|
||||
[preprocessor.anchors]
|
||||
renderers = ["html"]
|
||||
command = "jq --from-file doc/manual/anchors.jq"
|
||||
command = "jq --from-file ./anchors.jq"
|
||||
|
||||
[output.markdown]
|
||||
|
||||
[output.linkcheck]
|
||||
# no Internet during the build (in the sandbox)
|
||||
|
|
|
@ -12,8 +12,8 @@ h1.menu-title::before {
|
|||
}
|
||||
|
||||
|
||||
h1.menu-title {
|
||||
padding: 0.5em;
|
||||
.menu-bar {
|
||||
padding: 0.5em 0em;
|
||||
}
|
||||
|
||||
.sidebar .sidebar-scrollbox {
|
||||
|
|
|
@ -5,7 +5,15 @@ in
|
|||
|
||||
builtinsInfo:
|
||||
let
|
||||
showBuiltin = name: { doc, type ? null, args ? [ ], experimental-feature ? null, impure-only ? false }:
|
||||
showBuiltin =
|
||||
name:
|
||||
{
|
||||
doc,
|
||||
type ? null,
|
||||
args ? [ ],
|
||||
experimental-feature ? null,
|
||||
impure-only ? false,
|
||||
}:
|
||||
let
|
||||
type' = optionalString (type != null) " (${type})";
|
||||
|
||||
|
|
22
doc/manual/generate-deps.py
Executable file
22
doc/manual/generate-deps.py
Executable file
|
@ -0,0 +1,22 @@
|
|||
#!/usr/bin/env python3
|
||||
|
||||
import glob
|
||||
import sys
|
||||
|
||||
# meson expects makefile-style dependency declarations, i.e.
|
||||
#
|
||||
# target: dependency...
|
||||
#
|
||||
# meson seems to pass depfiles straight on to ninja even though
|
||||
# it also parses the file itself (or at least has code to do so
|
||||
# in its tree), so we must live by ninja's rules: only slashes,
|
||||
# spaces and octothorpes can be escaped, anything else is taken
|
||||
# literally. since the rules for these aren't even the same for
|
||||
# all three we will just fail when we encounter any of them (if
|
||||
# asserts are off for some reason the depfile will likely point
|
||||
# to nonexistant paths, making everything phony and thus fine.)
|
||||
for path in glob.glob(sys.argv[1] + '/**', recursive=True):
|
||||
assert '\\' not in path
|
||||
assert ' ' not in path
|
||||
assert '#' not in path
|
||||
print("ignored:", path)
|
|
@ -32,7 +32,13 @@ let
|
|||
|
||||
commandInfo = fromJSON commandDump;
|
||||
|
||||
showCommand = { command, details, filename, toplevel }:
|
||||
showCommand =
|
||||
{
|
||||
command,
|
||||
details,
|
||||
filename,
|
||||
toplevel,
|
||||
}:
|
||||
let
|
||||
|
||||
result = ''
|
||||
|
@ -51,26 +57,27 @@ let
|
|||
${maybeOptions}
|
||||
'';
|
||||
|
||||
showSynopsis = command: args:
|
||||
showSynopsis =
|
||||
command: args:
|
||||
let
|
||||
showArgument = arg: "*${arg.label}*" + optionalString (! arg ? arity) "...";
|
||||
showArgument = arg: "*${arg.label}*" + optionalString (!arg ? arity) "...";
|
||||
arguments = concatStringsSep " " (map showArgument args);
|
||||
in ''
|
||||
in
|
||||
''
|
||||
`${command}` [*option*...] ${arguments}
|
||||
'';
|
||||
|
||||
maybeSubcommands = optionalString (details ? commands && details.commands != {})
|
||||
''
|
||||
where *subcommand* is one of the following:
|
||||
maybeSubcommands = optionalString (details ? commands && details.commands != { }) ''
|
||||
where *subcommand* is one of the following:
|
||||
|
||||
${subcommands}
|
||||
'';
|
||||
${subcommands}
|
||||
'';
|
||||
|
||||
subcommands = if length categories > 1
|
||||
then listCategories
|
||||
else listSubcommands details.commands;
|
||||
subcommands = if length categories > 1 then listCategories else listSubcommands details.commands;
|
||||
|
||||
categories = sort (x: y: x.id < y.id) (unique (map (cmd: cmd.category) (attrValues details.commands)));
|
||||
categories = sort (x: y: x.id < y.id) (
|
||||
unique (map (cmd: cmd.category) (attrValues details.commands))
|
||||
);
|
||||
|
||||
listCategories = concatStrings (map showCategory categories);
|
||||
|
||||
|
@ -94,38 +101,39 @@ let
|
|||
|
||||
${allStores}
|
||||
'';
|
||||
index = replaceStrings
|
||||
[ "@store-types@" "./local-store.md" "./local-daemon-store.md" ]
|
||||
[ storesOverview "#local-store" "#local-daemon-store" ]
|
||||
details.doc;
|
||||
index =
|
||||
replaceStrings
|
||||
[ "@store-types@" "./local-store.md" "./local-daemon-store.md" ]
|
||||
[ storesOverview "#local-store" "#local-daemon-store" ]
|
||||
details.doc;
|
||||
storesOverview =
|
||||
let
|
||||
showEntry = store:
|
||||
"- [${store.name}](#${store.slug})";
|
||||
showEntry = store: "- [${store.name}](#${store.slug})";
|
||||
in
|
||||
concatStringsSep "\n" (map showEntry storesList) + "\n";
|
||||
allStores = concatStringsSep "\n" (attrValues storePages);
|
||||
storePages = listToAttrs
|
||||
(map (s: { name = s.filename; value = s.page; }) storesList);
|
||||
storePages = listToAttrs (
|
||||
map (s: {
|
||||
name = s.filename;
|
||||
value = s.page;
|
||||
}) storesList
|
||||
);
|
||||
storesList = showStoreDocs {
|
||||
storeInfo = commandInfo.stores;
|
||||
inherit inlineHTML;
|
||||
};
|
||||
hasInfix = infix: content:
|
||||
hasInfix =
|
||||
infix: content:
|
||||
builtins.stringLength content != builtins.stringLength (replaceStrings [ infix ] [ "" ] content);
|
||||
in
|
||||
optionalString (details ? doc) (
|
||||
# An alternate implementation with builtins.match stack overflowed on some systems.
|
||||
if hasInfix "@store-types@" details.doc
|
||||
then help-stores
|
||||
else details.doc
|
||||
if hasInfix "@store-types@" details.doc then help-stores else details.doc
|
||||
);
|
||||
|
||||
maybeOptions =
|
||||
let
|
||||
allVisibleOptions = filterAttrs
|
||||
(_: o: ! o.hiddenCategory)
|
||||
(details.flags // toplevel.flags);
|
||||
allVisibleOptions = filterAttrs (_: o: !o.hiddenCategory) (details.flags // toplevel.flags);
|
||||
in
|
||||
optionalString (allVisibleOptions != { }) ''
|
||||
# Options
|
||||
|
@ -137,55 +145,73 @@ let
|
|||
> See [`man nix.conf`](@docroot@/command-ref/conf-file.md#command-line-flags) for overriding configuration settings with command line flags.
|
||||
'';
|
||||
|
||||
showOptions = inlineHTML: allOptions:
|
||||
showOptions =
|
||||
inlineHTML: allOptions:
|
||||
let
|
||||
showCategory = cat: opts: ''
|
||||
${optionalString (cat != "") "## ${cat}"}
|
||||
|
||||
${concatStringsSep "\n" (attrValues (mapAttrs showOption opts))}
|
||||
'';
|
||||
showOption = name: option:
|
||||
showOption =
|
||||
name: option:
|
||||
let
|
||||
result = trim ''
|
||||
- ${item}
|
||||
|
||||
${option.description}
|
||||
'';
|
||||
item = if inlineHTML
|
||||
then ''<span id="opt-${name}">[`--${name}`](#opt-${name})</span> ${shortName} ${labels}''
|
||||
else "`--${name}` ${shortName} ${labels}";
|
||||
shortName = optionalString
|
||||
(option ? shortName)
|
||||
("/ `-${option.shortName}`");
|
||||
labels = optionalString
|
||||
(option ? labels)
|
||||
(concatStringsSep " " (map (s: "*${s}*") option.labels));
|
||||
in result;
|
||||
categories = mapAttrs
|
||||
# Convert each group from a list of key-value pairs back to an attrset
|
||||
(_: listToAttrs)
|
||||
(groupBy
|
||||
(cmd: cmd.value.category)
|
||||
(attrsToList allOptions));
|
||||
in concatStrings (attrValues (mapAttrs showCategory categories));
|
||||
in squash result;
|
||||
item =
|
||||
if inlineHTML then
|
||||
''<span id="opt-${name}">[`--${name}`](#opt-${name})</span> ${shortName} ${labels}''
|
||||
else
|
||||
"`--${name}` ${shortName} ${labels}";
|
||||
shortName = optionalString (option ? shortName) ("/ `-${option.shortName}`");
|
||||
labels = optionalString (option ? labels) (concatStringsSep " " (map (s: "*${s}*") option.labels));
|
||||
in
|
||||
result;
|
||||
categories =
|
||||
mapAttrs
|
||||
# Convert each group from a list of key-value pairs back to an attrset
|
||||
(_: listToAttrs)
|
||||
(groupBy (cmd: cmd.value.category) (attrsToList allOptions));
|
||||
in
|
||||
concatStrings (attrValues (mapAttrs showCategory categories));
|
||||
in
|
||||
squash result;
|
||||
|
||||
appendName = filename: name: (if filename == "nix" then "nix3" else filename) + "-" + name;
|
||||
|
||||
processCommand = { command, details, filename, toplevel }:
|
||||
processCommand =
|
||||
{
|
||||
command,
|
||||
details,
|
||||
filename,
|
||||
toplevel,
|
||||
}:
|
||||
let
|
||||
cmd = {
|
||||
inherit command;
|
||||
name = filename + ".md";
|
||||
value = showCommand { inherit command details filename toplevel; };
|
||||
value = showCommand {
|
||||
inherit
|
||||
command
|
||||
details
|
||||
filename
|
||||
toplevel
|
||||
;
|
||||
};
|
||||
};
|
||||
subcommand = subCmd: processCommand {
|
||||
command = command + " " + subCmd;
|
||||
details = details.commands.${subCmd};
|
||||
filename = appendName filename subCmd;
|
||||
inherit toplevel;
|
||||
};
|
||||
in [ cmd ] ++ concatMap subcommand (attrNames details.commands or {});
|
||||
subcommand =
|
||||
subCmd:
|
||||
processCommand {
|
||||
command = command + " " + subCmd;
|
||||
details = details.commands.${subCmd};
|
||||
filename = appendName filename subCmd;
|
||||
inherit toplevel;
|
||||
};
|
||||
in
|
||||
[ cmd ] ++ concatMap subcommand (attrNames details.commands or { });
|
||||
|
||||
manpages = processCommand {
|
||||
command = "nix";
|
||||
|
@ -194,9 +220,11 @@ let
|
|||
toplevel = commandInfo.args;
|
||||
};
|
||||
|
||||
tableOfContents = let
|
||||
showEntry = page:
|
||||
" - [${page.command}](command-ref/new-cli/${page.name})";
|
||||
in concatStringsSep "\n" (map showEntry manpages) + "\n";
|
||||
tableOfContents =
|
||||
let
|
||||
showEntry = page: " - [${page.command}](command-ref/new-cli/${page.name})";
|
||||
in
|
||||
concatStringsSep "\n" (map showEntry manpages) + "\n";
|
||||
|
||||
in (listToAttrs manpages) // { "SUMMARY.md" = tableOfContents; }
|
||||
in
|
||||
(listToAttrs manpages) // { "SUMMARY.md" = tableOfContents; }
|
||||
|
|
|
@ -1,67 +1,99 @@
|
|||
let
|
||||
inherit (builtins) attrValues concatStringsSep isAttrs isBool mapAttrs;
|
||||
inherit (import <nix/utils.nix>) concatStrings indent optionalString squash;
|
||||
inherit (builtins)
|
||||
attrValues
|
||||
concatStringsSep
|
||||
isAttrs
|
||||
isBool
|
||||
mapAttrs
|
||||
;
|
||||
inherit (import <nix/utils.nix>)
|
||||
concatStrings
|
||||
indent
|
||||
optionalString
|
||||
squash
|
||||
;
|
||||
in
|
||||
|
||||
# `inlineHTML` is a hack to accommodate inconsistent output from `lowdown`
|
||||
{ prefix, inlineHTML ? true }: settingsInfo:
|
||||
{
|
||||
prefix,
|
||||
inlineHTML ? true,
|
||||
}:
|
||||
settingsInfo:
|
||||
|
||||
let
|
||||
|
||||
showSetting = prefix: setting: { description, documentDefault, defaultValue, aliases, value, experimentalFeature }:
|
||||
showSetting =
|
||||
prefix: setting:
|
||||
{
|
||||
description,
|
||||
documentDefault,
|
||||
defaultValue,
|
||||
aliases,
|
||||
value,
|
||||
experimentalFeature,
|
||||
}:
|
||||
let
|
||||
result = squash ''
|
||||
- ${item}
|
||||
- ${item}
|
||||
|
||||
${indent " " body}
|
||||
'';
|
||||
item = if inlineHTML
|
||||
then ''<span id="${prefix}-${setting}">[`${setting}`](#${prefix}-${setting})</span>''
|
||||
else "`${setting}`";
|
||||
${indent " " body}
|
||||
'';
|
||||
item =
|
||||
if inlineHTML then
|
||||
''<span id="${prefix}-${setting}">[`${setting}`](#${prefix}-${setting})</span>''
|
||||
else
|
||||
"`${setting}`";
|
||||
# separate body to cleanly handle indentation
|
||||
body = ''
|
||||
${experimentalFeatureNote}
|
||||
${experimentalFeatureNote}
|
||||
|
||||
${description}
|
||||
${description}
|
||||
|
||||
**Default:** ${showDefault documentDefault defaultValue}
|
||||
**Default:** ${showDefault documentDefault defaultValue}
|
||||
|
||||
${showAliases aliases}
|
||||
'';
|
||||
${showAliases aliases}
|
||||
'';
|
||||
|
||||
experimentalFeatureNote = optionalString (experimentalFeature != null) ''
|
||||
> **Warning**
|
||||
>
|
||||
> This setting is part of an
|
||||
> [experimental feature](@docroot@/development/experimental-features.md).
|
||||
>
|
||||
> To change this setting, make sure the
|
||||
> [`${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):
|
||||
>
|
||||
> ```
|
||||
> extra-experimental-features = ${experimentalFeature}
|
||||
> ${setting} = ...
|
||||
> ```
|
||||
'';
|
||||
> **Warning**
|
||||
>
|
||||
> This setting is part of an
|
||||
> [experimental feature](@docroot@/development/experimental-features.md).
|
||||
>
|
||||
> To change this setting, make sure the
|
||||
> [`${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):
|
||||
>
|
||||
> ```
|
||||
> extra-experimental-features = ${experimentalFeature}
|
||||
> ${setting} = ...
|
||||
> ```
|
||||
'';
|
||||
|
||||
showDefault = documentDefault: defaultValue:
|
||||
showDefault =
|
||||
documentDefault: defaultValue:
|
||||
if documentDefault then
|
||||
# a StringMap value type is specified as a string, but
|
||||
# this shows the value type. The empty stringmap is `null` in
|
||||
# JSON, but that converts to `{ }` here.
|
||||
if defaultValue == "" || defaultValue == [] || isAttrs defaultValue
|
||||
then "*empty*"
|
||||
else if isBool defaultValue then
|
||||
if defaultValue then "`true`" else "`false`"
|
||||
else "`${toString defaultValue}`"
|
||||
else "*machine-specific*";
|
||||
if defaultValue == "" || defaultValue == [ ] || isAttrs defaultValue then
|
||||
"*empty*"
|
||||
else if isBool defaultValue then
|
||||
if defaultValue then "`true`" else "`false`"
|
||||
else
|
||||
"`${toString defaultValue}`"
|
||||
else
|
||||
"*machine-specific*";
|
||||
|
||||
showAliases = aliases:
|
||||
optionalString (aliases != [])
|
||||
"**Deprecated alias:** ${(concatStringsSep ", " (map (s: "`${s}`") aliases))}";
|
||||
showAliases =
|
||||
aliases:
|
||||
optionalString (aliases != [ ])
|
||||
"**Deprecated alias:** ${(concatStringsSep ", " (map (s: "`${s}`") aliases))}";
|
||||
|
||||
in result;
|
||||
in
|
||||
result;
|
||||
|
||||
in concatStrings (attrValues (mapAttrs (showSetting prefix) settingsInfo))
|
||||
in
|
||||
concatStrings (attrValues (mapAttrs (showSetting prefix) settingsInfo))
|
||||
|
|
|
@ -1,6 +1,20 @@
|
|||
let
|
||||
inherit (builtins) attrNames listToAttrs concatStringsSep readFile replaceStrings;
|
||||
inherit (import <nix/utils.nix>) optionalString filterAttrs trim squash toLower unique indent;
|
||||
inherit (builtins)
|
||||
attrNames
|
||||
listToAttrs
|
||||
concatStringsSep
|
||||
readFile
|
||||
replaceStrings
|
||||
;
|
||||
inherit (import <nix/utils.nix>)
|
||||
optionalString
|
||||
filterAttrs
|
||||
trim
|
||||
squash
|
||||
toLower
|
||||
unique
|
||||
indent
|
||||
;
|
||||
showSettings = import <nix/generate-settings.nix>;
|
||||
in
|
||||
|
||||
|
@ -14,7 +28,13 @@ in
|
|||
|
||||
let
|
||||
|
||||
showStore = { name, slug }: { settings, doc, experimentalFeature }:
|
||||
showStore =
|
||||
{ name, slug }:
|
||||
{
|
||||
settings,
|
||||
doc,
|
||||
experimentalFeature,
|
||||
}:
|
||||
let
|
||||
result = squash ''
|
||||
# ${name}
|
||||
|
@ -25,7 +45,10 @@ let
|
|||
|
||||
## Settings
|
||||
|
||||
${showSettings { prefix = "store-${slug}"; inherit inlineHTML; } settings}
|
||||
${showSettings {
|
||||
prefix = "store-${slug}";
|
||||
inherit inlineHTML;
|
||||
} settings}
|
||||
'';
|
||||
|
||||
experimentalFeatureNote = optionalString (experimentalFeature != null) ''
|
||||
|
@ -43,15 +66,15 @@ let
|
|||
> extra-experimental-features = ${experimentalFeature}
|
||||
> ```
|
||||
'';
|
||||
in result;
|
||||
in
|
||||
result;
|
||||
|
||||
storesList = map
|
||||
(name: rec {
|
||||
inherit name;
|
||||
slug = replaceStrings [ " " ] [ "-" ] (toLower name);
|
||||
filename = "${slug}.md";
|
||||
page = showStore { inherit name slug; } storeInfo.${name};
|
||||
})
|
||||
(attrNames storeInfo);
|
||||
storesList = map (name: rec {
|
||||
inherit name;
|
||||
slug = replaceStrings [ " " ] [ "-" ] (toLower name);
|
||||
filename = "${slug}.md";
|
||||
page = showStore { inherit name slug; } storeInfo.${name};
|
||||
}) (attrNames storeInfo);
|
||||
|
||||
in storesList
|
||||
in
|
||||
storesList
|
||||
|
|
|
@ -1,5 +1,11 @@
|
|||
let
|
||||
inherit (builtins) attrNames listToAttrs concatStringsSep readFile replaceStrings;
|
||||
inherit (builtins)
|
||||
attrNames
|
||||
listToAttrs
|
||||
concatStringsSep
|
||||
readFile
|
||||
replaceStrings
|
||||
;
|
||||
showSettings = import <nix/generate-settings.nix>;
|
||||
showStoreDocs = import <nix/generate-store-info.nix>;
|
||||
in
|
||||
|
@ -14,26 +20,28 @@ let
|
|||
|
||||
index =
|
||||
let
|
||||
showEntry = store:
|
||||
"- [${store.name}](./${store.filename})";
|
||||
showEntry = store: "- [${store.name}](./${store.filename})";
|
||||
in
|
||||
concatStringsSep "\n" (map showEntry storesList);
|
||||
|
||||
"index.md" = replaceStrings
|
||||
[ "@store-types@" ] [ index ]
|
||||
(readFile ./src/store/types/index.md.in);
|
||||
"index.md" =
|
||||
replaceStrings [ "@store-types@" ] [ index ]
|
||||
(readFile ./source/store/types/index.md.in);
|
||||
|
||||
tableOfContents =
|
||||
let
|
||||
showEntry = store:
|
||||
" - [${store.name}](store/types/${store.filename})";
|
||||
showEntry = store: " - [${store.name}](store/types/${store.filename})";
|
||||
in
|
||||
concatStringsSep "\n" (map showEntry storesList) + "\n";
|
||||
|
||||
"SUMMARY.md" = tableOfContents;
|
||||
|
||||
storePages = listToAttrs
|
||||
(map (s: { name = s.filename; value = s.page; }) storesList);
|
||||
storePages = listToAttrs (
|
||||
map (s: {
|
||||
name = s.filename;
|
||||
value = s.page;
|
||||
}) storesList
|
||||
);
|
||||
|
||||
in
|
||||
storePages // { inherit "index.md" "SUMMARY.md"; }
|
||||
|
|
|
@ -2,8 +2,8 @@ with builtins;
|
|||
with import <nix/utils.nix>;
|
||||
|
||||
let
|
||||
showExperimentalFeature = name: doc:
|
||||
''
|
||||
- [`${name}`](@docroot@/development/experimental-features.md#xp-feature-${name})
|
||||
'';
|
||||
in xps: indent " " (concatStrings (attrValues (mapAttrs showExperimentalFeature xps)))
|
||||
showExperimentalFeature = name: doc: ''
|
||||
- [`${name}`](@docroot@/development/experimental-features.md#xp-feature-${name})
|
||||
'';
|
||||
in
|
||||
xps: indent " " (concatStrings (attrValues (mapAttrs showExperimentalFeature xps)))
|
||||
|
|
|
@ -2,7 +2,8 @@ with builtins;
|
|||
with import <nix/utils.nix>;
|
||||
|
||||
let
|
||||
showExperimentalFeature = name: doc:
|
||||
showExperimentalFeature =
|
||||
name: doc:
|
||||
squash ''
|
||||
## [`${name}`]{#xp-feature-${name}}
|
||||
|
||||
|
|
|
@ -1,231 +0,0 @@
|
|||
# The version of Nix used to generate the doc. Can also be
|
||||
# `$(nix_INSTALL_PATH)` or just `nix` (to grap ambient from the `PATH`),
|
||||
# if one prefers.
|
||||
doc_nix = $(nix_PATH)
|
||||
|
||||
MANUAL_SRCS := \
|
||||
$(call rwildcard, $(d)/src, *.md) \
|
||||
$(call rwildcard, $(d)/src, */*.md)
|
||||
|
||||
man-pages := $(foreach n, \
|
||||
nix-env.1 nix-store.1 \
|
||||
nix-build.1 nix-shell.1 nix-instantiate.1 \
|
||||
nix-collect-garbage.1 \
|
||||
nix-prefetch-url.1 nix-channel.1 \
|
||||
nix-hash.1 nix-copy-closure.1 \
|
||||
nix.conf.5 nix-daemon.8 \
|
||||
nix-profiles.5 \
|
||||
, $(d)/$(n))
|
||||
|
||||
# man pages for subcommands
|
||||
# convert from `$(d)/src/command-ref/nix-{1}/{2}.md` to `$(d)/nix-{1}-{2}.1`
|
||||
# FIXME: unify with how nix3-cli man pages are generated
|
||||
man-pages += $(foreach subcommand, \
|
||||
$(filter-out %opt-common.md %env-common.md, $(wildcard $(d)/src/command-ref/nix-*/*.md)), \
|
||||
$(d)/$(subst /,-,$(subst $(d)/src/command-ref/,,$(subst .md,.1,$(subcommand)))))
|
||||
|
||||
clean-files += $(d)/*.1 $(d)/*.5 $(d)/*.8
|
||||
|
||||
# Provide a dummy environment for nix, so that it will not access files outside the macOS sandbox.
|
||||
# Set cores to 0 because otherwise `nix config show` resolves the cores based on the current machine
|
||||
dummy-env = env -i \
|
||||
HOME=/dummy \
|
||||
NIX_CONF_DIR=/dummy \
|
||||
NIX_SSL_CERT_FILE=/dummy/no-ca-bundle.crt \
|
||||
NIX_STATE_DIR=/dummy \
|
||||
NIX_CONFIG='cores = 0'
|
||||
|
||||
nix-eval = $(dummy-env) $(doc_nix) eval -I nix=doc/manual --store dummy:// --impure --raw
|
||||
|
||||
# re-implement mdBook's include directive to make it usable for terminal output and for proper @docroot@ substitution
|
||||
define process-includes
|
||||
while read -r line; do \
|
||||
set -euo pipefail; \
|
||||
filename="$$(dirname $(1))/$$(sed 's/{{#include \(.*\)}}/\1/'<<< $$line)"; \
|
||||
test -f "$$filename" || ( echo "#include-d file '$$filename' does not exist." >&2; exit 1; ); \
|
||||
matchline="$$(sed 's|/|\\/|g' <<< $$line)"; \
|
||||
sed -i "/$$matchline/r $$filename" $(2); \
|
||||
sed -i "s/$$matchline//" $(2); \
|
||||
done < <(grep '{{#include' $(1))
|
||||
endef
|
||||
|
||||
$(d)/nix-env-%.1: $(d)/src/command-ref/nix-env/%.md
|
||||
@printf "Title: %s\n\n" "$(subst nix-env-,nix-env --,$$(basename "$@" .1))" > $^.tmp
|
||||
$(render-subcommand)
|
||||
|
||||
$(d)/nix-store-%.1: $(d)/src/command-ref/nix-store/%.md
|
||||
@printf -- 'Title: %s\n\n' "$(subst nix-store-,nix-store --,$$(basename "$@" .1))" > $^.tmp
|
||||
$(render-subcommand)
|
||||
|
||||
# FIXME: there surely is some more deduplication to be achieved here with even darker Make magic
|
||||
define render-subcommand
|
||||
@cat $^ >> $^.tmp
|
||||
@$(call process-includes,$^,$^.tmp)
|
||||
$(trace-gen) lowdown -sT man --nroff-nolinks -M section=1 $^.tmp -o $@
|
||||
@# fix up `lowdown`'s automatic escaping of `--`
|
||||
@# https://github.com/kristapsdz/lowdown/blob/edca6ce6d5336efb147321a43c47a698de41bb7c/entity.c#L202
|
||||
@sed -i 's/\e\[u2013\]/--/' $@
|
||||
@rm $^.tmp
|
||||
endef
|
||||
|
||||
|
||||
$(d)/%.1: $(d)/src/command-ref/%.md
|
||||
@printf "Title: %s\n\n" "$$(basename $@ .1)" > $^.tmp
|
||||
@cat $^ >> $^.tmp
|
||||
@$(call process-includes,$^,$^.tmp)
|
||||
$(trace-gen) lowdown -sT man --nroff-nolinks -M section=1 $^.tmp -o $@
|
||||
@rm $^.tmp
|
||||
|
||||
$(d)/%.8: $(d)/src/command-ref/%.md
|
||||
@printf "Title: %s\n\n" "$$(basename $@ .8)" > $^.tmp
|
||||
@cat $^ >> $^.tmp
|
||||
$(trace-gen) lowdown -sT man --nroff-nolinks -M section=8 $^.tmp -o $@
|
||||
@rm $^.tmp
|
||||
|
||||
$(d)/nix.conf.5: $(d)/src/command-ref/conf-file.md
|
||||
@printf "Title: %s\n\n" "$$(basename $@ .5)" > $^.tmp
|
||||
@cat $^ >> $^.tmp
|
||||
@$(call process-includes,$^,$^.tmp)
|
||||
$(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@
|
||||
@rm $^.tmp
|
||||
|
||||
$(d)/nix-profiles.5: $(d)/src/command-ref/files/profiles.md
|
||||
@printf "Title: %s\n\n" "$$(basename $@ .5)" > $^.tmp
|
||||
@cat $^ >> $^.tmp
|
||||
$(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/development/experimental-feature-descriptions.md
|
||||
@cp $< $@
|
||||
@$(call process-includes,$@,$@)
|
||||
|
||||
$(d)/src/store/types: $(d)/nix.json $(d)/utils.nix $(d)/generate-store-info.nix $(d)/generate-store-types.nix $(d)/src/store/types/index.md.in $(doc_nix)
|
||||
@# FIXME: build out of tree!
|
||||
@rm -rf $@.tmp
|
||||
$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-store-types.nix (builtins.fromJSON (builtins.readFile $<)).stores'
|
||||
@# do not destroy existing contents
|
||||
@mv $@.tmp/* $@/
|
||||
|
||||
$(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/utils.nix $(d)/generate-manpage.nix $(d)/generate-settings.nix $(d)/generate-store-info.nix $(doc_nix)
|
||||
@rm -rf $@ $@.tmp
|
||||
$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-manpage.nix true (builtins.readFile $<)'
|
||||
@mv $@.tmp $@
|
||||
|
||||
$(d)/src/command-ref/conf-file.md: $(d)/conf-file.json $(d)/utils.nix $(d)/generate-settings.nix $(d)/src/command-ref/conf-file-prefix.md $(d)/src/command-ref/experimental-features-shortlist.md $(doc_nix)
|
||||
@cat doc/manual/src/command-ref/conf-file-prefix.md > $@.tmp
|
||||
$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-settings.nix { prefix = "conf"; } (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp;
|
||||
@mv $@.tmp $@
|
||||
|
||||
$(d)/nix.json: $(doc_nix)
|
||||
$(trace-gen) $(dummy-env) $(doc_nix) __dump-cli > $@.tmp
|
||||
@mv $@.tmp $@
|
||||
|
||||
$(d)/conf-file.json: $(doc_nix)
|
||||
$(trace-gen) $(dummy-env) $(doc_nix) config show --json > $@.tmp
|
||||
@mv $@.tmp $@
|
||||
|
||||
$(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 $@
|
||||
|
||||
$(d)/src/command-ref/experimental-features-shortlist.md: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features-shortlist.nix $(doc_nix)
|
||||
@rm -rf $@ $@.tmp
|
||||
$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-xp-features-shortlist.nix (builtins.fromJSON (builtins.readFile $<))'
|
||||
@mv $@.tmp $@
|
||||
|
||||
$(d)/xp-features.json: $(doc_nix)
|
||||
$(trace-gen) $(dummy-env) $(doc_nix) __dump-xp-features > $@.tmp
|
||||
@mv $@.tmp $@
|
||||
|
||||
$(d)/src/language/builtins.md: $(d)/language.json $(d)/generate-builtins.nix $(d)/src/language/builtins-prefix.md $(doc_nix)
|
||||
@cat doc/manual/src/language/builtins-prefix.md > $@.tmp
|
||||
$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp;
|
||||
@cat doc/manual/src/language/builtins-suffix.md >> $@.tmp
|
||||
@mv $@.tmp $@
|
||||
|
||||
$(d)/language.json: $(doc_nix)
|
||||
$(trace-gen) $(dummy-env) $(doc_nix) __dump-language > $@.tmp
|
||||
@mv $@.tmp $@
|
||||
|
||||
# Generate "Upcoming release" notes (or clear it and remove from menu)
|
||||
$(d)/src/release-notes/rl-next.md: $(d)/rl-next $(d)/rl-next/*
|
||||
@if type -p changelog-d > /dev/null; then \
|
||||
echo " GEN " $@; \
|
||||
changelog-d doc/manual/rl-next > $@; \
|
||||
else \
|
||||
echo " NULL " $@; \
|
||||
true > $@; \
|
||||
fi
|
||||
|
||||
$(d)/src/SUMMARY-rl-next.md: $(d)/src/release-notes/rl-next.md
|
||||
$(trace-gen) true
|
||||
@if [ -s $< ]; then \
|
||||
echo ' - [Upcoming release](release-notes/rl-next.md)' > $@; \
|
||||
else \
|
||||
true > $@; \
|
||||
fi
|
||||
|
||||
# Generate the HTML manual.
|
||||
.PHONY: manual-html
|
||||
manual-html: $(docdir)/manual/index.html
|
||||
|
||||
# Open the built HTML manual in the default browser.
|
||||
manual-html-open: $(docdir)/manual/index.html
|
||||
@echo " OPEN " $<; \
|
||||
xdg-open $< \
|
||||
|| open $< \
|
||||
|| { \
|
||||
echo "Could not open the manual in a browser. Please open '$<'" >&2; \
|
||||
false; \
|
||||
}
|
||||
install: $(docdir)/manual/index.html
|
||||
|
||||
# Generate 'nix' manpages.
|
||||
.PHONY: manpages
|
||||
manpages: $(mandir)/man1/nix3-manpages
|
||||
install: $(mandir)/man1/nix3-manpages
|
||||
man: doc/manual/generated/man1/nix3-manpages
|
||||
all: doc/manual/generated/man1/nix3-manpages
|
||||
|
||||
# FIXME: unify with how the other man pages are generated.
|
||||
# this one works differently and does not use any of the amenities provided by `/mk/lib.mk`.
|
||||
$(mandir)/man1/nix3-manpages: doc/manual/generated/man1/nix3-manpages
|
||||
@mkdir -p $(DESTDIR)$$(dirname $@)
|
||||
$(trace-install) install -m 0644 $$(dirname $<)/* $(DESTDIR)$$(dirname $@)
|
||||
|
||||
doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
|
||||
@mkdir -p $(DESTDIR)$$(dirname $@)
|
||||
$(trace-gen) for i in doc/manual/src/command-ref/new-cli/*.md; do \
|
||||
name=$$(basename $$i .md); \
|
||||
tmpFile=$$(mktemp); \
|
||||
if [[ $$name = SUMMARY ]]; then continue; fi; \
|
||||
printf "Title: %s\n\n" "$$name" > $$tmpFile; \
|
||||
cat $$i >> $$tmpFile; \
|
||||
lowdown -sT man --nroff-nolinks -M section=1 $$tmpFile -o $(DESTDIR)$$(dirname $@)/$$name.1; \
|
||||
rm $$tmpFile; \
|
||||
done
|
||||
@touch $@
|
||||
|
||||
# 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/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"; \
|
||||
find "$$tmp" -name '*.md' | while read -r file; do \
|
||||
$(call process-includes,$$file,$$file); \
|
||||
done; \
|
||||
find "$$tmp" -name '*.md' ! -name 'documentation.md' | while read -r file; do \
|
||||
docroot="$$(realpath --relative-to="$$(dirname "$$file")" $$tmp/manual/src)"; \
|
||||
sed -i "s,@docroot@,$$docroot,g" "$$file"; \
|
||||
done; \
|
||||
set -euo pipefail; \
|
||||
RUST_LOG=warn mdbook build "$$tmp/manual" -d $(DESTDIR)$(docdir)/manual.tmp 2>&1 \
|
||||
| { grep -Fv "because fragment resolution isn't implemented" || :; }; \
|
||||
rm -rf "$$tmp/manual"
|
||||
@rm -rf $(DESTDIR)$(docdir)/manual
|
||||
@mv $(DESTDIR)$(docdir)/manual.tmp/html $(DESTDIR)$(docdir)/manual
|
||||
@rm -rf $(DESTDIR)$(docdir)/manual.tmp
|
357
doc/manual/meson.build
Normal file
357
doc/manual/meson.build
Normal file
|
@ -0,0 +1,357 @@
|
|||
project('nix-manual',
|
||||
version : files('.version'),
|
||||
meson_version : '>= 1.1',
|
||||
license : 'LGPL-2.1-or-later',
|
||||
)
|
||||
|
||||
nix = find_program('nix', native : true)
|
||||
|
||||
mdbook = find_program('mdbook', native : true)
|
||||
bash = find_program('bash', native : true)
|
||||
|
||||
pymod = import('python')
|
||||
python = pymod.find_installation('python3')
|
||||
|
||||
nix_env_for_docs = {
|
||||
'HOME': '/dummy',
|
||||
'NIX_CONF_DIR': '/dummy',
|
||||
'NIX_SSL_CERT_FILE': '/dummy/no-ca-bundle.crt',
|
||||
'NIX_STATE_DIR': '/dummy',
|
||||
'NIX_CONFIG': 'cores = 0',
|
||||
}
|
||||
|
||||
nix_for_docs = [nix]
|
||||
nix_eval_for_docs_common = nix_for_docs + [
|
||||
'eval',
|
||||
'-I', 'nix=' + meson.current_source_dir(),
|
||||
'--store', 'dummy://',
|
||||
'--impure',
|
||||
]
|
||||
nix_eval_for_docs = nix_eval_for_docs_common + '--raw'
|
||||
|
||||
conf_file_json = custom_target(
|
||||
command : nix_for_docs + ['config', 'show', '--json'],
|
||||
capture : true,
|
||||
output : 'conf-file.json',
|
||||
env : nix_env_for_docs,
|
||||
)
|
||||
|
||||
language_json = custom_target(
|
||||
command: [nix, '__dump-language'],
|
||||
output : 'language.json',
|
||||
capture : true,
|
||||
env : nix_env_for_docs,
|
||||
)
|
||||
|
||||
nix3_cli_json = custom_target(
|
||||
command : [nix, '__dump-cli'],
|
||||
capture : true,
|
||||
output : 'nix.json',
|
||||
env : nix_env_for_docs,
|
||||
)
|
||||
|
||||
generate_manual_deps = files(
|
||||
'generate-deps.py',
|
||||
)
|
||||
|
||||
# Generates types
|
||||
subdir('source/store')
|
||||
# Generates builtins.md and builtin-constants.md.
|
||||
subdir('source/language')
|
||||
# Generates new-cli pages, experimental-features-shortlist.md, and conf-file.md.
|
||||
subdir('source/command-ref')
|
||||
# Generates experimental-feature-descriptions.md.
|
||||
subdir('source/development')
|
||||
# Generates rl-next-generated.md.
|
||||
subdir('source/release-notes')
|
||||
subdir('source')
|
||||
|
||||
# Hacky way to figure out if `nix` is an `ExternalProgram` or
|
||||
# `Exectuable`. Only the latter can occur in custom target input lists.
|
||||
if nix.full_path().startswith(meson.build_root())
|
||||
nix_input = nix
|
||||
else
|
||||
nix_input = []
|
||||
endif
|
||||
|
||||
manual = custom_target(
|
||||
'manual',
|
||||
command : [
|
||||
bash,
|
||||
'-euo', 'pipefail',
|
||||
'-c',
|
||||
'''
|
||||
@0@ @INPUT0@ @CURRENT_SOURCE_DIR@ > @DEPFILE@
|
||||
@0@ @INPUT1@ summary @2@ < @CURRENT_SOURCE_DIR@/source/SUMMARY.md.in > @2@/source/SUMMARY.md
|
||||
rsync -r --include='*.md' @CURRENT_SOURCE_DIR@/ @2@/
|
||||
(cd @2@; RUST_LOG=warn @1@ build -d @2@ 3>&2 2>&1 1>&3) | { grep -Fv "because fragment resolution isn't implemented" || :; } 3>&2 2>&1 1>&3
|
||||
rm -rf @2@/manual
|
||||
mv @2@/html @2@/manual
|
||||
find @2@/manual -iname meson.build -delete
|
||||
'''.format(
|
||||
python.full_path(),
|
||||
mdbook.full_path(),
|
||||
meson.current_build_dir(),
|
||||
),
|
||||
],
|
||||
input : [
|
||||
generate_manual_deps,
|
||||
'substitute.py',
|
||||
'book.toml',
|
||||
'anchors.jq',
|
||||
'custom.css',
|
||||
nix3_cli_files,
|
||||
experimental_features_shortlist_md,
|
||||
experimental_feature_descriptions_md,
|
||||
types_dir,
|
||||
conf_file_md,
|
||||
builtins_md,
|
||||
rl_next_generated,
|
||||
summary_rl_next,
|
||||
nix_input,
|
||||
],
|
||||
output : [
|
||||
'manual',
|
||||
'markdown',
|
||||
],
|
||||
depfile : 'manual.d',
|
||||
env : {
|
||||
'RUST_LOG': 'info',
|
||||
'MDBOOK_SUBSTITUTE_SEARCH': meson.current_build_dir() / 'source',
|
||||
},
|
||||
)
|
||||
manual_html = manual[0]
|
||||
manual_md = manual[1]
|
||||
|
||||
install_subdir(
|
||||
manual_html.full_path(),
|
||||
install_dir : get_option('datadir') / 'doc/nix',
|
||||
)
|
||||
|
||||
nix_nested_manpages = [
|
||||
[ 'nix-env',
|
||||
[
|
||||
'delete-generations',
|
||||
'install',
|
||||
'list-generations',
|
||||
'query',
|
||||
'rollback',
|
||||
'set-flag',
|
||||
'set',
|
||||
'switch-generation',
|
||||
'switch-profile',
|
||||
'uninstall',
|
||||
'upgrade',
|
||||
],
|
||||
],
|
||||
[ 'nix-store',
|
||||
[
|
||||
'add-fixed',
|
||||
'add',
|
||||
'delete',
|
||||
'dump-db',
|
||||
'dump',
|
||||
'export',
|
||||
'gc',
|
||||
'generate-binary-cache-key',
|
||||
'import',
|
||||
'load-db',
|
||||
'optimise',
|
||||
'print-env',
|
||||
'query',
|
||||
'read-log',
|
||||
'realise',
|
||||
'repair-path',
|
||||
'restore',
|
||||
'serve',
|
||||
'verify',
|
||||
'verify-path',
|
||||
],
|
||||
],
|
||||
]
|
||||
|
||||
foreach command : nix_nested_manpages
|
||||
foreach page : command[1]
|
||||
title = command[0] + ' --' + page
|
||||
section = '1'
|
||||
custom_target(
|
||||
command : [
|
||||
bash,
|
||||
files('./render-manpage.sh'),
|
||||
'--out-no-smarty',
|
||||
title,
|
||||
section,
|
||||
'@INPUT0@/command-ref' / command[0] / (page + '.md'),
|
||||
'@OUTPUT0@',
|
||||
],
|
||||
input : [
|
||||
manual_md,
|
||||
nix_input,
|
||||
],
|
||||
output : command[0] + '-' + page + '.1',
|
||||
install : true,
|
||||
install_dir : get_option('mandir') / 'man1',
|
||||
)
|
||||
endforeach
|
||||
endforeach
|
||||
|
||||
nix3_manpages = [
|
||||
'nix3-build',
|
||||
'nix3-bundle',
|
||||
'nix3-config',
|
||||
'nix3-config-check',
|
||||
'nix3-config-show',
|
||||
'nix3-copy',
|
||||
'nix3-daemon',
|
||||
'nix3-derivation-add',
|
||||
'nix3-derivation',
|
||||
'nix3-derivation-show',
|
||||
'nix3-develop',
|
||||
'nix3-edit',
|
||||
'nix3-env-shell',
|
||||
'nix3-eval',
|
||||
'nix3-flake-archive',
|
||||
'nix3-flake-check',
|
||||
'nix3-flake-clone',
|
||||
'nix3-flake-info',
|
||||
'nix3-flake-init',
|
||||
'nix3-flake-lock',
|
||||
'nix3-flake',
|
||||
'nix3-flake-metadata',
|
||||
'nix3-flake-new',
|
||||
'nix3-flake-prefetch',
|
||||
'nix3-flake-show',
|
||||
'nix3-flake-update',
|
||||
'nix3-fmt',
|
||||
'nix3-hash-file',
|
||||
'nix3-hash',
|
||||
'nix3-hash-convert',
|
||||
'nix3-hash-path',
|
||||
'nix3-hash-to-base16',
|
||||
'nix3-hash-to-base32',
|
||||
'nix3-hash-to-base64',
|
||||
'nix3-hash-to-sri',
|
||||
'nix3-help',
|
||||
'nix3-help-stores',
|
||||
'nix3-key-convert-secret-to-public',
|
||||
'nix3-key-generate-secret',
|
||||
'nix3-key',
|
||||
'nix3-log',
|
||||
'nix3-nar-cat',
|
||||
'nix3-nar-dump-path',
|
||||
'nix3-nar-ls',
|
||||
'nix3-nar-pack',
|
||||
'nix3-nar',
|
||||
'nix3-path-info',
|
||||
'nix3-print-dev-env',
|
||||
'nix3-profile-diff-closures',
|
||||
'nix3-profile-history',
|
||||
'nix3-profile-install',
|
||||
'nix3-profile-list',
|
||||
'nix3-profile',
|
||||
'nix3-profile-remove',
|
||||
'nix3-profile-rollback',
|
||||
'nix3-profile-upgrade',
|
||||
'nix3-profile-wipe-history',
|
||||
'nix3-realisation-info',
|
||||
'nix3-realisation',
|
||||
'nix3-registry-add',
|
||||
'nix3-registry-list',
|
||||
'nix3-registry',
|
||||
'nix3-registry-pin',
|
||||
'nix3-registry-remove',
|
||||
'nix3-repl',
|
||||
'nix3-run',
|
||||
'nix3-search',
|
||||
'nix3-store-add',
|
||||
'nix3-store-add-file',
|
||||
'nix3-store-add-path',
|
||||
'nix3-store-cat',
|
||||
'nix3-store-copy-log',
|
||||
'nix3-store-copy-sigs',
|
||||
'nix3-store-delete',
|
||||
'nix3-store-diff-closures',
|
||||
'nix3-store-dump-path',
|
||||
'nix3-store-gc',
|
||||
'nix3-store-info',
|
||||
'nix3-store-ls',
|
||||
'nix3-store-make-content-addressed',
|
||||
'nix3-store',
|
||||
'nix3-store-optimise',
|
||||
'nix3-store-path-from-hash-part',
|
||||
'nix3-store-ping',
|
||||
'nix3-store-prefetch-file',
|
||||
'nix3-store-repair',
|
||||
'nix3-store-sign',
|
||||
'nix3-store-verify',
|
||||
'nix3-upgrade-nix',
|
||||
'nix3-why-depends',
|
||||
'nix',
|
||||
]
|
||||
|
||||
foreach page : nix3_manpages
|
||||
section = '1'
|
||||
custom_target(
|
||||
command : [
|
||||
bash,
|
||||
'@INPUT0@',
|
||||
page,
|
||||
section,
|
||||
'@INPUT1@/command-ref/new-cli/@0@.md'.format(page),
|
||||
'@OUTPUT@',
|
||||
],
|
||||
input : [
|
||||
files('./render-manpage.sh'),
|
||||
manual_md,
|
||||
nix_input,
|
||||
],
|
||||
output : page + '.1',
|
||||
install : true,
|
||||
install_dir : get_option('mandir') / 'man1',
|
||||
)
|
||||
endforeach
|
||||
|
||||
nix_manpages = [
|
||||
[ 'nix-env', 1 ],
|
||||
[ 'nix-store', 1 ],
|
||||
[ 'nix-build', 1 ],
|
||||
[ 'nix-shell', 1 ],
|
||||
[ 'nix-instantiate', 1 ],
|
||||
[ 'nix-collect-garbage', 1 ],
|
||||
[ 'nix-prefetch-url', 1 ],
|
||||
[ 'nix-channel', 1 ],
|
||||
[ 'nix-hash', 1 ],
|
||||
[ 'nix-copy-closure', 1 ],
|
||||
[ 'nix.conf', 5, conf_file_md.full_path() ],
|
||||
[ 'nix-daemon', 8 ],
|
||||
[ 'nix-profiles', 5, 'files/profiles.md' ],
|
||||
]
|
||||
|
||||
foreach entry : nix_manpages
|
||||
title = entry[0]
|
||||
# nix.conf.5 and nix-profiles.5 are based off of conf-file.md and files/profiles.md,
|
||||
# rather than a stem identical to its mdbook source.
|
||||
# Therefore we use an optional third element of this array to override the name pattern
|
||||
md_file = entry.get(2, title + '.md')
|
||||
section = entry[1].to_string()
|
||||
md_file_resolved = join_paths('@INPUT1@/command-ref/', md_file)
|
||||
custom_target(
|
||||
command : [
|
||||
bash,
|
||||
'@INPUT0@',
|
||||
title,
|
||||
section,
|
||||
md_file_resolved,
|
||||
'@OUTPUT@',
|
||||
],
|
||||
input : [
|
||||
files('./render-manpage.sh'),
|
||||
manual_md,
|
||||
entry.get(3, []),
|
||||
nix_input,
|
||||
],
|
||||
output : '@0@.@1@'.format(entry[0], entry[1]),
|
||||
install : true,
|
||||
install_dir : get_option('mandir') / 'man@0@'.format(entry[1]),
|
||||
)
|
||||
endforeach
|
75
doc/manual/package.nix
Normal file
75
doc/manual/package.nix
Normal file
|
@ -0,0 +1,75 @@
|
|||
{
|
||||
lib,
|
||||
mkMesonDerivation,
|
||||
|
||||
meson,
|
||||
ninja,
|
||||
lowdown-unsandboxed,
|
||||
mdbook,
|
||||
mdbook-linkcheck,
|
||||
jq,
|
||||
python3,
|
||||
rsync,
|
||||
nix-cli,
|
||||
|
||||
# Configuration Options
|
||||
|
||||
version,
|
||||
}:
|
||||
|
||||
let
|
||||
inherit (lib) fileset;
|
||||
in
|
||||
|
||||
mkMesonDerivation (finalAttrs: {
|
||||
pname = "nix-manual";
|
||||
inherit version;
|
||||
|
||||
workDir = ./.;
|
||||
fileset =
|
||||
fileset.difference
|
||||
(fileset.unions [
|
||||
../../.version
|
||||
# Too many different types of files to filter for now
|
||||
../../doc/manual
|
||||
./.
|
||||
])
|
||||
# Do a blacklist instead
|
||||
../../doc/manual/package.nix;
|
||||
|
||||
# TODO the man pages should probably be separate
|
||||
outputs = [
|
||||
"out"
|
||||
"man"
|
||||
];
|
||||
|
||||
# Hack for sake of the dev shell
|
||||
passthru.externalNativeBuildInputs = [
|
||||
meson
|
||||
ninja
|
||||
(lib.getBin lowdown-unsandboxed)
|
||||
mdbook
|
||||
mdbook-linkcheck
|
||||
jq
|
||||
python3
|
||||
rsync
|
||||
];
|
||||
|
||||
nativeBuildInputs = finalAttrs.passthru.externalNativeBuildInputs ++ [
|
||||
nix-cli
|
||||
];
|
||||
|
||||
preConfigure = ''
|
||||
chmod u+w ./.version
|
||||
echo ${finalAttrs.version} > ./.version
|
||||
'';
|
||||
|
||||
postInstall = ''
|
||||
mkdir -p ''$out/nix-support
|
||||
echo "doc manual ''$out/share/doc/nix/manual" >> ''$out/nix-support/hydra-build-products
|
||||
'';
|
||||
|
||||
meta = {
|
||||
platforms = lib.platforms.all;
|
||||
};
|
||||
})
|
|
@ -1,7 +1,7 @@
|
|||
// redirect rules for URL fragments (client-side) to prevent link rot.
|
||||
// this must be done on the client side, as web servers do not see the fragment part of the URL.
|
||||
// it will only work with JavaScript enabled in the browser, but this is the best we can do here.
|
||||
// see src/_redirects for path redirects (server-side)
|
||||
// see source/_redirects for path redirects (server-side)
|
||||
|
||||
// redirects are declared as follows:
|
||||
// each entry has as its key a path matching the requested URL path, relative to the mdBook document root.
|
||||
|
@ -344,6 +344,7 @@ const redirects = {
|
|||
},
|
||||
"language/syntax.html": {
|
||||
"scoping-rules": "scoping.html",
|
||||
"string-literal": "string-literals.html",
|
||||
},
|
||||
"installation/installing-binary.html": {
|
||||
"linux": "uninstall.html#linux",
|
||||
|
|
33
doc/manual/remove_before_wrapper.py
Normal file
33
doc/manual/remove_before_wrapper.py
Normal file
|
@ -0,0 +1,33 @@
|
|||
#!/usr/bin/env python3
|
||||
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
import shutil
|
||||
import typing as t
|
||||
|
||||
def main():
|
||||
if len(sys.argv) < 4 or '--' not in sys.argv:
|
||||
print("Usage: remove-before-wrapper <output> -- <nix command...>")
|
||||
sys.exit(1)
|
||||
|
||||
# Extract the parts
|
||||
output: str = sys.argv[1]
|
||||
nix_command_idx: int = sys.argv.index('--') + 1
|
||||
nix_command: t.List[str] = sys.argv[nix_command_idx:]
|
||||
|
||||
output_temp: str = output + '.tmp'
|
||||
|
||||
# Remove the output and temp output in case they exist
|
||||
shutil.rmtree(output, ignore_errors=True)
|
||||
shutil.rmtree(output_temp, ignore_errors=True)
|
||||
|
||||
# Execute nix command with `--write-to` tempary output
|
||||
nix_command_write_to = nix_command + ['--write-to', output_temp]
|
||||
subprocess.run(nix_command_write_to, check=True)
|
||||
|
||||
# Move the temporary output to the intended location
|
||||
os.rename(output_temp, output)
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
25
doc/manual/render-manpage.sh
Executable file
25
doc/manual/render-manpage.sh
Executable file
|
@ -0,0 +1,25 @@
|
|||
#!/usr/bin/env bash
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
lowdown_args=
|
||||
|
||||
if [ "$1" = --out-no-smarty ]; then
|
||||
lowdown_args=--out-no-smarty
|
||||
shift
|
||||
fi
|
||||
|
||||
[ "$#" = 4 ] || {
|
||||
echo "wrong number of args passed" >&2
|
||||
exit 1
|
||||
}
|
||||
|
||||
title="$1"
|
||||
section="$2"
|
||||
infile="$3"
|
||||
outfile="$4"
|
||||
|
||||
(
|
||||
printf "Title: %s\n\n" "$title"
|
||||
cat "$infile"
|
||||
) | lowdown -sT man --nroff-nolinks $lowdown_args -M section="$section" -o "$outfile"
|
|
@ -28,6 +28,8 @@
|
|||
- [Data Types](language/types.md)
|
||||
- [String context](language/string-context.md)
|
||||
- [Syntax and semantics](language/syntax.md)
|
||||
- [Variables](language/variables.md)
|
||||
- [String literals](language/string-literals.md)
|
||||
- [Identifiers](language/identifiers.md)
|
||||
- [Scoping rules](language/scope.md)
|
||||
- [String interpolation](language/string-interpolation.md)
|
||||
|
@ -119,6 +121,7 @@
|
|||
- [Development](development/index.md)
|
||||
- [Building](development/building.md)
|
||||
- [Testing](development/testing.md)
|
||||
- [Debugging](development/debugging.md)
|
||||
- [Documentation](development/documentation.md)
|
||||
- [CLI guideline](development/cli-guideline.md)
|
||||
- [JSON guideline](development/json-guideline.md)
|
||||
|
@ -130,6 +133,8 @@
|
|||
- [Release 1.0 (2024-11-??)](release-notes-determinate/rl-1.0.md)
|
||||
- [Nix Releases Notes](release-notes/index.md)
|
||||
{{#include ./SUMMARY-rl-next.md}}
|
||||
- [Release 2.26 (2025-01-22)](release-notes/rl-2.26.md)
|
||||
- [Release 2.25 (2024-11-07)](release-notes/rl-2.25.md)
|
||||
- [Release 2.24 (2024-07-31)](release-notes/rl-2.24.md)
|
||||
- [Release 2.23 (2024-06-03)](release-notes/rl-2.23.md)
|
||||
- [Release 2.22 (2024-04-23)](release-notes/rl-2.22.md)
|
108
doc/manual/source/advanced-topics/distributed-builds.md
Normal file
108
doc/manual/source/advanced-topics/distributed-builds.md
Normal file
|
@ -0,0 +1,108 @@
|
|||
# Remote Builds
|
||||
|
||||
A local Nix installation can forward Nix builds to other machines,
|
||||
this allows multiple builds to be performed in parallel.
|
||||
|
||||
Remote builds also allow Nix to perform multi-platform builds in a
|
||||
semi-transparent way. For example, if you perform a build for a
|
||||
`x86_64-darwin` on an `i686-linux` machine, Nix can automatically
|
||||
forward the build to a `x86_64-darwin` machine, if one is available.
|
||||
|
||||
## Requirements
|
||||
|
||||
For a local machine to forward a build to a remote machine, the remote machine must:
|
||||
|
||||
- Have Nix installed
|
||||
- Be running an SSH server, e.g. `sshd`
|
||||
- Be accessible via SSH from the local machine over the network
|
||||
- Have the local machine's public SSH key in `/etc/ssh/authorized_keys.d/<username>`
|
||||
- Have the username of the SSH user in the `trusted-users` setting in `nix.conf`
|
||||
|
||||
## Testing
|
||||
|
||||
To test connecting to a remote Nix instance (in this case `mac`), run:
|
||||
|
||||
```console
|
||||
nix store info --store ssh://username@mac
|
||||
```
|
||||
|
||||
To specify an SSH identity file as part of the remote store URI add a
|
||||
query paramater, e.g.
|
||||
|
||||
```console
|
||||
nix store info --store ssh://username@mac?ssh-key=/home/alice/my-key
|
||||
```
|
||||
|
||||
Since builds should be non-interactive, the key should not have a
|
||||
passphrase. Alternatively, you can load identities ahead of time into
|
||||
`ssh-agent` or `gpg-agent`.
|
||||
|
||||
In a multi-user installation (default), builds are executed by the Nix
|
||||
Daemon. The Nix Daemon cannot prompt for a passphrase via the terminal
|
||||
or `ssh-agent`, so the SSH key must not have a passphrase.
|
||||
|
||||
In addition, the Nix Daemon's user (typically root) needs to have SSH
|
||||
access to the remote builder.
|
||||
|
||||
Access can be verified by running `sudo su`, and then validating SSH
|
||||
access, e.g. by running `ssh mac`. SSH identity files for root users
|
||||
are usually stored in `/root/.ssh/` (Linux) or `/var/root/.ssh` (MacOS).
|
||||
|
||||
If you get the error
|
||||
|
||||
```console
|
||||
bash: nix: command not found
|
||||
error: cannot connect to 'mac'
|
||||
```
|
||||
|
||||
then you need to ensure that the `PATH` of non-interactive login shells
|
||||
contains Nix.
|
||||
|
||||
The [list of remote build machines](@docroot@/command-ref/conf-file.md#conf-builders) can be specified on the command line or in the Nix configuration file.
|
||||
For example, the following command allows you to build a derivation for `x86_64-darwin` on a Linux machine:
|
||||
|
||||
```console
|
||||
uname
|
||||
```
|
||||
|
||||
```console
|
||||
Linux
|
||||
```
|
||||
|
||||
```console
|
||||
nix build --impure \
|
||||
--expr '(with import <nixpkgs> { system = "x86_64-darwin"; }; runCommand "foo" {} "uname > $out")' \
|
||||
--builders 'ssh://mac x86_64-darwin'
|
||||
```
|
||||
|
||||
```console
|
||||
[1/0/1 built, 0.0 MiB DL] building foo on ssh://mac
|
||||
```
|
||||
|
||||
```console
|
||||
cat ./result
|
||||
```
|
||||
|
||||
```console
|
||||
Darwin
|
||||
```
|
||||
|
||||
It is possible to specify multiple build machines separated by a semicolon or a newline, e.g.
|
||||
|
||||
```console
|
||||
--builders 'ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd'
|
||||
```
|
||||
|
||||
Remote build machines can also be configured in [`nix.conf`](@docroot@/command-ref/conf-file.md), e.g.
|
||||
|
||||
builders = ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd
|
||||
|
||||
After making changes to `nix.conf`, restart the Nix daemon for changes to take effect.
|
||||
|
||||
Finally, remote build machines can be configured in a separate configuration
|
||||
file included in `builders` via the syntax `@/path/to/file`. For example,
|
||||
|
||||
builders = @/etc/nix/machines
|
||||
|
||||
causes the list of machines in `/etc/nix/machines` to be included.
|
||||
(This is the default.)
|
|
@ -138,6 +138,19 @@ The following environment variables are used to determine locations of various s
|
|||
- [`XDG_STATE_HOME`]{#env-XDG_STATE_HOME} (default `~/.local/state`)
|
||||
- [`XDG_CACHE_HOME`]{#env-XDG_CACHE_HOME} (default `~/.cache`)
|
||||
|
||||
|
||||
[XDG Base Directory Specification]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
|
||||
[`use-xdg-base-directories`]: @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories
|
||||
|
||||
In addition, setting the following environment variables overrides the XDG base directories:
|
||||
|
||||
- [`NIX_CONFIG_HOME`]{#env-NIX_CONFIG_HOME} (default `$XDG_CONFIG_HOME/nix`)
|
||||
- [`NIX_STATE_HOME`]{#env-NIX_STATE_HOME} (default `$XDG_STATE_HOME/nix`)
|
||||
- [`NIX_CACHE_HOME`]{#env-NIX_CACHE_HOME} (default `$XDG_CACHE_HOME/nix`)
|
||||
|
||||
When [`use-xdg-base-directories`] is enabled, the configuration directory is:
|
||||
|
||||
1. `$NIX_CONFIG_HOME`, if it is defined
|
||||
2. Otherwise, `$XDG_CONFIG_HOME/nix`, if `XDG_CONFIG_HOME` is defined
|
||||
3. Otherwise, `~/.config/nix`.
|
||||
|
||||
Likewise for the state and cache directories.
|
|
@ -1,6 +1,6 @@
|
|||
## Default Nix expression
|
||||
|
||||
The source for the default [Nix expressions](@docroot@/language/index.md) used by [`nix-env`]:
|
||||
The source for the [Nix expressions](@docroot@/glossary.md#gloss-nix-expression) used by [`nix-env`] by default:
|
||||
|
||||
- `~/.nix-defexpr`
|
||||
- `$XDG_STATE_HOME/nix/defexpr` if [`use-xdg-base-directories`] is set to `true`.
|
||||
|
@ -18,24 +18,25 @@ Then, the resulting expression is interpreted like this:
|
|||
- If the expression is an attribute set, it is used as the default Nix expression.
|
||||
- If the expression is a function, an empty set is passed as argument and the return value is used as the default Nix expression.
|
||||
|
||||
|
||||
For example, if the default expression contains two files, `foo.nix` and `bar.nix`, then the default Nix expression will be equivalent to
|
||||
|
||||
```nix
|
||||
{
|
||||
foo = import ~/.nix-defexpr/foo.nix;
|
||||
bar = import ~/.nix-defexpr/bar.nix;
|
||||
}
|
||||
```
|
||||
> **Example**
|
||||
>
|
||||
> If the default expression contains two files, `foo.nix` and `bar.nix`, then the default Nix expression will be equivalent to
|
||||
>
|
||||
> ```nix
|
||||
> {
|
||||
> foo = import ~/.nix-defexpr/foo.nix;
|
||||
> bar = import ~/.nix-defexpr/bar.nix;
|
||||
> }
|
||||
> ```
|
||||
|
||||
The file [`manifest.nix`](@docroot@/command-ref/files/manifest.nix.md) is always ignored.
|
||||
|
||||
The command [`nix-channel`] places a symlink to the user's current [channels profile](@docroot@/command-ref/files/channels.md) in this directory.
|
||||
The command [`nix-channel`] places a symlink to the current user's [channels] in this directory, the [user channel link](#user-channel-link).
|
||||
This makes all subscribed channels available as attributes in the default expression.
|
||||
|
||||
## User channel link
|
||||
|
||||
A symlink that ensures that [`nix-env`] can find your channels:
|
||||
A symlink that ensures that [`nix-env`] can find the current user's [channels]:
|
||||
|
||||
- `~/.nix-defexpr/channels`
|
||||
- `$XDG_STATE_HOME/defexpr/channels` if [`use-xdg-base-directories`] is set to `true`.
|
||||
|
@ -45,8 +46,9 @@ This symlink points to:
|
|||
- `$XDG_STATE_HOME/profiles/channels` for regular users
|
||||
- `$NIX_STATE_DIR/profiles/per-user/root/channels` for `root`
|
||||
|
||||
In a multi-user installation, you may also have `~/.nix-defexpr/channels_root`, which links to the channels of the root user.[`nix-env`]: ../nix-env.md
|
||||
In a multi-user installation, you may also have `~/.nix-defexpr/channels_root`, which links to the channels of the root user.
|
||||
|
||||
[`nix-env`]: @docroot@/command-ref/nix-env.md
|
||||
[`nix-channel`]: @docroot@/command-ref/nix-channel.md
|
||||
[`nix-env`]: @docroot@/command-ref/nix-env.md
|
||||
[`use-xdg-base-directories`]: @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories
|
||||
[channels]: @docroot@/command-ref/files/channels.md
|
63
doc/manual/source/command-ref/meson.build
Normal file
63
doc/manual/source/command-ref/meson.build
Normal file
|
@ -0,0 +1,63 @@
|
|||
xp_features_json = custom_target(
|
||||
command : [nix, '__dump-xp-features'],
|
||||
capture : true,
|
||||
output : 'xp-features.json',
|
||||
)
|
||||
|
||||
experimental_features_shortlist_md = custom_target(
|
||||
command : nix_eval_for_docs + [
|
||||
'--expr',
|
||||
'import @INPUT0@ (builtins.fromJSON (builtins.readFile ./@INPUT1@))',
|
||||
],
|
||||
input : [
|
||||
'../../generate-xp-features-shortlist.nix',
|
||||
xp_features_json,
|
||||
],
|
||||
output : 'experimental-features-shortlist.md',
|
||||
capture : true,
|
||||
env : nix_env_for_docs,
|
||||
)
|
||||
|
||||
nix3_cli_files = custom_target(
|
||||
command : [
|
||||
python.full_path(),
|
||||
'@INPUT0@',
|
||||
'@OUTPUT@',
|
||||
'--'
|
||||
] + nix_eval_for_docs + [
|
||||
'--expr',
|
||||
'import @INPUT1@ true (builtins.readFile ./@INPUT2@)',
|
||||
],
|
||||
input : [
|
||||
'../../remove_before_wrapper.py',
|
||||
'../../generate-manpage.nix',
|
||||
nix3_cli_json,
|
||||
],
|
||||
output : 'new-cli',
|
||||
env : nix_env_for_docs,
|
||||
)
|
||||
|
||||
conf_file_md_body = custom_target(
|
||||
command : [
|
||||
nix_eval_for_docs,
|
||||
'--expr',
|
||||
'import @INPUT0@ { prefix = "conf"; } (builtins.fromJSON (builtins.readFile ./@INPUT1@))',
|
||||
],
|
||||
capture : true,
|
||||
input : [
|
||||
'../../generate-settings.nix',
|
||||
conf_file_json,
|
||||
],
|
||||
output : 'conf-file.body.md',
|
||||
env : nix_env_for_docs,
|
||||
)
|
||||
|
||||
conf_file_md = custom_target(
|
||||
command : [ 'cat', '@INPUT0@', '@INPUT1@' ],
|
||||
capture : true,
|
||||
input : [
|
||||
'conf-file-prefix.md',
|
||||
conf_file_md_body,
|
||||
],
|
||||
output : 'conf-file.md',
|
||||
)
|
|
@ -36,7 +36,7 @@ Instead, it looks in a few locations, and acts on all profiles it finds there:
|
|||
>
|
||||
> Not stable; subject to change
|
||||
>
|
||||
> Do not rely on this functionality; it just exists for migration purposes and is may change in the future.
|
||||
> Do not rely on this functionality; it just exists for migration purposes and may change in the future.
|
||||
> These deprecated paths remain a private implementation detail of Nix.
|
||||
|
||||
`$NIX_STATE_DIR/profiles` and `$NIX_STATE_DIR/profiles/per-user`.
|
||||
|
@ -62,6 +62,15 @@ These options are for deleting old [profiles] prior to deleting unreachable [sto
|
|||
This is the equivalent of invoking [`nix-env --delete-generations <period>`](@docroot@/command-ref/nix-env/delete-generations.md#generations-time) on each found profile.
|
||||
See the documentation of that command for additional information about the *period* argument.
|
||||
|
||||
- <span id="opt-max-freed">[`--max-freed`](#opt-max-freed)</span> *bytes*
|
||||
|
||||
<!-- duplication from https://github.com/NixOS/nix/blob/442a2623e48357ff72c77bb11cf2cf06d94d2f90/doc/manual/source/command-ref/nix-store/gc.md?plain=1#L39-L44 -->
|
||||
|
||||
Keep deleting paths until at least *bytes* bytes have been deleted,
|
||||
then stop. The argument *bytes* can be followed by the
|
||||
multiplicative suffix `K`, `M`, `G` or `T`, denoting KiB, MiB, GiB
|
||||
or TiB units.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ./env-common.md}}
|
|
@ -84,7 +84,7 @@ When using public key authentication, you can avoid typing the passphrase with `
|
|||
> Copy GNU Hello from a remote machine using a known store path, and run it:
|
||||
>
|
||||
> ```shell-session
|
||||
> $ storePath="$(nix-instantiate --eval '<nixpkgs>' -I nixpkgs=channel:nixpkgs-unstable -A hello.outPath | tr -d '"')"
|
||||
> $ storePath="$(nix-instantiate --eval --raw '<nixpkgs>' -I nixpkgs=channel:nixpkgs-unstable -A hello.outPath)"
|
||||
> $ nix-copy-closure --from alice@itchy.example.org "$storePath"
|
||||
> $ "$storePath"/bin/hello
|
||||
> Hello, world!
|
|
@ -62,7 +62,7 @@ These pages can be viewed offline:
|
|||
|
||||
Several operations, such as [`nix-env --query`](./nix-env/query.md) and [`nix-env --install`](./nix-env/install.md), take a list of *arguments* that specify the packages on which to operate.
|
||||
|
||||
Packages are identified based on a `name` part and a `version` part of a [symbolic derivation name](@docroot@/language/derivations.md#attr-names):
|
||||
Packages are identified based on a `name` part and a `version` part of a [symbolic derivation name](@docroot@/language/derivations.md#attr-name):
|
||||
|
||||
- `name`: Everything up to but not including the first dash (`-`) that is *not* followed by a letter.
|
||||
- `version`: The rest, excluding the separating dash.
|
|
@ -11,6 +11,7 @@
|
|||
[`--from-profile` *path*]
|
||||
[`--preserve-installed` | `-P`]
|
||||
[`--remove-all` | `-r`]
|
||||
[`--priority` *priority*]
|
||||
|
||||
# Description
|
||||
|
||||
|
@ -61,6 +62,10 @@ The arguments *args* map to store paths in a number of possible ways:
|
|||
The derivations returned by those function calls are installed.
|
||||
This allows derivations to be specified in an unambiguous way, which is necessary if there are multiple derivations with the same name.
|
||||
|
||||
- If `--priority` *priority* is given, the priority of the derivations being installed is set to *priority*.
|
||||
This can be used to override the priority of the derivations being installed.
|
||||
This is useful if *args* are [store paths], which don't have any priority information.
|
||||
|
||||
- If *args* are [store derivations](@docroot@/glossary.md#gloss-store-derivation), then these are [realised], and the resulting output paths are installed.
|
||||
|
||||
- If *args* are [store paths] that are not store derivations, then these are [realised] and installed.
|
||||
|
@ -235,4 +240,3 @@ channel:
|
|||
```console
|
||||
$ nix-env --file https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz --install --attr firefox
|
||||
```
|
||||
|
|
@ -5,7 +5,7 @@
|
|||
# Synopsis
|
||||
|
||||
`nix-instantiate`
|
||||
[`--parse` | `--eval` [`--strict`] [`--json`] [`--xml`] ]
|
||||
[`--parse` | `--eval` [`--strict`] [`--raw` | `--json` | `--xml`] ]
|
||||
[`--read-write-mode`]
|
||||
[`--arg` *name* *value*]
|
||||
[{`--attr`| `-A`} *attrPath*]
|
||||
|
@ -102,6 +102,11 @@ standard input.
|
|||
> This option can cause non-termination, because lazy data
|
||||
> structures can be infinitely large.
|
||||
|
||||
- `--raw`
|
||||
|
||||
When used with `--eval`, the evaluation result must be a string,
|
||||
which is printed verbatim, without quoting, escaping or trailing newline.
|
||||
|
||||
- `--json`
|
||||
|
||||
When used with `--eval`, print the resulting value as an JSON
|
|
@ -88,7 +88,9 @@ All options not listed here are passed to `nix-store
|
|||
cleared before the interactive shell is started, so you get an
|
||||
environment that more closely corresponds to the “real” Nix build. A
|
||||
few variables, in particular `HOME`, `USER` and `DISPLAY`, are
|
||||
retained.
|
||||
retained. Note that the shell used to run commands is obtained from
|
||||
[`NIX_BUILD_SHELL`](#env-NIX_BUILD_SHELL) / `<nixpkgs>` from
|
||||
`NIX_PATH`, and therefore not affected by `--pure`.
|
||||
|
||||
- `--packages` / `-p` *packages*…
|
||||
|
||||
|
@ -112,11 +114,30 @@ All options not listed here are passed to `nix-store
|
|||
|
||||
# Environment variables
|
||||
|
||||
- `NIX_BUILD_SHELL`
|
||||
- <span id="env-NIX_BUILD_SHELL">[`NIX_BUILD_SHELL`](#env-NIX_BUILD_SHELL)</span>
|
||||
|
||||
Shell used to start the interactive environment. Defaults to the
|
||||
`bash` found in `<nixpkgs>`, falling back to the `bash` found in
|
||||
`PATH` if not found.
|
||||
Shell used to start the interactive environment.
|
||||
Defaults to the `bash` from `bashInteractive` found in `<nixpkgs>`, falling back to the `bash` found in `PATH` if not found.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> The shell obtained using this method may not necessarily be the same as any shells requested in *path*.
|
||||
|
||||
<!-- -->
|
||||
|
||||
> **Example
|
||||
>
|
||||
> Despite `--pure`, this invocation will not result in a fully reproducible shell environment:
|
||||
>
|
||||
> ```nix
|
||||
> #!/usr/bin/env -S nix-shell --pure
|
||||
> let
|
||||
> pkgs = import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/854fdc68881791812eddd33b2fed94b954979a8e.tar.gz") {};
|
||||
> in
|
||||
> pkgs.mkShell {
|
||||
> buildInputs = pkgs.bashInteractive;
|
||||
> }
|
||||
> ```
|
||||
|
||||
{{#include ./env-common.md}}
|
||||
|
|
@ -21,6 +21,9 @@ This operation has the following options:
|
|||
Use recursive instead of flat hashing mode, used when adding
|
||||
directories to the store.
|
||||
|
||||
*paths* that refer to symlinks are not dereferenced, but added to the store
|
||||
as symlinks with the same target.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
|
@ -11,6 +11,9 @@
|
|||
The operation `--add` adds the specified paths to the Nix store. It
|
||||
prints the resulting paths in the Nix store on standard output.
|
||||
|
||||
*paths* that refer to symlinks are not dereferenced, but added to the store
|
||||
as symlinks with the same target.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
{{#include ../opt-common.md}}
|
|
@ -104,7 +104,7 @@ symlink.
|
|||
|
||||
Prints a set of derivation files (`.drv`) which are supposed produce
|
||||
said paths when realized. Might print nothing, for example for source paths
|
||||
or paths subsituted from a binary cache.
|
||||
or paths substituted from a binary cache.
|
||||
|
||||
- `--graph`
|
||||
|
||||
|
@ -241,4 +241,3 @@ $ nix-store --query --roots $(which svn)
|
|||
/nix/var/nix/profiles/default-82-link
|
||||
/home/eelco/.local/state/nix/profiles/profile-97-link
|
||||
```
|
||||
|
|
@ -1,3 +1,7 @@
|
|||
<!-- Some of the options documented here are hardcopied from
|
||||
src/libcmd/common-eval-args.cc
|
||||
-->
|
||||
|
||||
# Common Options
|
||||
|
||||
Most Nix commands accept the following command-line options:
|
||||
|
@ -161,6 +165,14 @@ Most Nix commands accept the following command-line options:
|
|||
You can override this using `--arg`, e.g., `nix-env --install --attr pkgname --arg system \"i686-freebsd\"`.
|
||||
(Note that since the argument is a Nix string literal, you have to escape the quotes.)
|
||||
|
||||
- <span id="opt-arg-from-file">[`--arg-from-file`](#opt-arg-from-file)</span> *name* *path*
|
||||
|
||||
Pass the contents of file *path* as the argument *name* to Nix functions.
|
||||
|
||||
- <span id="opt-arg-from-stdin">[`--arg-from-stdin`](#opt-arg-from-stdin)</span> *name*
|
||||
|
||||
Pass the contents of stdin as the argument *name* to Nix functions.
|
||||
|
||||
- <span id="opt-argstr">[`--argstr`](#opt-argstr)</span> *name* *value*
|
||||
|
||||
This option is like `--arg`, only the value is not a Nix expression but a string.
|
||||
|
@ -179,6 +191,10 @@ Most Nix commands accept the following command-line options:
|
|||
attribute of the fourth element of the array in the `foo` attribute
|
||||
of the top-level expression.
|
||||
|
||||
- <span id="opt-eval-store">[`--eval-store`](#opt-eval-store)</span> *store-url*
|
||||
|
||||
The [URL to the Nix store](@docroot@/store/types/index.md#store-url-format) to use for evaluation, i.e. where to store derivations (`.drv` files) and inputs referenced by them.
|
||||
|
||||
- <span id="opt-expr">[`--expr`](#opt-expr)</span> / `-E`
|
||||
|
||||
Interpret the command line arguments as a list of Nix expressions to be parsed and evaluated, rather than as a list of file names of Nix expressions.
|
||||
|
@ -194,6 +210,10 @@ Most Nix commands accept the following command-line options:
|
|||
|
||||
Paths added through `-I` take precedence over the [`nix-path` configuration setting](@docroot@/command-ref/conf-file.md#conf-nix-path) and the [`NIX_PATH` environment variable](@docroot@/command-ref/env-common.md#env-NIX_PATH).
|
||||
|
||||
- <span id="opt-impure">[`--impure`](#opt-impure)</span>
|
||||
|
||||
Allow access to mutable paths and repositories.
|
||||
|
||||
- <span id="opt-option">[`--option`](#opt-option)</span> *name* *value*
|
||||
|
||||
Set the Nix configuration option *name* to *value*.
|
|
@ -1,4 +1,4 @@
|
|||
## Building Nix
|
||||
# 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:
|
||||
|
||||
|
@ -22,16 +22,20 @@ $ nix develop .#native-clangStdenvPackages
|
|||
To build Nix itself in this shell:
|
||||
|
||||
```console
|
||||
[nix-shell]$ autoreconfPhase
|
||||
[nix-shell]$ configurePhase
|
||||
[nix-shell]$ make -j $NIX_BUILD_CORES OPTIMIZE=0
|
||||
[nix-shell]$ buildPhase
|
||||
```
|
||||
|
||||
To install it in `$(pwd)/outputs` and test it:
|
||||
To test it:
|
||||
|
||||
```console
|
||||
[nix-shell]$ make install OPTIMIZE=0
|
||||
[nix-shell]$ make installcheck check -j $NIX_BUILD_CORES
|
||||
[nix-shell]$ checkPhase
|
||||
```
|
||||
|
||||
To install it in `$(pwd)/outputs`:
|
||||
|
||||
```console
|
||||
[nix-shell]$ installPhase
|
||||
[nix-shell]$ nix --version
|
||||
nix (Nix) 2.12
|
||||
```
|
||||
|
@ -47,25 +51,6 @@ $ 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`.
|
||||
|
||||
Run `make` with [`-e` / `--environment-overrides`](https://www.gnu.org/software/make/manual/make.html#index-_002de) to allow environment variables to override `Makefile` variables:
|
||||
|
||||
- `ENABLE_BUILD=yes` to enable building the C++ code.
|
||||
- `ENABLE_DOC_GEN=yes` to enable building the documentation (manual, man pages, etc.).
|
||||
|
||||
The docs can take a while to build, so you may want to disable this for local development.
|
||||
- `ENABLE_FUNCTIONAL_TESTS=yes` to enable building the functional tests.
|
||||
- `OPTIMIZE=1` to enable optimizations.
|
||||
- `libraries=libutil programs=` to only build a specific library.
|
||||
|
||||
This will fail in the linking phase if the other libraries haven't been built, but is useful for checking types.
|
||||
- `libraries= programs=nix` to only build a specific program.
|
||||
|
||||
This will not work in general, because the programs need the libraries.
|
||||
|
||||
## Platforms
|
||||
|
||||
Nix can be built for various platforms, as specified in [`flake.nix`]:
|
||||
|
@ -106,27 +91,38 @@ Add more [system types](#system-type) to `crossSystems` in `flake.nix` to bootst
|
|||
|
||||
It is useful to perform multiple cross and native builds on the same source tree,
|
||||
for example to ensure that better support for one platform doesn't break the build for another.
|
||||
In order to facilitate this, Nix has some support for being built out of tree – that is, placing build artefacts in a different directory than the source code:
|
||||
Meson thankfully makes this very easy by confining all build products to the build directory --- one simple shares the source directory between multiple build directories, each of which contains the build for Nix to a different platform.
|
||||
|
||||
1. Create a directory for the build, e.g.
|
||||
Nixpkgs's `configurePhase` always chooses `build` in the current directory as the name and location of the build.
|
||||
This makes having multiple build directories slightly more inconvenient.
|
||||
The good news is that Meson/Ninja seem to cope well with relocating the build directory after it is created.
|
||||
|
||||
Here's how to do that
|
||||
|
||||
1. Configure as usual
|
||||
|
||||
```bash
|
||||
mkdir build
|
||||
configurePhase
|
||||
```
|
||||
|
||||
2. Run the configure script from that directory, e.g.
|
||||
2. Rename the build directory
|
||||
|
||||
```bash
|
||||
cd build
|
||||
../configure <configure flags>
|
||||
cd .. # since `configurePhase` cd'd inside
|
||||
mv build build-linux # or whatever name we want
|
||||
cd build-linux
|
||||
```
|
||||
|
||||
3. Run make from the source directory, but with the build directory specified, e.g.
|
||||
3. Build as usual
|
||||
|
||||
```bash
|
||||
make builddir=build <make flags>
|
||||
buildPhase
|
||||
```
|
||||
|
||||
> **N.B.**
|
||||
> [`nixpkgs#335818`](https://github.com/NixOS/nixpkgs/issues/335818) tracks giving `mesonConfigurePhase` proper support for custom build directories.
|
||||
> When it is fixed, we can simplify these instructions and then remove this notice.
|
||||
|
||||
## System type
|
||||
|
||||
Nix uses a string with the following format to identify the *system type* or *platform* it runs on:
|
||||
|
@ -180,11 +176,8 @@ You can use any of the other supported environments in place of `nix-ccacheStden
|
|||
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).
|
||||
|
||||
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 compile_commands.json
|
||||
```
|
||||
To use the LSP with your editor, you will want a `compile_commands.json` file telling `clangd` how we are compiling the code.
|
||||
Meson's configure always produces this inside the build directory.
|
||||
|
||||
Configure your editor to use the `clangd` from the `.#native-clangStdenvPackages` shell. You can do that 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).
|
||||
|
||||
|
@ -199,7 +192,7 @@ Configure your editor to use the `clangd` from the `.#native-clangStdenvPackages
|
|||
You may run the formatters as a one-off using:
|
||||
|
||||
```console
|
||||
make format
|
||||
./maintainers/format.sh
|
||||
```
|
||||
|
||||
If you'd like to run the formatters before every commit, install the hooks:
|
62
doc/manual/source/development/debugging.md
Normal file
62
doc/manual/source/development/debugging.md
Normal file
|
@ -0,0 +1,62 @@
|
|||
# Debugging Nix
|
||||
|
||||
This section shows how to build and debug Nix with debug symbols enabled.
|
||||
|
||||
## Building Nix with Debug Symbols
|
||||
|
||||
In the development shell, set the `mesonBuildType` environment variable to `debug` before configuring the build:
|
||||
|
||||
```console
|
||||
[nix-shell]$ export mesonBuildType=debugoptimized
|
||||
```
|
||||
|
||||
Then, proceed to build Nix as described in [Building Nix](./building.md).
|
||||
This will build Nix with debug symbols, which are essential for effective debugging.
|
||||
|
||||
## Debugging the Nix Binary
|
||||
|
||||
Obtain your preferred debugger within the development shell:
|
||||
|
||||
```console
|
||||
[nix-shell]$ nix-shell -p gdb
|
||||
```
|
||||
|
||||
On macOS, use `lldb`:
|
||||
|
||||
```console
|
||||
[nix-shell]$ nix-shell -p lldb
|
||||
```
|
||||
|
||||
### Launching the Debugger
|
||||
|
||||
To debug the Nix binary, run:
|
||||
|
||||
```console
|
||||
[nix-shell]$ gdb --args ../outputs/out/bin/nix
|
||||
```
|
||||
|
||||
On macOS, use `lldb`:
|
||||
|
||||
```console
|
||||
[nix-shell]$ lldb -- ../outputs/out/bin/nix
|
||||
```
|
||||
|
||||
### Using the Debugger
|
||||
|
||||
Inside the debugger, you can set breakpoints, run the program, and inspect variables.
|
||||
|
||||
```gdb
|
||||
(gdb) break main
|
||||
(gdb) run <arguments>
|
||||
```
|
||||
|
||||
Refer to the [GDB Documentation](https://www.gnu.org/software/gdb/documentation/) for comprehensive usage instructions.
|
||||
|
||||
On macOS, use `lldb`:
|
||||
|
||||
```lldb
|
||||
(lldb) breakpoint set --name main
|
||||
(lldb) process launch -- <arguments>
|
||||
```
|
||||
|
||||
Refer to the [LLDB Tutorial](https://lldb.llvm.org/use/tutorial.html) for comprehensive usage instructions.
|
|
@ -13,16 +13,17 @@ Incremental refactorings of the documentation build setup to make it faster or e
|
|||
Build the manual from scratch:
|
||||
|
||||
```console
|
||||
nix-build $(nix-instantiate)'!doc'
|
||||
nix-build -E '(import ./.).packages.${builtins.currentSystem}.nix.doc'
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```console
|
||||
nix build .#^doc
|
||||
nix build .#nix-manual
|
||||
```
|
||||
|
||||
and open `./result-doc/share/doc/nix/manual/index.html`.
|
||||
and open `./result/share/doc/nix/manual/index.html`.
|
||||
|
||||
|
||||
To build the manual incrementally, [enter the development shell](./building.md) and run:
|
||||
|
||||
|
@ -35,7 +36,7 @@ In order to reflect changes to the [Makefile for the manual], clear all generate
|
|||
[Makefile for the manual]: https://github.com/NixOS/nix/blob/master/doc/manual/local.mk
|
||||
|
||||
```console
|
||||
rm $(git ls-files doc/manual/ -o | grep -F '.md') && rmdir doc/manual/src/command-ref/new-cli && make manual-html -j $NIX_BUILD_CORES
|
||||
rm $(git ls-files doc/manual/ -o | grep -F '.md') && rmdir doc/manual/source/command-ref/new-cli && make manual-html -j $NIX_BUILD_CORES
|
||||
```
|
||||
|
||||
## Style guide
|
||||
|
@ -182,7 +183,7 @@ Please observe these guidelines to ease reviews:
|
|||
|
||||
`@docroot@` provides a base path for links that occur in reusable snippets or other documentation that doesn't have a base path of its own.
|
||||
|
||||
If a broken link occurs in a snippet that was inserted into multiple generated files in different directories, use `@docroot@` to reference the `doc/manual/src` directory.
|
||||
If a broken link occurs in a snippet that was inserted into multiple generated files in different directories, use `@docroot@` to reference the `doc/manual/source` directory.
|
||||
|
||||
If the `@docroot@` literal appears in an error message from the [`mdbook-linkcheck`] tool, the `@docroot@` replacement needs to be applied to the generated source file that mentions it.
|
||||
See existing `@docroot@` logic in the [Makefile for the manual].
|
||||
|
@ -203,7 +204,7 @@ $ xdg-open ./result/share/doc/nix/internal-api/html/index.html
|
|||
or inside `nix-shell` or `nix develop`:
|
||||
|
||||
```console
|
||||
$ mesonConfigurePhase
|
||||
$ configurePhase
|
||||
$ ninja src/internal-api-docs/html
|
||||
$ xdg-open src/internal-api-docs/html/index.html
|
||||
```
|
||||
|
@ -224,7 +225,7 @@ $ xdg-open ./result/share/doc/nix/external-api/html/index.html
|
|||
or inside `nix-shell` or `nix develop`:
|
||||
|
||||
```
|
||||
$ mesonConfigurePhase
|
||||
$ configurePhase
|
||||
$ ninja src/external-api-docs/html
|
||||
$ xdg-open src/external-api-docs/html/index.html
|
||||
```
|
|
@ -90,7 +90,7 @@ This representation is extensible and preserves the ordering:
|
|||
|
||||
## Self-describing values
|
||||
|
||||
As described in the previous section, it's crucial that schemas can be extended with with new fields without breaking compatibility.
|
||||
As described in the previous section, it's crucial that schemas can be extended with new fields without breaking compatibility.
|
||||
However, that should *not* mean we use the presence/absence of fields to indicate optional information *within* a version of the schema.
|
||||
Instead, always include the field, and use `null` to indicate the "nothing" case.
|
||||
|
12
doc/manual/source/development/meson.build
Normal file
12
doc/manual/source/development/meson.build
Normal file
|
@ -0,0 +1,12 @@
|
|||
experimental_feature_descriptions_md = custom_target(
|
||||
command : nix_eval_for_docs + [
|
||||
'--expr',
|
||||
'import @INPUT0@ (builtins.fromJSON (builtins.readFile @INPUT1@))',
|
||||
],
|
||||
input : [
|
||||
'../../generate-xp-features.nix',
|
||||
xp_features_json,
|
||||
],
|
||||
capture : true,
|
||||
output : 'experimental-feature-descriptions.md',
|
||||
)
|
|
@ -29,7 +29,7 @@ The unit tests are defined using the [googletest] and [rapidcheck] frameworks.
|
|||
> ```
|
||||
> src
|
||||
> ├── libexpr
|
||||
> │ ├── local.mk
|
||||
> │ ├── meson.build
|
||||
> │ ├── value/context.hh
|
||||
> │ ├── value/context.cc
|
||||
> │ …
|
||||
|
@ -37,33 +37,32 @@ The unit tests are defined using the [googletest] and [rapidcheck] frameworks.
|
|||
> ├── tests
|
||||
> │ │
|
||||
> │ …
|
||||
> │ └── unit
|
||||
> │ ├── libutil
|
||||
> │ │ ├── local.mk
|
||||
> │ │ …
|
||||
> │ │ └── data
|
||||
> │ │ ├── git/tree.txt
|
||||
> │ │ …
|
||||
> │ │
|
||||
> │ ├── libexpr-support
|
||||
> │ │ ├── local.mk
|
||||
> │ │ └── tests
|
||||
> │ │ ├── value/context.hh
|
||||
> │ │ ├── value/context.cc
|
||||
> │ │ …
|
||||
> │ │
|
||||
> │ ├── libexpr
|
||||
> │ … ├── local.mk
|
||||
> │ ├── value/context.cc
|
||||
> │ …
|
||||
> │ ├── libutil-tests
|
||||
> │ │ ├── meson.build
|
||||
> │ │ …
|
||||
> │ │ └── data
|
||||
> │ │ ├── git/tree.txt
|
||||
> │ │ …
|
||||
> │ │
|
||||
> │ ├── libexpr-test-support
|
||||
> │ │ ├── meson.build
|
||||
> │ │ └── tests
|
||||
> │ │ ├── value/context.hh
|
||||
> │ │ ├── value/context.cc
|
||||
> │ │ …
|
||||
> │ │
|
||||
> │ ├── libexpr-tests
|
||||
> │ … ├── meson.build
|
||||
> │ ├── value/context.cc
|
||||
> │ …
|
||||
> …
|
||||
> ```
|
||||
|
||||
The tests for each Nix library (`libnixexpr`, `libnixstore`, etc..) live inside a directory `src/${library_name_without-nix}-test`.
|
||||
Given an interface (header) and implementation pair in the original library, say, `src/libexpr/value/context.{hh,cc}`, we write tests for it in `src/nix-expr-tests/value/context.cc`, and (possibly) declare/define additional interfaces for testing purposes in `src/nix-expr-test-support/tests/value/context.{hh,cc}`.
|
||||
Given an interface (header) and implementation pair in the original library, say, `src/libexpr/value/context.{hh,cc}`, we write tests for it in `src/libexpr-tests/value/context.cc`, and (possibly) declare/define additional interfaces for testing purposes in `src/libexpr-test-support/tests/value/context.{hh,cc}`.
|
||||
|
||||
Data for unit tests is stored in a `data` subdir of the directory for each unit test executable.
|
||||
For example, `libnixstore` code is in `src/libstore`, and its test data is in `src/nix-store-tests/data`.
|
||||
For example, `libnixstore` code is in `src/libstore`, and its test data is in `src/libstore-tests/data`.
|
||||
The path to the `src/${library_name_without-nix}-test/data` directory is passed to the unit test executable with the environment variable `_NIX_TEST_UNIT_DATA`.
|
||||
Note that each executable only gets the data for its tests.
|
||||
|
||||
|
@ -128,67 +127,63 @@ On other platforms they wouldn't be run at all.
|
|||
|
||||
## Functional tests
|
||||
|
||||
The functional tests reside under the `tests/functional` directory and are listed in `tests/functional/local.mk`.
|
||||
The functional tests reside under the `tests/functional` directory and are listed in `tests/functional/meson.build`.
|
||||
Each test is a bash script.
|
||||
|
||||
Functional tests are run during `installCheck` in the `nix` package build, as well as separately from the build, in VM tests.
|
||||
|
||||
### Running the whole test suite
|
||||
|
||||
The whole test suite can be run with:
|
||||
The whole test suite (functional and unit tests) can be run with:
|
||||
|
||||
```shell-session
|
||||
$ make install && make installcheck
|
||||
ran test tests/functional/foo.sh... [PASS]
|
||||
ran test tests/functional/bar.sh... [PASS]
|
||||
...
|
||||
$ checkPhase
|
||||
```
|
||||
|
||||
### Grouping tests
|
||||
|
||||
Sometimes it is useful to group related tests so they can be easily run together without running the entire test suite.
|
||||
Each test group is in a subdirectory of `tests`.
|
||||
For example, `tests/functional/ca/local.mk` defines a `ca` test group for content-addressed derivation outputs.
|
||||
For example, `tests/functional/ca/meson.build` defines a `ca` test group for content-addressed derivation outputs.
|
||||
|
||||
That test group can be run like this:
|
||||
|
||||
```shell-session
|
||||
$ make ca.test-group -j50
|
||||
ran test tests/functional/ca/nix-run.sh... [PASS]
|
||||
ran test tests/functional/ca/import-derivation.sh... [PASS]
|
||||
...
|
||||
```
|
||||
|
||||
The test group is defined in Make like this:
|
||||
```makefile
|
||||
$(test-group-name)-tests := \
|
||||
$(d)/test0.sh \
|
||||
$(d)/test1.sh \
|
||||
...
|
||||
|
||||
install-tests-groups += $(test-group-name)
|
||||
$ meson test --suite ca
|
||||
ninja: Entering directory `/home/jcericson/src/nix/master/build'
|
||||
ninja: no work to do.
|
||||
[1-20/20] 🌑 nix-functional-tests:ca / ca/why-depends 1/20 nix-functional-tests:ca / ca/nix-run OK 0.16s
|
||||
[2-20/20] 🌒 nix-functional-tests:ca / ca/why-depends 2/20 nix-functional-tests:ca / ca/import-derivation OK 0.17s
|
||||
```
|
||||
|
||||
### Running individual tests
|
||||
|
||||
Individual tests can be run with `make`:
|
||||
Individual tests can be run with `meson`:
|
||||
|
||||
```shell-session
|
||||
$ make tests/functional/${testName}.sh.test
|
||||
ran test tests/functional/${testName}.sh... [PASS]
|
||||
$ meson test --verbose ${testName}
|
||||
ninja: Entering directory `/home/jcericson/src/nix/master/build'
|
||||
ninja: no work to do.
|
||||
1/1 nix-functional-tests:main / ${testName} OK 0.41s
|
||||
|
||||
Ok: 1
|
||||
Expected Fail: 0
|
||||
Fail: 0
|
||||
Unexpected Pass: 0
|
||||
Skipped: 0
|
||||
Timeout: 0
|
||||
|
||||
Full log written to /home/jcericson/src/nix/master/build/meson-logs/testlog.txt
|
||||
```
|
||||
|
||||
or without `make`:
|
||||
The `--verbose` flag will make Meson also show the console output of each test for easier debugging.
|
||||
The test script will then be traced with `set -x` and the output displayed as it happens,
|
||||
regardless of whether the test succeeds or fails.
|
||||
|
||||
Tests can be also run directly without `meson`:
|
||||
|
||||
```shell-session
|
||||
$ ./mk/run-test.sh tests/functional/${testName}.sh
|
||||
ran test tests/functional/${testName}.sh... [PASS]
|
||||
```
|
||||
|
||||
To see the complete output, one can also run:
|
||||
|
||||
```shell-session
|
||||
$ ./mk/debug-test.sh tests/functional/${testName}.sh
|
||||
$ TEST_NAME=${testName} NIX_REMOTE='' PS4='+(${BASH_SOURCE[0]-$0}:$LINENO) tests/functional/${testName}.sh
|
||||
+(${testName}.sh:1) foo
|
||||
output from foo
|
||||
+(${testName}.sh:2) bar
|
||||
|
@ -196,8 +191,6 @@ output from bar
|
|||
...
|
||||
```
|
||||
|
||||
The test script will then be traced with `set -x` and the output displayed as it happens, regardless of whether the test succeeds or fails.
|
||||
|
||||
### Debugging failing functional tests
|
||||
|
||||
When a functional test fails, it usually does so somewhere in the middle of the script.
|
||||
|
@ -254,7 +247,7 @@ It is frequently useful to regenerate the expected output.
|
|||
To do that, rerun the failed test(s) with `_NIX_TEST_ACCEPT=1`.
|
||||
For example:
|
||||
```bash
|
||||
_NIX_TEST_ACCEPT=1 make tests/functional/lang.sh.test
|
||||
_NIX_TEST_ACCEPT=1 meson test lang
|
||||
```
|
||||
This convention is shared with the [characterisation unit tests](#characterisation-testing-unit) too.
|
||||
|
||||
|
@ -276,14 +269,12 @@ To ensure that characterisation testing doesn't make it harder to intentionally
|
|||
We run the functional tests not just in the build, but also in VM tests.
|
||||
This helps us ensure that Nix works correctly on NixOS, and environments that have similar characteristics that are hard to reproduce in a build environment.
|
||||
|
||||
The recommended way to run these tests during development is:
|
||||
These can be run with:
|
||||
|
||||
```shell
|
||||
nix build .#hydraJobs.tests.functional_user.quickBuild
|
||||
nix build .#hydraJobs.tests.functional_user
|
||||
```
|
||||
|
||||
The `quickBuild` attribute configures the test to use a `nix` package that's built without integration tests, so that you can iterate on the tests without performing recompilations due to the changed sources for `installCheck`.
|
||||
|
||||
Generally, this build is sufficient, but in nightly or CI we also test the attributes `functional_root` and `functional_trusted`, in which the test suite is run with different levels of authorization.
|
||||
|
||||
## Integration tests
|
||||
|
@ -294,8 +285,6 @@ Because these tests are expensive and require more than what the standard github
|
|||
|
||||
You can run them manually with `nix build .#hydraJobs.tests.{testName}` or `nix-build -A hydraJobs.tests.{testName}`.
|
||||
|
||||
If you are testing a build of `nix` that you haven't compiled yet, you may iterate faster by appending the `quickBuild` attribute: `nix build .#hydraJobs.tests.{testName}.quickBuild`.
|
||||
|
||||
## Installer tests
|
||||
|
||||
After a one-time setup, the Nix repository's GitHub Actions continuous integration (CI) workflow can test the installer each time you push to a branch.
|
||||
|
@ -308,7 +297,7 @@ Creating a Cachix cache for your installer tests and adding its authorisation to
|
|||
- `armv7l-linux`
|
||||
- `x86_64-darwin`
|
||||
|
||||
- The `installer_test` job (which runs on `ubuntu-latest` and `macos-latest`) will try to install Nix with the cached installer and run a trivial Nix command.
|
||||
- The `installer_test` job (which runs on `ubuntu-24.04` and `macos-14`) will try to install Nix with the cached installer and run a trivial Nix command.
|
||||
|
||||
### One-time setup
|
||||
|
Before Width: | Height: | Size: 1.2 KiB After Width: | Height: | Size: 1.2 KiB |
Before Width: | Height: | Size: 2.5 KiB After Width: | Height: | Size: 2.5 KiB |
Before Width: | Height: | Size: 83 KiB After Width: | Height: | Size: 83 KiB |
Some files were not shown because too many files have changed in this diff Show more
Loading…
Add table
Add a link
Reference in a new issue