From 830f5b33ddfbfa8d8864a6724fcac87f893ec88a Mon Sep 17 00:00:00 2001 From: pennae Date: Sat, 10 Jun 2023 17:47:58 +0200 Subject: [PATCH 1/5] doc: add missing section IDs --- doc/builders/special/darwin-builder.section.md | 4 ++-- doc/builders/special/vm-tools.section.md | 18 +++++++++--------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/doc/builders/special/darwin-builder.section.md b/doc/builders/special/darwin-builder.section.md index 30bf2d095102..b5b6ab8971e9 100644 --- a/doc/builders/special/darwin-builder.section.md +++ b/doc/builders/special/darwin-builder.section.md @@ -62,7 +62,7 @@ builders-use-substitutes = true $ sudo launchctl kickstart -k system/org.nixos.nix-daemon ``` -## Example flake usage +## Example flake usage {#sec-darwin-builder-example-flake} ``` { @@ -120,7 +120,7 @@ $ sudo launchctl kickstart -k system/org.nixos.nix-daemon } ``` -## Reconfiguring the builder +## Reconfiguring the builder {#sec-darwin-builder-reconfiguring} Initially you should not change the builder configuration else you will not be able to use the binary cache. However, after you have the builder running locally diff --git a/doc/builders/special/vm-tools.section.md b/doc/builders/special/vm-tools.section.md index 3b6fb0d2556b..8feab04902d8 100644 --- a/doc/builders/special/vm-tools.section.md +++ b/doc/builders/special/vm-tools.section.md @@ -6,7 +6,7 @@ A set of VM related utilities, that help in building some packages in more advan A bash script fragment that produces a disk image at `destination`. -### Attributes +### Attributes {#vm-tools-createEmptyImage-attributes} * `size`. The disk size, in MiB. * `fullName`. Name that will be written to `${destination}/nix-support/full-name`. @@ -20,14 +20,14 @@ Thus, any pure Nix derivation should run unmodified. If the build fails and Nix is run with the `-K/--keep-failed` option, a script `run-vm` will be left behind in the temporary build directory that allows you to boot into the VM and debug it interactively. -### Attributes +### Attributes {#vm-tools-runInLinuxVM-attributes} * `preVM` (optional). Shell command to be evaluated *before* the VM is started (i.e., on the host). * `memSize` (optional, default `512`). The memory size of the VM in MiB. * `diskImage` (optional). A file system image to be attached to `/dev/sda`. Note that currently we expect the image to contain a filesystem, not a full disk image with a partition table etc. -### Examples +### Examples {#vm-tools-runInLinuxVM-examples} Build the derivation hello inside a VM: ```nix @@ -56,13 +56,13 @@ runInLinuxVM (hello.overrideAttrs (_: { Takes a file, such as an ISO, and extracts its contents into the store. -### Attributes +### Attributes {#vm-tools-extractFs-attributes} * `file`. Path to the file to be extracted. Note that currently we expect the image to contain a filesystem, not a full disk image with a partition table etc. * `fs` (optional). Filesystem of the contents of the file. -### Examples +### Examples {#vm-tools-extractFs-examples} Extract the contents of an ISO file: ```nix @@ -82,7 +82,7 @@ Like [](#vm-tools-runInLinuxVM), but instead of using `stdenv` from the Nix stor Generate a script that can be used to run an interactive session in the given image. -### Examples +### Examples {#vm-tools-makeImageTestScript-examples} Create a script for running a Fedora 27 VM: ```nix @@ -100,7 +100,7 @@ makeImageTestScript diskImages.ubuntu2004x86_64 A set of functions that build a predefined set of minimal Linux distributions images. -### Images +### Images {#vm-tools-diskImageFuns-images} * Fedora * `fedora26x86_64` @@ -126,12 +126,12 @@ A set of functions that build a predefined set of minimal Linux distributions im * `debian11i386` * `debian11x86_64` -### Attributes +### Attributes {#vm-tools-diskImageFuns-attributes} * `size` (optional, defaults to `4096`). The size of the image, in MiB. * `extraPackages` (optional). A list names of additional packages from the distribution that should be included in the image. -### Examples +### Examples {#vm-tools-diskImageFuns-examples} 8GiB image containing Firefox in addition to the default packages: ```nix From e42a5c78e75aba56b546cbcb8efdf46587fea276 Mon Sep 17 00:00:00 2001 From: pennae Date: Sat, 10 Jun 2023 17:54:02 +0200 Subject: [PATCH 2/5] doc: make sure section depths are consecutive skipping heading levels (eg from # to ###, or starting at ###) is legal in pandoc, but not in nixos-render-docs. pandoc acts as though section levels *were* consecutive, nixos-render-docs prefers to tell people not to do that kind of thing because it can make documents more fragile. --- doc/builders/special/makesetuphook.section.md | 2 +- doc/hooks/autoconf.section.md | 3 +-- doc/hooks/automake.section.md | 3 +-- doc/hooks/autopatchelf.section.md | 3 +-- doc/hooks/breakpoint.section.md | 3 +-- doc/hooks/cmake.section.md | 3 +-- doc/hooks/gdk-pixbuf.section.md | 3 +-- doc/hooks/ghc.section.md | 3 +-- doc/hooks/gnome.section.md | 3 +-- doc/hooks/installShellFiles.section.md | 3 +-- doc/hooks/libiconv.section.md | 3 +-- doc/hooks/libxml2.section.md | 3 +-- doc/hooks/meson.section.md | 15 +++++++-------- doc/hooks/ninja.section.md | 3 +-- doc/hooks/perl.section.md | 3 +-- doc/hooks/pkg-config.section.md | 3 +-- doc/hooks/python.section.md | 3 +-- doc/hooks/qt-4.section.md | 3 +-- doc/hooks/scons.section.md | 3 +-- doc/hooks/tetex-tex-live.section.md | 3 +-- doc/hooks/unzip.section.md | 3 +-- doc/hooks/validatePkgConfig.section.md | 3 +-- doc/hooks/waf.section.md | 3 +-- doc/hooks/xcbuild.section.md | 3 +-- doc/languages-frameworks/gnome.section.md | 10 +++++----- 25 files changed, 35 insertions(+), 58 deletions(-) diff --git a/doc/builders/special/makesetuphook.section.md b/doc/builders/special/makesetuphook.section.md index fee508dc29c2..eb042412137b 100644 --- a/doc/builders/special/makesetuphook.section.md +++ b/doc/builders/special/makesetuphook.section.md @@ -12,7 +12,7 @@ pkgs.makeSetupHook { } ./script.sh ``` -#### setup hook that depends on the hello package and runs hello and @shell@ is substituted with path to bash {#sec-pkgs.makeSetupHook-usage-example} +### setup hook that depends on the hello package and runs hello and @shell@ is substituted with path to bash {#sec-pkgs.makeSetupHook-usage-example} ```nix pkgs.makeSetupHook { diff --git a/doc/hooks/autoconf.section.md b/doc/hooks/autoconf.section.md index 13d75910f192..90e4681ef93f 100644 --- a/doc/hooks/autoconf.section.md +++ b/doc/hooks/autoconf.section.md @@ -1,4 +1,3 @@ - -### Autoconf {#setup-hook-autoconf} +# Autoconf {#setup-hook-autoconf} The `autoreconfHook` derivation adds `autoreconfPhase`, which runs autoreconf, libtoolize and automake, essentially preparing the configure script in autotools-based builds. Most autotools-based packages come with the configure script pre-generated, but this hook is necessary for a few packages and when you need to patch the package’s configure scripts. diff --git a/doc/hooks/automake.section.md b/doc/hooks/automake.section.md index 562ac18fcd93..dd0ff9c0cc09 100644 --- a/doc/hooks/automake.section.md +++ b/doc/hooks/automake.section.md @@ -1,4 +1,3 @@ - -### Automake {#setup-hook-automake} +# Automake {#setup-hook-automake} Adds the `share/aclocal` subdirectory of each build input to the `ACLOCAL_PATH` environment variable. diff --git a/doc/hooks/autopatchelf.section.md b/doc/hooks/autopatchelf.section.md index 9c2852ccf279..008a90d46140 100644 --- a/doc/hooks/autopatchelf.section.md +++ b/doc/hooks/autopatchelf.section.md @@ -1,5 +1,4 @@ - -### autoPatchelfHook {#setup-hook-autopatchelfhook} +# autoPatchelfHook {#setup-hook-autopatchelfhook} This is a special setup hook which helps in packaging proprietary software in that it automatically tries to find missing shared library dependencies of ELF files based on the given `buildInputs` and `nativeBuildInputs`. diff --git a/doc/hooks/breakpoint.section.md b/doc/hooks/breakpoint.section.md index 9600e06b7934..424a9424b55e 100644 --- a/doc/hooks/breakpoint.section.md +++ b/doc/hooks/breakpoint.section.md @@ -1,5 +1,4 @@ - -### breakpointHook {#breakpointhook} +# breakpointHook {#breakpointhook} This hook will make a build pause instead of stopping when a failure happens. It prevents nix from cleaning up the build environment immediately and allows the user to attach to a build environment using the `cntr` command. Upon build error it will print instructions on how to use `cntr`, which can be used to enter the environment for debugging. Installing cntr and running the command will provide shell access to the build sandbox of failed build. At `/var/lib/cntr` the sandboxed filesystem is mounted. All commands and files of the system are still accessible within the shell. To execute commands from the sandbox use the cntr exec subcommand. `cntr` is only supported on Linux-based platforms. To use it first add `cntr` to your `environment.systemPackages` on NixOS or alternatively to the root user on non-NixOS systems. Then in the package that is supposed to be inspected, add `breakpointHook` to `nativeBuildInputs`. diff --git a/doc/hooks/cmake.section.md b/doc/hooks/cmake.section.md index 58fbfa45a2e0..b5dc5a914434 100644 --- a/doc/hooks/cmake.section.md +++ b/doc/hooks/cmake.section.md @@ -1,4 +1,3 @@ - -### cmake {#cmake} +# cmake {#cmake} Overrides the default configure phase to run the CMake command. By default, we use the Make generator of CMake. In addition, dependencies are added automatically to `CMAKE_PREFIX_PATH` so that packages are correctly detected by CMake. Some additional flags are passed in to give similar behavior to configure-based packages. You can disable this hook’s behavior by setting `configurePhase` to a custom value, or by setting `dontUseCmakeConfigure`. `cmakeFlags` controls flags passed only to CMake. By default, parallel building is enabled as CMake supports parallel building almost everywhere. When Ninja is also in use, CMake will detect that and use the ninja generator. diff --git a/doc/hooks/gdk-pixbuf.section.md b/doc/hooks/gdk-pixbuf.section.md index 565216560abc..cf7203dfc66f 100644 --- a/doc/hooks/gdk-pixbuf.section.md +++ b/doc/hooks/gdk-pixbuf.section.md @@ -1,4 +1,3 @@ - -### gdk-pixbuf {#setup-hook-gdk-pixbuf} +# gdk-pixbuf {#setup-hook-gdk-pixbuf} Exports `GDK_PIXBUF_MODULE_FILE` environment variable to the builder. Add librsvg package to `buildInputs` to get svg support. See also the [setup hook description in GNOME platform docs](#ssec-gnome-hooks-gdk-pixbuf). diff --git a/doc/hooks/ghc.section.md b/doc/hooks/ghc.section.md index a4b0841ea486..ac054b954a92 100644 --- a/doc/hooks/ghc.section.md +++ b/doc/hooks/ghc.section.md @@ -1,4 +1,3 @@ - -### GHC {#ghc} +# GHC {#ghc} Creates a temporary package database and registers every Haskell build input in it (TODO: how?). diff --git a/doc/hooks/gnome.section.md b/doc/hooks/gnome.section.md index 8c209d9b472c..b10e80802027 100644 --- a/doc/hooks/gnome.section.md +++ b/doc/hooks/gnome.section.md @@ -1,4 +1,3 @@ - -### GNOME platform {#gnome-platform} +# GNOME platform {#gnome-platform} Hooks related to GNOME platform and related libraries like GLib, GTK and GStreamer are described in [](#sec-language-gnome). diff --git a/doc/hooks/installShellFiles.section.md b/doc/hooks/installShellFiles.section.md index d27527503fed..84adea2fa30c 100644 --- a/doc/hooks/installShellFiles.section.md +++ b/doc/hooks/installShellFiles.section.md @@ -1,5 +1,4 @@ - -### `installShellFiles` {#installshellfiles} +# `installShellFiles` {#installshellfiles} This hook helps with installing manpages and shell completion files. It exposes 2 shell functions `installManPage` and `installShellCompletion` that can be used from your `postInstall` hook. diff --git a/doc/hooks/libiconv.section.md b/doc/hooks/libiconv.section.md index c228fe339e14..0ffa6d09b0a8 100644 --- a/doc/hooks/libiconv.section.md +++ b/doc/hooks/libiconv.section.md @@ -1,4 +1,3 @@ - -### libiconv, libintl {#libiconv-libintl} +# libiconv, libintl {#libiconv-libintl} A few libraries automatically add to `NIX_LDFLAGS` their library, making their symbols automatically available to the linker. This includes libiconv and libintl (gettext). This is done to provide compatibility between GNU Linux, where libiconv and libintl are bundled in, and other systems where that might not be the case. Sometimes, this behavior is not desired. To disable this behavior, set `dontAddExtraLibs`. diff --git a/doc/hooks/libxml2.section.md b/doc/hooks/libxml2.section.md index 770ef9ff3ffe..df387fb5e222 100644 --- a/doc/hooks/libxml2.section.md +++ b/doc/hooks/libxml2.section.md @@ -1,4 +1,3 @@ - -### libxml2 {#setup-hook-libxml2} +# libxml2 {#setup-hook-libxml2} Adds every file named `catalog.xml` found under the `xml/dtd` and `xml/xsl` subdirectories of each build input to the `XML_CATALOG_FILES` environment variable. diff --git a/doc/hooks/meson.section.md b/doc/hooks/meson.section.md index 32804b5e32f2..fd7779e6468f 100644 --- a/doc/hooks/meson.section.md +++ b/doc/hooks/meson.section.md @@ -1,26 +1,25 @@ - -### Meson {#meson} +# Meson {#meson} Overrides the configure phase to run meson to generate Ninja files. To run these files, you should accompany Meson with ninja. By default, `enableParallelBuilding` is enabled as Meson supports parallel building almost everywhere. -#### Variables controlling Meson {#variables-controlling-meson} +## Variables controlling Meson {#variables-controlling-meson} -##### `mesonFlags` {#mesonflags} +### `mesonFlags` {#mesonflags} Controls the flags passed to meson. -##### `mesonBuildType` {#mesonbuildtype} +### `mesonBuildType` {#mesonbuildtype} Which [`--buildtype`](https://mesonbuild.com/Builtin-options.html#core-options) to pass to Meson. We default to `plain`. -##### `mesonAutoFeatures` {#mesonautofeatures} +### `mesonAutoFeatures` {#mesonautofeatures} What value to set [`-Dauto_features=`](https://mesonbuild.com/Builtin-options.html#core-options) to. We default to `enabled`. -##### `mesonWrapMode` {#mesonwrapmode} +### `mesonWrapMode` {#mesonwrapmode} What value to set [`-Dwrap_mode=`](https://mesonbuild.com/Builtin-options.html#core-options) to. We default to `nodownload` as we disallow network access. -##### `dontUseMesonConfigure` {#dontusemesonconfigure} +### `dontUseMesonConfigure` {#dontusemesonconfigure} Disables using Meson’s `configurePhase`. diff --git a/doc/hooks/ninja.section.md b/doc/hooks/ninja.section.md index 5ea1ee87070a..4b0e33feb5c3 100644 --- a/doc/hooks/ninja.section.md +++ b/doc/hooks/ninja.section.md @@ -1,4 +1,3 @@ - -### ninja {#ninja} +# ninja {#ninja} Overrides the build, install, and check phase to run ninja instead of make. You can disable this behavior with the `dontUseNinjaBuild`, `dontUseNinjaInstall`, and `dontUseNinjaCheck`, respectively. Parallel building is enabled by default in Ninja. diff --git a/doc/hooks/perl.section.md b/doc/hooks/perl.section.md index 403227a9bf18..06942bd3c0e1 100644 --- a/doc/hooks/perl.section.md +++ b/doc/hooks/perl.section.md @@ -1,4 +1,3 @@ - -### Perl {#setup-hook-perl} +# Perl {#setup-hook-perl} Adds the `lib/site_perl` subdirectory of each build input to the `PERL5LIB` environment variable. For instance, if `buildInputs` contains Perl, then the `lib/site_perl` subdirectory of each input is added to the `PERL5LIB` environment variable. diff --git a/doc/hooks/pkg-config.section.md b/doc/hooks/pkg-config.section.md index 969c81f6d18a..c98701cf9c9d 100644 --- a/doc/hooks/pkg-config.section.md +++ b/doc/hooks/pkg-config.section.md @@ -1,4 +1,3 @@ - -### pkg-config {#setup-hook-pkg-config} +# pkg-config {#setup-hook-pkg-config} Adds the `lib/pkgconfig` and `share/pkgconfig` subdirectories of each build input to the `PKG_CONFIG_PATH` environment variable. diff --git a/doc/hooks/python.section.md b/doc/hooks/python.section.md index a46a727e95b1..ecaae491e994 100644 --- a/doc/hooks/python.section.md +++ b/doc/hooks/python.section.md @@ -1,4 +1,3 @@ - -### Python {#setup-hook-python} +# Python {#setup-hook-python} Adds the `lib/${python.libPrefix}/site-packages` subdirectory of each build input to the `PYTHONPATH` environment variable. diff --git a/doc/hooks/qt-4.section.md b/doc/hooks/qt-4.section.md index f15d858e2377..4b704df49597 100644 --- a/doc/hooks/qt-4.section.md +++ b/doc/hooks/qt-4.section.md @@ -1,4 +1,3 @@ - -### Qt 4 {#qt-4} +# Qt 4 {#qt-4} Sets the `QTDIR` environment variable to Qt’s path. diff --git a/doc/hooks/scons.section.md b/doc/hooks/scons.section.md index 1392269e5d55..0a7a7aa023b6 100644 --- a/doc/hooks/scons.section.md +++ b/doc/hooks/scons.section.md @@ -1,4 +1,3 @@ - -### scons {#scons} +# scons {#scons} Overrides the build, install, and check phases. This uses the scons build system as a replacement for make. scons does not provide a configure phase, so everything is managed at build and install time. diff --git a/doc/hooks/tetex-tex-live.section.md b/doc/hooks/tetex-tex-live.section.md index 0ecdcc12e45a..b702971d727c 100644 --- a/doc/hooks/tetex-tex-live.section.md +++ b/doc/hooks/tetex-tex-live.section.md @@ -1,4 +1,3 @@ - -### teTeX / TeX Live {#tetex-tex-live} +# teTeX / TeX Live {#tetex-tex-live} Adds the `share/texmf-nix` subdirectory of each build input to the `TEXINPUTS` environment variable. diff --git a/doc/hooks/unzip.section.md b/doc/hooks/unzip.section.md index 91dc072de662..5ec67e576a33 100644 --- a/doc/hooks/unzip.section.md +++ b/doc/hooks/unzip.section.md @@ -1,4 +1,3 @@ - -### unzip {#unzip} +# unzip {#unzip} This setup hook will allow you to unzip .zip files specified in `$src`. There are many similar packages like `unrar`, `undmg`, etc. diff --git a/doc/hooks/validatePkgConfig.section.md b/doc/hooks/validatePkgConfig.section.md index 8719ae930fcb..aa6e0c06c223 100644 --- a/doc/hooks/validatePkgConfig.section.md +++ b/doc/hooks/validatePkgConfig.section.md @@ -1,4 +1,3 @@ - -### validatePkgConfig {#validatepkgconfig} +# validatePkgConfig {#validatepkgconfig} The `validatePkgConfig` hook validates all pkg-config (`.pc`) files in a package. This helps catching some common errors in pkg-config files, such as undefined variables. diff --git a/doc/hooks/waf.section.md b/doc/hooks/waf.section.md index de65abde4502..ee1bccff1d0a 100644 --- a/doc/hooks/waf.section.md +++ b/doc/hooks/waf.section.md @@ -1,4 +1,3 @@ - -### wafHook {#wafhook} +# wafHook {#wafhook} Overrides the configure, build, and install phases. This will run the “waf” script used by many projects. If `wafPath` (default `./waf`) doesn’t exist, it will copy the version of waf available in Nixpkgs. `wafFlags` can be used to pass flags to the waf script. diff --git a/doc/hooks/xcbuild.section.md b/doc/hooks/xcbuild.section.md index 1426431f6dce..bf404b64c3f9 100644 --- a/doc/hooks/xcbuild.section.md +++ b/doc/hooks/xcbuild.section.md @@ -1,4 +1,3 @@ - -### xcbuildHook {#xcbuildhook} +# xcbuildHook {#xcbuildhook} Overrides the build and install phases to run the "xcbuild" command. This hook is needed when a project only comes with build files for the XCode build system. You can disable this behavior by setting buildPhase and configurePhase to a custom value. xcbuildFlags controls flags passed only to xcbuild. diff --git a/doc/languages-frameworks/gnome.section.md b/doc/languages-frameworks/gnome.section.md index 3c8539ac4244..de402cdac0cf 100644 --- a/doc/languages-frameworks/gnome.section.md +++ b/doc/languages-frameworks/gnome.section.md @@ -137,15 +137,15 @@ Most GNOME package offer [`updateScript`](#var-passthru-updateScript), it is the ## Frequently encountered issues {#ssec-gnome-common-issues} -#### `GLib-GIO-ERROR **: 06:04:50.903: No GSettings schemas are installed on the system` {#ssec-gnome-common-issues-no-schemas} +### `GLib-GIO-ERROR **: 06:04:50.903: No GSettings schemas are installed on the system` {#ssec-gnome-common-issues-no-schemas} There are no schemas available in `XDG_DATA_DIRS`. Temporarily add a random package containing schemas like `gsettings-desktop-schemas` to `buildInputs`. [`glib`](#ssec-gnome-hooks-glib) and [`wrapGAppsHook`](#ssec-gnome-hooks-wrapgappshook) setup hooks will take care of making the schemas available to application and you will see the actual missing schemas with the [next error](#ssec-gnome-common-issues-missing-schema). Or you can try looking through the source code for the actual schemas used. -#### `GLib-GIO-ERROR **: 06:04:50.903: Settings schema ‘org.gnome.foo’ is not installed` {#ssec-gnome-common-issues-missing-schema} +### `GLib-GIO-ERROR **: 06:04:50.903: Settings schema ‘org.gnome.foo’ is not installed` {#ssec-gnome-common-issues-missing-schema} Package is missing some GSettings schemas. You can find out the package containing the schema with `nix-locate org.gnome.foo.gschema.xml` and let the hooks handle the wrapping as [above](#ssec-gnome-common-issues-no-schemas). -#### When using `wrapGAppsHook` with special derivers you can end up with double wrapped binaries. {#ssec-gnome-common-issues-double-wrapped} +### When using `wrapGAppsHook` with special derivers you can end up with double wrapped binaries. {#ssec-gnome-common-issues-double-wrapped} This is because derivers like `python.pkgs.buildPythonApplication` or `qt5.mkDerivation` have setup-hooks automatically added that produce wrappers with makeWrapper. The simplest way to workaround that is to disable the `wrapGAppsHook` automatic wrapping with `dontWrapGApps = true;` and pass the arguments it intended to pass to makeWrapper to another. @@ -193,7 +193,7 @@ mkDerivation { } ``` -#### I am packaging a project that cannot be wrapped, like a library or GNOME Shell extension. {#ssec-gnome-common-issues-unwrappable-package} +### I am packaging a project that cannot be wrapped, like a library or GNOME Shell extension. {#ssec-gnome-common-issues-unwrappable-package} You can rely on applications depending on the library setting the necessary environment variables but that is often easy to miss. Instead we recommend to patch the paths in the source code whenever possible. Here are some examples: @@ -209,6 +209,6 @@ You can rely on applications depending on the library setting the necessary envi []{#ssec-gnome-common-issues-unwrappable-package-gsettings-c} [Hard-coding GSettings schema path in C library](https://github.com/NixOS/nixpkgs/blob/29c120c065d03b000224872251bed93932d42412/pkgs/development/libraries/glib-networking/default.nix#L31-L34) – nothing special other than using [Coccinelle patch](https://github.com/NixOS/nixpkgs/pull/67957#issuecomment-527717467) to generate the patch itself. -#### I need to wrap a binary outside `bin` and `libexec` directories. {#ssec-gnome-common-issues-weird-location} +### I need to wrap a binary outside `bin` and `libexec` directories. {#ssec-gnome-common-issues-weird-location} You can manually trigger the wrapping with `wrapGApp` in `preFixup` phase. It takes a path to a program as a first argument; the remaining arguments are passed directly to [`wrapProgram`](#fun-wrapProgram) function. From f9ba30270ef6121e3923338d21fd63291c9baf28 Mon Sep 17 00:00:00 2001 From: pennae Date: Sat, 10 Jun 2023 17:57:37 +0200 Subject: [PATCH 3/5] pkgs/config: add missing mdDoc --- pkgs/top-level/config.nix | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkgs/top-level/config.nix b/pkgs/top-level/config.nix index 1de93a9f3fde..42053ce95de7 100644 --- a/pkgs/top-level/config.nix +++ b/pkgs/top-level/config.nix @@ -135,7 +135,7 @@ let checkMeta = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether to check that the `meta` attribute of derivations are correct during evaluation time. ''; }; From 2ecc93d6fe1be154da6ef9e268b46ec242998511 Mon Sep 17 00:00:00 2001 From: pennae Date: Sat, 10 Jun 2023 18:06:27 +0200 Subject: [PATCH 4/5] doc: normalize markdown for nixos-render-docs pandoc recognizes `::: note` admonitions, nixos-render-docs only recognizes `::: {.note}`. surprisingly pandoc also emits the correct docbook tags for `[](#xref)`s, so we can use that too. --- doc/builders/testers.chapter.md | 2 +- doc/stdenv/meta.chapter.md | 2 +- doc/stdenv/stdenv.chapter.md | 7 ++++--- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/builders/testers.chapter.md b/doc/builders/testers.chapter.md index 928a57673e77..fb6a28b7ee4b 100644 --- a/doc/builders/testers.chapter.md +++ b/doc/builders/testers.chapter.md @@ -1,5 +1,5 @@ # Testers {#chap-testers} -This chapter describes several testing builders which are available in the testers namespace. +This chapter describes several testing builders which are available in the `testers` namespace. ## `hasPkgConfigModule` {#tester-hasPkgConfigModule} diff --git a/doc/stdenv/meta.chapter.md b/doc/stdenv/meta.chapter.md index a21dfd0821af..1c34fc76d035 100644 --- a/doc/stdenv/meta.chapter.md +++ b/doc/stdenv/meta.chapter.md @@ -128,7 +128,7 @@ Prefer `passthru.tests` for tests that are introduced in nixpkgs because: * we can run `passthru.tests` independently * `installCheckPhase` adds overhead to each build -For more on how to write and run package tests, see . +For more on how to write and run package tests, see [](#sec-package-tests). #### NixOS tests {#var-meta-tests-nixos} diff --git a/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md index a923da935ced..bb98d9ad7bb2 100644 --- a/doc/stdenv/stdenv.chapter.md +++ b/doc/stdenv/stdenv.chapter.md @@ -971,7 +971,8 @@ to `~/.gdbinit`. GDB will then be able to find debug information installed via ` The installCheck phase checks whether the package was installed correctly by running its test suite against the installed directories. The default `installCheck` calls `make installcheck`. -It is often better to add tests that are not part of the source distribution to `passthru.tests` (see ). This avoids adding overhead to every build and enables us to run them independently. +It is often better to add tests that are not part of the source distribution to `passthru.tests` (see +[](#var-meta-tests)). This avoids adding overhead to every build and enables us to run them independently. #### Variables controlling the installCheck phase {#variables-controlling-the-installcheck-phase} @@ -1234,7 +1235,7 @@ This runs the strip command on installed binaries and libraries. This removes un This setup hook patches installed scripts to add Nix store paths to their shebang interpreter as found in the build environment. The [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) line tells a Unix-like operating system which interpreter to use to execute the script's contents. -::: note +::: {.note} The [generic builder][generic-builder] populates `PATH` from inputs of the derivation. ::: @@ -1272,7 +1273,7 @@ patchShebangs --build configure Interpreter paths that point to a valid Nix store location are not changed. -::: note +::: {.note} A script file must be marked as executable, otherwise it will not be considered. ::: From 2f76a3df6405df203b7392edca0e5000d4787057 Mon Sep 17 00:00:00 2001 From: pennae Date: Sat, 10 Jun 2023 18:13:33 +0200 Subject: [PATCH 5/5] doc: don't use docbook program listings/callouts nixos-render-docs does not support this, and since the examples are small there isn't that much value in callouts here. change them to simple MD code blocks and lists instead. --- doc/languages-frameworks/bower.section.md | 67 ++++++----------------- doc/languages-frameworks/qt.section.md | 29 +++------- 2 files changed, 23 insertions(+), 73 deletions(-) diff --git a/doc/languages-frameworks/bower.section.md b/doc/languages-frameworks/bower.section.md index 6226dc0702d7..c1e5ca4deb7d 100644 --- a/doc/languages-frameworks/bower.section.md +++ b/doc/languages-frameworks/bower.section.md @@ -41,32 +41,18 @@ The function is implemented in [pkgs/development/bower-modules/generic/default.n ### Example buildBowerComponents {#ex-buildBowerComponents} -```{=docbook} - +```nix bowerComponents = buildBowerComponents { name = "my-web-app"; - generated = ./bower-packages.nix; - src = myWebApp; + generated = ./bower-packages.nix; # note 1 + src = myWebApp; # note 2 }; - ``` In ["buildBowerComponents" example](#ex-buildBowerComponents) the following arguments are of special significance to the function: -```{=docbook} - - - - generated specifies the file which was created by bower2nix. - - - - - src is your project's sources. It needs to contain a bower.json file. - - - -``` +1. `generated` specifies the file which was created by {command}`bower2nix`. +2. `src` is your project's sources. It needs to contain a {file}`bower.json` file. `buildBowerComponents` will run Bower to link together the output of `bower2nix`, resulting in a `bower_components` directory which can be used. @@ -91,10 +77,9 @@ gulp.task('build', [], function () { ### Example Full example — default.nix {#ex-buildBowerComponentsDefaultNix} -```{=docbook} - +```nix { myWebApp ? { outPath = ./.; name = "myWebApp"; } -, pkgs ? import <nixpkgs> {} +, pkgs ? import {} }: pkgs.stdenv.mkDerivation { @@ -103,49 +88,29 @@ pkgs.stdenv.mkDerivation { buildInputs = [ pkgs.nodePackages.gulp ]; - bowerComponents = pkgs.buildBowerComponents { + bowerComponents = pkgs.buildBowerComponents { # note 1 name = "my-web-app"; generated = ./bower-packages.nix; src = myWebApp; }; buildPhase = '' - cp --reflink=auto --no-preserve=mode -R $bowerComponents/bower_components . - export HOME=$PWD - ${pkgs.nodePackages.gulp}/bin/gulp build + cp --reflink=auto --no-preserve=mode -R $bowerComponents/bower_components . # note 2 + export HOME=$PWD # note 3 + ${pkgs.nodePackages.gulp}/bin/gulp build # note 4 ''; installPhase = "mv gulpdist $out"; } - ``` A few notes about [Full example — `default.nix`](#ex-buildBowerComponentsDefaultNix): -```{=docbook} - - - - The result of buildBowerComponents is an input to the frontend build. - - - - - Whether to symlink or copy the bower_components directory depends on the build tool in use. In this case a copy is used to avoid gulp silliness with permissions. - - - - - gulp requires HOME to refer to a writeable directory. - - - - - The actual build command. Other tools could be used. - - - -``` +1. The result of `buildBowerComponents` is an input to the frontend build. +2. Whether to symlink or copy the {file}`bower_components` directory depends on the build tool in use. + In this case a copy is used to avoid {command}`gulp` silliness with permissions. +3. {command}`gulp` requires `HOME` to refer to a writeable directory. +4. The actual build command in this example is {command}`gulp`. Other tools could be used instead. ## Troubleshooting {#ssec-bower2nix-troubleshooting} diff --git a/doc/languages-frameworks/qt.section.md b/doc/languages-frameworks/qt.section.md index e09194e391e1..2300c5f60ede 100644 --- a/doc/languages-frameworks/qt.section.md +++ b/doc/languages-frameworks/qt.section.md @@ -10,37 +10,22 @@ pure and explicit at build-time, at the cost of introducing an extra indirection ## Nix expression for a Qt package (default.nix) {#qt-default-nix} -```{=docbook} - -{ stdenv, lib, qtbase, wrapQtAppsHook }: +```nix +{ stdenv, lib, qtbase, wrapQtAppsHook }: stdenv.mkDerivation { pname = "myapp"; version = "1.0"; buildInputs = [ qtbase ]; - nativeBuildInputs = [ wrapQtAppsHook ]; + nativeBuildInputs = [ wrapQtAppsHook ]; } - - - - - - Import Qt modules directly, that is: qtbase, qtdeclarative, etc. - Do not import Qt package sets such as qt5 - because the Qt versions of dependencies may not be coherent, causing build and runtime failures. - - - - - All Qt packages must include wrapQtAppsHook in - nativeBuildInputs, or you must explicitly set - dontWrapQtApps. - - - ``` +It is important to import Qt modules directly, that is: `qtbase`, `qtdeclarative`, etc. *Do not* import Qt package sets such as `qt5` because the Qt versions of dependencies may not be coherent, causing build and runtime failures. + +Additionally all Qt packages must include `wrapQtAppsHook` in `nativeBuildInputs`, or you must explicitly set `dontWrapQtApps`. + ## Locating runtime dependencies {#qt-runtime-dependencies} Qt applications must be wrapped to find runtime dependencies.