diff --git a/doc/hooks/index.md b/doc/hooks/index.md index e7b5972c84d7..8338c4629fd0 100644 --- a/doc/hooks/index.md +++ b/doc/hooks/index.md @@ -28,6 +28,11 @@ libxml2.section.md meson.section.md mpi-check-hook.section.md ninja.section.md +nodejs-install-executables.section.md +nodejs-install-manuals.section.md +npm-build-hook.section.md +npm-config-hook.section.md +npm-install-hook.section.md patch-rc-path-hooks.section.md perl.section.md pkg-config.section.md diff --git a/doc/hooks/nodejs-install-executables.section.md b/doc/hooks/nodejs-install-executables.section.md new file mode 100644 index 000000000000..7cf1f9ef20e6 --- /dev/null +++ b/doc/hooks/nodejs-install-executables.section.md @@ -0,0 +1,29 @@ +# nodejsInstallExecutables {#nodejs-install-executables} + +Hook for wrapping Node.js executables. +Primarily created for a multi-language environment. + +## Examples {#nodejs-install-executables-example} + +[](#npm-build-hook-example-snippet) + +## Variables controlling `nodejsInstallExecutables` {#nodejs-install-executables-variables} + +### `nodejsInstallExecutables` Exclusive Variables {#nodejs-install-executables-exclusive-variables} + +#### `makeWrapperArgs` {#nodejs-install-executables-wrapper-args} + +Flags to pass to the call to [`makeWrapper`](#fun-makeWrapper). +To avoid double-wrapping, this flag can also be accessed in Bash. + +```nix +stdenv.mkDerivation (finalAttrs: { + #... + dontWrapGApps = true; + + postInstall = '' + makeWrapperArgs+=("''${gappsWrapperArgs[@]}") + ''; + #... +}) +``` diff --git a/doc/hooks/nodejs-install-manuals.section.md b/doc/hooks/nodejs-install-manuals.section.md new file mode 100644 index 000000000000..454769e32b96 --- /dev/null +++ b/doc/hooks/nodejs-install-manuals.section.md @@ -0,0 +1,12 @@ +# nodejsInstallManuals {#nodejs-install-manuals} + +Detects manuals in Node.js packages, and attempts to install them in standard locations. +This detection is done by inspecting the package.json of the project and finding any entries +with type `man`. + + +There are no ways currently to configure this hook. + +## Examples {#nodejs-install-manuals-example} + +[](#npm-build-hook-example-snippet) diff --git a/doc/hooks/npm-build-hook.section.md b/doc/hooks/npm-build-hook.section.md new file mode 100644 index 000000000000..a3cda18b4449 --- /dev/null +++ b/doc/hooks/npm-build-hook.section.md @@ -0,0 +1,93 @@ +# npmHooks.npmBuildHook {#npm-build-hook} + +Hook for building packages that use npm. Can be used in multi-language environments. + +## Examples {#npm-build-hook-snippet} + +:::{.example #npm-build-hook-example-snippet} + +# Using `npmHooks` + +```nix +{ + stdenv, + fetchFromGitHub, + fetchNpmDeps, + npmHooks, + nodejsInstallExecutables, + nodejsInstallManuals, + nodejs, +}: +stdenv.mkDerivation (finalAttrs: { + pname = "some-npm-project"; + version = "1.0"; + + src = fetchFromGitHub { + owner = "JohnNpm"; + repo = "SomeProject"; + tag = finalAttrs.version; + hash = "..."; + }; + + strictDeps = true; + + nativeBuildInputs = [ + nodejs + nodejsInstallExecutables + nodejsInstallManuals + npmHooks.npmConfigHook + npmHooks.npmBuildHook + npmHooks.npmInstallHook + ]; + + npmBuildScript = "build"; + + npmBuildFlags = [ + "--prod" + ]; + + npmFlags = [ + "--ignore-scripts" + ]; + + npmDeps = fetchNpmDeps { + inherit (finalAttrs) src; + hash = "..."; + }; + + makeWrapperArgs = [ + "--set" + "NODE_ENV" + "production" + ]; + + meta = { + description = "npm project"; + }; +}) +``` +::: + +## Variables controlling `npmBuildHook` {#npm-build-hook-variables} + +### `npmBuildHook` Exclusive Variables {#npm-build-hook-exclusive-variables} + +#### `npmBuildScript` {#npm-build-hook-script} + +Controls the script ran to build the npm package within the `package.json` file. +Required to be set, usually to `build`, but can vary between packages. + +#### `npmBuildFlags` {#npm-build-hook-flags} + +Controls the arguments to the {command}`npm run $npmBuildScript` command. + +#### `dontNpmBuild` {#npm-build-hook-dont} + +Disables `npmBuildHook` when enabled + +### Honored Variables {#npm-build-hook-honored-variables} + +The following variables are honored by the `npmBuildHook`. + +- [`npmWorkspace`](#javascript-buildNpmPackage-npmWorkspace) +- [`npmFlags`](#javascript-buildNpmPackage-npmFlags) diff --git a/doc/hooks/npm-config-hook.section.md b/doc/hooks/npm-config-hook.section.md new file mode 100644 index 000000000000..0b1298457605 --- /dev/null +++ b/doc/hooks/npm-config-hook.section.md @@ -0,0 +1,41 @@ +# npmHooks.npmConfigHook {#npm-config-hook} + +Hook for configuring packages that use npm. +Primarily made for a multi-language environment. + +## Examples {#npm-config-hook-snippet} + +[](#npm-build-hook-example-snippet) + +## Variables controlling `npmConfigHook` {#npm-config-hook-variables} + +### `npmConfigHook` Exclusive Variables {#npm-config-hook-exclusive-variables} + +#### `npmDeps` {#npm-config-hook-deps} + +Derivation that contains the NPM package dependencies. +Usually built with `fetchNpmDeps`. +This attribute is required or the hook will abort the build. + +#### `makeCacheWritable` {#npm-config-hook-writable-cache} + +Whether to make the dependency cache writable prior to installing the dependencies. +Don't set this unless npm tries to write to the cache directory. + +#### `npmInstallFlags` {#npm-config-hook-install-flags} + +Flags to pass to the {command}`npm ci` call for installing the dependencies to the build environment. +Defaults to `--ignore-scripts`, which cannot be removed. +This does not control anything with the `npmInstallHook`. + +#### `npmRebuildFlags` {#npm-config-hook-rebuild-flags} + +Flags to pass to the {command}`npm rebuild` command after the dependencies are installed to the environment. + +### Honored Variables {#npm-config-hook-honored-variables} + +The following variables are honored by the `npmConfigHook`. + +- [`npmWorkspace`](#javascript-buildNpmPackage-npmWorkspace) +- [`npmFlags`](#javascript-buildNpmPackage-npmFlags) +- `npmRoot` diff --git a/doc/hooks/npm-install-hook.section.md b/doc/hooks/npm-install-hook.section.md new file mode 100644 index 000000000000..f099aec13b4a --- /dev/null +++ b/doc/hooks/npm-install-hook.section.md @@ -0,0 +1,35 @@ +# npmHooks.npmInstallHook {#npm-install-hook} + +Hook to install node_modules for npm packages. +Does not create wrappers for executable npm projects +Primarily made for a multi-language environment. + +## Examples {#npm-install-hook-snippet} + +[](#npm-build-hook-example-snippet) + +## Variables controlling `npmInstallHook` {#npm-install-hook-variables} + +### `npmInstallHook` Exclusive Variables {#npm-install-hook-exclusive-variables} + +#### `dontNpmPrune` {#npm-install-hook-dont-prune} + +Whether to run {command}`npm prune` on the `node_modules` or not. +Defaults to `true`. + +#### `npmInstallFlags` {#npm-install-hook-prune-flags} + +Flags to pass to the {command}`npm prune` call for the `node_modules` of the package. +Defaults to `--omit=dev --no-save` which cannot be modified. + +#### `dontNpmInstall` {#npm-install-hook-dont} + +Controls whether `npmInstallHook` is enabled or not. +Defaults to `true`, so the hook will run. + +### Honored Variables {#npm-install-hook-honored-variables} + +The following variables are honored by the `npmInstallHook`. + +- [`npmWorkspace`](#javascript-buildNpmPackage-npmWorkspace) +- [`npmFlags`](#javascript-buildNpmPackage-npmFlags) diff --git a/doc/languages-frameworks/javascript.section.md b/doc/languages-frameworks/javascript.section.md index 3af4d1d86099..d6ee39da6c33 100644 --- a/doc/languages-frameworks/javascript.section.md +++ b/doc/languages-frameworks/javascript.section.md @@ -147,10 +147,10 @@ If these are not defined, `npm pack` may miss some files, and no binaries will b * `npmDepsHash`: The output hash of the dependencies for this project. Can be calculated in advance with [`prefetch-npm-deps`](#javascript-buildNpmPackage-prefetch-npm-deps). * `makeCacheWritable`: Whether to make the cache writable prior to installing dependencies. Don't set this unless npm tries to write to the cache directory, as it can slow down the build. * `npmBuildScript`: The script to run to build the project. Defaults to `"build"`. -* `npmWorkspace`: The workspace directory within the project to build and install. +* []{#javascript-buildNpmPackage-npmWorkspace} `npmWorkspace`: The workspace directory within the project to build and install. * `dontNpmBuild`: Option to disable running the build script. Set to `true` if the package does not have a build script. Defaults to `false`. Alternatively, setting `buildPhase` explicitly also disables this. * `dontNpmInstall`: Option to disable running `npm install`. Defaults to `false`. Alternatively, setting `installPhase` explicitly also disables this. -* `npmFlags`: Flags to pass to all npm commands. +* []{#javascript-buildNpmPackage-npmFlags} `npmFlags`: Flags to pass to all npm commands. * `npmInstallFlags`: Flags to pass to `npm ci`. * `npmBuildFlags`: Flags to pass to `npm run ${npmBuildScript}`. * `npmPackFlags`: Flags to pass to `npm pack`. diff --git a/doc/redirects.json b/doc/redirects.json index 5c3b47442084..aa574709a71f 100644 --- a/doc/redirects.json +++ b/doc/redirects.json @@ -134,6 +134,12 @@ "inkscape-plugins": [ "index.html#inkscape-plugins" ], + "javascript-buildNpmPackage-npmFlags": [ + "index.html#javascript-buildNpmPackage-npmFlags" + ], + "javascript-buildNpmPackage-npmWorkspace": [ + "index.html#javascript-buildNpmPackage-npmWorkspace" + ], "libcxxhardeningextensive": [ "index.html#libcxxhardeningextensive" ], @@ -206,9 +212,108 @@ "no-broken-symlinks.sh": [ "index.html#no-broken-symlinks.sh" ], + "nodejs-install-executables": [ + "index.html#nodejs-install-executables" + ], + "nodejs-install-executables-example": [ + "index.html#nodejs-install-executables-example" + ], + "nodejs-install-executables-exclusive-variables": [ + "index.html#nodejs-install-executables-exclusive-variables" + ], + "nodejs-install-executables-variables": [ + "index.html#nodejs-install-executables-variables" + ], + "nodejs-install-executables-wrapper-args": [ + "index.html#nodejs-install-executables-wrapper-args" + ], + "nodejs-install-manuals": [ + "index.html#nodejs-install-manuals" + ], + "nodejs-install-manuals-example": [ + "index.html#nodejs-install-manuals-example" + ], "nostrictaliasing": [ "index.html#nostrictaliasing" ], + "npm-build-hook": [ + "index.html#npm-build-hook" + ], + "npm-build-hook-dont": [ + "index.html#npm-build-hook-dont" + ], + "npm-build-hook-example-snippet": [ + "index.html#npm-build-hook-example-snippet" + ], + "npm-build-hook-exclusive-variables": [ + "index.html#npm-build-hook-exclusive-variables" + ], + "npm-build-hook-flags": [ + "index.html#npm-build-hook-flags" + ], + "npm-build-hook-honored-variables": [ + "index.html#npm-build-hook-honored-variables" + ], + "npm-build-hook-script": [ + "index.html#npm-build-hook-script" + ], + "npm-build-hook-snippet": [ + "index.html#npm-build-hook-snippet" + ], + "npm-build-hook-variables": [ + "index.html#npm-build-hook-variables" + ], + "npm-config-hook": [ + "index.html#npm-config-hook" + ], + "npm-config-hook-deps": [ + "index.html#npm-config-hook-deps" + ], + "npm-config-hook-exclusive-variables": [ + "index.html#npm-config-hook-exclusive-variables" + ], + "npm-config-hook-honored-variables": [ + "index.html#npm-config-hook-honored-variables" + ], + "npm-config-hook-install-flags": [ + "index.html#npm-config-hook-install-flags" + ], + "npm-config-hook-rebuild-flags": [ + "index.html#npm-config-hook-rebuild-flags" + ], + "npm-config-hook-snippet": [ + "index.html#npm-config-hook-snippet" + ], + "npm-config-hook-variables": [ + "index.html#npm-config-hook-variables" + ], + "npm-config-hook-writable-cache": [ + "index.html#npm-config-hook-writable-cache" + ], + "npm-install-hook": [ + "index.html#npm-install-hook" + ], + "npm-install-hook-dont": [ + "index.html#npm-install-hook-dont" + ], + "npm-install-hook-dont-prune": [ + "index.html#npm-install-hook-dont-prune" + ], + "npm-install-hook-exclusive-variables": [ + "index.html#npm-install-hook-exclusive-variables" + ], + "npm-install-hook-honored-variables": [ + "index.html#npm-install-hook-honored-variables" + ], + "npm-install-hook-prune-flags": [ + "index.html#npm-install-hook-prune-flags" + ], + "npm-install-hook-snippet": [ + "index.html#npm-install-hook-snippet" + ], + "npm-install-hook-variables": [ + "index.html#npm-install-hook-variables" + ], "pkgs-replacevars": [ "index.html#pkgs-replacevars", "index.html#pkgs-substituteall",