diff options
Diffstat (limited to 'doc')
48 files changed, 694 insertions, 841 deletions
diff --git a/doc/.gitignore b/doc/.gitignore deleted file mode 100644 index b08285995f66f..0000000000000 --- a/doc/.gitignore +++ /dev/null @@ -1,11 +0,0 @@ -*.chapter.xml -*.section.xml -.version -functions/library/generated -functions/library/locations.xml -highlightjs -manual-full.xml -out -result -result-* -media diff --git a/doc/Makefile b/doc/Makefile deleted file mode 100644 index d5c0eeef69e27..0000000000000 --- a/doc/Makefile +++ /dev/null @@ -1,114 +0,0 @@ -MD_TARGETS=$(addsuffix .xml, $(basename $(shell find . -type f -regex '.*\.md$$' -not -name README.md))) - -PANDOC ?= pandoc - -pandoc_media_dir = media -# NOTE: Keep in sync with conversion script (/maintainers/scripts/db-to-md.sh). -# TODO: Remove raw-attribute when we can get rid of DocBook altogether. -pandoc_commonmark_enabled_extensions = +attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute -# Not needed: -# - docbook-reader/citerefentry-to-rst-role.lua (only relevant for DocBook → MarkDown/rST/MyST) -pandoc_flags = --extract-media=$(pandoc_media_dir) \ - --lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \ - --lua-filter=build-aux/pandoc-filters/myst-reader/roles.lua \ - --lua-filter=$(PANDOC_LINK_MANPAGES_FILTER) \ - --lua-filter=build-aux/pandoc-filters/docbook-writer/rst-roles.lua \ - --lua-filter=build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua \ - -f commonmark$(pandoc_commonmark_enabled_extensions)+smart - -.PHONY: all -all: validate format out/html/index.html out/epub/manual.epub - -.PHONY: render-md -render-md: ${MD_TARGETS} - -.PHONY: debug -debug: - nix-shell --run "xmloscopy --docbook5 ./manual.xml ./manual-full.xml" - -.PHONY: format -format: doc-support/result - find . -iname '*.xml' -type f | while read f; do \ - echo $$f ;\ - xmlformat --config-file "doc-support/result/xmlformat.conf" -i $$f ;\ - done - -.PHONY: fix-misc-xml -fix-misc-xml: - find . -iname '*.xml' -type f \ - -exec ../nixos/doc/varlistentry-fixer.rb {} ';' - -.PHONY: clean -clean: - rm -f ${MD_TARGETS} doc-support/result .version manual-full.xml functions/library/locations.xml functions/library/generated - rm -rf ./out/ ./highlightjs ./media - -.PHONY: validate -validate: manual-full.xml doc-support/result - jing doc-support/result/docbook.rng manual-full.xml - -out/html/index.html: doc-support/result manual-full.xml style.css highlightjs - mkdir -p out/html - xsltproc \ - --nonet --xinclude \ - --output $@ \ - doc-support/result/xhtml.xsl \ - ./manual-full.xml - - mkdir -p out/html/highlightjs/ - cp -r highlightjs out/html/ - - cp -r $(pandoc_media_dir) out/html/ - cp ./overrides.css out/html/ - cp ./style.css out/html/style.css - - mkdir -p out/html/images/callouts - cp doc-support/result/xsl/docbook/images/callouts/*.svg out/html/images/callouts/ - chmod u+w -R out/html/ - -out/epub/manual.epub: epub.xml - mkdir -p out/epub/scratch - xsltproc --nonet \ - --output out/epub/scratch/ \ - doc-support/result/epub.xsl \ - ./epub.xml - - echo "application/epub+zip" > mimetype - zip -0Xq "out/epub/manual.epub" mimetype - rm mimetype - cd "out/epub/scratch/" && zip -Xr9D "../manual.epub" * - rm -rf "out/epub/scratch/" - -highlightjs: doc-support/result - mkdir -p highlightjs - cp -r doc-support/result/highlightjs/highlight.pack.js highlightjs/ - cp -r doc-support/result/highlightjs/LICENSE highlightjs/ - cp -r doc-support/result/highlightjs/mono-blue.css highlightjs/ - cp -r doc-support/result/highlightjs/loader.js highlightjs/ - - -manual-full.xml: ${MD_TARGETS} .version functions/library/locations.xml functions/library/generated *.xml **/*.xml **/**/*.xml - xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml - -.version: doc-support/result - ln -rfs ./doc-support/result/version .version - -doc-support/result: doc-support/default.nix - (cd doc-support; nix-build) - -functions/library/locations.xml: doc-support/result - ln -rfs ./doc-support/result/function-locations.xml functions/library/locations.xml - -functions/library/generated: doc-support/result - ln -rfs ./doc-support/result/function-docs functions/library/generated - -%.section.xml: %.section.md - $(PANDOC) $^ -t docbook \ - $(pandoc_flags) \ - -o $@ - -%.chapter.xml: %.chapter.md - $(PANDOC) $^ -t docbook \ - --top-level-division=chapter \ - $(pandoc_flags) \ - -o $@ diff --git a/doc/build-aux/pandoc-filters/docbook-reader/citerefentry-to-rst-role.lua b/doc/build-aux/pandoc-filters/docbook-reader/citerefentry-to-rst-role.lua deleted file mode 100644 index 281e85af27178..0000000000000 --- a/doc/build-aux/pandoc-filters/docbook-reader/citerefentry-to-rst-role.lua +++ /dev/null @@ -1,23 +0,0 @@ ---[[ -Converts Code AST nodes produced by pandoc’s DocBook reader -from citerefentry elements into AST for corresponding role -for reStructuredText. - -We use subset of MyST syntax (CommonMark with features from rST) -so let’s use the rST AST for rST features. - -Reference: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage -]] - -function Code(elem) - elem.classes = elem.classes:map(function (x) - if x == 'citerefentry' then - elem.attributes['role'] = 'manpage' - return 'interpreted-text' - else - return x - end - end) - - return elem -end diff --git a/doc/build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua b/doc/build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua deleted file mode 100644 index fa97729a28bcf..0000000000000 --- a/doc/build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua +++ /dev/null @@ -1,34 +0,0 @@ ---[[ -Converts Link AST nodes with empty label to DocBook xref elements. - -This is a temporary script to be able use cross-references conveniently -using syntax taken from MyST, while we still use docbook-xsl -for generating the documentation. - -Reference: https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing -]] - -local function starts_with(start, str) - return str:sub(1, #start) == start -end - -local function escape_xml_arg(arg) - amps = arg:gsub('&', '&') - amps_quotes = amps:gsub('"', '"') - amps_quotes_lt = amps_quotes:gsub('<', '<') - - return amps_quotes_lt -end - -function Link(elem) - has_no_content = #elem.content == 0 - targets_anchor = starts_with('#', elem.target) - has_no_attributes = elem.title == '' and elem.identifier == '' and #elem.classes == 0 and #elem.attributes == 0 - - if has_no_content and targets_anchor and has_no_attributes then - -- xref expects idref without the pound-sign - target_without_hash = elem.target:sub(2, #elem.target) - - return pandoc.RawInline('docbook', '<xref linkend="' .. escape_xml_arg(target_without_hash) .. '" />') - end -end diff --git a/doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua b/doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua deleted file mode 100644 index 5c1b034d0792d..0000000000000 --- a/doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua +++ /dev/null @@ -1,44 +0,0 @@ ---[[ -Converts AST for reStructuredText roles into corresponding -DocBook elements. - -Currently, only a subset of roles is supported. - -Reference: - List of roles: - https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html - manpage: - https://tdg.docbook.org/tdg/5.1/citerefentry.html - file: - https://tdg.docbook.org/tdg/5.1/filename.html -]] - -function Code(elem) - if elem.classes:includes('interpreted-text') then - local tag = nil - local content = elem.text - if elem.attributes['role'] == 'manpage' then - tag = 'citerefentry' - local title, volnum = content:match('^(.+)%((%w+)%)$') - if title == nil then - -- No volnum in parentheses. - title = content - end - content = '<refentrytitle>' .. title .. '</refentrytitle>' .. (volnum ~= nil and ('<manvolnum>' .. volnum .. '</manvolnum>') or '') - elseif elem.attributes['role'] == 'file' then - tag = 'filename' - elseif elem.attributes['role'] == 'command' then - tag = 'command' - elseif elem.attributes['role'] == 'option' then - tag = 'option' - elseif elem.attributes['role'] == 'var' then - tag = 'varname' - elseif elem.attributes['role'] == 'env' then - tag = 'envar' - end - - if tag ~= nil then - return pandoc.RawInline('docbook', '<' .. tag .. '>' .. content .. '</' .. tag .. '>') - end - end -end diff --git a/doc/build-aux/pandoc-filters/link-manpages.nix b/doc/build-aux/pandoc-filters/link-manpages.nix deleted file mode 100644 index 2589a7c34251f..0000000000000 --- a/doc/build-aux/pandoc-filters/link-manpages.nix +++ /dev/null @@ -1,28 +0,0 @@ -{ pkgs ? import ../../.. {} }: -let - inherit (pkgs) lib; - manpageURLs = lib.importJSON (pkgs.path + "/doc/manpage-urls.json"); -in pkgs.writeText "link-manpages.lua" '' - --[[ - Adds links to known man pages that aren't already in a link. - ]] - - local manpage_urls = { - ${lib.concatStringsSep "\n" (lib.mapAttrsToList (man: url: - " [${builtins.toJSON man}] = ${builtins.toJSON url},") manpageURLs)} - } - - traverse = 'topdown' - - -- Returning false as the second value aborts processing of child elements. - function Link(elem) - return elem, false - end - - function Code(elem) - local is_man_role = elem.classes:includes('interpreted-text') and elem.attributes['role'] == 'manpage' - if is_man_role and manpage_urls[elem.text] ~= nil then - return pandoc.Link(elem, manpage_urls[elem.text]), false - end - end -'' diff --git a/doc/build-aux/pandoc-filters/myst-reader/roles.lua b/doc/build-aux/pandoc-filters/myst-reader/roles.lua deleted file mode 100644 index f4ef6d390b40b..0000000000000 --- a/doc/build-aux/pandoc-filters/myst-reader/roles.lua +++ /dev/null @@ -1,36 +0,0 @@ ---[[ -Replaces Str AST nodes containing {role}, followed by a Code node -by a Code node with attrs that would be produced by rST reader -from the role syntax. - -This is to emulate MyST syntax in Pandoc. -(MyST is a CommonMark flavour with rST features mixed in.) - -Reference: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point -]] - -function Inlines(inlines) - for i = #inlines-1,1,-1 do - local first = inlines[i] - local second = inlines[i+1] - local correct_tags = first.tag == 'Str' and second.tag == 'Code' - if correct_tags then - -- docutils supports alphanumeric strings separated by [-._:] - -- We are slightly more liberal for simplicity. - -- Allow preceding punctuation (eg '('), otherwise '({file}`...`)' - -- does not match. Also allow anything followed by a non-breaking space - -- since pandoc emits those after certain abbreviations (e.g. e.g.). - local prefix, role = first.text:match('^(.*){([-._+:%w]+)}$') - if role ~= nil and (prefix == '' or prefix:match("^.*[%p ]$") ~= nil) then - if prefix == '' then - inlines:remove(i) - else - first.text = prefix - end - second.attributes['role'] = role - second.classes:insert('interpreted-text') - end - end - end - return inlines -end diff --git a/doc/build-aux/pandoc-filters/myst-writer/roles.lua b/doc/build-aux/pandoc-filters/myst-writer/roles.lua deleted file mode 100644 index 0136bc5506529..0000000000000 --- a/doc/build-aux/pandoc-filters/myst-writer/roles.lua +++ /dev/null @@ -1,25 +0,0 @@ ---[[ -Replaces Code nodes with attrs that would be produced by rST reader -from the role syntax by a Str AST node containing {role}, followed by a Code node. - -This is to emulate MyST syntax in Pandoc. -(MyST is a CommonMark flavour with rST features mixed in.) - -Reference: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point -]] - -function Code(elem) - local role = elem.attributes['role'] - - if elem.classes:includes('interpreted-text') and role ~= nil then - elem.classes = elem.classes:filter(function (c) - return c ~= 'interpreted-text' - end) - elem.attributes['role'] = nil - - return { - pandoc.Str('{' .. role .. '}'), - elem, - } - end -end diff --git a/doc/builders.md b/doc/builders.md new file mode 100644 index 0000000000000..2e959422405b2 --- /dev/null +++ b/doc/builders.md @@ -0,0 +1,12 @@ +# Builders {#part-builders} + +```{=include=} chapters +builders/fetchers.chapter.md +builders/trivial-builders.chapter.md +builders/testers.chapter.md +builders/special.md +builders/images.md +hooks/index.md +languages-frameworks/index.md +builders/packages/index.md +``` diff --git a/doc/builders/images.md b/doc/builders/images.md new file mode 100644 index 0000000000000..5596784bfa487 --- /dev/null +++ b/doc/builders/images.md @@ -0,0 +1,13 @@ +# Images {#chap-images} + +This chapter describes tools for creating various types of images. + +```{=include=} sections +images/appimagetools.section.md +images/dockertools.section.md +images/ocitools.section.md +images/snaptools.section.md +images/portableservice.section.md +images/makediskimage.section.md +images/binarycache.section.md +``` diff --git a/doc/builders/images.xml b/doc/builders/images.xml deleted file mode 100644 index a4661ab5a7af7..0000000000000 --- a/doc/builders/images.xml +++ /dev/null @@ -1,15 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xi="http://www.w3.org/2001/XInclude" - xml:id="chap-images"> - <title>Images</title> - <para> - This chapter describes tools for creating various types of images. - </para> - <xi:include href="images/appimagetools.section.xml" /> - <xi:include href="images/dockertools.section.xml" /> - <xi:include href="images/ocitools.section.xml" /> - <xi:include href="images/snaptools.section.xml" /> - <xi:include href="images/portableservice.section.xml" /> - <xi:include href="images/makediskimage.section.xml" /> - <xi:include href="images/binarycache.section.xml" /> -</chapter> diff --git a/doc/builders/packages/dlib.section.md b/doc/builders/packages/dlib.section.md index 022195310a710..bd5b1a20a4d46 100644 --- a/doc/builders/packages/dlib.section.md +++ b/doc/builders/packages/dlib.section.md @@ -1,6 +1,6 @@ # DLib {#dlib} -[DLib](http://dlib.net/) is a modern, C++-based toolkit which provides several machine learning algorithms. +[DLib](http://dlib.net/) is a modern, C++\-based toolkit which provides several machine learning algorithms. ## Compiling without AVX support {#compiling-without-avx-support} diff --git a/doc/builders/packages/index.md b/doc/builders/packages/index.md new file mode 100644 index 0000000000000..1f44357024064 --- /dev/null +++ b/doc/builders/packages/index.md @@ -0,0 +1,27 @@ +# Packages {#chap-packages} + +This chapter contains information about how to use and maintain the Nix expressions for a number of specific packages, such as the Linux kernel or X.org. + +```{=include=} sections +citrix.section.md +dlib.section.md +eclipse.section.md +elm.section.md +emacs.section.md +firefox.section.md +fish.section.md +fuse.section.md +ibus.section.md +kakoune.section.md +linux.section.md +locales.section.md +etc-files.section.md +nginx.section.md +opengl.section.md +shell-helpers.section.md +steam.section.md +cataclysm-dda.section.md +urxvt.section.md +weechat.section.md +xorg.section.md +``` diff --git a/doc/builders/packages/index.xml b/doc/builders/packages/index.xml deleted file mode 100644 index 206e1e49f1f85..0000000000000 --- a/doc/builders/packages/index.xml +++ /dev/null @@ -1,29 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xi="http://www.w3.org/2001/XInclude" - xml:id="chap-packages"> - <title>Packages</title> - <para> - This chapter contains information about how to use and maintain the Nix expressions for a number of specific packages, such as the Linux kernel or X.org. - </para> - <xi:include href="citrix.section.xml" /> - <xi:include href="dlib.section.xml" /> - <xi:include href="eclipse.section.xml" /> - <xi:include href="elm.section.xml" /> - <xi:include href="emacs.section.xml" /> - <xi:include href="firefox.section.xml" /> - <xi:include href="fish.section.xml" /> - <xi:include href="fuse.section.xml" /> - <xi:include href="ibus.section.xml" /> - <xi:include href="kakoune.section.xml" /> - <xi:include href="linux.section.xml" /> - <xi:include href="locales.section.xml" /> - <xi:include href="etc-files.section.xml" /> - <xi:include href="nginx.section.xml" /> - <xi:include href="opengl.section.xml" /> - <xi:include href="shell-helpers.section.xml" /> - <xi:include href="steam.section.xml" /> - <xi:include href="cataclysm-dda.section.xml" /> - <xi:include href="urxvt.section.xml" /> - <xi:include href="weechat.section.xml" /> - <xi:include href="xorg.section.xml" /> -</chapter> diff --git a/doc/builders/special.md b/doc/builders/special.md new file mode 100644 index 0000000000000..6d07fa87f3f3e --- /dev/null +++ b/doc/builders/special.md @@ -0,0 +1,11 @@ +# Special builders {#chap-special} + +This chapter describes several special builders. + +```{=include=} sections +special/fhs-environments.section.md +special/makesetuphook.section.md +special/mkshell.section.md +special/darwin-builder.section.md +special/vm-tools.section.md +``` diff --git a/doc/builders/special.xml b/doc/builders/special.xml deleted file mode 100644 index 18cf6cfd39c70..0000000000000 --- a/doc/builders/special.xml +++ /dev/null @@ -1,13 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xi="http://www.w3.org/2001/XInclude" - xml:id="chap-special"> - <title>Special builders</title> - <para> - This chapter describes several special builders. - </para> - <xi:include href="special/fhs-environments.section.xml" /> - <xi:include href="special/makesetuphook.section.xml" /> - <xi:include href="special/mkshell.section.xml" /> - <xi:include href="special/darwin-builder.section.xml" /> - <xi:include href="special/vm-tools.section.xml" /> -</chapter> diff --git a/doc/builders/special/darwin-builder.section.md b/doc/builders/special/darwin-builder.section.md index b5b6ab8971e98..13d01a0e3af83 100644 --- a/doc/builders/special/darwin-builder.section.md +++ b/doc/builders/special/darwin-builder.section.md @@ -1,11 +1,12 @@ -# darwin.builder {#sec-darwin-builder} +# darwin.linux-builder {#sec-darwin-builder} -`darwin.builder` provides a way to bootstrap a Linux builder on a macOS machine. +`darwin.linux-builder` provides a way to bootstrap a Linux builder on a macOS machine. This requires macOS version 12.4 or later. -This also requires that port 22 on your machine is free (since Nix does not -permit specifying a non-default SSH port for builders). +The builder runs on host port 31022 by default. +You can change it by overriding `virtualisation.darwin-builder.hostPort`. +See the [example](#sec-darwin-builder-example-flake). You will also need to be a trusted user for your Nix installation. In other words, your `/etc/nix/nix.conf` should have something like: @@ -17,7 +18,7 @@ extra-trusted-users = <your username goes here> To launch the builder, run the following flake: ```ShellSession -$ nix run nixpkgs#darwin.builder +$ nix run nixpkgs#darwin.linux-builder ``` That will prompt you to enter your `sudo` password: @@ -50,12 +51,21 @@ To delegate builds to the remote builder, add the following options to your ``` # - Replace ${ARCH} with either aarch64 or x86_64 to match your host machine # - Replace ${MAX_JOBS} with the maximum number of builds (pick 4 if you're not sure) -builders = ssh-ng://builder@localhost ${ARCH}-linux /etc/nix/builder_ed25519 ${MAX_JOBS} - - - c3NoLWVkMjU1MTkgQUFBQUMzTnphQzFsWkRJMU5URTVBQUFBSUpCV2N4Yi9CbGFxdDFhdU90RStGOFFVV3JVb3RpQzVxQkorVXVFV2RWQ2Igcm9vdEBuaXhvcwo= +builders = ssh-ng://builder@linux-builder ${ARCH}-linux /etc/nix/builder_ed25519 ${MAX_JOBS} - - - c3NoLWVkMjU1MTkgQUFBQUMzTnphQzFsWkRJMU5URTVBQUFBSUpCV2N4Yi9CbGFxdDFhdU90RStGOFFVV3JVb3RpQzVxQkorVXVFV2RWQ2Igcm9vdEBuaXhvcwo= # Not strictly necessary, but this will reduce your disk utilization builders-use-substitutes = true ``` +To allow Nix to connect to a builder not running on port 22, you will also need to create a new file at `/etc/ssh/ssh_config.d/100-linux-builder.conf`: + +``` +Host linux-builder + Hostname localhost + HostKeyAlias linux-builder + Port 31022 +``` + … and then restart your Nix daemon to apply the change: ```ShellSession diff --git a/doc/contributing.md b/doc/contributing.md new file mode 100644 index 0000000000000..3215dbe32bec0 --- /dev/null +++ b/doc/contributing.md @@ -0,0 +1,10 @@ +# Contributing to Nixpkgs {#part-contributing} + +```{=include=} chapters +contributing/quick-start.chapter.md +contributing/coding-conventions.chapter.md +contributing/submitting-changes.chapter.md +contributing/vulnerability-roundup.chapter.md +contributing/reviewing-contributions.chapter.md +contributing/contributing-to-documentation.chapter.md +``` diff --git a/doc/contributing/staging-workflow.dot b/doc/contributing/staging-workflow.dot new file mode 100644 index 0000000000000..faca7a1cad4c7 --- /dev/null +++ b/doc/contributing/staging-workflow.dot @@ -0,0 +1,16 @@ +digraph { + "small changes" [shape=none] + "mass-rebuilds and other large changes" [shape=none] + "critical security fixes" [shape=none] + "broken staging-next fixes" [shape=none] + + "small changes" -> master + "mass-rebuilds and other large changes" -> staging + "critical security fixes" -> master + "broken staging-next fixes" -> "staging-next" + + "staging-next" -> master [color="#E85EB0"] [label="stabilization ends"] [fontcolor="#E85EB0"] + "staging" -> "staging-next" [color="#E85EB0"] [label="stabilization starts"] [fontcolor="#E85EB0"] + + master -> "staging-next" -> staging [color="#5F5EE8"] [label="every six hours (GitHub Action)"] [fontcolor="#5F5EE8"] +} diff --git a/doc/contributing/staging-workflow.svg b/doc/contributing/staging-workflow.svg new file mode 100644 index 0000000000000..1a174a78830e4 --- /dev/null +++ b/doc/contributing/staging-workflow.svg @@ -0,0 +1,102 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<!-- Generated by graphviz version 7.1.0 (0) + --> +<!-- Pages: 1 --> +<svg width="743pt" height="291pt" + viewBox="0.00 0.00 743.00 291.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> +<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 287)"> +<polygon fill="white" stroke="none" points="-4,4 -4,-287 739,-287 739,4 -4,4"/> +<!-- small changes --> +<g id="node1" class="node"> +<title>small changes</title> +<text text-anchor="middle" x="59" y="-261.3" font-family="Times,serif" font-size="14.00">small changes</text> +</g> +<!-- master --> +<g id="node5" class="node"> +<title>master</title> +<ellipse fill="none" stroke="black" cx="139" cy="-192" rx="43.59" ry="18"/> +<text text-anchor="middle" x="139" y="-188.3" font-family="Times,serif" font-size="14.00">master</text> +</g> +<!-- small changes->master --> +<g id="edge1" class="edge"> +<title>small changes->master</title> +<path fill="none" stroke="black" d="M77.96,-247.17C88.42,-237.89 101.55,-226.23 112.96,-216.11"/> +<polygon fill="black" stroke="black" points="114.99,-218.99 120.14,-209.74 110.34,-213.76 114.99,-218.99"/> +</g> +<!-- mass-rebuilds and other large changes --> +<g id="node2" class="node"> +<title>mass-rebuilds and other large changes</title> +<text text-anchor="middle" x="588" y="-101.3" font-family="Times,serif" font-size="14.00">mass-rebuilds and other large changes</text> +</g> +<!-- staging --> +<g id="node6" class="node"> +<title>staging</title> +<ellipse fill="none" stroke="black" cx="438" cy="-18" rx="45.49" ry="18"/> +<text text-anchor="middle" x="438" y="-14.3" font-family="Times,serif" font-size="14.00">staging</text> +</g> +<!-- mass-rebuilds and other large changes->staging --> +<g id="edge2" class="edge"> +<title>mass-rebuilds and other large changes->staging</title> +<path fill="none" stroke="black" d="M587.48,-87.47C586.26,-76.55 582.89,-62.7 574,-54 553.19,-33.63 522.2,-24.65 495.05,-20.86"/> +<polygon fill="black" stroke="black" points="495.53,-17.39 485.2,-19.71 494.72,-24.35 495.53,-17.39"/> +</g> +<!-- critical security fixes --> +<g id="node3" class="node"> +<title>critical security fixes</title> +<text text-anchor="middle" x="219" y="-261.3" font-family="Times,serif" font-size="14.00">critical security fixes</text> +</g> +<!-- critical security fixes->master --> +<g id="edge3" class="edge"> +<title>critical security fixes->master</title> +<path fill="none" stroke="black" d="M200.04,-247.17C189.58,-237.89 176.45,-226.23 165.04,-216.11"/> +<polygon fill="black" stroke="black" points="167.66,-213.76 157.86,-209.74 163.01,-218.99 167.66,-213.76"/> +</g> +<!-- broken staging-next fixes --> +<g id="node4" class="node"> +<title>broken staging-next fixes</title> +<text text-anchor="middle" x="414" y="-188.3" font-family="Times,serif" font-size="14.00">broken staging-next fixes</text> +</g> +<!-- staging-next --> +<g id="node7" class="node"> +<title>staging-next</title> +<ellipse fill="none" stroke="black" cx="272" cy="-105" rx="68.79" ry="18"/> +<text text-anchor="middle" x="272" y="-101.3" font-family="Times,serif" font-size="14.00">staging-next</text> +</g> +<!-- broken staging-next fixes->staging-next --> +<g id="edge4" class="edge"> +<title>broken staging-next fixes->staging-next</title> +<path fill="none" stroke="black" d="M410.2,-174.42C406.88,-163.48 400.98,-149.62 391,-141 377.77,-129.56 360.96,-121.86 344.17,-116.67"/> +<polygon fill="black" stroke="black" points="345.21,-113.33 334.63,-114.02 343.33,-120.07 345.21,-113.33"/> +</g> +<!-- master->staging-next --> +<g id="edge7" class="edge"> +<title>master->staging-next</title> +<path fill="none" stroke="#5f5ee8" d="M96.55,-187.26C53.21,-181.83 -4.5,-169.14 20,-141 41.99,-115.74 126.36,-108.13 191.48,-106.11"/> +<polygon fill="#5f5ee8" stroke="#5f5ee8" points="191.57,-109.61 201.47,-105.85 191.38,-102.62 191.57,-109.61"/> +<text text-anchor="middle" x="133" y="-144.8" font-family="Times,serif" font-size="14.00" fill="#5f5ee8">every six hours (GitHub Action)</text> +</g> +<!-- staging->staging-next --> +<g id="edge6" class="edge"> +<title>staging->staging-next</title> +<path fill="none" stroke="#e85eb0" d="M434.55,-36.2C431.48,-47.12 425.89,-60.72 416,-69 397.61,-84.41 373.51,-93.23 350.31,-98.23"/> +<polygon fill="#e85eb0" stroke="#e85eb0" points="349.67,-94.79 340.5,-100.1 350.98,-101.66 349.67,-94.79"/> +<text text-anchor="middle" x="493.5" y="-57.8" font-family="Times,serif" font-size="14.00" fill="#e85eb0">stabilization starts</text> +</g> +<!-- staging-next->master --> +<g id="edge5" class="edge"> +<title>staging-next->master</title> +<path fill="none" stroke="#e85eb0" d="M268.22,-123.46C265.05,-134.22 259.46,-147.52 250,-156 233.94,-170.4 211.98,-178.87 191.83,-183.86"/> +<polygon fill="#e85eb0" stroke="#e85eb0" points="191.35,-180.38 182.34,-185.96 192.86,-187.22 191.35,-180.38"/> +<text text-anchor="middle" x="323.5" y="-144.8" font-family="Times,serif" font-size="14.00" fill="#e85eb0">stabilization ends</text> +</g> +<!-- staging-next->staging --> +<g id="edge8" class="edge"> +<title>staging-next->staging</title> +<path fill="none" stroke="#5f5ee8" d="M221.07,-92.46C194.72,-84.14 170.92,-71.32 186,-54 210.78,-25.54 314.74,-19.48 381.15,-18.6"/> +<polygon fill="#5f5ee8" stroke="#5f5ee8" points="380.79,-22.1 390.76,-18.51 380.73,-15.1 380.79,-22.1"/> +<text text-anchor="middle" x="299" y="-57.8" font-family="Times,serif" font-size="14.00" fill="#5f5ee8">every six hours (GitHub Action)</text> +</g> +</g> +</svg> diff --git a/doc/contributing/submitting-changes.chapter.md b/doc/contributing/submitting-changes.chapter.md index 30fe4fa47d0d1..8e92686c82d32 100644 --- a/doc/contributing/submitting-changes.chapter.md +++ b/doc/contributing/submitting-changes.chapter.md @@ -214,24 +214,11 @@ The last checkbox is fits [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blo - Hydra builds for master and staging should not be used as testing platform, it’s a build farm for changes that have been already tested. - When changing the bootloader installation process, extra care must be taken. Grub installations cannot be rolled back, hence changes may break people’s installations forever. For any non-trivial change to the bootloader please file a PR asking for review, especially from \@edolstra. -```{.graphviz caption="Staging workflow"} -digraph { - "small changes" [shape=none] - "mass-rebuilds and other large changes" [shape=none] - "critical security fixes" [shape=none] - "broken staging-next fixes" [shape=none] - - "small changes" -> master - "mass-rebuilds and other large changes" -> staging - "critical security fixes" -> master - "broken staging-next fixes" -> "staging-next" - - "staging-next" -> master [color="#E85EB0"] [label="stabilization ends"] [fontcolor="#E85EB0"] - "staging" -> "staging-next" [color="#E85EB0"] [label="stabilization starts"] [fontcolor="#E85EB0"] - - master -> "staging-next" -> staging [color="#5F5EE8"] [label="every six hours (GitHub Action)"] [fontcolor="#5F5EE8"] -} -``` +::: {.figure #fig-staging-workflow} +# Staging workflow +<!-- generated from ./staging-workflow.dot using: dot -Tsvg staging-workflow.dot > staging-workflow.svg --> + +::: [This GitHub Action](https://github.com/NixOS/nixpkgs/blob/master/.github/workflows/periodic-merge-6h.yml) brings changes from `master` to `staging-next` and from `staging-next` to `staging` every 6 hours; these are the blue arrows in the diagram above. The purple arrows in the diagram above are done manually and much less frequently. You can get an idea of how often these merges occur by looking at the git history. diff --git a/doc/default.nix b/doc/default.nix index 86b4a8d978146..5954e4495adb9 100644 --- a/doc/default.nix +++ b/doc/default.nix @@ -1,69 +1,145 @@ { pkgs ? (import ./.. { }), nixpkgs ? { }}: let - doc-support = import ./doc-support { inherit pkgs nixpkgs; }; + inherit (pkgs) lib; + inherit (lib) hasPrefix removePrefix; + + lib-docs = import ./doc-support/lib-function-docs.nix { + inherit pkgs nixpkgs; + libsets = [ + { name = "asserts"; description = "assertion functions"; } + { name = "attrsets"; description = "attribute set functions"; } + { name = "strings"; description = "string manipulation functions"; } + { name = "versions"; description = "version string functions"; } + { name = "trivial"; description = "miscellaneous functions"; } + { name = "lists"; description = "list manipulation functions"; } + { name = "debug"; description = "debugging functions"; } + { name = "options"; description = "NixOS / nixpkgs option handling"; } + { name = "path"; description = "path functions"; } + { name = "filesystem"; description = "filesystem functions"; } + { name = "sources"; description = "source filtering functions"; } + { name = "cli"; description = "command-line serialization functions"; } + ]; + }; + + epub = pkgs.runCommand "manual.epub" { + nativeBuildInputs = with pkgs; [ libxslt zip ]; + + epub = '' + <book xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + version="5.0" + xml:id="nixpkgs-manual"> + <info> + <title>Nixpkgs Manual</title> + <subtitle>Version ${pkgs.lib.version}</subtitle> + </info> + <chapter> + <title>Temporarily unavailable</title> + <para> + The Nixpkgs manual is currently not available in EPUB format, + please use the <link xlink:href="https://nixos.org/nixpkgs/manual">HTML manual</link> + instead. + </para> + <para> + If you've used the EPUB manual in the past and it has been useful to you, please + <link xlink:href="https://github.com/NixOS/nixpkgs/issues/237234">let us know</link>. + </para> + </chapter> + </book> + ''; + + passAsFile = [ "epub" ]; + } '' + mkdir scratch + xsltproc \ + --param chapter.autolabel 0 \ + --nonet \ + --output scratch/ \ + ${pkgs.docbook_xsl_ns}/xml/xsl/docbook/epub/docbook.xsl \ + $epubPath + + echo "application/epub+zip" > mimetype + zip -0Xq "$out" mimetype + cd scratch && zip -Xr9D "$out" * + ''; + + # NB: This file describes the Nixpkgs manual, which happens to use module + # docs infra originally developed for NixOS. + optionsDoc = pkgs.nixosOptionsDoc { + inherit (pkgs.lib.evalModules { + modules = [ ../pkgs/top-level/config.nix ]; + class = "nixpkgsConfig"; + }) options; + documentType = "none"; + transformOptions = opt: + opt // { + declarations = + map + (decl: + if hasPrefix (toString ../..) (toString decl) + then + let subpath = removePrefix "/" (removePrefix (toString ../.) (toString decl)); + in { url = "https://github.com/NixOS/nixpkgs/blob/master/${subpath}"; name = subpath; } + else decl) + opt.declarations; + }; + }; in pkgs.stdenv.mkDerivation { name = "nixpkgs-manual"; nativeBuildInputs = with pkgs; [ - pandoc - graphviz - libxml2 - libxslt - zip - jing - xmlformat + nixos-render-docs ]; - src = pkgs.nix-gitignore.gitignoreSource [] ./.; + src = ./.; postPatch = '' - ln -s ${doc-support} ./doc-support/result + ln -s ${optionsDoc.optionsJSON}/share/doc/nixos/options.json ./config-options.json ''; - epub = '' - <book xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - version="5.0" - xml:id="nixpkgs-manual"> - <info> - <title>Nixpkgs Manual</title> - <subtitle>Version ${pkgs.lib.version}</subtitle> - </info> - <chapter> - <title>Temporarily unavailable</title> - <para> - The Nixpkgs manual is currently not available in EPUB format, - please use the <link xlink:href="https://nixos.org/nixpkgs/manual">HTML manual</link> - instead. - </para> - <para> - If you've used the EPUB manual in the past and it has been useful to you, please - <link xlink:href="https://github.com/NixOS/nixpkgs/issues/237234">let us know</link>. - </para> - </chapter> - </book> - ''; - passAsFile = [ "epub" ]; + buildPhase = '' + cat \ + ./functions/library.md.in \ + ${lib-docs}/index.md \ + > ./functions/library.md + substitute ./manual.md.in ./manual.md \ + --replace '@MANUAL_VERSION@' '${pkgs.lib.version}' + + mkdir -p out/media - preBuild = '' - cp $epubPath epub.xml - make -j$NIX_BUILD_CORES render-md + mkdir -p out/highlightjs + cp -t out/highlightjs \ + ${pkgs.documentation-highlighter}/highlight.pack.js \ + ${pkgs.documentation-highlighter}/LICENSE \ + ${pkgs.documentation-highlighter}/mono-blue.css \ + ${pkgs.documentation-highlighter}/loader.js + + cp -t out ./overrides.css ./style.css + + nixos-render-docs manual html \ + --manpage-urls ./manpage-urls.json \ + --revision ${pkgs.lib.trivial.revisionWithDefault (pkgs.rev or "master")} \ + --stylesheet style.css \ + --stylesheet overrides.css \ + --stylesheet highlightjs/mono-blue.css \ + --script ./highlightjs/highlight.pack.js \ + --script ./highlightjs/loader.js \ + --toc-depth 1 \ + --section-toc-depth 1 \ + manual.md \ + out/index.html ''; installPhase = '' dest="$out/share/doc/nixpkgs" mkdir -p "$(dirname "$dest")" - mv out/html "$dest" + mv out "$dest" mv "$dest/index.html" "$dest/manual.html" - mv out/epub/manual.epub "$dest/nixpkgs-manual.epub" + cp ${epub} "$dest/nixpkgs-manual.epub" mkdir -p $out/nix-support/ echo "doc manual $dest manual.html" >> $out/nix-support/hydra-build-products echo "doc manual $dest nixpkgs-manual.epub" >> $out/nix-support/hydra-build-products ''; - - # Environment variables - PANDOC_LUA_FILTERS_DIR = "${pkgs.pandoc-lua-filters}/share/pandoc/filters"; - PANDOC_LINK_MANPAGES_FILTER = import build-aux/pandoc-filters/link-manpages.nix { inherit pkgs; }; } diff --git a/doc/doc-support/default.nix b/doc/doc-support/default.nix deleted file mode 100644 index cfa7cbdc82839..0000000000000 --- a/doc/doc-support/default.nix +++ /dev/null @@ -1,87 +0,0 @@ -{ pkgs ? (import ../.. {}), nixpkgs ? { }}: -let - inherit (pkgs) lib; - inherit (lib) hasPrefix removePrefix; - - libsets = [ - { name = "asserts"; description = "assertion functions"; } - { name = "attrsets"; description = "attribute set functions"; } - { name = "strings"; description = "string manipulation functions"; } - { name = "versions"; description = "version string functions"; } - { name = "trivial"; description = "miscellaneous functions"; } - { name = "lists"; description = "list manipulation functions"; } - { name = "debug"; description = "debugging functions"; } - { name = "options"; description = "NixOS / nixpkgs option handling"; } - { name = "path"; description = "path functions"; } - { name = "filesystem"; description = "filesystem functions"; } - { name = "sources"; description = "source filtering functions"; } - { name = "cli"; description = "command-line serialization functions"; } - ]; - - locationsXml = import ./lib-function-locations.nix { inherit pkgs nixpkgs libsets; }; - functionDocs = import ./lib-function-docs.nix { inherit locationsXml pkgs libsets; }; - version = pkgs.lib.version; - - epub-xsl = pkgs.writeText "epub.xsl" '' - <?xml version='1.0'?> - <xsl:stylesheet - xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - version="1.0"> - <xsl:import href="${pkgs.docbook_xsl_ns}/xml/xsl/docbook/epub/docbook.xsl" /> - <xsl:import href="${./parameters.xml}"/> - </xsl:stylesheet> - ''; - - xhtml-xsl = pkgs.writeText "xhtml.xsl" '' - <?xml version='1.0'?> - <xsl:stylesheet - xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - version="1.0"> - <xsl:import href="${pkgs.docbook_xsl_ns}/xml/xsl/docbook/xhtml/docbook.xsl" /> - <xsl:import href="${./parameters.xml}"/> - </xsl:stylesheet> - ''; - - # NB: This file describes the Nixpkgs manual, which happens to use module - # docs infra originally developed for NixOS. - optionsDoc = pkgs.nixosOptionsDoc { - inherit (pkgs.lib.evalModules { - modules = [ ../../pkgs/top-level/config.nix ]; - class = "nixpkgsConfig"; - }) options; - documentType = "none"; - transformOptions = opt: - opt // { - declarations = - map - (decl: - if hasPrefix (toString ../..) (toString decl) - then - let subpath = removePrefix "/" (removePrefix (toString ../..) (toString decl)); - in { url = "https://github.com/NixOS/nixpkgs/blob/master/${subpath}"; name = subpath; } - else decl) - opt.declarations; - }; - }; - -in pkgs.runCommand "doc-support" {} -'' - mkdir result - ( - cd result - ln -s ${locationsXml} ./function-locations.xml - ln -s ${functionDocs} ./function-docs - ln -s ${optionsDoc.optionsDocBook} ./config-options.docbook.xml - - ln -s ${pkgs.docbook5}/xml/rng/docbook/docbook.rng ./docbook.rng - ln -s ${pkgs.docbook_xsl_ns}/xml/xsl ./xsl - ln -s ${epub-xsl} ./epub.xsl - ln -s ${xhtml-xsl} ./xhtml.xsl - - ln -s ${./xmlformat.conf} ./xmlformat.conf - ln -s ${pkgs.documentation-highlighter} ./highlightjs - - echo -n "${version}" > ./version - ) - mv result $out -'' diff --git a/doc/doc-support/lib-function-docs.nix b/doc/doc-support/lib-function-docs.nix index cf218fa704017..018b0bd5e9453 100644 --- a/doc/doc-support/lib-function-docs.nix +++ b/doc/doc-support/lib-function-docs.nix @@ -1,8 +1,13 @@ # Generates the documentation for library functions via nixdoc. -{ pkgs, locationsXml, libsets }: +{ pkgs, nixpkgs, libsets }: -with pkgs; stdenv.mkDerivation { +with pkgs; + +let + locationsJSON = import ./lib-function-locations.nix { inherit pkgs nixpkgs libsets; }; +in +stdenv.mkDerivation { name = "nixpkgs-lib-docs"; src = ../../lib; @@ -11,26 +16,23 @@ with pkgs; stdenv.mkDerivation { function docgen { # TODO: wrap lib.$1 in <literal>, make nixdoc not escape it if [[ -e "../lib/$1.nix" ]]; then - nixdoc -c "$1" -d "lib.$1: $2" -f "$1.nix" > "$out/$1.xml" + nixdoc -c "$1" -d "lib.$1: $2" -l ${locationsJSON} -f "$1.nix" > "$out/$1.md" else - nixdoc -c "$1" -d "lib.$1: $2" -f "$1/default.nix" > "$out/$1.xml" + nixdoc -c "$1" -d "lib.$1: $2" -l ${locationsJSON} -f "$1/default.nix" > "$out/$1.md" fi - echo "<xi:include href='$1.xml' />" >> "$out/index.xml" + echo "$out/$1.md" >> "$out/index.md" } mkdir -p "$out" - cat > "$out/index.xml" << 'EOF' - <?xml version="1.0" encoding="utf-8"?> - <root xmlns:xi="http://www.w3.org/2001/XInclude"> + cat > "$out/index.md" << 'EOF' + ```{=include=} sections EOF ${lib.concatMapStrings ({ name, description }: '' docgen ${name} ${lib.escapeShellArg description} '') libsets} - echo "</root>" >> "$out/index.xml" - - ln -s ${locationsXml} $out/locations.xml + echo '```' >> "$out/index.md" ''; } diff --git a/doc/doc-support/lib-function-locations.nix b/doc/doc-support/lib-function-locations.nix index 1ee59648330aa..e6794617fdd89 100644 --- a/doc/doc-support/lib-function-locations.nix +++ b/doc/doc-support/lib-function-locations.nix @@ -58,28 +58,18 @@ let [ "-prime" ]; urlPrefix = "https://github.com/NixOS/nixpkgs/blob/${revision}"; - xmlstrings = (nixpkgsLib.strings.concatMapStrings - ({ name, value }: - '' - <section><title>${name}</title> - <para xml:id="${sanitizeId name}"> - Located at - <link - xlink:href="${urlPrefix}/${value.file}#L${builtins.toString value.line}">${value.file}:${builtins.toString value.line}</link> - in <literal><nixpkgs></literal>. - </para> - </section> - '') - relativeLocs); + jsonLocs = builtins.listToAttrs + (builtins.map + ({ name, value }: { + name = sanitizeId name; + value = + let + text = "${value.file}:${builtins.toString value.line}"; + target = "${urlPrefix}/${value.file}#L${builtins.toString value.line}"; + in + "[${text}](${target}) in `<nixpkgs>`"; + }) + relativeLocs); -in pkgs.writeText - "locations.xml" - '' - <section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - version="5"> - <title>All the locations for every lib function</title> - <para>This file is only for inclusion by other files.</para> - ${xmlstrings} - </section> - '' +in +pkgs.writeText "locations.json" (builtins.toJSON jsonLocs) diff --git a/doc/doc-support/parameters.xml b/doc/doc-support/parameters.xml deleted file mode 100644 index 5b39d2f7f1a58..0000000000000 --- a/doc/doc-support/parameters.xml +++ /dev/null @@ -1,19 +0,0 @@ -<?xml version='1.0'?> -<xsl:stylesheet - xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - version="1.0"> - <xsl:param name="chapter.autolabel" select="0" /> - <xsl:param name="part.autolabel" select="0" /> - <xsl:param name="preface.autolabel" select="0" /> - <xsl:param name="reference.autolabel" select="0" /> - <xsl:param name="section.autolabel" select="0" /> - <xsl:param name="html.stylesheet" select="'style.css overrides.css highlightjs/mono-blue.css'" /> - <xsl:param name="html.script" select="'./highlightjs/highlight.pack.js ./highlightjs/loader.js'" /> - <xsl:param name="xref.with.number.and.title" select="0" /> - <xsl:param name="use.id.as.filename" select="1" /> - <xsl:param name="generate.section.toc.level" select="1" /> - <xsl:param name="toc.section.depth" select="0" /> - <xsl:param name="admon.style" select="''" /> - <xsl:param name="callout.graphics.extension" select="'.svg'" /> - <xsl:param name="generate.consistent.ids" select="1" /> -</xsl:stylesheet> diff --git a/doc/doc-support/xmlformat.conf b/doc/doc-support/xmlformat.conf deleted file mode 100644 index c3f39c7fd81b8..0000000000000 --- a/doc/doc-support/xmlformat.conf +++ /dev/null @@ -1,72 +0,0 @@ -# -# DocBook Configuration file for "xmlformat" -# see http://www.kitebird.com/software/xmlformat/ -# 10 Sept. 2004 -# - -# Only block elements -ackno address appendix article biblioentry bibliography bibliomixed \ -biblioset blockquote book bridgehead callout calloutlist caption caution \ -chapter chapterinfo classsynopsis cmdsynopsis colophon constraintdef \ -constructorsynopsis dedication destructorsynopsis entry epigraph equation example \ -figure formalpara funcsynopsis glossary glossdef glossdiv glossentry glosslist \ -glosssee glossseealso graphic graphicco highlights imageobjectco important \ -index indexdiv indexentry indexinfo info informalequation informalexample \ -informalfigure informaltable legalnotice literallayout lot lotentry mediaobject \ -mediaobjectco msgmain msgset note orderedlist para part preface primaryie \ -procedure qandadiv qandaentry qandaset refentry refentrytitle reference \ -refnamediv refsect1 refsect2 refsect3 refsection revhistory screenshot sect1 \ -sect2 sect3 sect4 sect5 section seglistitem set setindex sidebar simpara \ -simplesect step substeps synopfragment synopsis table term title \ -toc variablelist varlistentry warning itemizedlist listitem \ -footnote colspec partintro row simplelist subtitle tbody tgroup thead tip - format block - normalize no - - -#appendix bibliography chapter glossary preface reference -# element-break 3 - -sect1 section - element-break 2 - - -# -para abstract - format block - entry-break 1 - exit-break 1 - normalize yes - -title - format block - normalize = yes - entry-break = 0 - exit-break = 0 - -# Inline elements -abbrev accel acronym action application citation citebiblioid citerefentry citetitle \ -classname co code command computeroutput constant country database date email emphasis \ -envar errorcode errorname errortext errortype exceptionname fax filename \ -firstname firstterm footnoteref foreignphrase funcdef funcparams function \ -glossterm group guibutton guiicon guilabel guimenu guimenuitem guisubmenu \ -hardware holder honorific indexterm inlineequation inlinegraphic inlinemediaobject \ -interface interfacename \ -keycap keycode keycombo keysym lineage link literal manvolnum markup medialabel \ -menuchoice methodname methodparam modifier mousebutton olink ooclass ooexception \ -oointerface option optional otheraddr othername package paramdef parameter personname \ -phrase pob postcode productname prompt property quote refpurpose replaceable \ -returnvalue revnumber sgmltag state street structfield structname subscript \ -superscript surname symbol systemitem token trademark type ulink userinput \ -uri varargs varname void wordasword xref year mathphrase member tag - format inline - -programlisting screen - format verbatim - entry-break = 0 - exit-break = 0 - -# This is needed so that the spacing inside those tags is kept. -term cmdsynopsis arg - normalize yes - format block diff --git a/doc/functions.md b/doc/functions.md new file mode 100644 index 0000000000000..09033c9e3c199 --- /dev/null +++ b/doc/functions.md @@ -0,0 +1,11 @@ +# Functions reference {#chap-functions} + +The nixpkgs repository has several utility functions to manipulate Nix expressions. + +```{=include=} sections +functions/library.md +functions/generators.section.md +functions/debug.section.md +functions/prefer-remote-fetch.section.md +functions/nix-gitignore.section.md +``` diff --git a/doc/functions.xml b/doc/functions.xml deleted file mode 100644 index 8ef530d307cdc..0000000000000 --- a/doc/functions.xml +++ /dev/null @@ -1,14 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - xml:id="chap-functions"> - <title>Functions reference</title> - <para> - The nixpkgs repository has several utility functions to manipulate Nix expressions. - </para> - <xi:include href="functions/library.xml" /> - <xi:include href="functions/generators.section.xml" /> - <xi:include href="functions/debug.section.xml" /> - <xi:include href="functions/prefer-remote-fetch.section.xml" /> - <xi:include href="functions/nix-gitignore.section.xml" /> -</chapter> diff --git a/doc/functions/library.md.in b/doc/functions/library.md.in new file mode 100644 index 0000000000000..e17de86feb8ae --- /dev/null +++ b/doc/functions/library.md.in @@ -0,0 +1,5 @@ +# Nixpkgs Library Functions {#sec-functions-library} + +Nixpkgs provides a standard library at `pkgs.lib`, or through `import <nixpkgs/lib>`. + +<!-- nixdoc-generated documentation must be appended here during build! --> diff --git a/doc/functions/library.xml b/doc/functions/library.xml deleted file mode 100644 index 788ea0b94f1fe..0000000000000 --- a/doc/functions/library.xml +++ /dev/null @@ -1,14 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - xml:id="sec-functions-library"> - <title>Nixpkgs Library Functions</title> - - <para> - Nixpkgs provides a standard library at <varname>pkgs.lib</varname>, or through <code>import <nixpkgs/lib></code>. - </para> - - <!-- The index must have a root element to declare namespaces, but we - don't want to include it, so we select all of its children. --> - <xi:include href="./library/generated/index.xml" xpointer="xpointer(/root/*)" /> -</section> diff --git a/doc/hooks/index.md b/doc/hooks/index.md new file mode 100644 index 0000000000000..c1e86a3033073 --- /dev/null +++ b/doc/hooks/index.md @@ -0,0 +1,33 @@ +# Hooks reference {#chap-hooks} + +Nixpkgs has several hook packages that augment the stdenv phases. + +The stdenv built-in hooks are documented in [](#ssec-setup-hooks). + +```{=include=} sections +autoconf.section.md +automake.section.md +autopatchelf.section.md +breakpoint.section.md +cmake.section.md +gdk-pixbuf.section.md +ghc.section.md +gnome.section.md +installShellFiles.section.md +libiconv.section.md +libxml2.section.md +meson.section.md +ninja.section.md +patch-rc-path-hooks.section.md +perl.section.md +pkg-config.section.md +postgresql-test-hook.section.md +python.section.md +qt-4.section.md +scons.section.md +tetex-tex-live.section.md +unzip.section.md +validatePkgConfig.section.md +waf.section.md +xcbuild.section.md +``` diff --git a/doc/hooks/index.xml b/doc/hooks/index.xml deleted file mode 100644 index 0917fac6c0ac0..0000000000000 --- a/doc/hooks/index.xml +++ /dev/null @@ -1,37 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - xml:id="chap-hooks"> - <title>Hooks reference</title> - <para> - Nixpkgs has several hook packages that augment the stdenv phases. - </para> - <para> - The stdenv built-in hooks are documented in <xref linkend="ssec-setup-hooks"/>. - </para> - <xi:include href="./autoconf.section.xml" /> - <xi:include href="./automake.section.xml" /> - <xi:include href="./autopatchelf.section.xml" /> - <xi:include href="./breakpoint.section.xml" /> - <xi:include href="./cmake.section.xml" /> - <xi:include href="./gdk-pixbuf.section.xml" /> - <xi:include href="./ghc.section.xml" /> - <xi:include href="./gnome.section.xml" /> - <xi:include href="./installShellFiles.section.xml" /> - <xi:include href="./libiconv.section.xml" /> - <xi:include href="./libxml2.section.xml" /> - <xi:include href="./meson.section.xml" /> - <xi:include href="./ninja.section.xml" /> - <xi:include href="./patch-rc-path-hooks.section.xml" /> - <xi:include href="./perl.section.xml" /> - <xi:include href="./pkg-config.section.xml" /> - <xi:include href="./postgresql-test-hook.section.xml" /> - <xi:include href="./python.section.xml" /> - <xi:include href="./qt-4.section.xml" /> - <xi:include href="./scons.section.xml" /> - <xi:include href="./tetex-tex-live.section.xml" /> - <xi:include href="./unzip.section.xml" /> - <xi:include href="./validatePkgConfig.section.xml" /> - <xi:include href="./waf.section.xml" /> - <xi:include href="./xcbuild.section.xml" /> -</chapter> diff --git a/doc/languages-frameworks/haskell.section.md b/doc/languages-frameworks/haskell.section.md index e3b4327bdb299..a4afbf0e456a9 100644 --- a/doc/languages-frameworks/haskell.section.md +++ b/doc/languages-frameworks/haskell.section.md @@ -1066,6 +1066,18 @@ benchmark component. `dontCoverage drv` : Sets the `doCoverage` argument to `false` for `drv`. +`enableExecutableProfiling drv` +: Sets the `enableExecutableProfiling` argument to `true` for `drv`. + +`disableExecutableProfiling drv` +: Sets the `enableExecutableProfiling` argument to `false` for `drv`. + +`enableLibraryProfiling drv` +: Sets the `enableLibraryProfiling` argument to `true` for `drv`. + +`disableLibraryProfiling drv` +: Sets the `enableLibraryProfiling` argument to `false` for `drv`. + #### Library functions in the Haskell package sets {#haskell-package-set-lib-functions} Some library functions depend on packages from the Haskell package sets. Thus they are @@ -1140,6 +1152,124 @@ covered in the old [haskell4nix docs](https://haskell4nix.readthedocs.io/). If you feel any important topic is not documented at all, feel free to comment on the issue linked above. +### How to enable or disable profiling builds globally? {#haskell-faq-override-profiling} + +By default, Nixpkgs builds a profiling version of each Haskell library. The +exception to this rule are some platforms where it is disabled due to concerns +over output size. You may want to… + +* …enable profiling globally so that you can build a project you are working on + with profiling ability giving you insight in the time spent across your code + and code you depend on using [GHC's profiling feature][profiling]. + +* …disable profiling (globally) to reduce the time spent building the profiling + versions of libraries which a significant amount of build time is spent on + (although they are not as expensive as the “normal” build of a Haskell library). + +::: {.note} +The method described below affects the build of all libraries in the +respective Haskell package set as well as GHC. If your choices differ from +Nixpkgs' default for your (host) platform, you will lose the ability to +substitute from the official binary cache. + +If you are concerned about build times and thus want to disable profiling, it +probably makes sense to use `haskell.lib.compose.disableLibraryProfiling` (see +[](#haskell-trivial-helpers)) on the packages you are building locally while +continuing to substitute their dependencies and GHC. +::: + +Since we need to change the profiling settings for the desired Haskell package +set _and_ GHC (as the core libraries like `base`, `filepath` etc. are bundled +with GHC), it is recommended to use overlays for Nixpkgs to change them. +Since the interrelated parts, i.e. the package set and GHC, are connected +via the Nixpkgs fixpoint, we need to modify them both in a way that preserves +their connection (or else we'd have to wire it up again manually). This is +achieved by changing GHC and the package set in seperate overlays to prevent +the package set from pulling in GHC from `prev`. + +The result is two overlays like the ones shown below. Adjustable parts are +annotated with comments, as are any optional or alternative ways to achieve +the desired profiling settings without causing too many rebuilds. + +<!-- TODO(@sternenseemann): buildHaskellPackages != haskellPackages with this overlay, +affected by https://github.com/NixOS/nixpkgs/issues/235960 which needs to be fixed +properly still. +--> + +```nix +let + # Name of the compiler and package set you want to change. If you are using + # the default package set `haskellPackages`, you need to look up what version + # of GHC it currently uses (note that this is subject to change). + ghcName = "ghc92"; + # Desired new setting + enableProfiling = true; +in + +[ + # The first overlay modifies the GHC derivation so that it does or does not + # build profiling versions of the core libraries bundled with it. It is + # recommended to only use such an overlay if you are enabling profiling on a + # platform that doesn't by default, because compiling GHC from scratch is + # quite expensive. + (final: prev: + let + inherit (final) lib; + in + + { + haskell = lib.recursiveUpdate prev.haskell { + compiler.${ghcName} = prev.haskell.compiler.${ghcName}.override { + # Unfortunately, the GHC setting is named differently for historical reasons + enableProfiledLibs = enableProfiling; + }; + }; + }) + + (final: prev: + let + inherit (final) lib; + haskellLib = final.haskell.lib.compose; + in + + { + haskell = lib.recursiveUpdate prev.haskell { + packages.${ghcName} = prev.haskell.packages.${ghcName}.override { + overrides = hfinal: hprev: { + mkDerivation = args: hprev.mkDerivation (args // { + # Since we are forcing our ideas upon mkDerivation, this change will + # affect every package in the package set. + enableLibraryProfiling = enableProfiling; + + # To actually use profiling on an executable, executable profiling + # needs to be enabled for the executable you want to profile. You + # can either do this globally or… + enableExecutableProfiling = enableProfiling; + }); + + # …only for the package that contains an executable you want to profile. + # That saves on unnecessary rebuilds for packages that you only depend + # on for their library, but also contain executables (e.g. pandoc). + my-executable = haskellLib.enableExecutableProfiling hprev.my-executable; + + # If you are disabling profiling to save on build time, but want to + # retain the ability to substitute from the binary cache. Drop the + # override for mkDerivation above and instead have an override like + # this for the specific packages you are building locally and want + # to make cheaper to build. + my-library = haskellLib.disableLibraryProfiling hprev.my-library; + }; + }; + }; + }) +] +``` + +<!-- TODO(@sternenseemann): write overriding mkDerivation, overriding GHC, and +overriding the entire package set sections and link to them from here where +relevant. +--> + [Stackage]: https://www.stackage.org [cabal-project-files]: https://cabal.readthedocs.io/en/latest/cabal-project.html [cabal2nix]: https://github.com/nixos/cabal2nix diff --git a/doc/languages-frameworks/index.md b/doc/languages-frameworks/index.md new file mode 100644 index 0000000000000..cdbf08f1791bf --- /dev/null +++ b/doc/languages-frameworks/index.md @@ -0,0 +1,45 @@ +# Languages and frameworks {#chap-language-support} + +The [standard build environment](#chap-stdenv) makes it easy to build typical Autotools-based packages with very little code. Any other kind of package can be accommodated by overriding the appropriate phases of `stdenv`. However, there are specialised functions in Nixpkgs to easily build packages for other programming languages, such as Perl or Haskell. These are described in this chapter. + +```{=include=} sections +agda.section.md +android.section.md +beam.section.md +bower.section.md +chicken.section.md +coq.section.md +crystal.section.md +cuda.section.md +cuelang.section.md +dart.section.md +dhall.section.md +dotnet.section.md +emscripten.section.md +gnome.section.md +go.section.md +haskell.section.md +hy.section.md +idris.section.md +ios.section.md +java.section.md +javascript.section.md +lisp.section.md +lua.section.md +maven.section.md +nim.section.md +ocaml.section.md +octave.section.md +perl.section.md +php.section.md +pkg-config.section.md +python.section.md +qt.section.md +r.section.md +ruby.section.md +rust.section.md +swift.section.md +texlive.section.md +titanium.section.md +vim.section.md +``` diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml deleted file mode 100644 index 94c4e303027f7..0000000000000 --- a/doc/languages-frameworks/index.xml +++ /dev/null @@ -1,47 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xi="http://www.w3.org/2001/XInclude" - xml:id="chap-language-support"> - <title>Languages and frameworks</title> - <para> - The <link linkend="chap-stdenv">standard build environment</link> makes it easy to build typical Autotools-based packages with very little code. Any other kind of package can be accommodated by overriding the appropriate phases of <literal>stdenv</literal>. However, there are specialised functions in Nixpkgs to easily build packages for other programming languages, such as Perl or Haskell. These are described in this chapter. - </para> - <xi:include href="agda.section.xml" /> - <xi:include href="android.section.xml" /> - <xi:include href="beam.section.xml" /> - <xi:include href="bower.section.xml" /> - <xi:include href="chicken.section.xml" /> - <xi:include href="coq.section.xml" /> - <xi:include href="crystal.section.xml" /> - <xi:include href="cuda.section.xml" /> - <xi:include href="cuelang.section.xml" /> - <xi:include href="dart.section.xml" /> - <xi:include href="dhall.section.xml" /> - <xi:include href="dotnet.section.xml" /> - <xi:include href="emscripten.section.xml" /> - <xi:include href="gnome.section.xml" /> - <xi:include href="go.section.xml" /> - <xi:include href="haskell.section.xml" /> - <xi:include href="hy.section.xml" /> - <xi:include href="idris.section.xml" /> - <xi:include href="ios.section.xml" /> - <xi:include href="java.section.xml" /> - <xi:include href="javascript.section.xml" /> - <xi:include href="lisp.section.xml" /> - <xi:include href="lua.section.xml" /> - <xi:include href="maven.section.xml" /> - <xi:include href="nim.section.xml" /> - <xi:include href="ocaml.section.xml" /> - <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" /> - <xi:include href="ruby.section.xml" /> - <xi:include href="rust.section.xml" /> - <xi:include href="swift.section.xml" /> - <xi:include href="texlive.section.xml" /> - <xi:include href="titanium.section.xml" /> - <xi:include href="vim.section.xml" /> -</chapter> diff --git a/doc/languages-frameworks/javascript.section.md b/doc/languages-frameworks/javascript.section.md index 7fd84ed0e65e5..0a2099b0a6b12 100644 --- a/doc/languages-frameworks/javascript.section.md +++ b/doc/languages-frameworks/javascript.section.md @@ -196,12 +196,14 @@ buildNpmPackage rec { * `npmDepsHash`: The output hash of the dependencies for this project. Can be calculated in advance with [`prefetch-npm-deps`](#javascript-buildNpmPackage-prefetch-npm-deps). * `makeCacheWritable`: Whether to make the cache writable prior to installing dependencies. Don't set this unless npm tries to write to the cache directory, as it can slow down the build. * `npmBuildScript`: The script to run to build the project. Defaults to `"build"`. +* `npmWorkspace`: The workspace directory within the project to build and install. * `dontNpmBuild`: Option to disable running the build script. Set to `true` if the package does not have a build script. Defaults to `false`. Alternatively, setting `buildPhase` explicitly also disables this. * `dontNpmInstall`: Option to disable running `npm install`. Defaults to `false`. Alternatively, setting `installPhase` explicitly also disables this. * `npmFlags`: Flags to pass to all npm commands. -* `npmInstallFlags`: Flags to pass to `npm ci` and `npm prune`. +* `npmInstallFlags`: Flags to pass to `npm ci`. * `npmBuildFlags`: Flags to pass to `npm run ${npmBuildScript}`. * `npmPackFlags`: Flags to pass to `npm pack`. +* `npmPruneFlags`: Flags to pass to `npm prune`. Defaults to the value of `npmInstallFlags`. #### prefetch-npm-deps {#javascript-buildNpmPackage-prefetch-npm-deps} diff --git a/doc/languages-frameworks/maven.section.md b/doc/languages-frameworks/maven.section.md index cc5b4e3ed799b..3b5e2e14ee644 100644 --- a/doc/languages-frameworks/maven.section.md +++ b/doc/languages-frameworks/maven.section.md @@ -165,6 +165,39 @@ The build will fail, and tell you the expected `outputHash` to place. When you'v If your package uses _SNAPSHOT_ dependencies or _version ranges_; there is a strong likelihood that over-time your output hash will change since the resolved dependencies may change. Hence this method is less recommended then using `buildMaven`. +#### Stable Maven plugins {#stable-maven-plugins} + +Maven defines default versions for its core plugins, e.g. `maven-compiler-plugin`. +If your project does not override these versions, an upgrade of Maven will change the version of the used plugins. +This changes the output of the first invocation and the plugins required by the second invocation. +However, since a hash is given for the output of the first invocation, the second invocation will simply fail +because the requested plugins are missing. +This will prevent automatic upgrades of Maven: the manual fix for this is to change the hash of the first invocation. + +To make sure that your package does not add manual effort when upgrading Maven, explicitly define versions for all +plugins. You can check if this is the case by adding the following plugin to your (parent) POM: + +```xml +<plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-enforcer-plugin</artifactId> + <version>3.3.0</version> + <executions> + <execution> + <id>enforce-plugin-versions</id> + <goals> + <goal>enforce</goal> + </goals> + <configuration> + <rules> + <requirePluginVersions /> + </rules> + </configuration> + </execution> + </executions> +</plugin> +``` + ## Building a JAR {#building-a-jar} Regardless of which strategy is chosen above, the step to build the derivation is the same. diff --git a/doc/languages-frameworks/python.section.md b/doc/languages-frameworks/python.section.md index d9a13aef6e603..23c8526787b73 100644 --- a/doc/languages-frameworks/python.section.md +++ b/doc/languages-frameworks/python.section.md @@ -512,9 +512,10 @@ when building the bindings and are therefore added as `buildInputs`. ```nix { lib -, pkgs , buildPythonPackage , fetchPypi +, libxml2 +, libxslt }: buildPythonPackage rec { @@ -528,8 +529,8 @@ buildPythonPackage rec { }; buildInputs = [ - pkgs.libxml2 - pkgs.libxslt + libxml2 + libxslt ]; meta = with lib; { @@ -554,11 +555,13 @@ therefore we have to set `LDFLAGS` and `CFLAGS`. ```nix { lib -, pkgs , buildPythonPackage , fetchPypi # dependencies +, fftw +, fftwFloat +, fftwLongDouble , numpy , scipy }: @@ -574,9 +577,9 @@ buildPythonPackage rec { }; buildInputs = [ - pkgs.fftw - pkgs.fftwFloat - pkgs.fftwLongDouble + fftw + fftwFloat + fftwLongDouble ]; propagatedBuildInputs = [ @@ -585,8 +588,8 @@ buildPythonPackage rec { ]; preConfigure = '' - export LDFLAGS="-L${pkgs.fftw.dev}/lib -L${pkgs.fftwFloat.out}/lib -L${pkgs.fftwLongDouble.out}/lib" - export CFLAGS="-I${pkgs.fftw.dev}/include -I${pkgs.fftwFloat.dev}/include -I${pkgs.fftwLongDouble.dev}/include" + export LDFLAGS="-L${fftw.dev}/lib -L${fftwFloat.out}/lib -L${fftwLongDouble.out}/lib" + export CFLAGS="-I${fftw.dev}/include -I${fftwFloat.dev}/include -I${fftwLongDouble.dev}/include" ''; # Tests cannot import pyfftw. pyfftw works fine though. diff --git a/doc/lib.md b/doc/lib.md new file mode 100644 index 0000000000000..2c3105333ed09 --- /dev/null +++ b/doc/lib.md @@ -0,0 +1,6 @@ +# Nixpkgs `lib` {#id-1.4} + +```{=include=} chapters +functions.md +module-system/module-system.chapter.md +``` diff --git a/doc/manual.md.in b/doc/manual.md.in new file mode 100644 index 0000000000000..a4a73a913097a --- /dev/null +++ b/doc/manual.md.in @@ -0,0 +1,14 @@ +# Nixpkgs Manual {#nixpkgs-manual} +## Version @MANUAL_VERSION@ + +```{=include=} chapters +preface.chapter.md +``` + +```{=include=} parts +using-nixpkgs.md +lib.md +stdenv.md +builders.md +contributing.md +``` diff --git a/doc/manual.xml b/doc/manual.xml deleted file mode 100644 index de3d40f553c03..0000000000000 --- a/doc/manual.xml +++ /dev/null @@ -1,49 +0,0 @@ -<book xmlns="http://docbook.org/ns/docbook" - xmlns:xi="http://www.w3.org/2001/XInclude" - xml:id="nixpkgs-manual"> - <info> - <title>Nixpkgs Manual</title> - <subtitle>Version <xi:include href=".version" parse="text" /> - </subtitle> - </info> - <xi:include href="preface.chapter.xml" /> - <part xml:id="part-using"> - <title>Using Nixpkgs</title> - <xi:include href="using/configuration.chapter.xml" /> - <xi:include href="using/overlays.chapter.xml" /> - <xi:include href="using/overrides.chapter.xml" /> - </part> - <part> - <title>Nixpkgs <code>lib</code></title> - <xi:include href="functions.xml" /> - <xi:include href="module-system/module-system.chapter.xml" /> - </part> - <part xml:id="part-stdenv"> - <title>Standard environment</title> - <xi:include href="stdenv/stdenv.chapter.xml" /> - <xi:include href="stdenv/meta.chapter.xml" /> - <xi:include href="stdenv/multiple-output.chapter.xml" /> - <xi:include href="stdenv/cross-compilation.chapter.xml" /> - <xi:include href="stdenv/platform-notes.chapter.xml" /> - </part> - <part xml:id="part-builders"> - <title>Builders</title> - <xi:include href="builders/fetchers.chapter.xml" /> - <xi:include href="builders/trivial-builders.chapter.xml" /> - <xi:include href="builders/testers.chapter.xml" /> - <xi:include href="builders/special.xml" /> - <xi:include href="builders/images.xml" /> - <xi:include href="hooks/index.xml" /> - <xi:include href="languages-frameworks/index.xml" /> - <xi:include href="builders/packages/index.xml" /> - </part> - <part xml:id="part-contributing"> - <title>Contributing to Nixpkgs</title> - <xi:include href="contributing/quick-start.chapter.xml" /> - <xi:include href="contributing/coding-conventions.chapter.xml" /> - <xi:include href="contributing/submitting-changes.chapter.xml" /> - <xi:include href="contributing/vulnerability-roundup.chapter.xml" /> - <xi:include href="contributing/reviewing-contributions.chapter.xml" /> - <xi:include href="contributing/contributing-to-documentation.chapter.xml" /> - </part> -</book> diff --git a/doc/shell.nix b/doc/shell.nix deleted file mode 100644 index 5fa2b4424899a..0000000000000 --- a/doc/shell.nix +++ /dev/null @@ -1,3 +0,0 @@ -{ pkgs ? import ../. { } }: -(import ./default.nix { }).overrideAttrs -(x: { buildInputs = (x.buildInputs or [ ]) ++ [ pkgs.xmloscopy pkgs.ruby ]; }) diff --git a/doc/stdenv.md b/doc/stdenv.md new file mode 100644 index 0000000000000..1ef81f84b5141 --- /dev/null +++ b/doc/stdenv.md @@ -0,0 +1,9 @@ +# Standard environment {#part-stdenv} + +```{=include=} chapters +stdenv/stdenv.chapter.md +stdenv/meta.chapter.md +stdenv/multiple-output.chapter.md +stdenv/cross-compilation.chapter.md +stdenv/platform-notes.chapter.md +``` diff --git a/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md index 71d28282e9b25..a0f81b97f6bcb 100644 --- a/doc/stdenv/stdenv.chapter.md +++ b/doc/stdenv/stdenv.chapter.md @@ -464,10 +464,8 @@ The commit object contains the following values: If the returned array contains exactly one object (e.g. `[{}]`), all values are optional and will be determined automatically. -```{=docbook} -<example> -<title>Standard output of an update script using commit feature</title> -``` +::: {.example #var-passthru-updateScript-example-commit} +# Standard output of an update script using commit feature ```json [ @@ -481,10 +479,7 @@ If the returned array contains exactly one object (e.g. `[{}]`), all values are } ] ``` - -```{=docbook} -</example> -``` +::: ### Recursive attributes in `mkDerivation` {#mkderivation-recursive-attributes} diff --git a/doc/using-nixpkgs.md b/doc/using-nixpkgs.md new file mode 100644 index 0000000000000..bb222ae384fa6 --- /dev/null +++ b/doc/using-nixpkgs.md @@ -0,0 +1,7 @@ +# Using Nixpkgs {#part-using} + +```{=include=} chapters +using/configuration.chapter.md +using/overlays.chapter.md +using/overrides.chapter.md +``` diff --git a/doc/using/configuration.chapter.md b/doc/using/configuration.chapter.md index e657cb21c2959..8d246b117b05f 100644 --- a/doc/using/configuration.chapter.md +++ b/doc/using/configuration.chapter.md @@ -185,8 +185,10 @@ You can define a function called `packageOverrides` in your local `~/.config/nix The following attributes can be passed in [`config`](#chap-packageconfig). -```{=docbook} -<include xmlns="http://www.w3.org/2001/XInclude" href="../doc-support/result/config-options.docbook.xml"/> +```{=include=} options +id-prefix: opt- +list-id: configuration-variable-list +source: ../config-options.json ``` diff --git a/doc/using/overrides.chapter.md b/doc/using/overrides.chapter.md index 198b4504197db..a1ef9afb0b69d 100644 --- a/doc/using/overrides.chapter.md +++ b/doc/using/overrides.chapter.md @@ -16,6 +16,12 @@ Example usages: pkgs.foo.override { arg1 = val1; arg2 = val2; ... } ``` +It's also possible to access the previous arguments. + +```nix +pkgs.foo.override (previous: { arg1 = previous.arg1; ... }) +``` + <!-- TODO: move below programlisting to a new section about extending and overlays and reference it --> ```nix @@ -36,15 +42,15 @@ In the first example, `pkgs.foo` is the result of a function call with some defa The function `overrideAttrs` allows overriding the attribute set passed to a `stdenv.mkDerivation` call, producing a new derivation based on the original one. This function is available on all derivations produced by the `stdenv.mkDerivation` function, which is most packages in the nixpkgs expression `pkgs`. -Example usage: +Example usages: ```nix -helloWithDebug = pkgs.hello.overrideAttrs (finalAttrs: previousAttrs: { - separateDebugInfo = true; +helloBar = pkgs.hello.overrideAttrs (finalAttrs: previousAttrs: { + pname = previousAttrs.pname + "-bar"; }); ``` -In the above example, the `separateDebugInfo` attribute is overridden to be true, thus building debug info for `helloWithDebug`, while all other attributes will be retained from the original `hello` package. +In the above example, "-bar" is appended to the pname attribute, while all other attributes will be retained from the original `hello` package. The argument `previousAttrs` is conventionally used to refer to the attr set originally passed to `stdenv.mkDerivation`. @@ -52,6 +58,16 @@ The argument `finalAttrs` refers to the final attributes passed to `mkDerivation If only a one-argument function is written, the argument has the meaning of `previousAttrs`. +Function arguments can be omitted entirely if there is no need to access `previousAttrs` or `finalAttrs`. + +```nix +helloWithDebug = pkgs.hello.overrideAttrs { + separateDebugInfo = true; +}; +``` + +In the above example, the `separateDebugInfo` attribute is overridden to be true, thus building debug info for `helloWithDebug`. + ::: {.note} Note that `separateDebugInfo` is processed only by the `stdenv.mkDerivation` function, not the generated, raw Nix derivation. Thus, using `overrideDerivation` will not work in this case, as it overrides only the attributes of the final derivation. It is for this reason that `overrideAttrs` should be preferred in (almost) all cases to `overrideDerivation`, i.e. to allow using `stdenv.mkDerivation` to process input arguments, as well as the fact that it is easier to use (you can use the same attribute names you see in your Nix code, instead of the ones generated (e.g. `buildInputs` vs `nativeBuildInputs`), and it involves less typing). ::: |
