+#
+# Build platform: the platform on which we are doing this build
+# Host platform: the platform on which these binaries will run
+# Target platform: the platform for which this compiler will generate code
+#
+# We don't support build & host being different, because the build
+# process creates binaries that are run during the build, and also
+# installed.
+#
+# If host & target are different, then we are building a compiler
+# which will generate intermediate .hc files to port to the target
+# architecture for bootstrapping. The libraries and stage 2 compiler
+# will be built as HC files for the target system, and likely won't
+# build on this host platform.
+#
+# Guidelines for when to use HOST vs. TARGET:
+#
+# - In the build system (Makefile, foo.mk), normally we should test
+# $(HOSTPLATFORM). There are some cases (eg. installation), where
+# we expect $(HOSTPLATFORM)==$(TARGETPLATFORM), so in those cases it
+# doesn't matter which is used.
+#
+# - In the compiler itself, we should test HOST or TARGET depending
+# on whether the conditional relates to the code being generated, or
+# the platform on which the compiler is running. For stage 2,
+# HOSTPLATFORM should be reset to be TARGETPLATFORM (we currently
+# don't do this, but we should).
+#
+# - In the RTS and library code, we should be testing TARGET only.
+#
+# NOTE: cross-compiling is not well supported by the build system.
+# You have to do a lot of work by hand to cross compile: see the
+# section on "Porting GHC" in the Building Guide.