doc/hooks/waf.section.md: rewrite

- Normalize header IDs, in order to not cause conflicts with identically named
  headers in other docs.
- Reorganize the hierarchy of information.
This commit is contained in:
Anderson Torres 2023-09-10 08:56:09 -03:00
parent 2785d92e77
commit a0b25e2566

View File

@ -1,50 +1,58 @@
# waf.hook {#wafhook}
# wafHook {#waf-hook}
[Waf](https://waf.io) is a Python-based software building system.
In Nixpkgs, `waf.hook` overrides the default configure, build, and install phases.
In Nixpkgs, `wafHook` overrides the default configure, build, and install phases.
## Variables controlling waf.hook {#variablesControllingWafHook}
## Variables controlling wafHook {#waf-hook-variables-controlling}
### `wafPath` {#wafPath}
### `wafHook` Exclusive Variables {#waf-hook-exclusive-variables}
The variables below are exclusive of `wafHook`.
#### `wafPath` {#waf-path}
Location of the `waf` tool. It defaults to `./waf`, to honor software projects that include it directly inside their source trees.
If `wafPath` doesn't exist, then `waf.hook` will copy the `waf` provided from Nixpkgs to it.
If `wafPath` doesn't exist, then `wafHook` will copy the `waf` provided from Nixpkgs to it.
### `wafConfigureFlags` {#wafConfigureFlags}
#### `wafFlags` {#waf-flags}
Controls the flags passed to waf tool during configure phase.
Controls the flags passed to waf tool during build and install phases. For settings specific to build or install phases, use `wafBuildFlags` or `wafInstallFlags` respectively.
### `wafFlags` {#wafFlags}
Controls the flags passed to waf tool during build and install phases.
### `dontAddWafCrossFlags` {#dontAddWafCrossFlags}
#### `dontAddWafCrossFlags` {#dont-add-waf-cross-flags}
When set to `true`, don't add cross compilation flags during configure phase.
### `dontUseWafConfigure` {#dontUseWafConfigure}
#### `dontUseWafConfigure` {#dont-use-waf-configure}
When set to true, don't use the predefined `wafConfigurePhase`.
### `dontUseWafBuild` {#dontUseWafBuild}
#### `dontUseWafBuild` {#dont-use-waf-build}
When set to true, don't use the predefined `wafBuildPhase`.
### `dontUseWafInstall` {#dontUseWafInstall}
#### `dontUseWafInstall` {#dont-use-waf-install}
When set to true, don't use the predefined `wafInstallPhase`.
### Variables honored by waf.hook {#variablesHonoredByWafHook}
### Similar variables {#waf-hook-similar-variables}
The following variables commonly used by `stdenv.mkDerivation` are also honored by `waf.hook`.
The following variables are similar to their `stdenv.mkDerivation` counterparts.
| `wafHook` Variable | `stdenv.mkDerivation` Counterpart |
|-----------------------|-----------------------------------|
| `wafConfigureFlags` | `configureFlags` |
| `wafConfigureTargets` | `configureTargets` |
| `wafBuildFlags` | `buildFlags` |
| `wafBuildTargets` | `buildTargets` |
| `wafInstallFlags` | `installFlags` |
| `wafInstallTargets` | `installTargets` |
### Honored variables {#waf-hook-honored-variables}
The following variables commonly used by `stdenv.mkDerivation` are honored by `wafHook`.
- `prefixKey`
- `configureTargets`
- `enableParallelBuilding`
- `enableParallelInstalling`
- `buildFlags`
- `buildTargets`
- `installFlags`
- `installTargets`