···5050check, so the first step is to freeze the expression using `dhall freeze`,
5151like this:
52525353-```bash
5353+```ShellSession
5454$ dhall freeze --inplace ./true.dhall
5555```
5656···113113114114… which we can then build using this command:
115115116116-```bash
116116+```ShellSession
117117$ nix build --file ./example.nix dhallPackages.true
118118```
119119···121121122122The above package produces the following directory tree:
123123124124-```bash
124124+```ShellSession
125125$ tree -a ./result
126126result
127127├── .cache
···135135136136* `source.dhall` contains the result of interpreting our Dhall package:
137137138138- ```bash
138138+ ```ShellSession
139139 $ cat ./result/source.dhall
140140 True
141141 ```
···143143* The `.cache` subdirectory contains one binary cache product encoding the
144144 same result as `source.dhall`:
145145146146- ```bash
146146+ ```ShellSession
147147 $ dhall decode < ./result/.cache/dhall/122027abdeddfe8503496adeb623466caa47da5f63abd2bc6fa19f6cfcb73ecfed70
148148 True
149149 ```
···151151* `binary.dhall` contains a Dhall expression which handles fetching and decoding
152152 the same cache product:
153153154154- ```bash
154154+ ```ShellSession
155155 $ cat ./result/binary.dhall
156156 missing sha256:27abdeddfe8503496adeb623466caa47da5f63abd2bc6fa19f6cfcb73ecfed70
157157 $ cp -r ./result/.cache .cache
···168168example, if we build the Prelude package it will only contain the binary
169169encoding of the expression:
170170171171-```bash
171171+```ShellSession
172172$ nix build --file ./example.nix dhallPackages.Prelude
173173174174$ tree -a result
···199199… and now the Prelude will contain the fully decoded result of interpreting
200200the Prelude:
201201202202-```bash
202202+```ShellSession
203203$ nix build --file ./example.nix dhallPackages.Prelude
204204205205$ tree -a result
···302302You can use the `dhall-to-nixpkgs` command-line utility to automate
303303packaging Dhall code. For example:
304304305305-```bash
305305+```ShellSession
306306$ nix-env --install --attr haskellPackages.dhall-nixpkgs
307307308308$ nix-env --install --attr nix-prefetch-git # Used by dhall-to-nixpkgs
···329329them to package dependencies. You can also use the utility on local
330330Dhall directories, too:
331331332332-```bash
332332+```ShellSession
333333$ dhall-to-nixpkgs directory ~/proj/dhall-semver
334334{ buildDhallDirectoryPackage, Prelude }:
335335 buildDhallDirectoryPackage {
336336 name = "proj";
337337- src = /Users/gabriel/proj/dhall-semver;
337337+ src = ~/proj/dhall-semver;
338338 file = "package.dhall";
339339 source = false;
340340 document = false;
···342342 }
343343```
344344345345+### Remote imports as fixed-output derivations {#ssec-dhall-remote-imports-as-fod}
346346+347347+`dhall-to-nixpkgs` has the ability to fetch and build remote imports as
348348+fixed-output derivations by using their Dhall integrity check. This is
349349+sometimes easier than manually packaging all remote imports.
350350+351351+This can be used like the following:
352352+353353+```ShellSession
354354+$ dhall-to-nixpkgs directory --fixed-output-derivations ~/proj/dhall-semver
355355+{ buildDhallDirectoryPackage, buildDhallUrl }:
356356+ buildDhallDirectoryPackage {
357357+ name = "proj";
358358+ src = ~/proj/dhall-semver;
359359+ file = "package.dhall";
360360+ source = false;
361361+ document = false;
362362+ dependencies = [
363363+ (buildDhallUrl {
364364+ url = "https://prelude.dhall-lang.org/v17.0.0/package.dhall";
365365+ hash = "sha256-ENs8kZwl6QRoM9+Jeo/+JwHcOQ+giT2VjDQwUkvlpD4=";
366366+ dhallHash = "sha256:10db3c919c25e9046833df897a8ffe2701dc390fa0893d958c3430524be5a43e";
367367+ })
368368+ ];
369369+ }
370370+```
371371+372372+Here, `dhall-semver`'s `Prelude` dependency is fetched and built with the
373373+`buildDhallUrl` helper function, instead of being passed in as a function
374374+argument.
375375+345376## Overriding dependency versions {#ssec-dhall-overriding-dependency-versions}
346377347378Suppose that we change our `true.dhall` example expression to depend on an older
···359390360391If we try to rebuild that expression the build will fail:
361392362362-```
393393+```ShellSession
363394$ nix build --file ./example.nix dhallPackages.true
364395builder for '/nix/store/0f1hla7ff1wiaqyk1r2ky4wnhnw114fi-true.drv' failed with exit code 1; last 10 log lines:
365396···385416However, we can override the default Prelude version by using `dhall-to-nixpkgs`
386417to create a Dhall package for our desired Prelude:
387418388388-```bash
419419+```ShellSession
389420$ dhall-to-nixpkgs github https://github.com/dhall-lang/dhall-lang.git \
390421 --name Prelude \
391422 --directory Prelude \
···396427… and then referencing that package in our Dhall overlay, by either overriding
397428the Prelude globally for all packages, like this:
398429399399-```bash
430430+```nix
400431 dhallOverrides = self: super: {
401432 true = self.callPackage ./true.nix { };
402433···407438… or selectively overriding the Prelude dependency for just the `true` package,
408439like this:
409440410410-```bash
441441+```nix
411442 dhallOverrides = self: super: {
412443 true = self.callPackage ./true.nix {
413444 Prelude = self.callPackage ./Prelude.nix { };
···11+{ cacert, dhall, dhall-docs, haskell, lib, runCommand }:
22+33+# `buildDhallUrl` is similar to `buildDhallDirectoryPackage` or
44+# `buildDhallGitHubPackage`, but instead builds a Nixpkgs Dhall package
55+# based on a hashed URL. This will generally be a URL that has an integrity
66+# check in a Dhall file.
77+#
88+# Similar to `buildDhallDirectoryPackage` and `buildDhallGitHubPackage`, the output
99+# of this function is a derivation that has a `binary.dhall` file, along with
1010+# a `.cache/` directory with the actual contents of the Dhall file from the
1111+# suppiled URL.
1212+#
1313+# This function is primarily used by `dhall-to-nixpkgs directory --fixed-output-derivations`.
1414+1515+{ # URL of the input Dhall file.
1616+ # example: "https://raw.githubusercontent.com/cdepillabout/example-dhall-repo/c1b0d0327146648dcf8de997b2aa32758f2ed735/example1.dhall"
1717+ url
1818+1919+ # Nix hash of the input Dhall file.
2020+ # example: "sha256-ZTSiQUXpPbPfPvS8OeK6dDQE6j6NbP27ho1cg9YfENI="
2121+, hash
2222+2323+ # Dhall hash of the input Dhall file.
2424+ # example: "sha256:6534a24145e93db3df3ef4bc39e2ba743404ea3e8d6cfdbb868d5c83d61f10d2"
2525+, dhallHash
2626+2727+ # Name for this derivation.
2828+, name ? (baseNameOf url + "-cache")
2929+3030+ # `buildDhallUrl` can include both a "source distribution" in
3131+ # `source.dhall` and a "binary distribution" in `binary.dhall`:
3232+ #
3333+ # * `source.dhall` is a dependency-free αβ-normalized Dhall expression
3434+ #
3535+ # * `binary.dhall` is an expression of the form: `missing sha256:${HASH}`
3636+ #
3737+ # This expression requires you to install the cache product located at
3838+ # `.cache/dhall/1220${HASH}` to successfully resolve
3939+ #
4040+ # By default, `buildDhallUrl` only includes "binary.dhall" to conserve
4141+ # space within the Nix store, but if you set the following `source` option to
4242+ # `true` then the package will also include `source.dhall`.
4343+, source ? false
4444+}:
4545+4646+let
4747+ # HTTP support is disabled in order to force that HTTP dependencies are built
4848+ # using Nix instead of using Dhall's support for HTTP imports.
4949+ dhallNoHTTP = haskell.lib.appendConfigureFlag dhall "-f-with-http";
5050+5151+ # This uses Dhall's remote importing capabilities for downloading a Dhall file.
5252+ # The output Dhall file has all imports resolved, and then is
5353+ # alpha-normalized and binary-encoded.
5454+ downloadedEncodedFile =
5555+ runCommand
5656+ (baseNameOf url)
5757+ {
5858+ outputHashAlgo = null;
5959+ outputHash = hash;
6060+ name = baseNameOf url;
6161+ nativeBuildInputs = [ cacert ];
6262+ }
6363+ ''
6464+ echo "${url} ${dhallHash}" > in-dhall-file
6565+ ${dhall}/bin/dhall --alpha --plain --file in-dhall-file | ${dhallNoHTTP}/bin/dhall encode > $out
6666+ '';
6767+6868+ cache = ".cache";
6969+7070+ data = ".local/share";
7171+7272+ cacheDhall = "${cache}/dhall";
7373+7474+ dataDhall = "${data}/dhall";
7575+7676+ sourceFile = "source.dhall";
7777+7878+in
7979+ runCommand name { } (''
8080+ set -eu
8181+8282+ mkdir -p ${cacheDhall} $out/${cacheDhall}
8383+8484+ export XDG_CACHE_HOME=$PWD/${cache}
8585+8686+ SHA_HASH="${dhallHash}"
8787+8888+ HASH_FILE="''${SHA_HASH/sha256:/1220}"
8989+9090+ cp ${downloadedEncodedFile} $out/${cacheDhall}/$HASH_FILE
9191+9292+ echo "missing $SHA_HASH" > $out/binary.dhall
9393+ '' +
9494+ lib.optionalString source ''
9595+ ${dhallNoHTTP}/bin/dhall decode --file ${downloadedEncodedFile} > $out/${sourceFile}
9696+ '')
···11+{ dhallPackages, lib }:
22+33+# This file tests that dhallPackages.buildDhallUrl is able to successfully
44+# build a Nix Dhall package for a given remote Dhall import.
55+#
66+# TODO: It would be nice to extend this test to make sure that the resulting
77+# Nix Dhall package is has the expected contents.
88+99+dhallPackages.buildDhallUrl {
1010+ url = "https://raw.githubusercontent.com/cdepillabout/example-dhall-nix/e6a675c72ecd4dd23d254a02aea8181fe875747f/mydhallfile.dhall";
1111+ hash = "sha256-434x+QjHRzuprBdw0h6wmwB1Zj6yZqQb533me8XdO4c=";
1212+ dhallHash = "sha256:e37e31f908c7473ba9ac1770d21eb09b0075663eb266a41be77de67bc5dd3b87";
1313+ source = true;
1414+}