commit 4d2b3b4d5a51475ffade486ef0e241a9a3e2a588 · pyrox.dev/nixpkgs

+46 -15

doc/languages-frameworks/dhall.section.md

···

       50
       50
        
       check, so the first step is to freeze the expression using `dhall freeze`,

     

       51
       51
        
       like this:

     

       52
       52
        
       

     

       53
       53
       -
       ```bash

     

       53
       53
       +
       ```ShellSession

     

       54
       54
        
       $ dhall freeze --inplace ./true.dhall

     

       55
       55
        
       ```

     

       56
       56
        
       

     
···

       113
       113
        
       

     

       114
       114
        
       … which we can then build using this command:

     

       115
       115
        
       

     

       116
       116
       -
       ```bash

     

       116
       116
       +
       ```ShellSession

     

       117
       117
        
       $ nix build --file ./example.nix dhallPackages.true

     

       118
       118
        
       ```

     

       119
       119
        
       

     
···

       121
       121
        
       

     

       122
       122
        
       The above package produces the following directory tree:

     

       123
       123
        
       

     

       124
       124
       -
       ```bash

     

       124
       124
       +
       ```ShellSession

     

       125
       125
        
       $ tree -a ./result

     

       126
       126
        
       result

     

       127
       127
        
       ├── .cache

     
···

       135
       135
        
       

     

       136
       136
        
       * `source.dhall` contains the result of interpreting our Dhall package:

     

       137
       137
        
       

     

       138
       138
       -
         ```bash

     

       138
       138
       +
         ```ShellSession

     

       139
       139
        
         $ cat ./result/source.dhall

     

       140
       140
        
         True

     

       141
       141
        
         ```

     
···

       143
       143
        
       * The `.cache` subdirectory contains one binary cache product encoding the

     

       144
       144
        
         same result as `source.dhall`:

     

       145
       145
        
       

     

       146
       146
       -
         ```bash

     

       146
       146
       +
         ```ShellSession

     

       147
       147
        
         $ dhall decode < ./result/.cache/dhall/122027abdeddfe8503496adeb623466caa47da5f63abd2bc6fa19f6cfcb73ecfed70

     

       148
       148
        
         True

     

       149
       149
        
         ```

     
···

       151
       151
        
       * `binary.dhall` contains a Dhall expression which handles fetching and decoding

     

       152
       152
        
         the same cache product:

     

       153
       153
        
       

     

       154
       154
       -
         ```bash

     

       154
       154
       +
         ```ShellSession

     

       155
       155
        
         $ cat ./result/binary.dhall

     

       156
       156
        
         missing sha256:27abdeddfe8503496adeb623466caa47da5f63abd2bc6fa19f6cfcb73ecfed70

     

       157
       157
        
         $ cp -r ./result/.cache .cache

     
···

       168
       168
        
       example, if we build the Prelude package it will only contain the binary

     

       169
       169
        
       encoding of the expression:

     

       170
       170
        
       

     

       171
       171
       -
       ```bash

     

       171
       171
       +
       ```ShellSession

     

       172
       172
        
       $ nix build --file ./example.nix dhallPackages.Prelude

     

       173
       173
        
       

     

       174
       174
        
       $ tree -a result

     
···

       199
       199
        
       … and now the Prelude will contain the fully decoded result of interpreting

     

       200
       200
        
       the Prelude:

     

       201
       201
        
       

     

       202
       202
       -
       ```bash

     

       202
       202
       +
       ```ShellSession

     

       203
       203
        
       $ nix build --file ./example.nix dhallPackages.Prelude

     

       204
       204
        
       

     

       205
       205
        
       $ tree -a result

     
···

       302
       302
        
       You can use the `dhall-to-nixpkgs` command-line utility to automate

     

       303
       303
        
       packaging Dhall code.  For example:

     

       304
       304
        
       

     

       305
       305
       -
       ```bash

     

       305
       305
       +
       ```ShellSession

     

       306
       306
        
       $ nix-env --install --attr haskellPackages.dhall-nixpkgs

     

       307
       307
        
       

     

       308
       308
        
       $ nix-env --install --attr nix-prefetch-git  # Used by dhall-to-nixpkgs

     
···

       329
       329
        
       them to package dependencies.  You can also use the utility on local

     

       330
       330
        
       Dhall directories, too:

     

       331
       331
        
       

     

       332
       332
       -
       ```bash

     

       332
       332
       +
       ```ShellSession

     

       333
       333
        
       $ dhall-to-nixpkgs directory ~/proj/dhall-semver

     

       334
       334
        
       { buildDhallDirectoryPackage, Prelude }:

     

       335
       335
        
         buildDhallDirectoryPackage {

     

       336
       336
        
           name = "proj";

     

       337
       337
       -
           src = /Users/gabriel/proj/dhall-semver;

     

       337
       337
       +
           src = ~/proj/dhall-semver;

     

       338
       338
        
           file = "package.dhall";

     

       339
       339
        
           source = false;

     

       340
       340
        
           document = false;

     
···

       342
       342
        
           }

     

       343
       343
        
       ```

     

       344
       344
        
       

     

       345
       345
       +
       ### Remote imports as fixed-output derivations {#ssec-dhall-remote-imports-as-fod}

     

       346
       346
       +
       

     

       347
       347
       +
       `dhall-to-nixpkgs` has the ability to fetch and build remote imports as

     

       348
       348
       +
       fixed-output derivations by using their Dhall integrity check. This is

     

       349
       349
       +
       sometimes easier than manually packaging all remote imports.

     

       350
       350
       +
       

     

       351
       351
       +
       This can be used like the following:

     

       352
       352
       +
       

     

       353
       353
       +
       ```ShellSession

     

       354
       354
       +
       $ dhall-to-nixpkgs directory --fixed-output-derivations ~/proj/dhall-semver

     

       355
       355
       +
       { buildDhallDirectoryPackage, buildDhallUrl }:

     

       356
       356
       +
         buildDhallDirectoryPackage {

     

       357
       357
       +
           name = "proj";

     

       358
       358
       +
           src = ~/proj/dhall-semver;

     

       359
       359
       +
           file = "package.dhall";

     

       360
       360
       +
           source = false;

     

       361
       361
       +
           document = false;

     

       362
       362
       +
           dependencies = [

     

       363
       363
       +
             (buildDhallUrl {

     

       364
       364
       +
               url = "https://prelude.dhall-lang.org/v17.0.0/package.dhall";

     

       365
       365
       +
               hash = "sha256-ENs8kZwl6QRoM9+Jeo/+JwHcOQ+giT2VjDQwUkvlpD4=";

     

       366
       366
       +
               dhallHash = "sha256:10db3c919c25e9046833df897a8ffe2701dc390fa0893d958c3430524be5a43e";

     

       367
       367
       +
               })

     

       368
       368
       +
             ];

     

       369
       369
       +
           }

     

       370
       370
       +
       ```

     

       371
       371
       +
       

     

       372
       372
       +
       Here, `dhall-semver`'s `Prelude` dependency is fetched and built with the

     

       373
       373
       +
       `buildDhallUrl` helper function, instead of being passed in as a function

     

       374
       374
       +
       argument.

     

       375
       375
       +
       

     

       345
       376
        
       ## Overriding dependency versions {#ssec-dhall-overriding-dependency-versions}

     

       346
       377
        
       

     

       347
       378
        
       Suppose that we change our `true.dhall` example expression to depend on an older

     
···

       359
       390
        
       

     

       360
       391
        
       If we try to rebuild that expression the build will fail:

     

       361
       392
        
       

     

       362
       362
       -
       ```

     

       393
       393
       +
       ```ShellSession

     

       363
       394
        
       $ nix build --file ./example.nix dhallPackages.true

     

       364
       395
        
       builder for '/nix/store/0f1hla7ff1wiaqyk1r2ky4wnhnw114fi-true.drv' failed with exit code 1; last 10 log lines:

     

       365
       396
        
       

     
···

       385
       416
        
       However, we can override the default Prelude version by using `dhall-to-nixpkgs`

     

       386
       417
        
       to create a Dhall package for our desired Prelude:

     

       387
       418
        
       

     

       388
       388
       -
       ```bash

     

       419
       419
       +
       ```ShellSession

     

       389
       420
        
       $ dhall-to-nixpkgs github https://github.com/dhall-lang/dhall-lang.git \

     

       390
       421
        
           --name Prelude \

     

       391
       422
        
           --directory Prelude \

     
···

       396
       427
        
       … and then referencing that package in our Dhall overlay, by either overriding

     

       397
       428
        
       the Prelude globally for all packages, like this:

     

       398
       429
        
       

     

       399
       399
       -
       ```bash

     

       430
       430
       +
       ```nix

     

       400
       431
        
         dhallOverrides = self: super: {

     

       401
       432
        
           true = self.callPackage ./true.nix { };

     

       402
       433
        
       

     
···

       407
       438
        
       … or selectively overriding the Prelude dependency for just the `true` package,

     

       408
       439
        
       like this:

     

       409
       440
        
       

     

       410
       410
       -
       ```bash

     

       441
       441
       +
       ```nix

     

       411
       442
        
         dhallOverrides = self: super: {

     

       412
       443
        
           true = self.callPackage ./true.nix {

     

       413
       444
        
             Prelude = self.callPackage ./Prelude.nix { };

+96

pkgs/development/interpreters/dhall/build-dhall-url.nix

···

       1
       1
       +
       { cacert, dhall, dhall-docs, haskell, lib, runCommand }:

     

       2
       2
       +
       

     

       3
       3
       +
       # `buildDhallUrl` is similar to `buildDhallDirectoryPackage` or

     

       4
       4
       +
       # `buildDhallGitHubPackage`, but instead builds a Nixpkgs Dhall package

     

       5
       5
       +
       # based on a hashed URL.  This will generally be a URL that has an integrity

     

       6
       6
       +
       # check in a Dhall file.

     

       7
       7
       +
       #

     

       8
       8
       +
       # Similar to `buildDhallDirectoryPackage` and `buildDhallGitHubPackage`, the output

     

       9
       9
       +
       # of this function is a derivation that has a `binary.dhall` file, along with

     

       10
       10
       +
       # a `.cache/` directory with the actual contents of the Dhall file from the

     

       11
       11
       +
       # suppiled URL.

     

       12
       12
       +
       #

     

       13
       13
       +
       # This function is primarily used by `dhall-to-nixpkgs directory --fixed-output-derivations`.

     

       14
       14
       +
       

     

       15
       15
       +
       { # URL of the input Dhall file.

     

       16
       16
       +
         # example: "https://raw.githubusercontent.com/cdepillabout/example-dhall-repo/c1b0d0327146648dcf8de997b2aa32758f2ed735/example1.dhall"

     

       17
       17
       +
         url

     

       18
       18
       +
       

     

       19
       19
       +
         # Nix hash of the input Dhall file.

     

       20
       20
       +
         # example: "sha256-ZTSiQUXpPbPfPvS8OeK6dDQE6j6NbP27ho1cg9YfENI="

     

       21
       21
       +
       , hash

     

       22
       22
       +
       

     

       23
       23
       +
         # Dhall hash of the input Dhall file.

     

       24
       24
       +
         # example: "sha256:6534a24145e93db3df3ef4bc39e2ba743404ea3e8d6cfdbb868d5c83d61f10d2"

     

       25
       25
       +
       , dhallHash

     

       26
       26
       +
       

     

       27
       27
       +
         # Name for this derivation.

     

       28
       28
       +
       , name ? (baseNameOf url + "-cache")

     

       29
       29
       +
       

     

       30
       30
       +
         # `buildDhallUrl` can include both a "source distribution" in

     

       31
       31
       +
         # `source.dhall` and a "binary distribution" in `binary.dhall`:

     

       32
       32
       +
         #

     

       33
       33
       +
         # * `source.dhall` is a dependency-free αβ-normalized Dhall expression

     

       34
       34
       +
         #

     

       35
       35
       +
         # * `binary.dhall` is an expression of the form: `missing sha256:${HASH}`

     

       36
       36
       +
         #

     

       37
       37
       +
         #   This expression requires you to install the cache product located at

     

       38
       38
       +
         #   `.cache/dhall/1220${HASH}` to successfully resolve

     

       39
       39
       +
         #

     

       40
       40
       +
         # By default, `buildDhallUrl` only includes "binary.dhall" to conserve

     

       41
       41
       +
         # space within the Nix store, but if you set the following `source` option to

     

       42
       42
       +
         # `true` then the package will also include `source.dhall`.

     

       43
       43
       +
       , source ? false

     

       44
       44
       +
       }:

     

       45
       45
       +
       

     

       46
       46
       +
       let

     

       47
       47
       +
         # HTTP support is disabled in order to force that HTTP dependencies are built

     

       48
       48
       +
         # using Nix instead of using Dhall's support for HTTP imports.

     

       49
       49
       +
         dhallNoHTTP = haskell.lib.appendConfigureFlag dhall "-f-with-http";

     

       50
       50
       +
       

     

       51
       51
       +
         # This uses Dhall's remote importing capabilities for downloading a Dhall file.

     

       52
       52
       +
         # The output Dhall file has all imports resolved, and then is

     

       53
       53
       +
         # alpha-normalized and binary-encoded.

     

       54
       54
       +
         downloadedEncodedFile =

     

       55
       55
       +
           runCommand

     

       56
       56
       +
             (baseNameOf url)

     

       57
       57
       +
             {

     

       58
       58
       +
               outputHashAlgo = null;

     

       59
       59
       +
               outputHash = hash;

     

       60
       60
       +
               name = baseNameOf url;

     

       61
       61
       +
               nativeBuildInputs = [ cacert ];

     

       62
       62
       +
             }

     

       63
       63
       +
             ''

     

       64
       64
       +
               echo "${url} ${dhallHash}" > in-dhall-file

     

       65
       65
       +
               ${dhall}/bin/dhall --alpha --plain --file in-dhall-file | ${dhallNoHTTP}/bin/dhall encode > $out

     

       66
       66
       +
             '';

     

       67
       67
       +
       

     

       68
       68
       +
          cache = ".cache";

     

       69
       69
       +
       

     

       70
       70
       +
          data = ".local/share";

     

       71
       71
       +
       

     

       72
       72
       +
          cacheDhall = "${cache}/dhall";

     

       73
       73
       +
       

     

       74
       74
       +
          dataDhall = "${data}/dhall";

     

       75
       75
       +
       

     

       76
       76
       +
          sourceFile = "source.dhall";

     

       77
       77
       +
       

     

       78
       78
       +
       in

     

       79
       79
       +
         runCommand name { } (''

     

       80
       80
       +
           set -eu

     

       81
       81
       +
       

     

       82
       82
       +
           mkdir -p ${cacheDhall} $out/${cacheDhall}

     

       83
       83
       +
       

     

       84
       84
       +
           export XDG_CACHE_HOME=$PWD/${cache}

     

       85
       85
       +
       

     

       86
       86
       +
           SHA_HASH="${dhallHash}"

     

       87
       87
       +
       

     

       88
       88
       +
           HASH_FILE="''${SHA_HASH/sha256:/1220}"

     

       89
       89
       +
       

     

       90
       90
       +
           cp ${downloadedEncodedFile} $out/${cacheDhall}/$HASH_FILE

     

       91
       91
       +
       

     

       92
       92
       +
           echo "missing $SHA_HASH" > $out/binary.dhall

     

       93
       93
       +
         '' +

     

       94
       94
       +
         lib.optionalString source ''

     

       95
       95
       +
           ${dhallNoHTTP}/bin/dhall decode --file ${downloadedEncodedFile} > $out/${sourceFile}

     

       96
       96
       +
         '')

pkgs/test/default.nix

···

       58
       58
        
         };

     

       59
       59
        
       

     

       60
       60
        
         writers = callPackage ../build-support/writers/test.nix {};

     

       61
       61
       +
       

     

       62
       62
       +
         dhall = callPackage ./dhall { };

     

       61
       63
        
       }

+14

pkgs/test/dhall/buildDhallUrl/default.nix

···

       1
       1
       +
       { dhallPackages, lib }:

     

       2
       2
       +
       

     

       3
       3
       +
       # This file tests that dhallPackages.buildDhallUrl is able to successfully

     

       4
       4
       +
       # build a Nix Dhall package for a given remote Dhall import.

     

       5
       5
       +
       #

     

       6
       6
       +
       # TODO: It would be nice to extend this test to make sure that the resulting

     

       7
       7
       +
       # Nix Dhall package is has the expected contents.

     

       8
       8
       +
       

     

       9
       9
       +
       dhallPackages.buildDhallUrl {

     

       10
       10
       +
         url = "https://raw.githubusercontent.com/cdepillabout/example-dhall-nix/e6a675c72ecd4dd23d254a02aea8181fe875747f/mydhallfile.dhall";

     

       11
       11
       +
         hash = "sha256-434x+QjHRzuprBdw0h6wmwB1Zj6yZqQb533me8XdO4c=";

     

       12
       12
       +
         dhallHash = "sha256:e37e31f908c7473ba9ac1770d21eb09b0075663eb266a41be77de67bc5dd3b87";

     

       13
       13
       +
         source = true;

     

       14
       14
       +
       }

pkgs/test/dhall/default.nix

···

       1
       1
       +
       { lib, callPackage }:

     

       2
       2
       +
       

     

       3
       3
       +
       lib.recurseIntoAttrs {

     

       4
       4
       +
         buildDhallUrl = callPackage ./buildDhallUrl { };

     

       5
       5
       +
       }

pkgs/top-level/dhall-packages.nix

···

       17
       17
        
             buildDhallDirectoryPackage =

     

       18
       18
        
               callPackage ../development/interpreters/dhall/build-dhall-directory-package.nix { };

     

       19
       19
        
       

     

       20
       20
       +
             buildDhallUrl =

     

       21
       21
       +
               callPackage ../development/interpreters/dhall/build-dhall-url.nix { };

     

       22
       22
       +
       

     

       20
       23
        
           in

     

       21
       24
        
             { inherit

     

       22
       25
        
                 callPackage

     

       23
       26
        
                 buildDhallPackage

     

       24
       27
        
                 buildDhallGitHubPackage

     

       25
       28
        
                 buildDhallDirectoryPackage

     

       29
       29
       +
                 buildDhallUrl

     

       26
       30
        
               ;

     

       27
       31
        
       

     

       28
       32
        
               lib = import ../development/dhall-modules/lib.nix { inherit lib; };