@@ -0,0 +1,90 @@
1+# Developer Architecture Overview
3+This shall give a sufficiently good overview over the haskell.nix
4+ideas, such that a new developer can navigate around without too
9+`haskell.nix` is centered around packages (haskell package
10+descriptions as nix-expressions). These are generated by
11+`cabal-to-nix` from the `nix-tools` package. `stack-to-nix` and
12+`plan-to-nix` will delegate the transformation of cabal packages to
13+nix expressions to the same code that `cabal-to-nix` uses.
15+These packages will look similar to the following:
18+{ system, compiler, flags, pkgs, hsPkgs, pkgconfPkgs, ... }:
23+ "library" = { depends = [ ... ]; };
24+ exes = { "..." = { depends = [ ... ]; }; ... };
25+ sublibs = { "..." = { depends = [ ... ]; }; ... };
26+ tests = { "..." = { depends = [ ... ]; }; ... };
27+ benchmarks = { "..." = { depends = [ ... ]; }; ... };
32+The exact specification can be found in `modules/package.nix`.
36+Packages (unless specified directly in the `packages` attribute of the
37+module) usually come from a plan. A plan is either a Stackage snapshot
38+(nightly or LTS) or a build plan as produced by `cabal`.
40+Plan files usually look like the following:
45+ "$pkg".revision = hackage.$pkg.$version.revisions.default;
46+ "$pkg".flags = { flag1 = true; flag2 = false; ... };
53+ "binary" = "0.8.5.1";
60+This provides enough information about the compiler, what packages the
61+compiler ships with and the packages we want to use in our plan.
63+This revision and flag information will be inlined into a list of
64+packages in `config.packages` in `modules/plan.nix`. Thus
65+`config.packages` will only contains packages as described in the
68+## Package Sets (of derivations)
70+We finally tie this all together in `package-set.nix` where we use
71+`modules/component-driver.nix` to produce the derivations for each
72+packages component to produce the final `config.hsPkgs` value.
74+There is also a `modules/compat-driver.nix` that should produce the
75+same packageset to be used with the stock haskell infrastructure in
76+nixpkgs (*This has undergone substantially less testing*).
80+To prevent depending on mutliple instances of the same libraries, the
81+component builder will try to build every package from scratch and
82+rely as little as possible on packages that are shipped with the GHC
83+distribution. The exceptions are packages that are known to not be
84+reinstallable. See `config.nonReinstallablePkgs`.
86+The component builder can be found in `modules/component-driver.nix`
87+and `builder/default.nix`. The component-driver will ensure that we do
88+not try to rebuild non-reinstallable packages, and call the
89+`builder/default.nix` on each package in `config.packages` to produce