+ <sect2>
+ <title>Build trees</title>
+ <indexterm><primary>build trees</primary></indexterm>
+ <indexterm><primary>link trees, for building</primary></indexterm>
+
+ <para>If you just want to build the software once on a single
+ platform, then your source tree can also be your build tree, and
+ you can skip the rest of this section.</para>
+
+ <para>We often want to build multiple versions of our software
+ for different architectures, or with different options
+ (e.g. profiling). It's very desirable to share a single copy of
+ the source code among all these builds.</para>
+
+ <para>So for every source tree we have zero or more
+ <emphasis>build trees</emphasis>. Each build tree is initially
+ an exact copy of the source tree, except that each file is a
+ symbolic link to the source file, rather than being a copy of
+ the source file. There are “standard” Unix
+ utilities that make such copies, so standard that they go by
+ different names:
+ <command>lndir</command><indexterm><primary>lndir</primary></indexterm>,
+ <command>mkshadowdir</command><indexterm><primary>mkshadowdir</primary></indexterm>
+ are two (If you don't have either, the source distribution
+ includes sources for the X11
+ <command>lndir</command>—check out
+ <filename>fptools/glafp-utils/lndir</filename>). See <Xref
+ LinkEnd="sec-storysofar"> for a typical invocation.</para>
+
+ <para>The build tree does not need to be anywhere near the
+ source tree in the file system. Indeed, one advantage of
+ separating the build tree from the source is that the build tree
+ can be placed in a non-backed-up partition, saving your systems
+ support people from backing up untold megabytes of
+ easily-regenerated, and rapidly-changing, gubbins. The golden
+ rule is that (with a single exception—<XRef
+ LinkEnd="sec-build-config">) <emphasis>absolutely everything in
+ the build tree is either a symbolic link to the source tree, or
+ else is mechanically generated</emphasis>. It should be
+ perfectly OK for your build tree to vanish overnight; an hour or
+ two compiling and you're on the road again.</para>
+
+ <para>You need to be a bit careful, though, that any new files
+ you create (if you do any development work) are in the source
+ tree, not a build tree!</para>
+
+ <para>Remember, that the source files in the build tree are
+ <emphasis>symbolic links</emphasis> to the files in the source
+ tree. (The build tree soon accumulates lots of built files like
+ <filename>Foo.o</filename>, as well.) You can
+ <emphasis>delete</emphasis> a source file from the build tree
+ without affecting the source tree (though it's an odd thing to
+ do). On the other hand, if you <emphasis>edit</emphasis> a
+ source file from the build tree, you'll edit the source-tree
+ file directly. (You can set up Emacs so that if you edit a
+ source file from the build tree, Emacs will silently create an
+ edited copy of the source file in the build tree, leaving the
+ source file unchanged; but the danger is that you think you've
+ edited the source file whereas actually all you've done is edit
+ the build-tree copy. More commonly you do want to edit the
+ source file.)</para>
+
+ <para>Like the source tree, the top level of your build tree
+ must be (a linked copy of) the root directory of the
+ <literal>fptools</literal> suite. Inside Makefiles, the root of
+ your build tree is called
+ <constant>$(FPTOOLS_TOP)</constant><indexterm><primary>FPTOOLS_TOP</primary></indexterm>.
+ In the rest of this document path names are relative to
+ <constant>$(FPTOOLS_TOP)</constant> unless
+ otherwise stated. For example, the file
+ <filename>ghc/mk/target.mk</filename> is actually
+ <filename><constant>$(FPTOOLS_TOP)</constant>/ghc/mk/target.mk</filename>.</para>
+ </sect2>