diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/builders/images/dockertools.section.md | 2 | ||||
-rw-r--r-- | doc/builders/testers.chapter.md | 13 | ||||
-rw-r--r-- | doc/contributing/contributing-to-documentation.chapter.md | 14 | ||||
-rw-r--r-- | doc/hooks/postgresql-test-hook.section.md | 6 | ||||
-rw-r--r-- | doc/languages-frameworks/android.section.md | 6 | ||||
-rw-r--r-- | doc/languages-frameworks/index.xml | 1 | ||||
-rw-r--r-- | doc/languages-frameworks/ocaml.section.md | 5 | ||||
-rw-r--r-- | doc/languages-frameworks/pkg-config.section.md | 9 | ||||
-rw-r--r-- | doc/languages-frameworks/python.section.md | 8 | ||||
-rw-r--r-- | doc/stdenv/stdenv.chapter.md | 6 |
10 files changed, 52 insertions, 18 deletions
diff --git a/doc/builders/images/dockertools.section.md b/doc/builders/images/dockertools.section.md index dfc012b80c5a7..2467739a1a5e2 100644 --- a/doc/builders/images/dockertools.section.md +++ b/doc/builders/images/dockertools.section.md @@ -145,7 +145,7 @@ Create a Docker image with many of the store paths being on their own layer to i `architecture` is _optional_ and used to specify the image architecture, this is useful for multi-architecture builds that don't need cross compiling. If not specified it will default to `hostPlatform`. -: Run-time configuration of the container. A full list of the options are available at in the [Docker Image Specification v1.2.0](https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions). +: Run-time configuration of the container. A full list of the options available is in the [Docker Image Specification v1.2.0](https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions). *Default:* `{}` diff --git a/doc/builders/testers.chapter.md b/doc/builders/testers.chapter.md index 3d91f096051ee..a0f0f97f9d53f 100644 --- a/doc/builders/testers.chapter.md +++ b/doc/builders/testers.chapter.md @@ -1,6 +1,19 @@ # Testers {#chap-testers} This chapter describes several testing builders which are available in the <literal>testers</literal> namespace. +## `hasPkgConfigModule` {#tester-hasPkgConfigModule} + +Checks whether a package exposes a certain `pkg-config` module. + +Example: + +```nix +passthru.tests.pkg-config = testers.hasPkgConfigModule { + package = finalAttrs.finalPackage; + moduleName = "libfoo"; +} +``` + ## `testVersion` {#tester-testVersion} Checks the command output contains the specified version diff --git a/doc/contributing/contributing-to-documentation.chapter.md b/doc/contributing/contributing-to-documentation.chapter.md index 889b4114accaf..a732eee4b9627 100644 --- a/doc/contributing/contributing-to-documentation.chapter.md +++ b/doc/contributing/contributing-to-documentation.chapter.md @@ -27,7 +27,7 @@ If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual. As per [RFC 0072](https://github.com/NixOS/rfcs/pull/72), all new documentation content should be written in [CommonMark](https://commonmark.org/) Markdown dialect. -Additional syntax extensions are available, though not all extensions can be used in NixOS option documentation. The following extensions are currently used: +Additional syntax extensions are available, all of which can be used in NixOS option documentation. The following extensions are currently used: - []{#ssec-contributing-markup-anchors} Explicitly defined **anchors** on headings, to allow linking to sections. These should be always used, to ensure the anchors can be linked even when the heading text changes, and to prevent conflicts between [automatically assigned identifiers](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/auto_identifiers.md). @@ -38,6 +38,10 @@ Additional syntax extensions are available, though not all extensions can be use ## Syntax {#sec-contributing-markup} ``` + ::: {.note} + NixOS option documentation does not support headings in general. + ::: + - []{#ssec-contributing-markup-anchors-inline} **Inline anchors**, which allow linking arbitrary place in the text (e.g. individual list items, sentences…). @@ -67,10 +71,6 @@ Additional syntax extensions are available, though not all extensions can be use This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point). Though, the feature originates from [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage) with slightly different syntax. - ::: {.note} - Inline roles are available for option documentation. - ::: - - []{#ssec-contributing-markup-admonitions} **Admonitions**, set off from the text to bring attention to something. @@ -96,10 +96,6 @@ Additional syntax extensions are available, though not all extensions can be use - [`tip`](https://tdg.docbook.org/tdg/5.0/tip.html) - [`warning`](https://tdg.docbook.org/tdg/5.0/warning.html) - ::: {.note} - Admonitions are available for option documentation. - ::: - - []{#ssec-contributing-markup-definition-lists} [**Definition lists**](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/definition_lists.md), for defining a group of terms: diff --git a/doc/hooks/postgresql-test-hook.section.md b/doc/hooks/postgresql-test-hook.section.md index c53d841883e54..8b37ca1e4b3e7 100644 --- a/doc/hooks/postgresql-test-hook.section.md +++ b/doc/hooks/postgresql-test-hook.section.md @@ -46,6 +46,12 @@ Bash-only variables: - `postgresqlEnableTCP`: set to `1` to enable TCP listening. Flaky; not recommended. - `postgresqlStartCommands`: defaults to `pg_ctl start`. +## Hooks {#sec-postgresqlTestHook-hooks} + +A number of additional hooks are ran in postgresqlTestHook + + - `postgresqlTestSetupPost`: ran after postgresql has been set up. + ## TCP and the Nix sandbox {#sec-postgresqlTestHook-tcp} `postgresqlEnableTCP` relies on network sandboxing, which is not available on macOS and some custom Nix installations, resulting in flaky tests. diff --git a/doc/languages-frameworks/android.section.md b/doc/languages-frameworks/android.section.md index 15b8d3839b193..6f9717ca09cca 100644 --- a/doc/languages-frameworks/android.section.md +++ b/doc/languages-frameworks/android.section.md @@ -13,6 +13,7 @@ with import <nixpkgs> {}; let androidComposition = androidenv.composeAndroidPackages { + cmdLineToolsVersion = "8.0"; toolsVersion = "26.1.1"; platformToolsVersion = "30.0.5"; buildToolsVersions = [ "30.0.3" ]; @@ -42,7 +43,10 @@ exceptions are the tools, platform-tools and build-tools sub packages. The following parameters are supported: -* `toolsVersion`, specifies the version of the tools package to use +* `cmdLineToolsVersion `, specifies the version of the `cmdline-tools` package to use +* `toolsVersion`, specifies the version of the `tools` package. Notice `tools` is + obsolete, and currently only `26.1.1` is available, so there's not a lot of + options here, however, you can set it as `null` if you don't want it. * `platformsToolsVersion` specifies the version of the `platform-tools` plugin * `buildToolsVersions` specifies the versions of the `build-tools` plugins to use. diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml index 7d404643d3693..3774924c0be4a 100644 --- a/doc/languages-frameworks/index.xml +++ b/doc/languages-frameworks/index.xml @@ -32,6 +32,7 @@ <xi:include href="octave.section.xml" /> <xi:include href="perl.section.xml" /> <xi:include href="php.section.xml" /> + <xi:include href="pkg-config.section.xml" /> <xi:include href="python.section.xml" /> <xi:include href="qt.section.xml" /> <xi:include href="r.section.xml" /> diff --git a/doc/languages-frameworks/ocaml.section.md b/doc/languages-frameworks/ocaml.section.md index 347b2ea2ecabe..1e5a5cb4536fb 100644 --- a/doc/languages-frameworks/ocaml.section.md +++ b/doc/languages-frameworks/ocaml.section.md @@ -129,3 +129,8 @@ packaged libraries may still use the old spelling: maintainers are invited to fix this when updating packages. Massive renaming is strongly discouraged as it would be challenging to review, difficult to test, and will cause unnecessary rebuild. + +The build will automatically fail if two distinct versions of the same library +are added to `buildInputs` (which usually happens transitively because of +`propagatedBuildInputs`). Set `dontDetectOcamlConflicts` to true to disable this +behavior. diff --git a/doc/languages-frameworks/pkg-config.section.md b/doc/languages-frameworks/pkg-config.section.md new file mode 100644 index 0000000000000..ee0a471be3e57 --- /dev/null +++ b/doc/languages-frameworks/pkg-config.section.md @@ -0,0 +1,9 @@ +# pkg-config {#sec-pkg-config} + +*pkg-config* is a unified interface for declaring and querying built C/C++ libraries. + +Nixpkgs provides a couple of facilities for working with this tool. + + - A [setup hook](#setup-hook-pkg-config) bundled with in the `pkg-config` package, to bring a derivation's declared build inputs into the environment. + - The [`validatePkgConfig` setup hook](https://nixos.org/manual/nixpkgs/stable/#validatepkgconfig), for packages that provide pkg-config modules. + - The `defaultPkgConfigPackages` package set: a set of aliases, named after the modules they provide. This is meant to be used by language-to-nix integrations. Hand-written packages should use the normal Nixpkgs attribute name instead. diff --git a/doc/languages-frameworks/python.section.md b/doc/languages-frameworks/python.section.md index 7b8a804106af7..c1945adb1cd30 100644 --- a/doc/languages-frameworks/python.section.md +++ b/doc/languages-frameworks/python.section.md @@ -58,7 +58,7 @@ with a nix-shell that has `numpy` and `toolz` in Python 3.9; then we will create a re-usable environment in a single-file Python script; then we will create a full Python environment for development with this same environment. -Philosphically, this should be familiar to users who are used to a `venv` style +Philosophically, this should be familiar to users who are used to a `venv` style of development: individual projects create their own Python environments without impacting the global environment or each other. @@ -744,17 +744,17 @@ work in any of the formats supported by `buildPythonPackage` currently, with the exception of `other` (see `format` in [`buildPythonPackage` parameters](#buildpythonpackage-parameters) for more details). -### Using unittestCheckHook {#using-unittestcheckhook} +#### Using unittestCheckHook {#using-unittestcheckhook} `unittestCheckHook` is a hook which will substitute the setuptools `test` command for a `checkPhase` which runs `python -m unittest discover`: ``` nativeCheckInputs = [ unittestCheckHook ]; - unittestFlags = [ "-s" "tests" "-v" ]; + unittestFlagsArray = [ "-s" "tests" "-v" ]; ``` -##### Using sphinxHook {#using-sphinxhook} +#### Using sphinxHook {#using-sphinxhook} The `sphinxHook` is a helpful tool to build documentation and manpages using the popular Sphinx documentation generator. diff --git a/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md index e66cc3476776b..a12d68c0934f8 100644 --- a/doc/stdenv/stdenv.chapter.md +++ b/doc/stdenv/stdenv.chapter.md @@ -253,7 +253,7 @@ The propagated equivalent of `depsTargetTarget`. This is prefixed for the same r #### `NIX_DEBUG` {#var-stdenv-NIX_DEBUG} -A natural number indicating how much information to log. If set to 1 or higher, `stdenv` will print moderate debugging information during the build. In particular, the `gcc` and `ld` wrapper scripts will print out the complete command line passed to the wrapped tools. If set to 6 or higher, the `stdenv` setup script will be run with `set -x` tracing. If set to 7 or higher, the `gcc` and `ld` wrapper scripts will also be run with `set -x` tracing. +A number between 0 and 7 indicating how much information to log. If set to 1 or higher, `stdenv` will print moderate debugging information during the build. In particular, the `gcc` and `ld` wrapper scripts will print out the complete command line passed to the wrapped tools. If set to 6 or higher, the `stdenv` setup script will be run with `set -x` tracing. If set to 7 or higher, the `gcc` and `ld` wrapper scripts will also be run with `set -x` tracing. ### Attributes affecting build properties {#attributes-affecting-build-properties} @@ -626,7 +626,7 @@ Before and after running `make`, the hooks `preBuild` and `postBuild` are called ### The check phase {#ssec-check-phase} -The check phase checks whether the package was built correctly by running its test suite. The default `checkPhase` calls `make check`, but only if the `doCheck` variable is enabled. +The check phase checks whether the package was built correctly by running its test suite. The default `checkPhase` calls `make $checkTarget`, but only if the `doCheck` variable is enabled (see below). #### Variables controlling the check phase {#variables-controlling-the-check-phase} @@ -646,7 +646,7 @@ See the [build phase](#var-stdenv-makeFlags) for details. ##### `checkTarget` {#var-stdenv-checkTarget} -The make target that runs the tests. Defaults to `check`. +The make target that runs the tests. Defaults to `check` if it exists, otherwise `test`; if neither is found, do nothing. ##### `checkFlags` / `checkFlagsArray` {#var-stdenv-checkFlags} |