diff options
author | github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> | 2024-06-07 00:13:56 +0000 |
---|---|---|
committer | GitHub <noreply@github.com> | 2024-06-07 00:13:56 +0000 |
commit | a5d1b908b4c7e30c9305b814ae9adea475e975ca (patch) | |
tree | fd5f9cde0b75554f7d06c083831a84f74dfd182c /doc/languages-frameworks | |
parent | f166c7778ccf61d7f8b89a9a94060dce070458d0 (diff) | |
parent | 4549509555e834dc567ba15d4fcd49efa8b14b6e (diff) |
Merge master into haskell-updates
Diffstat (limited to 'doc/languages-frameworks')
-rw-r--r-- | doc/languages-frameworks/hare.section.md | 53 | ||||
-rw-r--r-- | doc/languages-frameworks/index.md | 1 | ||||
-rw-r--r-- | doc/languages-frameworks/javascript.section.md | 65 |
3 files changed, 119 insertions, 0 deletions
diff --git a/doc/languages-frameworks/hare.section.md b/doc/languages-frameworks/hare.section.md new file mode 100644 index 0000000000000..0ae8abeba45c1 --- /dev/null +++ b/doc/languages-frameworks/hare.section.md @@ -0,0 +1,53 @@ +# Hare {#sec-language-hare} + +## Building Hare programs with `hareHook` {#ssec-language-hare} + +The `hareHook` package sets up the environment for building Hare programs by +doing the following: + +1. Setting the `HARECACHE`, `HAREPATH` and `NIX_HAREFLAGS` environment variables; +1. Propagating `harec`, `qbe` and two wrapper scripts for the hare binary. + +It is not a function as is the case for some other languages --- *e. g.*, Go or +Rust ---, but a package to be added to `nativeBuildInputs`. + +## Attributes of `hareHook` {#hareHook-attributes} + +The following attributes are accepted by `hareHook`: + +1. `hareBuildType`: Either `release` (default) or `debug`. It controls if the + `-R` flag is added to `NIX_HAREFLAGS`. + +## Example for `hareHook` {#ex-hareHook} + +```nix +{ + hareHook, + lib, + stdenv, +}: stdenv.mkDerivation { + pname = "<name>"; + version = "<version>"; + src = "<src>"; + + nativeBuildInputs = [ hareHook ]; + + meta = { + description = "<description>"; + inherit (hareHook) badPlatforms platforms; + }; +} +``` + +## Cross Compilation {#hareHook-cross-compilation} + +`hareHook` should handle cross compilation out of the box. This is the main +purpose of `NIX_HAREFLAGS`: In it, the `-a` flag is passed with the architecture +of the `hostPlatform`. + +However, manual intervention may be needed when a binary compiled by the build +process must be run for the build to complete --- *e. g.*, when using Hare's +`hare` module for code generation. + +In those cases, `hareHook` provides the `hare-native` script, which is a wrapper +around the hare binary for using the native (`buildPlatform`) toolchain. diff --git a/doc/languages-frameworks/index.md b/doc/languages-frameworks/index.md index 920e5e7bd431e..e8fee9c45216c 100644 --- a/doc/languages-frameworks/index.md +++ b/doc/languages-frameworks/index.md @@ -19,6 +19,7 @@ dotnet.section.md emscripten.section.md gnome.section.md go.section.md +hare.section.md haskell.section.md hy.section.md idris.section.md diff --git a/doc/languages-frameworks/javascript.section.md b/doc/languages-frameworks/javascript.section.md index f706f92c6691f..76db9d0007ce5 100644 --- a/doc/languages-frameworks/javascript.section.md +++ b/doc/languages-frameworks/javascript.section.md @@ -310,6 +310,71 @@ See `node2nix` [docs](https://github.com/svanderburg/node2nix) for more info. - `node2nix` has some [bugs](https://github.com/svanderburg/node2nix/issues/238) related to working with lock files from npm distributed with `nodejs_16`. - `node2nix` does not like missing packages from npm. If you see something like `Cannot resolve version: vue-loader-v16@undefined` then you might want to try another tool. The package might have been pulled off of npm. +### pnpm {#javascript-pnpm} + +Pnpm is available as the top-level package `pnpm`. Additionally, there are variants pinned to certain major versions, like `pnpm_8` and `pnpm_9`, which support different sets of lock file versions. + +When packaging an application that includes a `pnpm-lock.yaml`, you need to fetch the pnpm store for that project using a fixed-output-derivation. The functions `pnpm_8.fetchDeps` and `pnpm_9.fetchDeps` can create this pnpm store derivation. In conjunction, the setup hooks `pnpm_8.configHook` and `pnpm_9.configHook` will prepare the build environment to install the prefetched dependencies store. Here is an example for a package that contains a `package.json` and a `pnpm-lock.yaml` files using the above `pnpm_` attributes: + +```nix +{ + stdenv, + nodejs, + # This is pinned as { pnpm = pnpm_9; } + pnpm +}: + +stdenv.mkDerivation (finalAttrs: { + pname = "foo"; + version = "0-unstable-1980-01-01"; + + src = ...; + + nativeBuildInputs = [ + nodejs + pnpm.configHook + ]; + + pnpmDeps = pnpm.fetchDeps { + inherit (finalAttrs) pname version src; + hash = "..."; + }; +}) +``` + +NOTE: It is highly recommended to use a pinned version of pnpm (i.e. `pnpm_8` or `pnpm_9`), to increase future reproducibility. It might also be required to use an older version, if the package needs support for a certain lock file version. + +In case you are patching `package.json` or `pnpm-lock.yaml`, make sure to pass `finalAttrs.patches` to the function as well (i.e. `inherit (finalAttrs) patches`. + +#### Dealing with `sourceRoot` {#javascript-pnpm-sourceRoot} + +NOTE: Nixpkgs pnpm tooling doesn't support building projects with a `pnpm-workspace.yaml`, or building monorepos. It maybe possible to use `pnpm.fetchDeps` for these projects, but it may be hard or impossible to produce a binary from such projects ([an example attempt](https://github.com/NixOS/nixpkgs/pull/290715#issuecomment-2144543728)). + +If the pnpm project is in a subdirectory, you can just define `sourceRoot` or `setSourceRoot` for `fetchDeps`. Note, that projects using `pnpm-workspace.yaml` are currently not supported, and will probably not work using this approach. +If `sourceRoot` is different between the parent derivation and `fetchDeps`, you will have to set `pnpmRoot` to effectively be the same location as it is in `fetchDeps`. + +Assuming the following directory structure, we can define `sourceRoot` and `pnpmRoot` as follows: + +``` +. +├── frontend +│ ├── ... +│ ├── package.json +│ └── pnpm-lock.yaml +└── ... +``` + +```nix + ... + pnpmDeps = pnpm.fetchDeps { + ... + sourceRoot = "${finalAttrs.src.name}/frontend"; + }; + + # by default the working directory is the extracted source + pnpmRoot = "frontend"; +``` + ### yarn2nix {#javascript-yarn2nix} #### Preparation {#javascript-yarn2nix-preparation} |