aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2017-10-02 16:54:28 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2017-10-02 16:54:28 +0200
commit0fe0b18432621713f96c437dfa3c81d4e3ae8e36 (patch)
tree7c94d12d278145a14f99813f77790cb233e50348
parentef1459feaf422fbbb069f2525547ef9b2204ccdf (diff)
Add additional notes to module documentation
-rw-r--r--doc/manual.cli29
1 files changed, 21 insertions, 8 deletions
diff --git a/doc/manual.cli b/doc/manual.cli
index 04db55c..f3f9023 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -1542,14 +1542,27 @@ header/source separation and have everything in a single file.
There are a number of drawbacks with this approach: Every time we change
anything in the module interface unit, all its consumers have to be
recompiled. If we keep everything in a single file, then every time we change
-the implementation we trigger recompilations that would have been avoided
-had the implementation been factored out into a separate unit.
-
-Another issues is the readability of the interface which could be
-significantly reduced if littered with implementation details. We could keep
-the interface separate by moving the implementation to the bottom of the
-interface file but then we might as well move it into a separate file and
-avoid the unnecessary recompilations.
+the implementation we trigger recompilations that would have been avoided had
+the implementation been factored out into a separate unit. Note that a build
+system in cooperation with the compiler could theoretically avoid such
+unnecessary recompilations: if the compiler produces identical binary
+interface files when the module interface is unchanged, then the build system
+could detect this and skip recompiling the module's consumers.
+
+A related issue with single-file modules is the reduction in the build
+parallelization opportunities. If the implementation is part of the interface
+unit, then the build system cannot start compiling the module's consumers
+until both the interface and the implementation are compiled. On the other
+hand, had the implementation been split into a separate file, the build system
+could start compiling the module's consumers (as well as the implementation
+unit) as soon as the module interface is compiled.
+
+Another issues with combining the interface with the implementation is the
+readability of the interface which could be significantly reduced if littered
+with implementation details. We could keep the interface separate by moving
+the implementation to the bottom of the interface file but then we might as
+well move it into a separate file and avoid the unnecessary recompilations or
+parallelization issues.
The sensible guideline is then to have a separate module implementation unit
except perhaps for modules with a simple implementation that is mostly