- <sect2>
- <title>A larger project</title>
-
- <para>Larger projects are usually structured into a number of
- sub-directories, each of which has its own
- <filename>Makefile</filename>. (In very large projects, this
- sub-structure might be iterated recursively, though that is
- rare.) To give you the idea, here's part of the directory
- structure for the (rather large) GHC project:</para>
-
-<programlisting>$(FPTOOLS_TOP)/ghc/
- Makefile
- mk/
- boilerplate.mk
- rules.mk
- docs/
- Makefile
- ...source files for documentation...
- driver/
- Makefile
- ...source files for driver...
- compiler/
- Makefile
- parser/...source files for parser...
- renamer/...source files for renamer...
- ...etc...</programlisting>
-
- <para>The sub-directories <filename>docs</filename>,
- <filename>driver</filename>, <filename>compiler</filename>, and
- so on, each contains a sub-component of GHC, and each has its
- own <filename>Makefile</filename>. There must also be a
- <filename>Makefile</filename> in
- <filename>$(FPTOOLS_TOP)/ghc</filename>.
- It does most of its work by recursively invoking
- <command>gmake</command> on the <filename>Makefile</filename>s
- in the sub-directories. We say that
- <filename>ghc/Makefile</filename> is a <emphasis>non-leaf
- <filename>Makefile</filename></emphasis>, because it does little
- except organise its children, while the
- <filename>Makefile</filename>s in the sub-directories are all
- <emphasis>leaf <filename>Makefile</filename>s</emphasis>. (In
- principle the sub-directories might themselves contain a
- non-leaf <filename>Makefile</filename> and several
- sub-sub-directories, but that does not happen in GHC.)</para>
-
- <para>The <filename>Makefile</filename> in
- <filename>ghc/compiler</filename> is considered a leaf
- <filename>Makefile</filename> even though the
- <filename>ghc/compiler</filename> has sub-directories, because
- these sub-directories do not themselves have
- <filename>Makefile</filename>s in them. They are just used to
- structure the collection of modules that make up GHC, but all
- are managed by the single <filename>Makefile</filename> in
- <filename>ghc/compiler</filename>.</para>
-
- <para>You will notice that <filename>ghc/</filename> also
- contains a directory <filename>ghc/mk/</filename>. It contains
- GHC-specific <filename>Makefile</filename> boilerplate code.
- More precisely:</para>
-
- <itemizedlist>
- <listitem>
- <para><filename>ghc/mk/boilerplate.mk</filename> is included
- at the top of <filename>ghc/Makefile</filename>, and of all
- the leaf <filename>Makefile</filename>s in the
- sub-directories. It in turn <literal>include</literal>s the
- main boilerplate file
- <filename>mk/boilerplate.mk</filename>.</para>
- </listitem>
-
- <listitem>
- <para><filename>ghc/mk/target.mk</filename> is
- <literal>include</literal>d at the bottom of
- <filename>ghc/Makefile</filename>, and of all the leaf
- <filename>Makefile</filename>s in the sub-directories. It
- in turn <literal>include</literal>s the file
- <filename>mk/target.mk</filename>.</para>
- </listitem>
- </itemizedlist>
-
- <para>So these two files are the place to look for GHC-wide
- customisation of the standard boilerplate.</para>
- </sect2>
-