From cab1fb0b05383bede96f0e94bed773a589dac231 Mon Sep 17 00:00:00 2001 From: Qyriad Date: Mon, 20 May 2024 20:54:00 -0600 Subject: [PATCH 1/3] build: make internal-api-docs PHONEY Since we're skipping Meson's dependency tracking, for the internal-api-docs custom target, we should just consider it a phoney target and build it on every request. Change-Id: I3b0bcea30ee9a4830023ccc5bededf995e96cccc --- doc/internal-api/meson.build | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/internal-api/meson.build b/doc/internal-api/meson.build index 35d8a0e5b..faa30f194 100644 --- a/doc/internal-api/meson.build +++ b/doc/internal-api/meson.build @@ -28,6 +28,7 @@ internal_api_docs = custom_target( output : 'html', install : true, install_dir : datadir / 'doc/nix/internal-api', + build_always_stale : true, ) alias_target('internal-api-html', internal_api_docs) From 5c6d4f903c83324c4dd05b3b5268cbec332fd201 Mon Sep 17 00:00:00 2001 From: Qyriad Date: Mon, 20 May 2024 21:58:27 -0600 Subject: [PATCH 2/3] docs: linkify nix3-build mention in nix-build.md Change-Id: I462a8cf0da42b5045ce84b48dc1841ecdccbb89e --- doc/manual/src/command-ref/nix-build.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/manual/src/command-ref/nix-build.md b/doc/manual/src/command-ref/nix-build.md index b548edf82..92e642ddd 100644 --- a/doc/manual/src/command-ref/nix-build.md +++ b/doc/manual/src/command-ref/nix-build.md @@ -14,9 +14,8 @@ # Disambiguation -This man page describes the command `nix-build`, which is distinct from `nix -build`. For documentation on the latter, run `nix build --help` or see `man -nix3-build`. +This man page describes the command [`nix-build`](./new-cli/nix3-build.md), which is distinct from `nix build`. +For documentation on the latter, run `nix build --help` or see `man nix3-build`. # Description From 1796c9fb20b808c89a8f167157a9bbf64cef0960 Mon Sep 17 00:00:00 2001 From: Qyriad Date: Mon, 20 May 2024 22:21:14 -0600 Subject: [PATCH 3/3] docs: document lookupFileArg syntax in nix-build Change-Id: Ib6d68594a16132805ba5d97526e16f7b3633117e --- doc/manual/src/command-ref/nix-build.md | 38 ++++++++++++++++++++++--- 1 file changed, 34 insertions(+), 4 deletions(-) diff --git a/doc/manual/src/command-ref/nix-build.md b/doc/manual/src/command-ref/nix-build.md index 92e642ddd..5baa86e47 100644 --- a/doc/manual/src/command-ref/nix-build.md +++ b/doc/manual/src/command-ref/nix-build.md @@ -29,10 +29,40 @@ created (`result`, `result-2`, and so on). If no *paths* are specified, then `nix-build` will use `default.nix` in the current directory, if it exists. -If an element of *paths* starts with `http://` or `https://`, it is -interpreted as the URL of a tarball that will be downloaded and unpacked -to a temporary location. The tarball must include a single top-level -directory containing at least a file named `default.nix`. +## Path Syntax + +A given element of *paths* may take one of a few different forms, the first being a simple filesystem path, e.g. `nix-build /tmp/some-file.nix`. +It may also be a [search path](./env-common.html#env-NIX_PATH) like ``, which is convenient to use with `--attr`/`-A`: + +```console +$ nix-build '' -A firefox +``` + +(Note the quotation marks around ``, which will be necessary in most Unix shells.) + +If an element of *paths* starts with `http://` or `https://`, it is interpreted as the URL of a tarball which will be fetched and unpacked. +Lix will then `import` the unpacked directory, so these tarballs must include at least single top-level directory with a file called `default.nix` +For example, you could build from a specific version of Nixpkgs with something like: + +```console +$ nix-build "https://github.com/NixOS/nixpkgs/archive/refs/heads/release-23.11.tar.gz" -A firefox +``` + +If a path starts with `flake:`, the rest of the argument is interpreted as a [flakeref](./new-cli/nix3-flake.html#flake-references) (see `nix flake --help` or `man nix3-flake`), which requires the "flakes" experimental feature to be enabled. +Lix will fetch the flake, and then `import` its unpacked directory, so the flake must include a file called `default.nix`. +For example, the flake analogue to the above `nix-build` commands are: + +```console +$ nix-build flake:nixpkgs -A firefox +$ nix-build flake:github:NixOS/nixpkgs/release-23.11 -A firefox +``` + +Finally, for legacy reasons, if a path starts with `channel:`, the rest of the argument is interpreted as the name of a channel to fetch from `https://nixos.org/channels/$CHANNEL_NAME/nixexprs.tar.xz`. + +> **NOTE:**: any of the special syntaxes may always be disambiguated by prefixing the path. +> For example: a file in the current directory called `'` can be addressed as `./`, to escape the special interpretation. + +## Notes `nix-build` is essentially a wrapper around [`nix-instantiate`](nix-instantiate.md) (to translate a high-level Nix