···

       
1
       
1
       
-
       
*.chapter.xml

     

       
2
       
2
       
-
       
*.section.xml

     

       
3
       
3
       
-
       
.version

     

       
4
       
4
       
-
       
functions/library/generated

     

       
5
       
5
       
-
       
functions/library/locations.xml

     

       
6
       
6
       
-
       
highlightjs

     

       
7
       
7
       
-
       
manual-full.xml

     

       
8
       
8
       
-
       
out

     

       
9
       
9
       
-
       
result

     

       
10
       
10
       
-
       
result-*

     

       
11
       
11
       
-
       
media

     

···

       
1
       
1
       
-
       
MD_TARGETS=$(addsuffix .xml, $(basename $(shell find . -type f -regex '.*\.md$$' -not -name README.md)))

     

       
2
       
2
       
-
       


     

       
3
       
3
       
-
       
PANDOC ?= pandoc

     

       
4
       
4
       
-
       


     

       
5
       
5
       
-
       
pandoc_media_dir = media

     

       
6
       
6
       
-
       
# NOTE: Keep in sync with conversion script (/maintainers/scripts/db-to-md.sh).

     

       
7
       
7
       
-
       
# TODO: Remove raw-attribute when we can get rid of DocBook altogether.

     

       
8
       
8
       
-
       
pandoc_commonmark_enabled_extensions = +attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute

     

       
9
       
9
       
-
       
# Not needed:

     

       
10
       
10
       
-
       
# - docbook-reader/citerefentry-to-rst-role.lua (only relevant for DocBook → MarkDown/rST/MyST)

     

       
11
       
11
       
-
       
pandoc_flags = --extract-media=$(pandoc_media_dir) \

     

       
12
       
12
       
-
       
	--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \

     

       
13
       
13
       
-
       
	--lua-filter=build-aux/pandoc-filters/myst-reader/roles.lua \

     

       
14
       
14
       
-
       
	--lua-filter=$(PANDOC_LINK_MANPAGES_FILTER) \

     

       
15
       
15
       
-
       
	--lua-filter=build-aux/pandoc-filters/docbook-writer/rst-roles.lua \

     

       
16
       
16
       
-
       
	--lua-filter=build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua \

     

       
17
       
17
       
-
       
	-f commonmark$(pandoc_commonmark_enabled_extensions)+smart

     

       
18
       
18
       
-
       


     

       
19
       
19
       
-
       
.PHONY: all

     

       
20
       
20
       
-
       
all: validate format out/html/index.html out/epub/manual.epub

     

       
21
       
21
       
-
       


     

       
22
       
22
       
-
       
.PHONY: render-md

     

       
23
       
23
       
-
       
render-md: ${MD_TARGETS}

     

       
24
       
24
       
-
       


     

       
25
       
25
       
-
       
.PHONY: debug

     

       
26
       
26
       
-
       
debug:

     

       
27
       
27
       
-
       
	nix-shell --run "xmloscopy --docbook5 ./manual.xml ./manual-full.xml"

     

       
28
       
28
       
-
       


     

       
29
       
29
       
-
       
.PHONY: format

     

       
30
       
30
       
-
       
format: doc-support/result

     

       
31
       
31
       
-
       
	find . -iname '*.xml' -type f | while read f; do \

     

       
32
       
32
       
-
       
		echo $$f ;\

     

       
33
       
33
       
-
       
		xmlformat --config-file "doc-support/result/xmlformat.conf" -i $$f ;\

     

       
34
       
34
       
-
       
	done

     

       
35
       
35
       
-
       


     

       
36
       
36
       
-
       
.PHONY: fix-misc-xml

     

       
37
       
37
       
-
       
fix-misc-xml:

     

       
38
       
38
       
-
       
	find . -iname '*.xml' -type f \

     

       
39
       
39
       
-
       
		-exec ../nixos/doc/varlistentry-fixer.rb {} ';'

     

       
40
       
40
       
-
       


     

       
41
       
41
       
-
       
.PHONY: clean

     

       
42
       
42
       
-
       
clean:

     

       
43
       
43
       
-
       
	rm -f ${MD_TARGETS} doc-support/result .version manual-full.xml functions/library/locations.xml functions/library/generated

     

       
44
       
44
       
-
       
	rm -rf ./out/ ./highlightjs ./media

     

       
45
       
45
       
-
       


     

       
46
       
46
       
-
       
.PHONY: validate

     

       
47
       
47
       
-
       
validate: manual-full.xml doc-support/result

     

       
48
       
48
       
-
       
	jing doc-support/result/docbook.rng manual-full.xml

     

       
49
       
49
       
-
       


     

       
50
       
50
       
-
       
out/html/index.html: doc-support/result manual-full.xml style.css highlightjs

     

       
51
       
51
       
-
       
	mkdir -p out/html

     

       
52
       
52
       
-
       
	xsltproc \

     

       
53
       
53
       
-
       
		--nonet --xinclude \

     

       
54
       
54
       
-
       
		--output $@ \

     

       
55
       
55
       
-
       
		doc-support/result/xhtml.xsl \

     

       
56
       
56
       
-
       
		./manual-full.xml

     

       
57
       
57
       
-
       


     

       
58
       
58
       
-
       
	mkdir -p out/html/highlightjs/

     

       
59
       
59
       
-
       
	cp -r highlightjs out/html/

     

       
60
       
60
       
-
       


     

       
61
       
61
       
-
       
	cp -r $(pandoc_media_dir) out/html/

     

       
62
       
62
       
-
       
	cp ./overrides.css out/html/

     

       
63
       
63
       
-
       
	cp ./style.css out/html/style.css

     

       
64
       
64
       
-
       


     

       
65
       
65
       
-
       
	mkdir -p out/html/images/callouts

     

       
66
       
66
       
-
       
	cp doc-support/result/xsl/docbook/images/callouts/*.svg out/html/images/callouts/

     

       
67
       
67
       
-
       
	chmod u+w -R out/html/

     

       
68
       
68
       
-
       


     

       
69
       
69
       
-
       
out/epub/manual.epub: epub.xml

     

       
70
       
70
       
-
       
	mkdir -p out/epub/scratch

     

       
71
       
71
       
-
       
	xsltproc --nonet \

     

       
72
       
72
       
-
       
		--output out/epub/scratch/ \

     

       
73
       
73
       
-
       
		doc-support/result/epub.xsl \

     

       
74
       
74
       
-
       
		./epub.xml

     

       
75
       
75
       
-
       


     

       
76
       
76
       
-
       
	echo "application/epub+zip" > mimetype

     

       
77
       
77
       
-
       
	zip -0Xq "out/epub/manual.epub" mimetype

     

       
78
       
78
       
-
       
	rm mimetype

     

       
79
       
79
       
-
       
	cd "out/epub/scratch/" && zip -Xr9D "../manual.epub" *

     

       
80
       
80
       
-
       
	rm -rf "out/epub/scratch/"

     

       
81
       
81
       
-
       


     

       
82
       
82
       
-
       
highlightjs: doc-support/result

     

       
83
       
83
       
-
       
	mkdir -p highlightjs

     

       
84
       
84
       
-
       
	cp -r doc-support/result/highlightjs/highlight.pack.js highlightjs/

     

       
85
       
85
       
-
       
	cp -r doc-support/result/highlightjs/LICENSE highlightjs/

     

       
86
       
86
       
-
       
	cp -r doc-support/result/highlightjs/mono-blue.css highlightjs/

     

       
87
       
87
       
-
       
	cp -r doc-support/result/highlightjs/loader.js highlightjs/

     

       
88
       
88
       
-
       


     

       
89
       
89
       
-
       


     

       
90
       
90
       
-
       
manual-full.xml: ${MD_TARGETS} .version functions/library/locations.xml functions/library/generated *.xml **/*.xml **/**/*.xml

     

       
91
       
91
       
-
       
	xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml

     

       
92
       
92
       
-
       


     

       
93
       
93
       
-
       
.version: doc-support/result

     

       
94
       
94
       
-
       
	ln -rfs ./doc-support/result/version .version

     

       
95
       
95
       
-
       


     

       
96
       
96
       
-
       
doc-support/result: doc-support/default.nix

     

       
97
       
97
       
-
       
	(cd doc-support; nix-build)

     

       
98
       
98
       
-
       


     

       
99
       
99
       
-
       
functions/library/locations.xml: doc-support/result

     

       
100
       
100
       
-
       
	ln -rfs ./doc-support/result/function-locations.xml functions/library/locations.xml

     

       
101
       
101
       
-
       


     

       
102
       
102
       
-
       
functions/library/generated: doc-support/result

     

       
103
       
103
       
-
       
	ln -rfs ./doc-support/result/function-docs functions/library/generated

     

       
104
       
104
       
-
       


     

       
105
       
105
       
-
       
%.section.xml: %.section.md

     

       
106
       
106
       
-
       
	$(PANDOC) $^ -t docbook \

     

       
107
       
107
       
-
       
		$(pandoc_flags) \

     

       
108
       
108
       
-
       
		-o $@

     

       
109
       
109
       
-
       


     

       
110
       
110
       
-
       
%.chapter.xml: %.chapter.md

     

       
111
       
111
       
-
       
	$(PANDOC) $^ -t docbook \

     

       
112
       
112
       
-
       
		--top-level-division=chapter \

     

       
113
       
113
       
-
       
		$(pandoc_flags) \

     

       
114
       
114
       
-
       
		-o $@

     

···

       
1
       
1
       
-
       
--[[

     

       
2
       
2
       
-
       
Converts Code AST nodes produced by pandoc’s DocBook reader

     

       
3
       
3
       
-
       
from citerefentry elements into AST for corresponding role

     

       
4
       
4
       
-
       
for reStructuredText.

     

       
5
       
5
       
-
       


     

       
6
       
6
       
-
       
We use subset of MyST syntax (CommonMark with features from rST)

     

       
7
       
7
       
-
       
so let’s use the rST AST for rST features.

     

       
8
       
8
       
-
       


     

       
9
       
9
       
-
       
Reference: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage

     

       
10
       
10
       
-
       
]]

     

       
11
       
11
       
-
       


     

       
12
       
12
       
-
       
function Code(elem)

     

       
13
       
13
       
-
       
  elem.classes = elem.classes:map(function (x)

     

       
14
       
14
       
-
       
    if x == 'citerefentry' then

     

       
15
       
15
       
-
       
      elem.attributes['role'] = 'manpage'

     

       
16
       
16
       
-
       
      return 'interpreted-text'

     

       
17
       
17
       
-
       
    else

     

       
18
       
18
       
-
       
      return x

     

       
19
       
19
       
-
       
    end

     

       
20
       
20
       
-
       
  end)

     

       
21
       
21
       
-
       


     

       
22
       
22
       
-
       
  return elem

     

       
23
       
23
       
-
       
end

     

···

       
1
       
1
       
-
       
--[[

     

       
2
       
2
       
-
       
Converts Link AST nodes with empty label to DocBook xref elements.

     

       
3
       
3
       
-
       


     

       
4
       
4
       
-
       
This is a temporary script to be able use cross-references conveniently

     

       
5
       
5
       
-
       
using syntax taken from MyST, while we still use docbook-xsl

     

       
6
       
6
       
-
       
for generating the documentation.

     

       
7
       
7
       
-
       


     

       
8
       
8
       
-
       
Reference: https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing

     

       
9
       
9
       
-
       
]]

     

       
10
       
10
       
-
       


     

       
11
       
11
       
-
       
local function starts_with(start, str)

     

       
12
       
12
       
-
       
  return str:sub(1, #start) == start

     

       
13
       
13
       
-
       
end

     

       
14
       
14
       
-
       


     

       
15
       
15
       
-
       
local function escape_xml_arg(arg)

     

       
16
       
16
       
-
       
  amps = arg:gsub('&', '&')

     

       
17
       
17
       
-
       
  amps_quotes = amps:gsub('"', '"')

     

       
18
       
18
       
-
       
  amps_quotes_lt = amps_quotes:gsub('<', '&lt;')

     

       
19
       
19
       
-
       


     

       
20
       
20
       
-
       
  return amps_quotes_lt

     

       
21
       
21
       
-
       
end

     

       
22
       
22
       
-
       


     

       
23
       
23
       
-
       
function Link(elem)

     

       
24
       
24
       
-
       
  has_no_content = #elem.content == 0

     

       
25
       
25
       
-
       
  targets_anchor = starts_with('#', elem.target)

     

       
26
       
26
       
-
       
  has_no_attributes = elem.title == '' and elem.identifier == '' and #elem.classes == 0 and #elem.attributes == 0

     

       
27
       
27
       
-
       


     

       
28
       
28
       
-
       
  if has_no_content and targets_anchor and has_no_attributes then

     

       
29
       
29
       
-
       
    -- xref expects idref without the pound-sign

     

       
30
       
30
       
-
       
    target_without_hash = elem.target:sub(2, #elem.target)

     

       
31
       
31
       
-
       


     

       
32
       
32
       
-
       
    return pandoc.RawInline('docbook', '<xref linkend="' .. escape_xml_arg(target_without_hash) .. '" />')

     

       
33
       
33
       
-
       
  end

     

       
34
       
34
       
-
       
end

     

···

       
1
       
1
       
-
       
--[[

     

       
2
       
2
       
-
       
Converts AST for reStructuredText roles into corresponding

     

       
3
       
3
       
-
       
DocBook elements.

     

       
4
       
4
       
-
       


     

       
5
       
5
       
-
       
Currently, only a subset of roles is supported.

     

       
6
       
6
       
-
       


     

       
7
       
7
       
-
       
Reference:

     

       
8
       
8
       
-
       
  List of roles:

     

       
9
       
9
       
-
       
    https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html

     

       
10
       
10
       
-
       
  manpage:

     

       
11
       
11
       
-
       
    https://tdg.docbook.org/tdg/5.1/citerefentry.html

     

       
12
       
12
       
-
       
  file:

     

       
13
       
13
       
-
       
    https://tdg.docbook.org/tdg/5.1/filename.html

     

       
14
       
14
       
-
       
]]

     

       
15
       
15
       
-
       


     

       
16
       
16
       
-
       
function Code(elem)

     

       
17
       
17
       
-
       
  if elem.classes:includes('interpreted-text') then

     

       
18
       
18
       
-
       
    local tag = nil

     

       
19
       
19
       
-
       
    local content = elem.text

     

       
20
       
20
       
-
       
    if elem.attributes['role'] == 'manpage' then

     

       
21
       
21
       
-
       
      tag = 'citerefentry'

     

       
22
       
22
       
-
       
      local title, volnum = content:match('^(.+)%((%w+)%)$')

     

       
23
       
23
       
-
       
      if title == nil then

     

       
24
       
24
       
-
       
        -- No volnum in parentheses.

     

       
25
       
25
       
-
       
        title = content

     

       
26
       
26
       
-
       
      end

     

       
27
       
27
       
-
       
      content = '<refentrytitle>' .. title .. '</refentrytitle>' .. (volnum ~= nil and ('<manvolnum>' .. volnum .. '</manvolnum>') or '')

     

       
28
       
28
       
-
       
    elseif elem.attributes['role'] == 'file' then

     

       
29
       
29
       
-
       
      tag = 'filename'

     

       
30
       
30
       
-
       
    elseif elem.attributes['role'] == 'command' then

     

       
31
       
31
       
-
       
      tag = 'command'

     

       
32
       
32
       
-
       
    elseif elem.attributes['role'] == 'option' then

     

       
33
       
33
       
-
       
      tag = 'option'

     

       
34
       
34
       
-
       
    elseif elem.attributes['role'] == 'var' then

     

       
35
       
35
       
-
       
      tag = 'varname'

     

       
36
       
36
       
-
       
    elseif elem.attributes['role'] == 'env' then

     

       
37
       
37
       
-
       
      tag = 'envar'

     

       
38
       
38
       
-
       
    end

     

       
39
       
39
       
-
       


     

       
40
       
40
       
-
       
    if tag ~= nil then

     

       
41
       
41
       
-
       
      return pandoc.RawInline('docbook', '<' .. tag .. '>' .. content .. '</' .. tag .. '>')

     

       
42
       
42
       
-
       
    end

     

       
43
       
43
       
-
       
  end

     

       
44
       
44
       
-
       
end

     

···

       
1
       
1
       
-
       
{ pkgs ? import ../../.. {} }:

     

       
2
       
2
       
-
       
let

     

       
3
       
3
       
-
       
  inherit (pkgs) lib;

     

       
4
       
4
       
-
       
  manpageURLs = lib.importJSON (pkgs.path + "/doc/manpage-urls.json");

     

       
5
       
5
       
-
       
in pkgs.writeText "link-manpages.lua" ''

     

       
6
       
6
       
-
       
  --[[

     

       
7
       
7
       
-
       
  Adds links to known man pages that aren't already in a link.

     

       
8
       
8
       
-
       
  ]]

     

       
9
       
9
       
-
       


     

       
10
       
10
       
-
       
  local manpage_urls = {

     

       
11
       
11
       
-
       
  ${lib.concatStringsSep "\n" (lib.mapAttrsToList (man: url:

     

       
12
       
12
       
-
       
    "  [${builtins.toJSON man}] = ${builtins.toJSON url},") manpageURLs)}

     

       
13
       
13
       
-
       
  }

     

       
14
       
14
       
-
       


     

       
15
       
15
       
-
       
  traverse = 'topdown'

     

       
16
       
16
       
-
       


     

       
17
       
17
       
-
       
  -- Returning false as the second value aborts processing of child elements.

     

       
18
       
18
       
-
       
  function Link(elem)

     

       
19
       
19
       
-
       
    return elem, false

     

       
20
       
20
       
-
       
  end

     

       
21
       
21
       
-
       


     

       
22
       
22
       
-
       
  function Code(elem)

     

       
23
       
23
       
-
       
    local is_man_role = elem.classes:includes('interpreted-text') and elem.attributes['role'] == 'manpage'

     

       
24
       
24
       
-
       
    if is_man_role and manpage_urls[elem.text] ~= nil then

     

       
25
       
25
       
-
       
      return pandoc.Link(elem, manpage_urls[elem.text]), false

     

       
26
       
26
       
-
       
    end

     

       
27
       
27
       
-
       
  end

     

       
28
       
28
       
-
       
''

     

···

       
1
       
1
       
-
       
--[[

     

       
2
       
2
       
-
       
Replaces Str AST nodes containing {role}, followed by a Code node

     

       
3
       
3
       
-
       
by a Code node with attrs that would be produced by rST reader

     

       
4
       
4
       
-
       
from the role syntax.

     

       
5
       
5
       
-
       


     

       
6
       
6
       
-
       
This is to emulate MyST syntax in Pandoc.

     

       
7
       
7
       
-
       
(MyST is a CommonMark flavour with rST features mixed in.)

     

       
8
       
8
       
-
       


     

       
9
       
9
       
-
       
Reference: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point

     

       
10
       
10
       
-
       
]]

     

       
11
       
11
       
-
       


     

       
12
       
12
       
-
       
function Inlines(inlines)

     

       
13
       
13
       
-
       
  for i = #inlines-1,1,-1 do

     

       
14
       
14
       
-
       
    local first = inlines[i]

     

       
15
       
15
       
-
       
    local second = inlines[i+1]

     

       
16
       
16
       
-
       
    local correct_tags = first.tag == 'Str' and second.tag == 'Code'

     

       
17
       
17
       
-
       
    if correct_tags then

     

       
18
       
18
       
-
       
      -- docutils supports alphanumeric strings separated by [-._:]

     

       
19
       
19
       
-
       
      -- We are slightly more liberal for simplicity.

     

       
20
       
20
       
-
       
      -- Allow preceding punctuation (eg '('), otherwise '({file}`...`)'

     

       
21
       
21
       
-
       
      -- does not match. Also allow anything followed by a non-breaking space

     

       
22
       
22
       
-
       
      -- since pandoc emits those after certain abbreviations (e.g. e.g.).

     

       
23
       
23
       
-
       
      local prefix, role = first.text:match('^(.*){([-._+:%w]+)}$')

     

       
24
       
24
       
-
       
      if role ~= nil and (prefix == '' or prefix:match("^.*[%p ]$") ~= nil) then

     

       
25
       
25
       
-
       
        if prefix == '' then

     

       
26
       
26
       
-
       
          inlines:remove(i)

     

       
27
       
27
       
-
       
        else

     

       
28
       
28
       
-
       
          first.text = prefix

     

       
29
       
29
       
-
       
        end

     

       
30
       
30
       
-
       
        second.attributes['role'] = role

     

       
31
       
31
       
-
       
        second.classes:insert('interpreted-text')

     

       
32
       
32
       
-
       
      end

     

       
33
       
33
       
-
       
    end

     

       
34
       
34
       
-
       
  end

     

       
35
       
35
       
-
       
  return inlines

     

       
36
       
36
       
-
       
end

     

···

       
1
       
1
       
-
       
--[[

     

       
2
       
2
       
-
       
Replaces Code nodes with attrs that would be produced by rST reader

     

       
3
       
3
       
-
       
from the role syntax by a Str AST node containing {role}, followed by a Code node.

     

       
4
       
4
       
-
       


     

       
5
       
5
       
-
       
This is to emulate MyST syntax in Pandoc.

     

       
6
       
6
       
-
       
(MyST is a CommonMark flavour with rST features mixed in.)

     

       
7
       
7
       
-
       


     

       
8
       
8
       
-
       
Reference: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point

     

       
9
       
9
       
-
       
]]

     

       
10
       
10
       
-
       


     

       
11
       
11
       
-
       
function Code(elem)

     

       
12
       
12
       
-
       
  local role = elem.attributes['role']

     

       
13
       
13
       
-
       


     

       
14
       
14
       
-
       
  if elem.classes:includes('interpreted-text') and role ~= nil then

     

       
15
       
15
       
-
       
    elem.classes = elem.classes:filter(function (c)

     

       
16
       
16
       
-
       
      return c ~= 'interpreted-text'

     

       
17
       
17
       
-
       
    end)

     

       
18
       
18
       
-
       
    elem.attributes['role'] = nil

     

       
19
       
19
       
-
       


     

       
20
       
20
       
-
       
    return {

     

       
21
       
21
       
-
       
      pandoc.Str('{' .. role .. '}'),

     

       
22
       
22
       
-
       
      elem,

     

       
23
       
23
       
-
       
    }

     

       
24
       
24
       
-
       
  end

     

       
25
       
25
       
-
       
end

     

···

       
1
       
1
       
+
       
# Builders {#part-builders}

     

       
2
       
2
       
+
       


     

       
3
       
3
       
+
       
```{=include=} chapters

     

       
4
       
4
       
+
       
builders/fetchers.chapter.md

     

       
5
       
5
       
+
       
builders/trivial-builders.chapter.md

     

       
6
       
6
       
+
       
builders/testers.chapter.md

     

       
7
       
7
       
+
       
builders/special.md

     

       
8
       
8
       
+
       
builders/images.md

     

       
9
       
9
       
+
       
hooks/index.md

     

       
10
       
10
       
+
       
languages-frameworks/index.md

     

       
11
       
11
       
+
       
builders/packages/index.md

     

       
12
       
12
       
+
       
```

     

···

       
1
       
1
       
+
       
# Images {#chap-images}

     

       
2
       
2
       
+
       


     

       
3
       
3
       
+
       
This chapter describes tools for creating various types of images.

     

       
4
       
4
       
+
       


     

       
5
       
5
       
+
       
```{=include=} sections

     

       
6
       
6
       
+
       
images/appimagetools.section.md

     

       
7
       
7
       
+
       
images/dockertools.section.md

     

       
8
       
8
       
+
       
images/ocitools.section.md

     

       
9
       
9
       
+
       
images/snaptools.section.md

     

       
10
       
10
       
+
       
images/portableservice.section.md

     

       
11
       
11
       
+
       
images/makediskimage.section.md

     

       
12
       
12
       
+
       
images/binarycache.section.md

     

       
13
       
13
       
+
       
```

     

···

       
1
       
1
       
-
       
<chapter xmlns="http://docbook.org/ns/docbook"

     

       
2
       
2
       
-
       
         xmlns:xi="http://www.w3.org/2001/XInclude"

     

       
3
       
3
       
-
       
         xml:id="chap-images">

     

       
4
       
4
       
-
       
 <title>Images</title>

     

       
5
       
5
       
-
       
 <para>

     

       
6
       
6
       
-
       
  This chapter describes tools for creating various types of images.

     

       
7
       
7
       
-
       
 </para>

     

       
8
       
8
       
-
       
 <xi:include href="images/appimagetools.section.xml" />

     

       
9
       
9
       
-
       
 <xi:include href="images/dockertools.section.xml" />

     

       
10
       
10
       
-
       
 <xi:include href="images/ocitools.section.xml" />

     

       
11
       
11
       
-
       
 <xi:include href="images/snaptools.section.xml" />

     

       
12
       
12
       
-
       
 <xi:include href="images/portableservice.section.xml" />

     

       
13
       
13
       
-
       
 <xi:include href="images/makediskimage.section.xml" />

     

       
14
       
14
       
-
       
 <xi:include href="images/binarycache.section.xml" />

     

       
15
       
15
       
-
       
</chapter>

     

···

       
1
       
1
       
 
       
# DLib {#dlib}

     

       
2
       
2
       
 
       


     

       
3
       
3
       
-
       
[DLib](http://dlib.net/) is a modern, C++-based toolkit which provides several machine learning algorithms.

     

       
3
       
3
       
+
       
[DLib](http://dlib.net/) is a modern, C++\-based toolkit which provides several machine learning algorithms.

     

       
4
       
4
       
 
       


     

       
5
       
5
       
 
       
## Compiling without AVX support {#compiling-without-avx-support}

     

       
6
       
6
       
 
       


     

···

       
1
       
1
       
+
       
# Packages {#chap-packages}

     

       
2
       
2
       
+
       


     

       
3
       
3
       
+
       
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.

     

       
4
       
4
       
+
       


     

       
5
       
5
       
+
       
```{=include=} sections

     

       
6
       
6
       
+
       
citrix.section.md

     

       
7
       
7
       
+
       
dlib.section.md

     

       
8
       
8
       
+
       
eclipse.section.md

     

       
9
       
9
       
+
       
elm.section.md

     

       
10
       
10
       
+
       
emacs.section.md

     

       
11
       
11
       
+
       
firefox.section.md

     

       
12
       
12
       
+
       
fish.section.md

     

       
13
       
13
       
+
       
fuse.section.md

     

       
14
       
14
       
+
       
ibus.section.md

     

       
15
       
15
       
+
       
kakoune.section.md

     

       
16
       
16
       
+
       
linux.section.md

     

       
17
       
17
       
+
       
locales.section.md

     

       
18
       
18
       
+
       
etc-files.section.md

     

       
19
       
19
       
+
       
nginx.section.md

     

       
20
       
20
       
+
       
opengl.section.md

     

       
21
       
21
       
+
       
shell-helpers.section.md

     

       
22
       
22
       
+
       
steam.section.md

     

       
23
       
23
       
+
       
cataclysm-dda.section.md

     

       
24
       
24
       
+
       
urxvt.section.md

     

       
25
       
25
       
+
       
weechat.section.md

     

       
26
       
26
       
+
       
xorg.section.md

     

       
27
       
27
       
+
       
```

     

···

       
1
       
1
       
-
       
<chapter xmlns="http://docbook.org/ns/docbook"

     

       
2
       
2
       
-
       
         xmlns:xi="http://www.w3.org/2001/XInclude"

     

       
3
       
3
       
-
       
         xml:id="chap-packages">

     

       
4
       
4
       
-
       
 <title>Packages</title>

     

       
5
       
5
       
-
       
 <para>

     

       
6
       
6
       
-
       
  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.

     

       
7
       
7
       
-
       
 </para>

     

       
8
       
8
       
-
       
 <xi:include href="citrix.section.xml" />

     

       
9
       
9
       
-
       
 <xi:include href="dlib.section.xml" />

     

       
10
       
10
       
-
       
 <xi:include href="eclipse.section.xml" />

     

       
11
       
11
       
-
       
 <xi:include href="elm.section.xml" />

     

       
12
       
12
       
-
       
 <xi:include href="emacs.section.xml" />

     

       
13
       
13
       
-
       
 <xi:include href="firefox.section.xml" />

     

       
14
       
14
       
-
       
 <xi:include href="fish.section.xml" />

     

       
15
       
15
       
-
       
 <xi:include href="fuse.section.xml" />

     

       
16
       
16
       
-
       
 <xi:include href="ibus.section.xml" />

     

       
17
       
17
       
-
       
 <xi:include href="kakoune.section.xml" />

     

       
18
       
18
       
-
       
 <xi:include href="linux.section.xml" />

     

       
19
       
19
       
-
       
 <xi:include href="locales.section.xml" />

     

       
20
       
20
       
-
       
 <xi:include href="etc-files.section.xml" />

     

       
21
       
21
       
-
       
 <xi:include href="nginx.section.xml" />

     

       
22
       
22
       
-
       
 <xi:include href="opengl.section.xml" />

     

       
23
       
23
       
-
       
 <xi:include href="shell-helpers.section.xml" />

     

       
24
       
24
       
-
       
 <xi:include href="steam.section.xml" />

     

       
25
       
25
       
-
       
 <xi:include href="cataclysm-dda.section.xml" />

     

       
26
       
26
       
-
       
 <xi:include href="urxvt.section.xml" />

     

       
27
       
27
       
-
       
 <xi:include href="weechat.section.xml" />

     

       
28
       
28
       
-
       
 <xi:include href="xorg.section.xml" />

     

       
29
       
29
       
-
       
</chapter>

     

···

       
1
       
1
       
+
       
# Special builders {#chap-special}

     

       
2
       
2
       
+
       


     

       
3
       
3
       
+
       
This chapter describes several special builders.

     

       
4
       
4
       
+
       


     

       
5
       
5
       
+
       
```{=include=} sections

     

       
6
       
6
       
+
       
special/fhs-environments.section.md

     

       
7
       
7
       
+
       
special/makesetuphook.section.md

     

       
8
       
8
       
+
       
special/mkshell.section.md

     

       
9
       
9
       
+
       
special/darwin-builder.section.md

     

       
10
       
10
       
+
       
special/vm-tools.section.md

     

       
11
       
11
       
+
       
```

     

···

       
1
       
1
       
-
       
<chapter xmlns="http://docbook.org/ns/docbook"

     

       
2
       
2
       
-
       
         xmlns:xi="http://www.w3.org/2001/XInclude"

     

       
3
       
3
       
-
       
         xml:id="chap-special">

     

       
4
       
4
       
-
       
 <title>Special builders</title>

     

       
5
       
5
       
-
       
 <para>

     

       
6
       
6
       
-
       
  This chapter describes several special builders.

     

       
7
       
7
       
-
       
 </para>

     

       
8
       
8
       
-
       
 <xi:include href="special/fhs-environments.section.xml" />

     

       
9
       
9
       
-
       
 <xi:include href="special/makesetuphook.section.xml" />

     

       
10
       
10
       
-
       
 <xi:include href="special/mkshell.section.xml" />

     

       
11
       
11
       
-
       
 <xi:include href="special/darwin-builder.section.xml" />

     

       
12
       
12
       
-
       
 <xi:include href="special/vm-tools.section.xml" />

     

       
13
       
13
       
-
       
</chapter>

     

···

       
1
       
1
       
+
       
# Contributing to Nixpkgs {#part-contributing}

     

       
2
       
2
       
+
       


     

       
3
       
3
       
+
       
```{=include=} chapters

     

       
4
       
4
       
+
       
contributing/quick-start.chapter.md

     

       
5
       
5
       
+
       
contributing/coding-conventions.chapter.md

     

       
6
       
6
       
+
       
contributing/submitting-changes.chapter.md

     

       
7
       
7
       
+
       
contributing/vulnerability-roundup.chapter.md

     

       
8
       
8
       
+
       
contributing/reviewing-contributions.chapter.md

     

       
9
       
9
       
+
       
contributing/contributing-to-documentation.chapter.md

     

       
10
       
10
       
+
       
```

     

···

       
1
       
1
       
+
       
digraph {

     

       
2
       
2
       
+
       
    "small changes" [shape=none]

     

       
3
       
3
       
+
       
    "mass-rebuilds and other large changes" [shape=none]

     

       
4
       
4
       
+
       
    "critical security fixes" [shape=none]

     

       
5
       
5
       
+
       
    "broken staging-next fixes" [shape=none]

     

       
6
       
6
       
+
       


     

       
7
       
7
       
+
       
    "small changes" -> master

     

       
8
       
8
       
+
       
    "mass-rebuilds and other large changes" -> staging

     

       
9
       
9
       
+
       
    "critical security fixes" -> master

     

       
10
       
10
       
+
       
    "broken staging-next fixes" -> "staging-next"

     

       
11
       
11
       
+
       


     

       
12
       
12
       
+
       
    "staging-next" -> master [color="#E85EB0"] [label="stabilization ends"] [fontcolor="#E85EB0"]

     

       
13
       
13
       
+
       
    "staging" -> "staging-next" [color="#E85EB0"] [label="stabilization starts"] [fontcolor="#E85EB0"]

     

       
14
       
14
       
+
       


     

       
15
       
15
       
+
       
    master -> "staging-next" -> staging [color="#5F5EE8"] [label="every six hours (GitHub Action)"] [fontcolor="#5F5EE8"]

     

       
16
       
16
       
+
       
}

     

···

       
1
       
1
       
+
       
<?xml version="1.0" encoding="UTF-8" standalone="no"?>

     

       
2
       
2
       
+
       
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"

     

       
3
       
3
       
+
       
 "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">

     

       
4
       
4
       
+
       
<!-- Generated by graphviz version 7.1.0 (0)

     

       
5
       
5
       
+
       
 -->

     

       
6
       
6
       
+
       
<!-- Pages: 1 -->

     

       
7
       
7
       
+
       
<svg width="743pt" height="291pt"

     

       
8
       
8
       
+
       
 viewBox="0.00 0.00 743.00 291.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">

     

       
9
       
9
       
+
       
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 287)">

     

       
10
       
10
       
+
       
<polygon fill="white" stroke="none" points="-4,4 -4,-287 739,-287 739,4 -4,4"/>

     

       
11
       
11
       
+
       
<!-- small changes -->

     

       
12
       
12
       
+
       
<g id="node1" class="node">

     

       
13
       
13
       
+
       
<title>small changes</title>

     

       
14
       
14
       
+
       
<text text-anchor="middle" x="59" y="-261.3" font-family="Times,serif" font-size="14.00">small changes</text>

     

       
15
       
15
       
+
       
</g>

     

       
16
       
16
       
+
       
<!-- master -->

     

       
17
       
17
       
+
       
<g id="node5" class="node">

     

       
18
       
18
       
+
       
<title>master</title>

     

       
19
       
19
       
+
       
<ellipse fill="none" stroke="black" cx="139" cy="-192" rx="43.59" ry="18"/>

     

       
20
       
20
       
+
       
<text text-anchor="middle" x="139" y="-188.3" font-family="Times,serif" font-size="14.00">master</text>

     

       
21
       
21
       
+
       
</g>

     

       
22
       
22
       
+
       
<!-- small changes&#45;&gt;master -->

     

       
23
       
23
       
+
       
<g id="edge1" class="edge">

     

       
24
       
24
       
+
       
<title>small changes&#45;&gt;master</title>

     

       
25
       
25
       
+
       
<path fill="none" stroke="black" d="M77.96,-247.17C88.42,-237.89 101.55,-226.23 112.96,-216.11"/>

     

       
26
       
26
       
+
       
<polygon fill="black" stroke="black" points="114.99,-218.99 120.14,-209.74 110.34,-213.76 114.99,-218.99"/>

     

       
27
       
27
       
+
       
</g>

     

       
28
       
28
       
+
       
<!-- mass&#45;rebuilds and other large changes -->

     

       
29
       
29
       
+
       
<g id="node2" class="node">

     

       
30
       
30
       
+
       
<title>mass&#45;rebuilds and other large changes</title>

     

       
31
       
31
       
+
       
<text text-anchor="middle" x="588" y="-101.3" font-family="Times,serif" font-size="14.00">mass&#45;rebuilds and other large changes</text>

     

       
32
       
32
       
+
       
</g>

     

       
33
       
33
       
+
       
<!-- staging -->

     

       
34
       
34
       
+
       
<g id="node6" class="node">

     

       
35
       
35
       
+
       
<title>staging</title>

     

       
36
       
36
       
+
       
<ellipse fill="none" stroke="black" cx="438" cy="-18" rx="45.49" ry="18"/>

     

       
37
       
37
       
+
       
<text text-anchor="middle" x="438" y="-14.3" font-family="Times,serif" font-size="14.00">staging</text>

     

       
38
       
38
       
+
       
</g>

     

       
39
       
39
       
+
       
<!-- mass&#45;rebuilds and other large changes&#45;&gt;staging -->

     

       
40
       
40
       
+
       
<g id="edge2" class="edge">

     

       
41
       
41
       
+
       
<title>mass&#45;rebuilds and other large changes&#45;&gt;staging</title>

     

       
42
       
42
       
+
       
<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"/>

     

       
43
       
43
       
+
       
<polygon fill="black" stroke="black" points="495.53,-17.39 485.2,-19.71 494.72,-24.35 495.53,-17.39"/>

     

       
44
       
44
       
+
       
</g>

     

       
45
       
45
       
+
       
<!-- critical security fixes -->

     

       
46
       
46
       
+
       
<g id="node3" class="node">

     

       
47
       
47
       
+
       
<title>critical security fixes</title>

     

       
48
       
48
       
+
       
<text text-anchor="middle" x="219" y="-261.3" font-family="Times,serif" font-size="14.00">critical security fixes</text>

     

       
49
       
49
       
+
       
</g>

     

       
50
       
50
       
+
       
<!-- critical security fixes&#45;&gt;master -->

     

       
51
       
51
       
+
       
<g id="edge3" class="edge">

     

       
52
       
52
       
+
       
<title>critical security fixes&#45;&gt;master</title>

     

       
53
       
53
       
+
       
<path fill="none" stroke="black" d="M200.04,-247.17C189.58,-237.89 176.45,-226.23 165.04,-216.11"/>

     

       
54
       
54
       
+
       
<polygon fill="black" stroke="black" points="167.66,-213.76 157.86,-209.74 163.01,-218.99 167.66,-213.76"/>

     

       
55
       
55
       
+
       
</g>

     

       
56
       
56
       
+
       
<!-- broken staging&#45;next fixes -->

     

       
57
       
57
       
+
       
<g id="node4" class="node">

     

       
58
       
58
       
+
       
<title>broken staging&#45;next fixes</title>

     

       
59
       
59
       
+
       
<text text-anchor="middle" x="414" y="-188.3" font-family="Times,serif" font-size="14.00">broken staging&#45;next fixes</text>

     

       
60
       
60
       
+
       
</g>

     

       
61
       
61
       
+
       
<!-- staging&#45;next -->

     

       
62
       
62
       
+
       
<g id="node7" class="node">

     

       
63
       
63
       
+
       
<title>staging&#45;next</title>

     

       
64
       
64
       
+
       
<ellipse fill="none" stroke="black" cx="272" cy="-105" rx="68.79" ry="18"/>

     

       
65
       
65
       
+
       
<text text-anchor="middle" x="272" y="-101.3" font-family="Times,serif" font-size="14.00">staging&#45;next</text>

     

       
66
       
66
       
+
       
</g>

     

       
67
       
67
       
+
       
<!-- broken staging&#45;next fixes&#45;&gt;staging&#45;next -->

     

       
68
       
68
       
+
       
<g id="edge4" class="edge">

     

       
69
       
69
       
+
       
<title>broken staging&#45;next fixes&#45;&gt;staging&#45;next</title>

     

       
70
       
70
       
+
       
<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"/>

     

       
71
       
71
       
+
       
<polygon fill="black" stroke="black" points="345.21,-113.33 334.63,-114.02 343.33,-120.07 345.21,-113.33"/>

     

       
72
       
72
       
+
       
</g>

     

       
73
       
73
       
+
       
<!-- master&#45;&gt;staging&#45;next -->

     

       
74
       
74
       
+
       
<g id="edge7" class="edge">

     

       
75
       
75
       
+
       
<title>master&#45;&gt;staging&#45;next</title>

     

       
76
       
76
       
+
       
<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"/>

     

       
77
       
77
       
+
       
<polygon fill="#5f5ee8" stroke="#5f5ee8" points="191.57,-109.61 201.47,-105.85 191.38,-102.62 191.57,-109.61"/>

     

       
78
       
78
       
+
       
<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>

     

       
79
       
79
       
+
       
</g>

     

       
80
       
80
       
+
       
<!-- staging&#45;&gt;staging&#45;next -->

     

       
81
       
81
       
+
       
<g id="edge6" class="edge">

     

       
82
       
82
       
+
       
<title>staging&#45;&gt;staging&#45;next</title>

     

       
83
       
83
       
+
       
<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"/>

     

       
84
       
84
       
+
       
<polygon fill="#e85eb0" stroke="#e85eb0" points="349.67,-94.79 340.5,-100.1 350.98,-101.66 349.67,-94.79"/>

     

       
85
       
85
       
+
       
<text text-anchor="middle" x="493.5" y="-57.8" font-family="Times,serif" font-size="14.00" fill="#e85eb0">stabilization starts</text>

     

       
86
       
86
       
+
       
</g>

     

       
87
       
87
       
+
       
<!-- staging&#45;next&#45;&gt;master -->

     

       
88
       
88
       
+
       
<g id="edge5" class="edge">

     

       
89
       
89
       
+
       
<title>staging&#45;next&#45;&gt;master</title>

     

       
90
       
90
       
+
       
<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"/>

     

       
91
       
91
       
+
       
<polygon fill="#e85eb0" stroke="#e85eb0" points="191.35,-180.38 182.34,-185.96 192.86,-187.22 191.35,-180.38"/>

     

       
92
       
92
       
+
       
<text text-anchor="middle" x="323.5" y="-144.8" font-family="Times,serif" font-size="14.00" fill="#e85eb0">stabilization ends</text>

     

       
93
       
93
       
+
       
</g>

     

       
94
       
94
       
+
       
<!-- staging&#45;next&#45;&gt;staging -->

     

       
95
       
95
       
+
       
<g id="edge8" class="edge">

     

       
96
       
96
       
+
       
<title>staging&#45;next&#45;&gt;staging</title>

     

       
97
       
97
       
+
       
<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"/>

     

       
98
       
98
       
+
       
<polygon fill="#5f5ee8" stroke="#5f5ee8" points="380.79,-22.1 390.76,-18.51 380.73,-15.1 380.79,-22.1"/>

     

       
99
       
99
       
+
       
<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>

     

       
100
       
100
       
+
       
</g>

     

       
101
       
101
       
+
       
</g>

     

       
102
       
102
       
+
       
</svg>

     

···

       
214
       
214
       
 
       
- 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.

     

       
215
       
215
       
 
       
- 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.

     

       
216
       
216
       
 
       


     

       
217
       
217
       
-
       
```{.graphviz caption="Staging workflow"}

     

       
218
       
218
       
-
       
digraph {

     

       
219
       
219
       
-
       
    "small changes" [shape=none]

     

       
220
       
220
       
-
       
    "mass-rebuilds and other large changes" [shape=none]

     

       
221
       
221
       
-
       
    "critical security fixes" [shape=none]

     

       
222
       
222
       
-
       
    "broken staging-next fixes" [shape=none]

     

       
223
       
223
       
-
       


     

       
224
       
224
       
-
       
    "small changes" -> master

     

       
225
       
225
       
-
       
    "mass-rebuilds and other large changes" -> staging

     

       
226
       
226
       
-
       
    "critical security fixes" -> master

     

       
227
       
227
       
-
       
    "broken staging-next fixes" -> "staging-next"

     

       
228
       
228
       
-
       


     

       
229
       
229
       
-
       
    "staging-next" -> master [color="#E85EB0"] [label="stabilization ends"] [fontcolor="#E85EB0"]

     

       
230
       
230
       
-
       
    "staging" -> "staging-next" [color="#E85EB0"] [label="stabilization starts"] [fontcolor="#E85EB0"]

     

       
231
       
231
       
-
       


     

       
232
       
232
       
-
       
    master -> "staging-next" -> staging [color="#5F5EE8"] [label="every six hours (GitHub Action)"] [fontcolor="#5F5EE8"]

     

       
233
       
233
       
-
       
}

     

       
234
       
234
       
-
       
```

     

       
217
       
217
       
+
       
::: {.figure #fig-staging-workflow}

     

       
218
       
218
       
+
       
# Staging workflow

     

       
219
       
219
       
+
       
<!-- generated from ./staging-workflow.dot using: dot -Tsvg staging-workflow.dot > staging-workflow.svg -->

     

       
220
       
220
       
+
       
![Staging workflow](./staging-workflow.svg)

     

       
221
       
221
       
+
       
:::

     

       
235
       
222
       
 
       


     

       
236
       
223
       
 
       
[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.

     

       
237
       
224
       
 
       


     

···

       
1
       
1
       
 
       
{ pkgs ? (import ./.. { }), nixpkgs ? { }}:

     

       
2
       
2
       
 
       
let

     

       
3
       
3
       
-
       
  doc-support = import ./doc-support { inherit pkgs nixpkgs; };

     

       
3
       
3
       
+
       
  inherit (pkgs) lib;

     

       
4
       
4
       
+
       
  inherit (lib) hasPrefix removePrefix;

     

       
5
       
5
       
+
       


     

       
6
       
6
       
+
       
  lib-docs = import ./doc-support/lib-function-docs.nix {

     

       
7
       
7
       
+
       
    inherit pkgs nixpkgs;

     

       
8
       
8
       
+
       
    libsets = [

     

       
9
       
9
       
+
       
      { name = "asserts"; description = "assertion functions"; }

     

       
10
       
10
       
+
       
      { name = "attrsets"; description = "attribute set functions"; }

     

       
11
       
11
       
+
       
      { name = "strings"; description = "string manipulation functions"; }

     

       
12
       
12
       
+
       
      { name = "versions"; description = "version string functions"; }

     

       
13
       
13
       
+
       
      { name = "trivial"; description = "miscellaneous functions"; }

     

       
14
       
14
       
+
       
      { name = "lists"; description = "list manipulation functions"; }

     

       
15
       
15
       
+
       
      { name = "debug"; description = "debugging functions"; }

     

       
16
       
16
       
+
       
      { name = "options"; description = "NixOS / nixpkgs option handling"; }

     

       
17
       
17
       
+
       
      { name = "path"; description = "path functions"; }

     

       
18
       
18
       
+
       
      { name = "filesystem"; description = "filesystem functions"; }

     

       
19
       
19
       
+
       
      { name = "sources"; description = "source filtering functions"; }

     

       
20
       
20
       
+
       
      { name = "cli"; description = "command-line serialization functions"; }

     

       
21
       
21
       
+
       
    ];

     

       
22
       
22
       
+
       
  };

     

       
23
       
23
       
+
       


     

       
24
       
24
       
+
       
  epub = pkgs.runCommand "manual.epub" {

     

       
25
       
25
       
+
       
    nativeBuildInputs = with pkgs; [ libxslt zip ];

     

       
26
       
26
       
+
       


     

       
27
       
27
       
+
       
    epub = ''

     

       
28
       
28
       
+
       
      <book xmlns="http://docbook.org/ns/docbook"

     

       
29
       
29
       
+
       
            xmlns:xlink="http://www.w3.org/1999/xlink"

     

       
30
       
30
       
+
       
            version="5.0"

     

       
31
       
31
       
+
       
            xml:id="nixpkgs-manual">

     

       
32
       
32
       
+
       
        <info>

     

       
33
       
33
       
+
       
          <title>Nixpkgs Manual</title>

     

       
34
       
34
       
+
       
          <subtitle>Version ${pkgs.lib.version}</subtitle>

     

       
35
       
35
       
+
       
        </info>

     

       
36
       
36
       
+
       
        <chapter>

     

       
37
       
37
       
+
       
          <title>Temporarily unavailable</title>

     

       
38
       
38
       
+
       
          <para>

     

       
39
       
39
       
+
       
            The Nixpkgs manual is currently not available in EPUB format,

     

       
40
       
40
       
+
       
            please use the <link xlink:href="https://nixos.org/nixpkgs/manual">HTML manual</link>

     

       
41
       
41
       
+
       
            instead.

     

       
42
       
42
       
+
       
          </para>

     

       
43
       
43
       
+
       
          <para>

     

       
44
       
44
       
+
       
            If you've used the EPUB manual in the past and it has been useful to you, please

     

       
45
       
45
       
+
       
            <link xlink:href="https://github.com/NixOS/nixpkgs/issues/237234">let us know</link>.

     

       
46
       
46
       
+
       
          </para>

     

       
47
       
47
       
+
       
        </chapter>

     

       
48
       
48
       
+
       
      </book>

     

       
49
       
49
       
+
       
    '';

     

       
50
       
50
       
+
       


     

       
51
       
51
       
+
       
    passAsFile = [ "epub" ];

     

       
52
       
52
       
+
       
  } ''

     

       
53
       
53
       
+
       
    mkdir scratch

     

       
54
       
54
       
+
       
    xsltproc \

     

       
55
       
55
       
+
       
      --param chapter.autolabel 0 \

     

       
56
       
56
       
+
       
      --nonet \

     

       
57
       
57
       
+
       
      --output scratch/ \

     

       
58
       
58
       
+
       
      ${pkgs.docbook_xsl_ns}/xml/xsl/docbook/epub/docbook.xsl \

     

       
59
       
59
       
+
       
      $epubPath

     

       
60
       
60
       
+
       


     

       
61
       
61
       
+
       
    echo "application/epub+zip" > mimetype

     

       
62
       
62
       
+
       
    zip -0Xq "$out" mimetype

     

       
63
       
63
       
+
       
    cd scratch && zip -Xr9D "$out" *

     

       
64
       
64
       
+
       
  '';

     

       
65
       
65
       
+
       


     

       
66
       
66
       
+
       
  # NB: This file describes the Nixpkgs manual, which happens to use module

     

       
67
       
67
       
+
       
  #     docs infra originally developed for NixOS.

     

       
68
       
68
       
+
       
  optionsDoc = pkgs.nixosOptionsDoc {

     

       
69
       
69
       
+
       
    inherit (pkgs.lib.evalModules {

     

       
70
       
70
       
+
       
      modules = [ ../pkgs/top-level/config.nix ];

     

       
71
       
71
       
+
       
      class = "nixpkgsConfig";

     

       
72
       
72
       
+
       
    }) options;

     

       
73
       
73
       
+
       
    documentType = "none";

     

       
74
       
74
       
+
       
    transformOptions = opt:

     

       
75
       
75
       
+
       
      opt // {

     

       
76
       
76
       
+
       
        declarations =

     

       
77
       
77
       
+
       
          map

     

       
78
       
78
       
+
       
            (decl:

     

       
79
       
79
       
+
       
              if hasPrefix (toString ../..) (toString decl)

     

       
80
       
80
       
+
       
              then

     

       
81
       
81
       
+
       
                let subpath = removePrefix "/" (removePrefix (toString ../.) (toString decl));

     

       
82
       
82
       
+
       
                in { url = "https://github.com/NixOS/nixpkgs/blob/master/${subpath}"; name = subpath; }

     

       
83
       
83
       
+
       
              else decl)

     

       
84
       
84
       
+
       
            opt.declarations;

     

       
85
       
85
       
+
       
        };

     

       
86
       
86
       
+
       
  };

     

       
4
       
87
       
 
       
in pkgs.stdenv.mkDerivation {

     

       
5
       
88
       
 
       
  name = "nixpkgs-manual";

     

       
6
       
89
       
 
       


     

       
7
       
90
       
 
       
  nativeBuildInputs = with pkgs; [

     

       
8
       
8
       
-
       
    pandoc

     

       
9
       
9
       
-
       
    graphviz

     

       
10
       
10
       
-
       
    libxml2

     

       
11
       
11
       
-
       
    libxslt

     

       
12
       
12
       
-
       
    zip

     

       
13
       
13
       
-
       
    jing

     

       
14
       
14
       
-
       
    xmlformat

     

       
91
       
91
       
+
       
    nixos-render-docs

     

       
15
       
92
       
 
       
  ];

     

       
16
       
93
       
 
       


     

       
17
       
17
       
-
       
  src = pkgs.nix-gitignore.gitignoreSource [] ./.;

     

       
94
       
94
       
+
       
  src = ./.;

     

       
18
       
95
       
 
       


     

       
19
       
96
       
 
       
  postPatch = ''

     

       
20
       
20
       
-
       
    ln -s ${doc-support} ./doc-support/result

     

       
97
       
97
       
+
       
    ln -s ${optionsDoc.optionsJSON}/share/doc/nixos/options.json ./config-options.json

     

       
21
       
98
       
 
       
  '';

     

       
22
       
99
       
 
       


     

       
23
       
23
       
-
       
  epub = ''

     

       
24
       
24
       
-
       
    <book xmlns="http://docbook.org/ns/docbook"

     

       
25
       
25
       
-
       
          xmlns:xlink="http://www.w3.org/1999/xlink"

     

       
26
       
26
       
-
       
          version="5.0"

     

       
27
       
27
       
-
       
          xml:id="nixpkgs-manual">

     

       
28
       
28
       
-
       
      <info>

     

       
29
       
29
       
-
       
        <title>Nixpkgs Manual</title>

     

       
30
       
30
       
-
       
        <subtitle>Version ${pkgs.lib.version}</subtitle>

     

       
31
       
31
       
-
       
      </info>

     

       
32
       
32
       
-
       
      <chapter>

     

       
33
       
33
       
-
       
        <title>Temporarily unavailable</title>

     

       
34
       
34
       
-
       
        <para>

     

       
35
       
35
       
-
       
          The Nixpkgs manual is currently not available in EPUB format,

     

       
36
       
36
       
-
       
          please use the <link xlink:href="https://nixos.org/nixpkgs/manual">HTML manual</link>

     

       
37
       
37
       
-
       
          instead.

     

       
38
       
38
       
-
       
        </para>

     

       
39
       
39
       
-
       
        <para>

     

       
40
       
40
       
-
       
          If you've used the EPUB manual in the past and it has been useful to you, please

     

       
41
       
41
       
-
       
          <link xlink:href="https://github.com/NixOS/nixpkgs/issues/237234">let us know</link>.

     

       
42
       
42
       
-
       
        </para>

     

       
43
       
43
       
-
       
      </chapter>

     

       
44
       
44
       
-
       
    </book>

     

       
45
       
45
       
-
       
  '';

     

       
46
       
46
       
-
       
  passAsFile = [ "epub" ];

     

       
100
       
100
       
+
       
  buildPhase = ''

     

       
101
       
101
       
+
       
    cat \

     

       
102
       
102
       
+
       
      ./functions/library.md.in \

     

       
103
       
103
       
+
       
      ${lib-docs}/index.md \

     

       
104
       
104
       
+
       
      > ./functions/library.md

     

       
105
       
105
       
+
       
    substitute ./manual.md.in ./manual.md \

     

       
106
       
106
       
+
       
      --replace '@MANUAL_VERSION@' '${pkgs.lib.version}'

     

       
107
       
107
       
+
       


     

       
108
       
108
       
+
       
    mkdir -p out/media

     

       
109
       
109
       
+
       


     

       
110
       
110
       
+
       
    mkdir -p out/highlightjs

     

       
111
       
111
       
+
       
    cp -t out/highlightjs \

     

       
112
       
112
       
+
       
      ${pkgs.documentation-highlighter}/highlight.pack.js \

     

       
113
       
113
       
+
       
      ${pkgs.documentation-highlighter}/LICENSE \

     

       
114
       
114
       
+
       
      ${pkgs.documentation-highlighter}/mono-blue.css \

     

       
115
       
115
       
+
       
      ${pkgs.documentation-highlighter}/loader.js

     

       
116
       
116
       
+
       


     

       
117
       
117
       
+
       
    cp -t out ./overrides.css ./style.css

     

       
47
       
118
       
 
       


     

       
48
       
48
       
-
       
  preBuild = ''

     

       
49
       
49
       
-
       
    cp $epubPath epub.xml

     

       
50
       
50
       
-
       
    make -j$NIX_BUILD_CORES render-md

     

       
119
       
119
       
+
       
    nixos-render-docs manual html \

     

       
120
       
120
       
+
       
      --manpage-urls ./manpage-urls.json \

     

       
121
       
121
       
+
       
      --revision ${pkgs.lib.trivial.revisionWithDefault (pkgs.rev or "master")} \

     

       
122
       
122
       
+
       
      --stylesheet style.css \

     

       
123
       
123
       
+
       
      --stylesheet overrides.css \

     

       
124
       
124
       
+
       
      --stylesheet highlightjs/mono-blue.css \

     

       
125
       
125
       
+
       
      --script ./highlightjs/highlight.pack.js \

     

       
126
       
126
       
+
       
      --script ./highlightjs/loader.js \

     

       
127
       
127
       
+
       
      --toc-depth 1 \

     

       
128
       
128
       
+
       
      --section-toc-depth 1 \

     

       
129
       
129
       
+
       
      manual.md \

     

       
130
       
130
       
+
       
      out/index.html

     

       
51
       
131
       
 
       
  '';

     

       
52
       
132
       
 
       


     

       
53
       
133
       
 
       
  installPhase = ''

     

       
54
       
134
       
 
       
    dest="$out/share/doc/nixpkgs"

     

       
55
       
135
       
 
       
    mkdir -p "$(dirname "$dest")"

     

       
56
       
56
       
-
       
    mv out/html "$dest"

     

       
136
       
136
       
+
       
    mv out "$dest"

     

       
57
       
137
       
 
       
    mv "$dest/index.html" "$dest/manual.html"

     

       
58
       
138
       
 
       


     

       
59
       
59
       
-
       
    mv out/epub/manual.epub "$dest/nixpkgs-manual.epub"

     

       
139
       
139
       
+
       
    cp ${epub} "$dest/nixpkgs-manual.epub"

     

       
60
       
140
       
 
       


     

       
61
       
141
       
 
       
    mkdir -p $out/nix-support/

     

       
62
       
142
       
 
       
    echo "doc manual $dest manual.html" >> $out/nix-support/hydra-build-products

     

       
63
       
143
       
 
       
    echo "doc manual $dest nixpkgs-manual.epub" >> $out/nix-support/hydra-build-products

     

       
64
       
144
       
 
       
  '';

     

       
65
       
65
       
-
       


     

       
66
       
66
       
-
       
  # Environment variables

     

       
67
       
67
       
-
       
  PANDOC_LUA_FILTERS_DIR = "${pkgs.pandoc-lua-filters}/share/pandoc/filters";

     

       
68
       
68
       
-
       
  PANDOC_LINK_MANPAGES_FILTER = import build-aux/pandoc-filters/link-manpages.nix { inherit pkgs; };

     

       
69
       
145
       
 
       
}

     

···

       
1
       
1
       
-
       
{ pkgs ? (import ../.. {}), nixpkgs ? { }}:

     

       
2
       
2
       
-
       
let

     

       
3
       
3
       
-
       
  inherit (pkgs) lib;

     

       
4
       
4
       
-
       
  inherit (lib) hasPrefix removePrefix;

     

       
5
       
5
       
-
       


     

       
6
       
6
       
-
       
  libsets = [

     

       
7
       
7
       
-
       
    { name = "asserts"; description = "assertion functions"; }

     

       
8
       
8
       
-
       
    { name = "attrsets"; description = "attribute set functions"; }

     

       
9
       
9
       
-
       
    { name = "strings"; description = "string manipulation functions"; }

     

       
10
       
10
       
-
       
    { name = "versions"; description = "version string functions"; }

     

       
11
       
11
       
-
       
    { name = "trivial"; description = "miscellaneous functions"; }

     

       
12
       
12
       
-
       
    { name = "lists"; description = "list manipulation functions"; }

     

       
13
       
13
       
-
       
    { name = "debug"; description = "debugging functions"; }

     

       
14
       
14
       
-
       
    { name = "options"; description = "NixOS / nixpkgs option handling"; }

     

       
15
       
15
       
-
       
    { name = "path"; description = "path functions"; }

     

       
16
       
16
       
-
       
    { name = "filesystem"; description = "filesystem functions"; }

     

       
17
       
17
       
-
       
    { name = "sources"; description = "source filtering functions"; }

     

       
18
       
18
       
-
       
    { name = "cli"; description = "command-line serialization functions"; }

     

       
19
       
19
       
-
       
  ];

     

       
20
       
20
       
-
       


     

       
21
       
21
       
-
       
  locationsXml = import ./lib-function-locations.nix { inherit pkgs nixpkgs libsets; };

     

       
22
       
22
       
-
       
  functionDocs = import ./lib-function-docs.nix { inherit locationsXml pkgs libsets; };

     

       
23
       
23
       
-
       
  version = pkgs.lib.version;

     

       
24
       
24
       
-
       


     

       
25
       
25
       
-
       
  epub-xsl = pkgs.writeText "epub.xsl" ''

     

       
26
       
26
       
-
       
    <?xml version='1.0'?>

     

       
27
       
27
       
-
       
    <xsl:stylesheet

     

       
28
       
28
       
-
       
      xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

     

       
29
       
29
       
-
       
      version="1.0">

     

       
30
       
30
       
-
       
      <xsl:import href="${pkgs.docbook_xsl_ns}/xml/xsl/docbook/epub/docbook.xsl" />

     

       
31
       
31
       
-
       
      <xsl:import href="${./parameters.xml}"/>

     

       
32
       
32
       
-
       
    </xsl:stylesheet>

     

       
33
       
33
       
-
       
  '';

     

       
34
       
34
       
-
       


     

       
35
       
35
       
-
       
  xhtml-xsl = pkgs.writeText "xhtml.xsl" ''

     

       
36
       
36
       
-
       
    <?xml version='1.0'?>

     

       
37
       
37
       
-
       
    <xsl:stylesheet

     

       
38
       
38
       
-
       
      xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

     

       
39
       
39
       
-
       
      version="1.0">

     

       
40
       
40
       
-
       
      <xsl:import href="${pkgs.docbook_xsl_ns}/xml/xsl/docbook/xhtml/docbook.xsl" />

     

       
41
       
41
       
-
       
      <xsl:import href="${./parameters.xml}"/>

     

       
42
       
42
       
-
       
    </xsl:stylesheet>

     

       
43
       
43
       
-
       
  '';

     

       
44
       
44
       
-
       


     

       
45
       
45
       
-
       
  # NB: This file describes the Nixpkgs manual, which happens to use module

     

       
46
       
46
       
-
       
  #     docs infra originally developed for NixOS.

     

       
47
       
47
       
-
       
  optionsDoc = pkgs.nixosOptionsDoc {

     

       
48
       
48
       
-
       
    inherit (pkgs.lib.evalModules {

     

       
49
       
49
       
-
       
      modules = [ ../../pkgs/top-level/config.nix ];

     

       
50
       
50
       
-
       
      class = "nixpkgsConfig";

     

       
51
       
51
       
-
       
    }) options;

     

       
52
       
52
       
-
       
    documentType = "none";

     

       
53
       
53
       
-
       
    transformOptions = opt:

     

       
54
       
54
       
-
       
      opt // {

     

       
55
       
55
       
-
       
        declarations =

     

       
56
       
56
       
-
       
          map

     

       
57
       
57
       
-
       
            (decl:

     

       
58
       
58
       
-
       
              if hasPrefix (toString ../..) (toString decl)

     

       
59
       
59
       
-
       
              then

     

       
60
       
60
       
-
       
                let subpath = removePrefix "/" (removePrefix (toString ../..) (toString decl));

     

       
61
       
61
       
-
       
                in { url = "https://github.com/NixOS/nixpkgs/blob/master/${subpath}"; name = subpath; }

     

       
62
       
62
       
-
       
              else decl)

     

       
63
       
63
       
-
       
            opt.declarations;

     

       
64
       
64
       
-
       
        };

     

       
65
       
65
       
-
       
  };

     

       
66
       
66
       
-
       


     

       
67
       
67
       
-
       
in pkgs.runCommand "doc-support" {}

     

       
68
       
68
       
-
       
''

     

       
69
       
69
       
-
       
  mkdir result

     

       
70
       
70
       
-
       
  (

     

       
71
       
71
       
-
       
    cd result

     

       
72
       
72
       
-
       
    ln -s ${locationsXml} ./function-locations.xml

     

       
73
       
73
       
-
       
    ln -s ${functionDocs} ./function-docs

     

       
74
       
74
       
-
       
    ln -s ${optionsDoc.optionsDocBook} ./config-options.docbook.xml

     

       
75
       
75
       
-
       


     

       
76
       
76
       
-
       
    ln -s ${pkgs.docbook5}/xml/rng/docbook/docbook.rng ./docbook.rng

     

       
77
       
77
       
-
       
    ln -s ${pkgs.docbook_xsl_ns}/xml/xsl ./xsl

     

       
78
       
78
       
-
       
    ln -s ${epub-xsl} ./epub.xsl

     

       
79
       
79
       
-
       
    ln -s ${xhtml-xsl} ./xhtml.xsl

     

       
80
       
80
       
-
       


     

       
81
       
81
       
-
       
    ln -s ${./xmlformat.conf} ./xmlformat.conf

     

       
82
       
82
       
-
       
    ln -s ${pkgs.documentation-highlighter} ./highlightjs

     

       
83
       
83
       
-
       


     

       
84
       
84
       
-
       
    echo -n "${version}" > ./version

     

       
85
       
85
       
-
       
  )

     

       
86
       
86
       
-
       
  mv result $out

     

       
87
       
87
       
-
       
''

     

···

       
1
       
1
       
 
       
# Generates the documentation for library functions via nixdoc.

     

       
2
       
2
       
 
       


     

       
3
       
3
       
-
       
{ pkgs, locationsXml, libsets }:

     

       
3
       
3
       
+
       
{ pkgs, nixpkgs, libsets }:

     

       
4
       
4
       
 
       


     

       
5
       
5
       
-
       
with pkgs; stdenv.mkDerivation {

     

       
5
       
5
       
+
       
with pkgs;

     

       
6
       
6
       
+
       


     

       
7
       
7
       
+
       
let

     

       
8
       
8
       
+
       
  locationsJSON = import ./lib-function-locations.nix { inherit pkgs nixpkgs libsets; };

     

       
9
       
9
       
+
       
in

     

       
10
       
10
       
+
       
stdenv.mkDerivation {

     

       
6
       
11
       
 
       
  name = "nixpkgs-lib-docs";

     

       
7
       
12
       
 
       
  src = ../../lib;

     

       
8
       
13
       
 
       


     
···

       
11
       
16
       
 
       
    function docgen {

     

       
12
       
17
       
 
       
      # TODO: wrap lib.$1 in <literal>, make nixdoc not escape it

     

       
13
       
18
       
 
       
      if [[ -e "../lib/$1.nix" ]]; then

     

       
14
       
14
       
-
       
        nixdoc -c "$1" -d "lib.$1: $2" -f "$1.nix" > "$out/$1.xml"

     

       
19
       
19
       
+
       
        nixdoc -c "$1" -d "lib.$1: $2" -l ${locationsJSON} -f "$1.nix" > "$out/$1.md"

     

       
15
       
20
       
 
       
      else

     

       
16
       
16
       
-
       
        nixdoc -c "$1" -d "lib.$1: $2" -f "$1/default.nix" > "$out/$1.xml"

     

       
21
       
21
       
+
       
        nixdoc -c "$1" -d "lib.$1: $2" -l ${locationsJSON} -f "$1/default.nix" > "$out/$1.md"

     

       
17
       
22
       
 
       
      fi

     

       
18
       
18
       
-
       
      echo "<xi:include href='$1.xml' />" >> "$out/index.xml"

     

       
23
       
23
       
+
       
      echo "$out/$1.md" >> "$out/index.md"

     

       
19
       
24
       
 
       
    }

     

       
20
       
25
       
 
       


     

       
21
       
26
       
 
       
    mkdir -p "$out"

     

       
22
       
27
       
 
       


     

       
23
       
23
       
-
       
    cat > "$out/index.xml" << 'EOF'

     

       
24
       
24
       
-
       
    <?xml version="1.0" encoding="utf-8"?>

     

       
25
       
25
       
-
       
    <root xmlns:xi="http://www.w3.org/2001/XInclude">

     

       
28
       
28
       
+
       
    cat > "$out/index.md" << 'EOF'

     

       
29
       
29
       
+
       
    ```{=include=} sections

     

       
26
       
30
       
 
       
    EOF

     

       
27
       
31
       
 
       


     

       
28
       
32
       
 
       
    ${lib.concatMapStrings ({ name, description }: ''

     

       
29
       
33
       
 
       
      docgen ${name} ${lib.escapeShellArg description}

     

       
30
       
34
       
 
       
    '') libsets}

     

       
31
       
35
       
 
       


     

       
32
       
32
       
-
       
    echo "</root>" >> "$out/index.xml"

     

       
33
       
33
       
-
       


     

       
34
       
34
       
-
       
    ln -s ${locationsXml} $out/locations.xml

     

       
36
       
36
       
+
       
    echo '```' >> "$out/index.md"

     

       
35
       
37
       
 
       
  '';

     

       
36
       
38
       
 
       
}

     

···

       
58
       
58
       
 
       
    [ "-prime" ];

     

       
59
       
59
       
 
       


     

       
60
       
60
       
 
       
  urlPrefix = "https://github.com/NixOS/nixpkgs/blob/${revision}";

     

       
61
       
61
       
-
       
  xmlstrings = (nixpkgsLib.strings.concatMapStrings

     

       
62
       
62
       
-
       
      ({ name, value }:

     

       
63
       
63
       
-
       
      ''

     

       
64
       
64
       
-
       
      <section><title>${name}</title>

     

       
65
       
65
       
-
       
        <para xml:id="${sanitizeId name}">

     

       
66
       
66
       
-
       
        Located at

     

       
67
       
67
       
-
       
        <link

     

       
68
       
68
       
-
       
          xlink:href="${urlPrefix}/${value.file}#L${builtins.toString value.line}">${value.file}:${builtins.toString value.line}</link>

     

       
69
       
69
       
-
       
        in  <literal>&lt;nixpkgs&gt;</literal>.

     

       
70
       
70
       
-
       
        </para>

     

       
71
       
71
       
-
       
        </section>

     

       
72
       
72
       
-
       
      '')

     

       
73
       
73
       
-
       
      relativeLocs);

     

       
61
       
61
       
+
       
  jsonLocs = builtins.listToAttrs

     

       
62
       
62
       
+
       
    (builtins.map

     

       
63
       
63
       
+
       
      ({ name, value }: {

     

       
64
       
64
       
+
       
        name = sanitizeId name;

     

       
65
       
65
       
+
       
        value =

     

       
66
       
66
       
+
       
          let

     

       
67
       
67
       
+
       
            text = "${value.file}:${builtins.toString value.line}";

     

       
68
       
68
       
+
       
            target = "${urlPrefix}/${value.file}#L${builtins.toString value.line}";

     

       
69
       
69
       
+
       
          in

     

       
70
       
70
       
+
       
            "[${text}](${target}) in `<nixpkgs>`";

     

       
71
       
71
       
+
       
      })

     

       
72
       
72
       
+
       
    relativeLocs);

     

       
74
       
73
       
 
       


     

       
75
       
75
       
-
       
in pkgs.writeText

     

       
76
       
76
       
-
       
    "locations.xml"

     

       
77
       
77
       
-
       
    ''

     

       
78
       
78
       
-
       
    <section xmlns="http://docbook.org/ns/docbook"

     

       
79
       
79
       
-
       
         xmlns:xlink="http://www.w3.org/1999/xlink"

     

       
80
       
80
       
-
       
         version="5">

     

       
81
       
81
       
-
       
         <title>All the locations for every lib function</title>

     

       
82
       
82
       
-
       
         <para>This file is only for inclusion by other files.</para>

     

       
83
       
83
       
-
       
         ${xmlstrings}

     

       
84
       
84
       
-
       
    </section>

     

       
85
       
85
       
-
       
    ''

     

       
74
       
74
       
+
       
in

     

       
75
       
75
       
+
       
pkgs.writeText "locations.json" (builtins.toJSON jsonLocs)

     

···

       
1
       
1
       
-
       
<?xml version='1.0'?>

     

       
2
       
2
       
-
       
<xsl:stylesheet

     

       
3
       
3
       
-
       
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

     

       
4
       
4
       
-
       
    version="1.0">

     

       
5
       
5
       
-
       
 <xsl:param name="chapter.autolabel" select="0" />

     

       
6
       
6
       
-
       
 <xsl:param name="part.autolabel" select="0" />

     

       
7
       
7
       
-
       
 <xsl:param name="preface.autolabel" select="0" />

     

       
8
       
8
       
-
       
 <xsl:param name="reference.autolabel" select="0" />

     

       
9
       
9
       
-
       
 <xsl:param name="section.autolabel" select="0" />

     

       
10
       
10
       
-
       
 <xsl:param name="html.stylesheet" select="'style.css overrides.css highlightjs/mono-blue.css'" />

     

       
11
       
11
       
-
       
 <xsl:param name="html.script" select="'./highlightjs/highlight.pack.js ./highlightjs/loader.js'" />

     

       
12
       
12
       
-
       
 <xsl:param name="xref.with.number.and.title" select="0" />

     

       
13
       
13
       
-
       
 <xsl:param name="use.id.as.filename" select="1" />

     

       
14
       
14
       
-
       
 <xsl:param name="generate.section.toc.level" select="1" />

     

       
15
       
15
       
-
       
 <xsl:param name="toc.section.depth" select="0" />

     

       
16
       
16
       
-
       
 <xsl:param name="admon.style" select="''" />

     

       
17
       
17
       
-
       
 <xsl:param name="callout.graphics.extension" select="'.svg'" />

     

       
18
       
18
       
-
       
 <xsl:param name="generate.consistent.ids" select="1" />

     

       
19
       
19
       
-
       
</xsl:stylesheet>

     

···

       
1
       
1
       
-
       
#

     

       
2
       
2
       
-
       
# DocBook Configuration file for "xmlformat"

     

       
3
       
3
       
-
       
# see http://www.kitebird.com/software/xmlformat/

     

       
4
       
4
       
-
       
# 10 Sept. 2004

     

       
5
       
5
       
-
       
#

     

       
6
       
6
       
-
       


     

       
7
       
7
       
-
       
# Only block elements

     

       
8
       
8
       
-
       
ackno address appendix article biblioentry bibliography bibliomixed \

     

       
9
       
9
       
-
       
biblioset blockquote book bridgehead callout calloutlist caption caution \

     

       
10
       
10
       
-
       
chapter chapterinfo classsynopsis cmdsynopsis colophon constraintdef \

     

       
11
       
11
       
-
       
constructorsynopsis dedication destructorsynopsis entry epigraph equation example \

     

       
12
       
12
       
-
       
figure formalpara funcsynopsis glossary glossdef glossdiv glossentry glosslist \

     

       
13
       
13
       
-
       
glosssee glossseealso graphic graphicco highlights imageobjectco important \

     

       
14
       
14
       
-
       
index indexdiv indexentry indexinfo info informalequation informalexample \

     

       
15
       
15
       
-
       
informalfigure informaltable legalnotice literallayout lot lotentry mediaobject \

     

       
16
       
16
       
-
       
mediaobjectco msgmain msgset note orderedlist para part preface primaryie \

     

       
17
       
17
       
-
       
procedure qandadiv qandaentry qandaset refentry refentrytitle reference \

     

       
18
       
18
       
-
       
refnamediv refsect1 refsect2 refsect3 refsection revhistory screenshot sect1 \

     

       
19
       
19
       
-
       
sect2 sect3 sect4 sect5 section seglistitem set setindex sidebar simpara \

     

       
20
       
20
       
-
       
simplesect step substeps synopfragment synopsis table term title \

     

       
21
       
21
       
-
       
toc variablelist varlistentry warning itemizedlist listitem \

     

       
22
       
22
       
-
       
footnote colspec partintro row simplelist subtitle tbody tgroup thead tip

     

       
23
       
23
       
-
       
  format      block

     

       
24
       
24
       
-
       
  normalize   no

     

       
25
       
25
       
-
       


     

       
26
       
26
       
-
       


     

       
27
       
27
       
-
       
#appendix bibliography chapter glossary preface reference

     

       
28
       
28
       
-
       
#  element-break   3

     

       
29
       
29
       
-
       


     

       
30
       
30
       
-
       
sect1 section

     

       
31
       
31
       
-
       
  element-break   2

     

       
32
       
32
       
-
       


     

       
33
       
33
       
-
       


     

       
34
       
34
       
-
       
#

     

       
35
       
35
       
-
       
para abstract

     

       
36
       
36
       
-
       
  format       block

     

       
37
       
37
       
-
       
  entry-break  1

     

       
38
       
38
       
-
       
  exit-break   1

     

       
39
       
39
       
-
       
  normalize    yes

     

       
40
       
40
       
-
       


     

       
41
       
41
       
-
       
title

     

       
42
       
42
       
-
       
  format       block

     

       
43
       
43
       
-
       
  normalize = yes

     

       
44
       
44
       
-
       
  entry-break = 0

     

       
45
       
45
       
-
       
  exit-break = 0

     

       
46
       
46
       
-
       


     

       
47
       
47
       
-
       
# Inline elements

     

       
48
       
48
       
-
       
abbrev accel acronym action application citation citebiblioid citerefentry citetitle \

     

       
49
       
49
       
-
       
classname co code command computeroutput constant country database date email emphasis \

     

       
50
       
50
       
-
       
envar errorcode errorname errortext errortype exceptionname fax filename \

     

       
51
       
51
       
-
       
firstname firstterm footnoteref foreignphrase funcdef funcparams function \

     

       
52
       
52
       
-
       
glossterm group guibutton guiicon guilabel guimenu guimenuitem guisubmenu \

     

       
53
       
53
       
-
       
hardware holder honorific indexterm inlineequation inlinegraphic inlinemediaobject \

     

       
54
       
54
       
-
       
interface interfacename \

     

       
55
       
55
       
-
       
keycap keycode keycombo keysym lineage link literal manvolnum markup medialabel \

     

       
56
       
56
       
-
       
menuchoice methodname methodparam modifier mousebutton olink ooclass ooexception \

     

       
57
       
57
       
-
       
oointerface option optional otheraddr othername package paramdef parameter personname \

     

       
58
       
58
       
-
       
phrase pob postcode productname prompt property quote refpurpose replaceable \

     

       
59
       
59
       
-
       
returnvalue revnumber sgmltag state street structfield structname subscript \

     

       
60
       
60
       
-
       
superscript surname symbol systemitem token trademark type ulink userinput \

     

       
61
       
61
       
-
       
uri varargs varname void wordasword xref year mathphrase member tag

     

       
62
       
62
       
-
       
  format       inline

     

       
63
       
63
       
-
       


     

       
64
       
64
       
-
       
programlisting screen

     

       
65
       
65
       
-
       
  format       verbatim

     

       
66
       
66
       
-
       
  entry-break = 0

     

       
67
       
67
       
-
       
  exit-break = 0

     

       
68
       
68
       
-
       


     

       
69
       
69
       
-
       
# This is needed so that the spacing inside those tags is kept.

     

       
70
       
70
       
-
       
term cmdsynopsis arg

     

       
71
       
71
       
-
       
  normalize yes

     

       
72
       
72
       
-
       
  format    block

     

···

       
1
       
1
       
+
       
# Functions reference {#chap-functions}

     

       
2
       
2
       
+
       


     

       
3
       
3
       
+
       
The nixpkgs repository has several utility functions to manipulate Nix expressions.

     

       
4
       
4
       
+
       


     

       
5
       
5
       
+
       
```{=include=} sections

     

       
6
       
6
       
+
       
functions/library.md

     

       
7
       
7
       
+
       
functions/generators.section.md

     

       
8
       
8
       
+
       
functions/debug.section.md

     

       
9
       
9
       
+
       
functions/prefer-remote-fetch.section.md

     

       
10
       
10
       
+
       
functions/nix-gitignore.section.md

     

       
11
       
11
       
+
       
```

     

···

       
1
       
1
       
-
       
<chapter xmlns="http://docbook.org/ns/docbook"

     

       
2
       
2
       
-
       
         xmlns:xlink="http://www.w3.org/1999/xlink"

     

       
3
       
3
       
-
       
         xmlns:xi="http://www.w3.org/2001/XInclude"

     

       
4
       
4
       
-
       
         xml:id="chap-functions">

     

       
5
       
5
       
-
       
 <title>Functions reference</title>

     

       
6
       
6
       
-
       
 <para>

     

       
7
       
7
       
-
       
  The nixpkgs repository has several utility functions to manipulate Nix expressions.

     

       
8
       
8
       
-
       
 </para>

     

       
9
       
9
       
-
       
 <xi:include href="functions/library.xml" />

     

       
10
       
10
       
-
       
 <xi:include href="functions/generators.section.xml" />

     

       
11
       
11
       
-
       
 <xi:include href="functions/debug.section.xml" />

     

       
12
       
12
       
-
       
 <xi:include href="functions/prefer-remote-fetch.section.xml" />

     

       
13
       
13
       
-
       
 <xi:include href="functions/nix-gitignore.section.xml" />

     

       
14
       
14
       
-
       
</chapter>