From 0fe0b18432621713f96c437dfa3c81d4e3ae8e36 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Mon, 2 Oct 2017 16:54:28 +0200 Subject: Add additional notes to module documentation --- doc/manual.cli | 29 +++++++++++++++++++++-------- 1 file changed, 21 insertions(+), 8 deletions(-) (limited to 'doc/manual.cli') 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 -- cgit v1.1