Developing-Hadrian.md

@@ -6,7 +6,7 @@ Shake, Hadrian's underlying build system, has a cloud shared cache feature. This
 
 * **Direct Dependency**: All files read by a rule are direct dependencies of that rule
 * **Direct Output**: All files created by a rule that are the target of the rule or are direct dependencies of other rules.
-* **Vital Dependency**: a subset of direct dependencies that excludes files whose existence have no affect on the vital output (i.e. cache files of external tools).
+* **Vital Dependency**: a subset of direct dependencies that excludes files whose *existence* have no affect on the vital output (i.e. cache files of external tools).
 * **Vital Output**: a subset of direct outputs that are the target of the current rule or are vital dependencies of any rule.
 * **Shallow Dependency**: A subset of the direct dependencies such that: *no change in the shallow dependencies -> no change in the vital output*. This set is not unique (the direct dependencies are trivially a set of shallow dependencies), but we try to define this as a minimal (or close to minimal) set. With respect to a rule for a haskell object file X.o, the shallow dependencies are the source file X.hs and interface files Y.hi (or Y.hi-boot) for all modules Y imported by X (see [makefile-dependencies](https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/separate_compilation.html#makefile-dependencies)). These are the dependencies of X.o as reported by `ghc -M X.hs`. Note that ghc reads some transitively imported module's .hi files, but those files are deep dependencies as ghc guarantees that the shallow .hi dependencies (directly imported modules) will change if the deep .hi dependencies (transitively imported modules) change.
 * **Deep Dependency**: The direct dependencies minus the shallow dependencies. With respect to a rule for a haskell object file X.o, the deep dependencies are all hi/hi-boot files required by ghc to build X.o excluding direct dependencies. This is a subset of modules transitively imported by X. These dependencies are NOT reported by `ghc -M X.hs`
@@ -36,8 +36,10 @@ In this case the rule to build A.o via `ghc -c A.hs` has:
 
 How accurate do dependencies need to be? In any given build rule, dependencies are generally expressed via the `need` function, and outputs are the target file(s) of the rule and any files passed to the `produces` function. Must we `need` all direct inputs and `produces` all direct outputs? Not really, in fact that would often be an onerous task. For a cloud build systems the following invariants must hold:
 
-* need all shallow dependencies.
-* `produces` all vital outputs (excluding the rule target).
+* All rules need all their shallow dependencies.
+* All rules `produces` all vital outputs excluding the rule targets(s).
+
+This implies that All shallow dependencies of all rules must match some rule target (as opposed to being passed to `produces`) or be source files (i.e. exist without needing to be built).
 
 ### Linting with fsatrace