pyrox.dev
doc: don't use docbook program listings/callouts
nixos-render-docs does not support this, and since the examples are
small there isn't that much value in callouts here. change them to
simple MD code blocks and lists instead.
+16
-51
doc/languages-frameworks/bower.section.md
+16
-51
doc/languages-frameworks/bower.section.md
···
41
41
42
42
### Example buildBowerComponents {#ex-buildBowerComponents}
43
43
44
-
```{=docbook}
45
-
<programlisting language="nix">
44
+
```nix
46
45
bowerComponents = buildBowerComponents {
47
46
name = "my-web-app";
48
-
generated = ./bower-packages.nix; <co xml:id="ex-buildBowerComponents-1" />
49
-
src = myWebApp; <co xml:id="ex-buildBowerComponents-2" />
47
+
generated = ./bower-packages.nix; # note 1
48
+
src = myWebApp; # note 2
50
49
};
51
-
</programlisting>
52
50
```
53
51
54
52
In ["buildBowerComponents" example](#ex-buildBowerComponents) the following arguments are of special significance to the function:
55
53
56
-
```{=docbook}
57
-
<calloutlist>
58
-
<callout arearefs="ex-buildBowerComponents-1">
59
-
<para>
60
-
<varname>generated</varname> specifies the file which was created by <command>bower2nix</command>.
61
-
</para>
62
-
</callout>
63
-
<callout arearefs="ex-buildBowerComponents-2">
64
-
<para>
65
-
<varname>src</varname> is your project's sources. It needs to contain a <filename>bower.json</filename> file.
66
-
</para>
67
-
</callout>
68
-
</calloutlist>
69
-
```
54
+
1. `generated` specifies the file which was created by {command}`bower2nix`.
55
+
2. `src` is your project's sources. It needs to contain a {file}`bower.json` file.
70
56
71
57
`buildBowerComponents` will run Bower to link together the output of `bower2nix`, resulting in a `bower_components` directory which can be used.
72
58
···
91
77
92
78
### Example Full example — default.nix {#ex-buildBowerComponentsDefaultNix}
93
79
94
-
```{=docbook}
95
-
<programlisting language="nix">
80
+
```nix
96
81
{ myWebApp ? { outPath = ./.; name = "myWebApp"; }
97
-
, pkgs ? import <nixpkgs> {}
82
+
, pkgs ? import <nixpkgs> {}
98
83
}:
99
84
100
85
pkgs.stdenv.mkDerivation {
···
103
88
104
89
buildInputs = [ pkgs.nodePackages.gulp ];
105
90
106
-
bowerComponents = pkgs.buildBowerComponents { <co xml:id="ex-buildBowerComponentsDefault-1" />
91
+
bowerComponents = pkgs.buildBowerComponents { # note 1
107
92
name = "my-web-app";
108
93
generated = ./bower-packages.nix;
109
94
src = myWebApp;
110
95
};
111
96
112
97
buildPhase = ''
113
-
cp --reflink=auto --no-preserve=mode -R $bowerComponents/bower_components . <co xml:id="ex-buildBowerComponentsDefault-2" />
114
-
export HOME=$PWD <co xml:id="ex-buildBowerComponentsDefault-3" />
115
-
${pkgs.nodePackages.gulp}/bin/gulp build <co xml:id="ex-buildBowerComponentsDefault-4" />
98
+
cp --reflink=auto --no-preserve=mode -R $bowerComponents/bower_components . # note 2
99
+
export HOME=$PWD # note 3
100
+
${pkgs.nodePackages.gulp}/bin/gulp build # note 4
116
101
'';
117
102
118
103
installPhase = "mv gulpdist $out";
119
104
}
120
-
</programlisting>
121
105
```
122
106
123
107
A few notes about [Full example — `default.nix`](#ex-buildBowerComponentsDefaultNix):
124
108
125
-
```{=docbook}
126
-
<calloutlist>
127
-
<callout arearefs="ex-buildBowerComponentsDefault-1">
128
-
<para>
129
-
The result of <varname>buildBowerComponents</varname> is an input to the frontend build.
130
-
</para>
131
-
</callout>
132
-
<callout arearefs="ex-buildBowerComponentsDefault-2">
133
-
<para>
134
-
Whether to symlink or copy the <filename>bower_components</filename> directory depends on the build tool in use. In this case a copy is used to avoid <command>gulp</command> silliness with permissions.
135
-
</para>
136
-
</callout>
137
-
<callout arearefs="ex-buildBowerComponentsDefault-3">
138
-
<para>
139
-
<command>gulp</command> requires <varname>HOME</varname> to refer to a writeable directory.
140
-
</para>
141
-
</callout>
142
-
<callout arearefs="ex-buildBowerComponentsDefault-4">
143
-
<para>
144
-
The actual build command. Other tools could be used.
145
-
</para>
146
-
</callout>
147
-
</calloutlist>
148
-
```
109
+
1. The result of `buildBowerComponents` is an input to the frontend build.
110
+
2. Whether to symlink or copy the {file}`bower_components` directory depends on the build tool in use.
111
+
In this case a copy is used to avoid {command}`gulp` silliness with permissions.
112
+
3. {command}`gulp` requires `HOME` to refer to a writeable directory.
113
+
4. The actual build command in this example is {command}`gulp`. Other tools could be used instead.
149
114
150
115
## Troubleshooting {#ssec-bower2nix-troubleshooting}
151
116
+7
-22
doc/languages-frameworks/qt.section.md
+7
-22
doc/languages-frameworks/qt.section.md
···
10
10
11
11
## Nix expression for a Qt package (default.nix) {#qt-default-nix}
12
12
13
-
```{=docbook}
14
-
<programlisting>
15
-
{ stdenv, lib, qtbase, wrapQtAppsHook }: <co xml:id='qt-default-nix-co-1' />
13
+
```nix
14
+
{ stdenv, lib, qtbase, wrapQtAppsHook }:
16
15
17
16
stdenv.mkDerivation {
18
17
pname = "myapp";
19
18
version = "1.0";
20
19
21
20
buildInputs = [ qtbase ];
22
-
nativeBuildInputs = [ wrapQtAppsHook ]; <co xml:id='qt-default-nix-co-2' />
21
+
nativeBuildInputs = [ wrapQtAppsHook ];
23
22
}
24
-
</programlisting>
23
+
```
25
24
26
-
<calloutlist>
27
-
<callout arearefs='qt-default-nix-co-1'>
28
-
<para>
29
-
Import Qt modules directly, that is: <literal>qtbase</literal>, <literal>qtdeclarative</literal>, etc.
30
-
<emphasis>Do not</emphasis> import Qt package sets such as <literal>qt5</literal>
31
-
because the Qt versions of dependencies may not be coherent, causing build and runtime failures.
32
-
</para>
33
-
</callout>
34
-
<callout arearefs='qt-default-nix-co-2'>
35
-
<para>
36
-
All Qt packages must include <literal>wrapQtAppsHook</literal> in
37
-
<literal>nativeBuildInputs</literal>, or you must explicitly set
38
-
<literal>dontWrapQtApps</literal>.
39
-
</para>
40
-
</callout>
41
-
</calloutlist>
42
-
```
25
+
It is important to import Qt modules directly, that is: `qtbase`, `qtdeclarative`, etc. *Do not* import Qt package sets such as `qt5` because the Qt versions of dependencies may not be coherent, causing build and runtime failures.
26
+
27
+
Additionally all Qt packages must include `wrapQtAppsHook` in `nativeBuildInputs`, or you must explicitly set `dontWrapQtApps`.
43
28
44
29
## Locating runtime dependencies {#qt-runtime-dependencies}
45
30