@@ -0,0 +1,90 @@
1+# Developer Architecture Overview
2+
3+This shall give a sufficiently good overview over the haskell.nix
4+ideas, such that a new developer can navigate around without too
5+much trouble.
6+
7+## Packages
8+
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.
14+
15+These packages will look similar to the following:
16+
17+```nix
18+{ system, compiler, flags, pkgs, hsPkgs, pkgconfPkgs, ... }:
19+{
20+ flags = {};
21+ package = { ... };
22+ components = {
23+ "library" = { depends = [ ... ]; };
24+ exes = { "..." = { depends = [ ... ]; }; ... };
25+ sublibs = { "..." = { depends = [ ... ]; }; ... };
26+ tests = { "..." = { depends = [ ... ]; }; ... };
27+ benchmarks = { "..." = { depends = [ ... ]; }; ... };
28+ };
29+};
30+```
31+
32+The exact specification can be found in `modules/package.nix`.
33+
34+## Plans
35+
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`.
39+
40+Plan files usually look like the following:
41+```nix
42+hackage:
43+{
44+ packages = {
45+ "$pkg".revision = hackage.$pkg.$version.revisions.default;
46+ "$pkg".flags = { flag1 = true; flag2 = false; ... };
47+ ...
48+ };
49+ compiler = {
50+ version = "8.4.4";
51+ nix-name = "ghc844";
52+ packages = {
53+ "binary" = "0.8.5.1";
54+ ...
55+ };
56+ };
57+}
58+```
59+
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.
62+
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
66+previous section.
67+
68+## Package Sets (of derivations)
69+
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.
73+
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*).
77+
78+### Component builder
79+
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`.
85+
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
90+`config.hsPkgs`.