nordic-dev.net/nixpkgs
nordic-dev.net/nixpkgs
2
0
Fork 0
mirror of https://github.com/NixOS/nixpkgs.git synced 2024-10-31 06:31:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: don't use docbook program listings/callouts

Browse Source 
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 2023-06-10 18:13:33 +02:00
parent 2ecc93d6fe
commit 2f76a3df64
2 changed files with 23 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
doc/languages-frameworks/bower.section.md
View File

@ -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 &lt;nixpkgs&gt; {}
, 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}

29
doc/languages-frameworks/qt.section.md
View File

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