doc/build-helpers/trivial-build-helpers.chapter.md

   1 # Trivial build helpers {#chap-trivial-builders}
   2
   3 Nixpkgs provides a variety of wrapper functions that help build commonly useful derivations.
   4 Like [`stdenv.mkDerivation`](#sec-using-stdenv), each of these build helpers creates a derivation, but the arguments passed are different (usually simpler) from those required by `stdenv.mkDerivation`.
   5
   6
   7 ## `runCommandWith` {#trivial-builder-runCommandWith}
   8
   9 The function `runCommandWith` returns a derivation built using the specified command(s), in a specified environment.
  10
  11 It is the underlying base function of  all [`runCommand*` variants].
  12 The general behavior is controlled via a single attribute set passed
  13 as the first argument, and allows specifying `stdenv` freely.
  14
  15 The following [`runCommand*` variants] exist: `runCommand`, `runCommandCC`, and `runCommandLocal`.
  16
  17 [`runCommand*` variants]: #trivial-builder-runCommand
  18
  19 ### Type {#trivial-builder-runCommandWith-Type}
  20
  21 ```
  22 runCommandWith :: {
  23   name :: name;
  24   stdenv? :: Derivation;
  25   runLocal? :: Bool;
  26   derivationArgs? :: { ... };
  27 } -> String -> Derivation
  28 ```
  29
  30 ### Inputs {#trivial-builder-runCommandWith-Inputs}
  31
  32 `name` (String)
  33 :   The derivation's name, which Nix will append to the store path; see [`mkDerivation`](#sec-using-stdenv).
  34
  35 `runLocal` (Boolean)
  36 :   If set to `true` this forces the derivation to be built locally, not using [substitutes] nor remote builds.
  37     This is intended for very cheap commands (<1s execution time) which can be sped up by avoiding the network round-trip(s).
  38     Its effect is to set [`preferLocalBuild = true`][preferLocalBuild] and [`allowSubstitutes = false`][allowSubstitutes].
  39
  40    ::: {.note}
  41    This prevents the use of [substituters][substituter], so only set `runLocal` (or use `runCommandLocal`) when certain the user will
  42    always have a builder for the `system` of the derivation. This should be true for most trivial use cases
  43    (e.g., just copying some files to a different location or adding symlinks) because there the `system`
  44    is usually the same as `builtins.currentSystem`.
  45    :::
  46
  47 `stdenv` (Derivation)
  48 :   The [standard environment](#chap-stdenv) to use, defaulting to `pkgs.stdenv`
  49
  50 `derivationArgs` (Attribute set)
  51 :   Additional arguments for [`mkDerivation`](#sec-using-stdenv).
  52
  53 `buildCommand` (String)
  54 :   Shell commands to run in the derivation builder.
  55
  56     ::: {.note}
  57     You have to create a file or directory `$out` for Nix to be able to run the builder successfully.
  58     :::
  59
  60 [allowSubstitutes]: https://nixos.org/nix/manual/#adv-attr-allowSubstitutes
  61 [preferLocalBuild]: https://nixos.org/nix/manual/#adv-attr-preferLocalBuild
  62 [substituter]: https://nix.dev/manual/nix/latest/glossary#gloss-substituter
  63 [substitutes]: https://nix.dev/manual/nix/2.23/glossary#gloss-substitute
  64
  65 ::: {.example #ex-runcommandwith}
  66 # Invocation of `runCommandWith`
  67
  68 ```nix
  69 runCommandWith {
  70   name = "example";
  71   derivationArgs.nativeBuildInputs = [ cowsay ];
  72 } ''
  73   cowsay > $out <<EOMOO
  74   'runCommandWith' is a bit cumbersome,
  75   so we have more ergonomic wrappers.
  76   EOMOO
  77 ''
  78 ```
  79
  80 :::
  81
  82
  83 ## `runCommand` and `runCommandCC` {#trivial-builder-runCommand}
  84
  85 The function `runCommand` returns a derivation built using the specified command(s), in the `stdenvNoCC` environment.
  86
  87 `runCommandCC` is similar but uses the default compiler environment. To minimize dependencies, `runCommandCC`
  88 should only be used when the build command needs a C compiler.
  89
  90 `runCommandLocal` is also similar to `runCommand`, but forces the derivation to be built locally.
  91 See the note on [`runCommandWith`] about `runLocal`.
  92
  93 [`runCommandWith`]: #trivial-builder-runCommandWith
  94
  95 ### Type {#trivial-builder-runCommand-Type}
  96
  97 ```
  98 runCommand      :: String -> AttrSet -> String -> Derivation
  99 runCommandCC    :: String -> AttrSet -> String -> Derivation
 100 runCommandLocal :: String -> AttrSet -> String -> Derivation
 101 ```
 102
 103 ### Input {#trivial-builder-runCommand-Input}
 104
 105 While the type signature(s) differ from [`runCommandWith`], individual arguments with the same name will have the same type and meaning:
 106
 107 `name` (String)
 108 :   The derivation's name
 109
 110 `derivationArgs` (Attribute set)
 111 :   Additional parameters passed to [`mkDerivation`]
 112
 113 `buildCommand` (String)
 114 :   The command(s) run to build the derivation.
 115
 116
 117 ::: {.example #ex-runcommand-simple}
 118 # Invocation of `runCommand`
 119
 120 ```nix
 121 runCommand "my-example" {} ''
 122   echo My example command is running
 123
 124   mkdir $out
 125
 126   echo I can write data to the Nix store > $out/message
 127
 128   echo I can also run basic commands like:
 129
 130   echo ls
 131   ls
 132
 133   echo whoami
 134   whoami
 135
 136   echo date
 137   date
 138 ''
 139 ```
 140 :::
 141
 142 ::: {.note}
 143 `runCommand name derivationArgs buildCommand` is equivalent to
 144 ```nix
 145 runCommandWith {
 146   inherit name derivationArgs;
 147   stdenv = stdenvNoCC;
 148 } buildCommand
 149 ```
 150
 151 Likewise, `runCommandCC name derivationArgs buildCommand` is equivalent to
 152 ```nix
 153 runCommandWith {
 154   inherit name derivationArgs;
 155 } buildCommand
 156 ```
 157 :::
 158
 159
 160 ## Writing text files {#trivial-builder-text-writing}
 161
 162 Nixpkgs provides the following functions for producing derivations which write text files or executable scripts into the Nix store.
 163 They are useful for creating files from Nix expression, and are all implemented as convenience wrappers around `writeTextFile`.
 164
 165 Each of these functions will cause a derivation to be produced.
 166 When you coerce the result of each of these functions to a string with [string interpolation](https://nixos.org/manual/nix/stable/language/string-interpolation) or [`builtins.toString`](https://nixos.org/manual/nix/stable/language/builtins#builtins-toString), it will evaluate to the [store path](https://nixos.org/manual/nix/stable/store/store-path) of this derivation.
 167
 168 :::: {.note}
 169 Some of these functions will put the resulting files within a directory inside the [derivation output](https://nixos.org/manual/nix/stable/language/derivations#attr-outputs).
 170 If you need to refer to the resulting files somewhere else in a Nix expression, append their path to the derivation's store path.
 171
 172 For example, if the file destination is a directory:
 173
 174 ```nix
 175 {
 176   my-file = writeTextFile {
 177     name = "my-file";
 178     text = ''
 179       Contents of File
 180     '';
 181     destination = "/share/my-file";
 182   };
 183 }
 184 ```
 185
 186 Remember to append "/share/my-file" to the resulting store path when using it elsewhere:
 187
 188 ```nix
 189 writeShellScript "evaluate-my-file.sh" ''
 190   cat ${my-file}/share/my-file
 191 ''
 192 ```
 193 ::::
 194
 195 ### `makeDesktopItem` {#trivial-builder-makeDesktopItem}
 196
 197 Write an [XDG desktop file](https://specifications.freedesktop.org/desktop-entry-spec/1.4/) to the Nix store.
 198
 199 This function is usually used to add desktop items to a package through the `copyDesktopItems` hook.
 200
 201 `makeDesktopItem` adheres to version 1.4 of the specification.
 202
 203 #### Inputs {#trivial-builder-makeDesktopItem-inputs}
 204
 205 `makeDesktopItem` takes an attribute set that accepts most values from the [XDG specification](https://specifications.freedesktop.org/desktop-entry-spec/1.4/ar01s06.html).
 206
 207 All recognised keys from the specification are supported with the exception of the "Hidden" field. The keys are converted into camelCase format, but correspond 1:1 to their equivalent in the specification: `genericName`, `noDisplay`, `comment`, `icon`, `onlyShowIn`, `notShowIn`, `dbusActivatable`, `tryExec`, `exec`, `path`, `terminal`, `mimeTypes`, `categories`, `implements`, `keywords`, `startupNotify`, `startupWMClass`, `url`, `prefersNonDefaultGPU`.
 208
 209 The "Version" field is hardcoded to the version `makeDesktopItem` currently adheres to.
 210
 211 The following fields are either required, are of a different type than in the specification, carry specific default values, or are additional fields supported by `makeDesktopItem`:
 212
 213 `name` (String)
 214
 215 : The name of the desktop file in the Nix store.
 216
 217 `type` (String; _optional_)
 218
 219 : Default value: `"Application"`
 220
 221 `desktopName` (String)
 222
 223 : Corresponds to the "Name" field of the specification.
 224
 225 `actions` (List of Attribute set; _optional_)
 226
 227 : A list of attribute sets {name, exec?, icon?}
 228
 229 `extraConfig` (Attribute set; _optional_)
 230
 231 : Additional key/value pairs to be added verbatim to the desktop file. Attributes need to be prefixed with 'X-'.
 232
 233 #### Examples {#trivial-builder-makeDesktopItem-examples}
 234
 235 ::: {.example #ex-makeDesktopItem}
 236 # Usage 1 of `makeDesktopItem`
 237
 238 Write a desktop file `/nix/store/<store path>/my-program.desktop` to the Nix store.
 239
 240 ```nix
 241 {makeDesktopItem}:
 242 makeDesktopItem {
 243   name = "my-program";
 244   desktopName = "My Program";
 245   genericName = "Video Player";
 246   noDisplay = false;
 247   comment = "Cool video player";
 248   icon = "/path/to/icon";
 249   onlyShowIn = [ "KDE" ];
 250   dbusActivatable = true;
 251   tryExec = "my-program";
 252   exec = "my-program --someflag";
 253   path = "/some/working/path";
 254   terminal = false;
 255   actions.example = {
 256     name = "New Window";
 257     exec = "my-program --new-window";
 258     icon = "/some/icon";
 259   };
 260   mimeTypes = [ "video/mp4" ];
 261   categories = [ "Utility" ];
 262   implements = [ "org.my-program" ];
 263   keywords = [ "Video" "Player" ];
 264   startupNotify = false;
 265   startupWMClass = "MyProgram";
 266   prefersNonDefaultGPU = false;
 267   extraConfig.X-SomeExtension = "somevalue";
 268 }
 269 ```
 270
 271 :::
 272
 273 ::: {.example #ex2-makeDesktopItem}
 274 # Usage 2 of `makeDesktopItem`
 275
 276 Override the `hello` package to add a desktop item.
 277
 278 ```nix
 279 { copyDesktopItems
 280 , hello
 281 , makeDesktopItem }:
 282
 283 hello.overrideAttrs {
 284   nativeBuildInputs = [ copyDesktopItems ];
 285
 286   desktopItems = [(makeDesktopItem {
 287     name = "hello";
 288     desktopName = "Hello";
 289     exec = "hello";
 290   })];
 291 }
 292 ```
 293
 294 :::
 295
 296 ### `writeTextFile` {#trivial-builder-writeTextFile}
 297
 298 Write a text file to the Nix store.
 299
 300 `writeTextFile` takes an attribute set with the following possible attributes:
 301
 302 `name` (String)
 303
 304 : Corresponds to the name used in the Nix store path identifier.
 305
 306 `text` (String)
 307
 308 : The contents of the file.
 309
 310 `executable` (Bool, _optional_)
 311
 312 : Make this file have the executable bit set.
 313
 314   Default: `false`
 315
 316 `destination` (String, _optional_)
 317
 318 : A subpath under the derivation's output path into which to put the file.
 319   Subdirectories are created automatically when the derivation is realised.
 320
 321   By default, the store path itself will be a file containing the text contents.
 322
 323   Default: `""`
 324
 325 `checkPhase` (String, _optional_)
 326
 327 : Commands to run after generating the file.
 328
 329   Default: `""`
 330
 331 `meta` (Attribute set, _optional_)
 332
 333 : Additional metadata for the derivation.
 334
 335   Default: `{}`
 336
 337 `allowSubstitutes` (Bool, _optional_)
 338
 339 : Whether to allow substituting from a binary cache.
 340   Passed through to [`allowSubstitutes`](https://nixos.org/manual/nix/stable/language/advanced-attributes#adv-attr-allowSubstitutes) of the underlying call to `builtins.derivation`.
 341
 342   It defaults to `false`, as running the derivation's simple `builder` executable locally is assumed to be faster than network operations.
 343   Set it to true if the `checkPhase` step is expensive.
 344
 345   Default: `false`
 346
 347 `preferLocalBuild` (Bool, _optional_)
 348
 349 : Whether to prefer building locally, even if faster [remote build machines](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-substituters) are available.
 350
 351   Passed through to [`preferLocalBuild`](https://nixos.org/manual/nix/stable/language/advanced-attributes#adv-attr-preferLocalBuild) of the underlying call to `builtins.derivation`.
 352
 353   It defaults to `true` for the same reason `allowSubstitutes` defaults to `false`.
 354
 355   Default: `true`
 356
 357 `derivationArgs` (Attribute set, _optional_)
 358
 359 : Extra arguments to pass to the underlying call to `stdenv.mkDerivation`.
 360
 361   Default: `{}`
 362
 363 The resulting store path will include some variation of the name, and it will be a file unless `destination` is used, in which case it will be a directory.
 364
 365 ::: {.example #ex-writeTextFile}
 366 # Usage 1 of `writeTextFile`
 367
 368 Write `my-file` to `/nix/store/<store path>/some/subpath/my-cool-script`, making it executable.
 369 Also run a check on the resulting file in a `checkPhase`, and supply values for the less-used options.
 370
 371 ```nix
 372 writeTextFile {
 373   name = "my-cool-script";
 374   text = ''
 375     #!/bin/sh
 376     echo "This is my cool script!"
 377   '';
 378   executable = true;
 379   destination = "/some/subpath/my-cool-script";
 380   checkPhase = ''
 381     ${pkgs.shellcheck}/bin/shellcheck $out/some/subpath/my-cool-script
 382   '';
 383   meta = {
 384     license = pkgs.lib.licenses.cc0;
 385   };
 386   allowSubstitutes = true;
 387   preferLocalBuild = false;
 388 }
 389 ```
 390 :::
 391
 392 ::: {.example #ex2-writeTextFile}
 393 # Usage 2 of `writeTextFile`
 394
 395 Write the string `Contents of File` to `/nix/store/<store path>`.
 396 See also the [](#trivial-builder-writeText) helper function.
 397
 398 ```nix
 399 writeTextFile {
 400   name = "my-file";
 401   text = ''
 402     Contents of File
 403   '';
 404 }
 405 ```
 406 :::
 407
 408 ::: {.example #ex3-writeTextFile}
 409 # Usage 3 of `writeTextFile`
 410
 411 Write an executable script `my-script` to `/nix/store/<store path>/bin/my-script`.
 412 See also the [](#trivial-builder-writeScriptBin) helper function.
 413
 414 ```nix
 415 writeTextFile {
 416   name = "my-script";
 417   text = ''
 418     echo "hi"
 419   '';
 420   executable = true;
 421   destination = "/bin/my-script";
 422 }
 423 ```
 424 :::
 425
 426 ### `writeText` {#trivial-builder-writeText}
 427
 428 Write a text file to the Nix store
 429
 430 `writeText` takes the following arguments:
 431 a string.
 432
 433 `name` (String)
 434
 435 : The name used in the Nix store path.
 436
 437 `text` (String)
 438
 439 : The contents of the file.
 440
 441 The store path will include the name, and it will be a file.
 442
 443 ::: {.example #ex-writeText}
 444 # Usage of `writeText`
 445
 446 Write the string `Contents of File` to `/nix/store/<store path>`:
 447
 448 ```nix
 449 writeText "my-file"
 450   ''
 451   Contents of File
 452   ''
 453 ```
 454 :::
 455
 456 This is equivalent to:
 457
 458 ```nix
 459 writeTextFile {
 460   name = "my-file";
 461   text = ''
 462     Contents of File
 463   '';
 464 }
 465 ```
 466
 467 ### `writeTextDir` {#trivial-builder-writeTextDir}
 468
 469 Write a text file within a subdirectory of the Nix store.
 470
 471 `writeTextDir` takes the following arguments:
 472
 473 `path` (String)
 474
 475 : The destination within the Nix store path under which to create the file.
 476
 477 `text` (String)
 478
 479 : The contents of the file.
 480
 481 The store path will be a directory.
 482
 483 ::: {.example #ex-writeTextDir}
 484 # Usage of `writeTextDir`
 485
 486 Write the string `Contents of File` to `/nix/store/<store path>/share/my-file`:
 487
 488 ```nix
 489 writeTextDir "share/my-file"
 490   ''
 491   Contents of File
 492   ''
 493 ```
 494 :::
 495
 496 This is equivalent to:
 497
 498 ```nix
 499 writeTextFile {
 500   name = "my-file";
 501   text = ''
 502     Contents of File
 503   '';
 504   destination = "/share/my-file";
 505 }
 506 ```
 507
 508 ### `writeScript` {#trivial-builder-writeScript}
 509
 510 Write an executable script file to the Nix store.
 511
 512 `writeScript` takes the following arguments:
 513
 514 `name` (String)
 515
 516 : The name used in the Nix store path.
 517
 518 `text` (String)
 519
 520 : The contents of the file.
 521
 522 The created file is marked as executable.
 523 The store path will include the name, and it will be a file.
 524
 525 ::: {.example #ex-writeScript}
 526 # Usage of `writeScript`
 527
 528 Write the string `Contents of File` to `/nix/store/<store path>` and make the file executable.
 529
 530 ```nix
 531 writeScript "my-file"
 532   ''
 533   Contents of File
 534   ''
 535 ```
 536
 537 This is equivalent to:
 538
 539 ```nix
 540 writeTextFile {
 541   name = "my-file";
 542   text = ''
 543     Contents of File
 544   '';
 545   executable = true;
 546 }
 547 ```
 548 :::
 549
 550 ### `writeScriptBin` {#trivial-builder-writeScriptBin}
 551
 552 Write a script within a `bin` subdirectory of a directory in the Nix store.
 553 This is for consistency with the convention of software packages placing executables under `bin`.
 554
 555 `writeScriptBin` takes the following arguments:
 556
 557 `name` (String)
 558
 559 : The name used in the Nix store path and within the file created under the store path.
 560
 561 `text` (String)
 562
 563 : The contents of the file.
 564
 565 The created file is marked as executable.
 566 The file's contents will be put into `/nix/store/<store path>/bin/<name>`.
 567 The store path will include the name, and it will be a directory.
 568
 569 ::: {.example #ex-writeScriptBin}
 570 # Usage of `writeScriptBin`
 571
 572 ```nix
 573 writeScriptBin "my-script"
 574   ''
 575   echo "hi"
 576   ''
 577 ```
 578 :::
 579
 580 This is equivalent to:
 581
 582 ```nix
 583 writeTextFile {
 584   name = "my-script";
 585   text = ''
 586     echo "hi"
 587   '';
 588   executable = true;
 589   destination = "/bin/my-script";
 590 }
 591 ```
 592
 593 ### `writeShellScript` {#trivial-builder-writeShellScript}
 594
 595 Write a Bash script to the store.
 596
 597 `writeShellScript` takes the following arguments:
 598
 599 `name` (String)
 600
 601 : The name used in the Nix store path.
 602
 603 `text` (String)
 604
 605 : The contents of the file.
 606
 607 The created file is marked as executable.
 608 The store path will include the name, and it will be a file.
 609
 610 This function is almost exactly like [](#trivial-builder-writeScript), except that it prepends to the file a [shebang](https://en.wikipedia.org/wiki/Shebang_%28Unix%29) line that points to the version of Bash used in Nixpkgs.
 611 <!-- this cannot be changed in practice, so there is no point pretending it's somehow generic -->
 612
 613 ::: {.example #ex-writeShellScript}
 614 # Usage of `writeShellScript`
 615
 616 ```nix
 617 writeShellScript "my-script"
 618   ''
 619   echo "hi"
 620   ''
 621 ```
 622 :::
 623
 624 This is equivalent to:
 625
 626 ```nix
 627 writeTextFile {
 628   name = "my-script";
 629   text = ''
 630     #! ${pkgs.runtimeShell}
 631     echo "hi"
 632   '';
 633   executable = true;
 634 }
 635 ```
 636
 637 ### `writeShellScriptBin` {#trivial-builder-writeShellScriptBin}
 638
 639 Write a Bash script to a "bin" subdirectory of a directory in the Nix store.
 640
 641 `writeShellScriptBin` takes the following arguments:
 642
 643 `name` (String)
 644
 645 : The name used in the Nix store path and within the file generated under the store path.
 646
 647 `text` (String)
 648
 649 : The contents of the file.
 650
 651 The file's contents will be put into `/nix/store/<store path>/bin/<name>`.
 652 The store path will include the the name, and it will be a directory.
 653
 654 This function is a combination of [](#trivial-builder-writeShellScript) and [](#trivial-builder-writeScriptBin).
 655
 656 ::: {.example #ex-writeShellScriptBin}
 657 # Usage of `writeShellScriptBin`
 658
 659 ```nix
 660 writeShellScriptBin "my-script"
 661   ''
 662   echo "hi"
 663   ''
 664 ```
 665 :::
 666
 667 This is equivalent to:
 668
 669 ```nix
 670 writeTextFile {
 671   name = "my-script";
 672   text = ''
 673     #! ${pkgs.runtimeShell}
 674     echo "hi"
 675   '';
 676   executable = true;
 677   destination = "/bin/my-script";
 678 }
 679 ```
 680
 681 ## `concatTextFile`, `concatText`, `concatScript` {#trivial-builder-concatText}
 682
 683 These functions concatenate `files` to the Nix store in a single file. This is useful for configuration files structured in lines of text. `concatTextFile` takes an attribute set and expects two arguments, `name` and `files`. `name` corresponds to the name used in the Nix store path. `files` will be the files to be concatenated. You can also set `executable` to true to make this file have the executable bit set.
 684 `concatText` and`concatScript` are simple wrappers over `concatTextFile`.
 685
 686 Here are a few examples:
 687 ```nix
 688
 689 # Writes my-file to /nix/store/<store path>
 690 concatTextFile {
 691   name = "my-file";
 692   files = [ drv1 "${drv2}/path/to/file" ];
 693 }
 694 # See also the `concatText` helper function below.
 695
 696 # Writes executable my-file to /nix/store/<store path>/bin/my-file
 697 concatTextFile {
 698   name = "my-file";
 699   files = [ drv1 "${drv2}/path/to/file" ];
 700   executable = true;
 701   destination = "/bin/my-file";
 702 }
 703 # Writes contents of files to /nix/store/<store path>
 704 concatText "my-file" [ file1 file2 ]
 705
 706 # Writes contents of files to /nix/store/<store path>
 707 concatScript "my-file" [ file1 file2 ]
 708 ```
 709
 710 ## `writeShellApplication` {#trivial-builder-writeShellApplication}
 711
 712 `writeShellApplication` is similar to `writeShellScriptBin` and `writeScriptBin` but supports runtime dependencies with `runtimeInputs`.
 713 Writes an executable shell script to `/nix/store/<store path>/bin/<name>` and checks its syntax with [`shellcheck`](https://github.com/koalaman/shellcheck) and the `bash`'s `-n` option.
 714 Some basic Bash options are set by default (`errexit`, `nounset`, and `pipefail`), but can be overridden with `bashOptions`.
 715
 716 Extra arguments may be passed to `stdenv.mkDerivation` by setting `derivationArgs`; note that variables set in this manner will be set when the shell script is _built,_ not when it's run.
 717 Runtime environment variables can be set with the `runtimeEnv` argument.
 718
 719 For example, the following shell application can refer to `curl` directly, rather than needing to write `${curl}/bin/curl`:
 720
 721 ```nix
 722 writeShellApplication {
 723   name = "show-nixos-org";
 724
 725   runtimeInputs = [ curl w3m ];
 726
 727   text = ''
 728     curl -s 'https://nixos.org' | w3m -dump -T text/html
 729   '';
 730 }
 731 ```
 732
 733 ## `symlinkJoin` {#trivial-builder-symlinkJoin}
 734
 735 This can be used to put many derivations into the same directory structure. It works by creating a new derivation and adding symlinks to each of the paths listed. It expects two arguments, `name`, and `paths`. `name` (or alternatively `pname` and `version`) is the name used in the Nix store path for the created derivation. `paths` is a list of paths that will be symlinked. These paths can be to Nix store derivations or any other subdirectory contained within.
 736 Here is an example:
 737 ```nix
 738 # adds symlinks of hello and stack to current build and prints "links added"
 739 symlinkJoin { name = "myexample"; paths = [ pkgs.hello pkgs.stack ]; postBuild = "echo links added"; }
 740 ```
 741 This creates a derivation with a directory structure like the following:
 742 ```
 743 /nix/store/sglsr5g079a5235hy29da3mq3hv8sjmm-myexample
 744 |-- bin
 745 |   |-- hello -> /nix/store/qy93dp4a3rqyn2mz63fbxjg228hffwyw-hello-2.10/bin/hello
 746 |   `-- stack -> /nix/store/6lzdpxshx78281vy056lbk553ijsdr44-stack-2.1.3.1/bin/stack
 747 `-- share
 748     |-- bash-completion
 749     |   `-- completions
 750     |       `-- stack -> /nix/store/6lzdpxshx78281vy056lbk553ijsdr44-stack-2.1.3.1/share/bash-completion/completions/stack
 751     |-- fish
 752     |   `-- vendor_completions.d
 753     |       `-- stack.fish -> /nix/store/6lzdpxshx78281vy056lbk553ijsdr44-stack-2.1.3.1/share/fish/vendor_completions.d/stack.fish
 754 ...
 755 ```
 756
 757 ## `writeClosure` {#trivial-builder-writeClosure}
 758
 759 Given a list of [store paths](https://nixos.org/manual/nix/stable/glossary#gloss-store-path) (or string-like expressions coercible to store paths), write their collective [closure](https://nixos.org/manual/nix/stable/glossary#gloss-closure) to a text file.
 760
 761 The result is equivalent to the output of `nix-store -q --requisites`.
 762
 763 For example,
 764
 765 ```nix
 766 writeClosure [ (writeScriptBin "hi" ''${hello}/bin/hello'') ]
 767 ```
 768
 769 produces an output path `/nix/store/<hash>-runtime-deps` containing
 770
 771 ```
 772 /nix/store/<hash>-hello-2.10
 773 /nix/store/<hash>-hi
 774 /nix/store/<hash>-libidn2-2.3.0
 775 /nix/store/<hash>-libunistring-0.9.10
 776 /nix/store/<hash>-glibc-2.32-40
 777 ```
 778
 779 You can see that this includes `hi`, the original input path,
 780 `hello`, which is a direct reference, but also
 781 the other paths that are indirectly required to run `hello`.
 782
 783 ## `writeDirectReferencesToFile` {#trivial-builder-writeDirectReferencesToFile}
 784
 785 Writes the set of references to the output file, that is, their immediate dependencies.
 786
 787 This produces the equivalent of `nix-store -q --references`.
 788
 789 For example,
 790
 791 ```nix
 792 writeDirectReferencesToFile (writeScriptBin "hi" ''${hello}/bin/hello'')
 793 ```
 794
 795 produces an output path `/nix/store/<hash>-runtime-references` containing
 796
 797 ```
 798 /nix/store/<hash>-hello-2.10
 799 ```
 800
 801 but none of `hello`'s dependencies because those are not referenced directly
 802 by `hi`'s output.