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.
This commit is contained in:
pennae
parent
2ecc93d6fe
commit
2f76a3df64
|
|
@ -41,32 +41,18 @@ The function is implemented in [pkgs/development/bower-modules/generic/default.n
|
|||
|
||||
### Example buildBowerComponents {#ex-buildBowerComponents}
|
||||
|
||||
```{=docbook}
|
||||
<programlisting language="nix">
|
||||
```nix
|
||||
bowerComponents = buildBowerComponents {
|
||||
name = "my-web-app";
|
||||
generated = ./bower-packages.nix; <co xml:id="ex-buildBowerComponents-1" />
|
||||
src = myWebApp; <co xml:id="ex-buildBowerComponents-2" />
|
||||
generated = ./bower-packages.nix; # note 1
|
||||
src = myWebApp; # note 2
|
||||
};
|
||||
</programlisting>
|
||||
```
|
||||
|
||||
In ["buildBowerComponents" example](#ex-buildBowerComponents) the following arguments are of special significance to the function:
|
||||
|
||||
```{=docbook}
|
||||
<calloutlist>
|
||||
<callout arearefs="ex-buildBowerComponents-1">
|
||||
<para>
|
||||
<varname>generated</varname> specifies the file which was created by <command>bower2nix</command>.
|
||||
</para>
|
||||
</callout>
|
||||
<callout arearefs="ex-buildBowerComponents-2">
|
||||
<para>
|
||||
<varname>src</varname> is your project's sources. It needs to contain a <filename>bower.json</filename> file.
|
||||
</para>
|
||||
</callout>
|
||||
</calloutlist>
|
||||
```
|
||||
1. `generated` specifies the file which was created by {command}`bower2nix`.
|
||||
2. `src` is your project's sources. It needs to contain a {file}`bower.json` file.
|
||||
|
||||
`buildBowerComponents` will run Bower to link together the output of `bower2nix`, resulting in a `bower_components` directory which can be used.
|
||||
|
||||
|
|
@ -91,10 +77,9 @@ gulp.task('build', [], function () {
|
|||
|
||||
### Example Full example — default.nix {#ex-buildBowerComponentsDefaultNix}
|
||||
|
||||
```{=docbook}
|
||||
<programlisting language="nix">
|
||||
```nix
|
||||
{ myWebApp ? { outPath = ./.; name = "myWebApp"; }
|
||||
, pkgs ? import <nixpkgs> {}
|
||||
, pkgs ? import <nixpkgs> {}
|
||||
}:
|
||||
|
||||
pkgs.stdenv.mkDerivation {
|
||||
|
|
@ -103,49 +88,29 @@ pkgs.stdenv.mkDerivation {
|
|||
|
||||
buildInputs = [ pkgs.nodePackages.gulp ];
|
||||
|
||||
bowerComponents = pkgs.buildBowerComponents { <co xml:id="ex-buildBowerComponentsDefault-1" />
|
||||
bowerComponents = pkgs.buildBowerComponents { # note 1
|
||||
name = "my-web-app";
|
||||
generated = ./bower-packages.nix;
|
||||
src = myWebApp;
|
||||
};
|
||||
|
||||
buildPhase = ''
|
||||
cp --reflink=auto --no-preserve=mode -R $bowerComponents/bower_components . <co xml:id="ex-buildBowerComponentsDefault-2" />
|
||||
export HOME=$PWD <co xml:id="ex-buildBowerComponentsDefault-3" />
|
||||
${pkgs.nodePackages.gulp}/bin/gulp build <co xml:id="ex-buildBowerComponentsDefault-4" />
|
||||
cp --reflink=auto --no-preserve=mode -R $bowerComponents/bower_components . # note 2
|
||||
export HOME=$PWD # note 3
|
||||
${pkgs.nodePackages.gulp}/bin/gulp build # note 4
|
||||
'';
|
||||
|
||||
installPhase = "mv gulpdist $out";
|
||||
}
|
||||
</programlisting>
|
||||
```
|
||||
|
||||
A few notes about [Full example — `default.nix`](#ex-buildBowerComponentsDefaultNix):
|
||||
|
||||
```{=docbook}
|
||||
<calloutlist>
|
||||
<callout arearefs="ex-buildBowerComponentsDefault-1">
|
||||
<para>
|
||||
The result of <varname>buildBowerComponents</varname> is an input to the frontend build.
|
||||
</para>
|
||||
</callout>
|
||||
<callout arearefs="ex-buildBowerComponentsDefault-2">
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</callout>
|
||||
<callout arearefs="ex-buildBowerComponentsDefault-3">
|
||||
<para>
|
||||
<command>gulp</command> requires <varname>HOME</varname> to refer to a writeable directory.
|
||||
</para>
|
||||
</callout>
|
||||
<callout arearefs="ex-buildBowerComponentsDefault-4">
|
||||
<para>
|
||||
The actual build command. Other tools could be used.
|
||||
</para>
|
||||
</callout>
|
||||
</calloutlist>
|
||||
```
|
||||
1. The result of `buildBowerComponents` is an input to the frontend build.
|
||||
2. Whether to symlink or copy the {file}`bower_components` directory depends on the build tool in use.
|
||||
In this case a copy is used to avoid {command}`gulp` silliness with permissions.
|
||||
3. {command}`gulp` requires `HOME` to refer to a writeable directory.
|
||||
4. The actual build command in this example is {command}`gulp`. Other tools could be used instead.
|
||||
|
||||
## Troubleshooting {#ssec-bower2nix-troubleshooting}
|
||||
|
||||
|
|
|
|||
|
|
@ -10,37 +10,22 @@ pure and explicit at build-time, at the cost of introducing an extra indirection
|
|||
|
||||
## Nix expression for a Qt package (default.nix) {#qt-default-nix}
|
||||
|
||||
```{=docbook}
|
||||
<programlisting>
|
||||
{ stdenv, lib, qtbase, wrapQtAppsHook }: <co xml:id='qt-default-nix-co-1' />
|
||||
```nix
|
||||
{ stdenv, lib, qtbase, wrapQtAppsHook }:
|
||||
|
||||
stdenv.mkDerivation {
|
||||
pname = "myapp";
|
||||
version = "1.0";
|
||||
|
||||
buildInputs = [ qtbase ];
|
||||
nativeBuildInputs = [ wrapQtAppsHook ]; <co xml:id='qt-default-nix-co-2' />
|
||||
nativeBuildInputs = [ wrapQtAppsHook ];
|
||||
}
|
||||
</programlisting>
|
||||
|
||||
<calloutlist>
|
||||
<callout arearefs='qt-default-nix-co-1'>
|
||||
<para>
|
||||
Import Qt modules directly, that is: <literal>qtbase</literal>, <literal>qtdeclarative</literal>, etc.
|
||||
<emphasis>Do not</emphasis> import Qt package sets such as <literal>qt5</literal>
|
||||
because the Qt versions of dependencies may not be coherent, causing build and runtime failures.
|
||||
</para>
|
||||
</callout>
|
||||
<callout arearefs='qt-default-nix-co-2'>
|
||||
<para>
|
||||
All Qt packages must include <literal>wrapQtAppsHook</literal> in
|
||||
<literal>nativeBuildInputs</literal>, or you must explicitly set
|
||||
<literal>dontWrapQtApps</literal>.
|
||||
</para>
|
||||
</callout>
|
||||
</calloutlist>
|
||||
```
|
||||
|
||||
It is important to import Qt modules directly, that is: `qtbase`, `qtdeclarative`, etc. *Do not* import Qt package sets such as `qt5` because the Qt versions of dependencies may not be coherent, causing build and runtime failures.
|
||||
|
||||
Additionally all Qt packages must include `wrapQtAppsHook` in `nativeBuildInputs`, or you must explicitly set `dontWrapQtApps`.
|
||||
|
||||
## Locating runtime dependencies {#qt-runtime-dependencies}
|
||||
|
||||
Qt applications must be wrapped to find runtime dependencies.
|
||||
|
|
|
|||
Loading…
Reference in a new issue