Merge pull request #332466 from hsjobeki/doc/compressDrv

Doc: pkgs{compressDrv,compressDrvWeb} improve clarity
2024-11-22 15:03:28 +00:00 · 2024-08-05 14:56:30 -07:00 · 2024-08-05 14:56:30 -07:00 · 1e6e7faa18
commit 1e6e7faa18
parent 67231dd5a4 782c1eabe2
2 changed files with 113 additions and 69 deletions
--- a/pkgs/build-support/compress-drv/default.nix
+++ b/pkgs/build-support/compress-drv/default.nix
@ -4,36 +4,51 @@
  runCommand,
 }:
 /**
-  #  compressDrv compresses files in a given derivation.
+  Compresses files of a given derivation, and returns a new derivation with
+  compressed files

-  ## Inputs:
+  # Inputs

  `formats` ([String])

  : List of file extensions to compress. Example: `["txt" "svg" "xml"]`.

-  `compressors` (String -> String)
+  `compressors` ( { ${fileExtension} :: String })

  : Map a desired extension (e.g. `gz`) to a compress program.

-  The compressor program that will be executed to get the `COMPRESSOR` extension.
-  The program should have a single " {}", which will be the replaced with the
-  target filename.
+    The compressor program that will be executed to get the `COMPRESSOR` extension.
+    The program should have a single " {}", which will be the replaced with the
+    target filename.

-  Compressor must:
-  - read symlinks (thus --force is needed to gzip, zstd, xz).
-  - keep the original file in place (--keep).
+    Compressor must:

-  Example:
+    - read symlinks (thus --force is needed to gzip, zstd, xz).
+    - keep the original file in place (--keep).
+
+  # Type

  ```
-  {
-    xz = "${xz}/bin/xz --force --keep {}";
+  compressDrv :: Derivation -> { formats :: [ String ]; compressors :: { ${fileExtension} :: String; } } -> Derivation
+  ```
+
+  # Examples
+  :::{.example}
+  ## `pkgs.compressDrv` usage example
+  ```
+  compressDrv pkgs.spdx-license-list-data.json {
+    formats = ["json"];
+    compressors = {
+      "json" = "${zopfli}/bin/zopfli --keep {}";
+    };
  }
+  =>
+  «derivation /nix/store/...-spdx-license-list-data-3.24.0-compressed.drv»
  ```

-  See compressDrvWeb, which is a wrapper on top of compressDrv, for broader use
+  See also pkgs.compressDrvWeb, which is a wrapper on top of compressDrv, for broader usage
  examples.
+  :::
 */
 drv:
 { formats, compressors, ... }:
--- a/pkgs/build-support/compress-drv/web.nix
+++ b/pkgs/build-support/compress-drv/web.nix
@ -4,76 +4,105 @@
  compressDrv,
 }:
 /**
-  # compressDrvWeb compresses a derivation for common web server use.
+  compressDrvWeb compresses a derivation for common web server use.

  Useful when one wants to pre-compress certain static assets and pass them to
-  the web server. For example, `pkgs.gamja` creates this derivation:
+  the web server.

-      /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/
-      ├── index.2fd01148.js
-      ├── index.2fd01148.js.map
-      ├── index.37aa9a8a.css
-      ├── index.37aa9a8a.css.map
-      ├── index.html
-      └── manifest.webmanifest
+  # Inputs

-  `pkgs.compressDrvWeb pkgs.gamja`:
+  `formats` ([String])

-      /nix/store/f5ryid7zrw2hid7h9kil5g5j29q5r2f7-gamja-1.0.0-beta.9-compressed
-      ├── index.2fd01148.js -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/index.2fd01148.js
-      ├── index.2fd01148.js.br
-      ├── index.2fd01148.js.gz
-      ├── index.2fd01148.js.map -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/index.2fd01148.js.map
-      ├── index.2fd01148.js.map.br
-      ├── index.2fd01148.js.map.gz
-      ├── index.37aa9a8a.css -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/index.37aa9a8a.css
-      ├── index.37aa9a8a.css.br
-      ├── index.37aa9a8a.css.gz
-      ├── index.37aa9a8a.css.map -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/index.37aa9a8a.css.map
-      ├── index.37aa9a8a.css.map.br
-      ├── index.37aa9a8a.css.map.gz
-      ├── index.html -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/index.html
-      ├── index.html.br
-      ├── index.html.gz
-      ├── manifest.webmanifest -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/manifest.webmanifest
-      ├── manifest.webmanifest.br
-      └── manifest.webmanifest.gz
+  : List of file extensions to compress.

-  When this `-compressed` directory is passed to a properly configured web
-  server, it will serve those pre-compressed files:
+    Defaults to common formats that compress well.

-      $ curl -I -H 'Accept-Encoding: br' https://irc.example.org/
-      <...>
-      content-encoding: br
-      <...>
+  `extraFormats` ([ String ])
+
+  : Extra extensions to compress in addition to `formats`.
+
+  `compressors` ( { ${fileExtension} :: String })
+
+  : Map a desired extension (e.g. `gz`) to a compress program.
+
+  # Type
+
+  ```
+  compressDrvWeb :: Derivation -> { formats :: [ String ]; extraFormats :: [ String ]; compressors :: { ${fileExtension} :: String; } } -> Derivation
+  ```
+
+  # Examples
+  :::{.example}
+  ## `pkgs.compressDrvWeb` full usage example with `pkgs.gamja` and a webserver
+  ```nix
+
+  For example, building `pkgs.gamja` produces the following output:
+
+    /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/
+    ├── index.2fd01148.js
+    ├── index.2fd01148.js.map
+    ├── index.37aa9a8a.css
+    ├── index.37aa9a8a.css.map
+    ├── index.html
+    └── manifest.webmanifest
+
+  With `pkgs.compressDrvWeb`, one can compress these files:
+
+  ```nix
+  pkgs.compressDrvWeb pkgs.gamja {}
+  =>
+  «derivation /nix/store/...-gamja-compressed.drv»
+  ```
+
+  ```bash
+  /nix/store/f5ryid7zrw2hid7h9kil5g5j29q5r2f7-gamja-1.0.0-beta.9-compressed
+  ├── index.2fd01148.js -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/index.2fd01148.js
+  ├── index.2fd01148.js.br
+  ├── index.2fd01148.js.gz
+  ├── index.2fd01148.js.map -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/index.2fd01148.js.map
+  ├── index.2fd01148.js.map.br
+  ├── index.2fd01148.js.map.gz
+  ├── index.37aa9a8a.css -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/index.37aa9a8a.css
+  ├── index.37aa9a8a.css.br
+  ├── index.37aa9a8a.css.gz
+  ├── index.37aa9a8a.css.map -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/index.37aa9a8a.css.map
+  ├── index.37aa9a8a.css.map.br
+  ├── index.37aa9a8a.css.map.gz
+  ├── index.html -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/index.html
+  ├── index.html.br
+  ├── index.html.gz
+  ├── manifest.webmanifest -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/manifest.webmanifest
+  ├── manifest.webmanifest.br
+  └── manifest.webmanifest.gz
+  ```
+
+  When the `-compressed` derivation is passed to a properly configured web server,
+  it enables direct serving of the pre-compressed files.
+
+  ```shell-session
+  $ curl -I -H 'Accept-Encoding: br' https://irc.example.org/
+  <...>
+  content-encoding: br
+  <...>
+  ```

  For example, a caddy configuration snippet for gamja to serve
  the static assets (JS, CSS files) pre-compressed:

-      virtualHosts."irc.example.org".extraConfig = ''
-        root * ${pkgs.compressDrvWeb pkgs.gamja {}}
-        file_server browse {
-            precompressed br gzip
-        }
-      '';
+  ```nix
+  {
+    virtualHosts."irc.example.org".extraConfig = ''
+      root * ${pkgs.compressDrvWeb pkgs.gamja {}}
+      file_server browse {
+          precompressed br gzip
+      }
+    '';
+  }
+  ```

  This feature is also available in nginx via `ngx_brotli` and
  `ngx_http_gzip_static_module`.
-
-  ## Inputs
-
-  `formats` ([String])
-
-  : List of file extensions to compress. Default is common formats that compress
-  well. The list may be expanded.
-
-  `extraFormats` ([String])
-
-  : Extra extensions to compress in addition to `formats`.
-
-  `compressors` (String -> String)
-
-  : See parameter `compressors` of compressDrv.
+  :::
 */
 drv:
 {