This is a small quality-of-life improvement so that
the package version/revision can be inferred from the
/nix/store path (which is the convention for most of the
Nixpkgs ecosystem).
By default, `dhall-docs` uses the name of the input directory
as the initial component of the documentation header. However,
since the input directory is built using Nix the header contains
the Nix store hash in the name, which then appears in the
generated documentation.
The fix is to override this default behavior by supplying the
`--package-name` flag to `dhall-docs`.
The `buildDhall{Directory,GitHub}Package` utilities now take an
optional `document` argument for generating documentation using
`dhall-docs`. The documentation is stored underneath the `./docs`
subdirectory of the build product.
Before this change, a Dhall package like the Prelude would be
encoded as a record with one field per supported version. Then
downstream packages would specify which package to override
by selecting a different record field.
The problem with that approach is that it did not provide an
easy way to override a package to a version other than the default
ones supplied by Nixpkgs. Normally you would use the `.override`
method for this purpose, but the `override` method added by
`buildDhall{Directory,GitHub}Package` is clobbered by the
`override` method added by `callPackage` in
`./pkgs/top-level/dhall-packages.nix`.
The solution is to add a separate `.overridePackage` method which is
essentially the exact same as `.override`, except that it is no
longer clobbered by `callPackage`. This `.overridePackage` method
allows one to override the arguments supplied to
`buildDhall{Directory,GitHub}Package`, making it easier to specify
package versions outside of the ones supported by Nixpkgs..
This also includes a change to only build one (preferred) version of each
package (instead of multiple supported versions per package), in order to
minimize the maintenance burden for the Dhall package set.
The motivation for this change is to enable a new Dhall command-line
utility called `dhall-to-nixpkgs` which converts Dhall packages to
buildable Nix packages. You can think of `dhall-to-nixpkgs` as the
Dhall analog of `cabal2nix`.
You can find the matching pull request for `dhall-to-nixpkgs` here:
https://github.com/dhall-lang/dhall-haskell/pull/1826
The two main changes required to support `dhall-to-nixpkgs` are:
* Two new `buildDhall{Directory,GitHub}Package` utilities are added
`dhall-to-nixpkgs` uses these in the generated output
* `pkgs.dhallPackages` now selects a default version for each package
using the `prefer` utility
All other versions are still buildable via a `passthru` attribute
One of the motivations for this change is the following Discourse
discussion:
https://discourse.dhall-lang.org/t/offline-use-of-prelude/137
Many users have requested Dhall support for "offline" packages
that can be fetched/built/installed using ordinary package
management tools (like Nix) instead of using Dhall's HTTP import system.
I will continue to use the term "offline" to mean Dhall package
builds that do not use Dhall's language support for HTTP imports (and
instead use the package manager's support for HTTP requests, such
as `pkgs.fetchFromGitHub`)
The goal of this change is to document what is the idiomatic way to
implement "offline" Dhall builds by implementing Nixpkgs support
for such builds. That way when other package management tools ask
me how to package Dhall with their tools I can refer them to how it
is done in Nixpkgs.
This change contains a fully "offline" build for the largest Dhall
package in existence, known as "dhall-packages" (not to be confused
with `dhallPackages`, which is our Nix attribute set containing
Dhall packages).
The trick to implementing offline builds in Dhall is to take
advantage of Dhall's support for semantic integrity checks. If an
HTTP import is protected by an integrity check and a cached build
product matches the integrity check then the HTTP import is never
resolved and the expression is instead fetched from cache.
By "installing" dependencies in a pre-seeded and isolated cache
we can replace remote HTTP imports with dependencies that have
been built and supplied by Nix instead.
The offline nature of the builds are enforced by compiling the
Haskell interpreter with the `-f-with-http` flag, which disables
the interpreter's support for HTTP imports. If a user forgets
to supply a necessary dependency as a Nix build product then the
build fails informing them that HTTP imports are disabled.
By default, built packages are "binary distributions", containing
just a cache product and a Dhall expression which can be used to
resolve the corresponding cache product.
Users can also optionally enable a "source distribution" of a package
which already includes the equivalent fully-evaluated Dhall code (for
convenience), but this is disabled by default to keep `/nix/store`
utilization as compact as possible.
