docs: describe where the build system is evolving to

Add a manifesto which describes where the build infrastructure is slowly
evolving to.  Although a good chunk of the necessary work to enable this
is already in the tree, this helps explain the desired state to everyone
working on the project.

Author: compnerd

docs/BuildManifesto.md

@@ -0,0 +1,96 @@
+# Build System
+
+## Introduction
+
+Modularising the build of Swift is a large undertaking that will simplify the
+infrastructure used to build the compiler, runtime, standard library, as well
+as the core libraries.  Additionally, the work will enable a unified, uniform
+build system that reduces the barrier to entry for new contributors.
+
+## Current State
+
+Currently, the Swift build is setup similar to the way that the GCC build was
+setup.  This requires the understanding of the terms `build`, `host`, `target`
+as used by autotools.
+
+<dl>
+  <dt><strong>build</strong></dt>
+  <dd>the system where the package is being configured and compiled<br/>
+    x86_64-unknown-linux-gnu
+  </dd>
+  <dt><strong>host</strong></dt>
+  <dd>the system where the package runs (by default the same as <i>build</i>)<br/>
+    x86-64-unknown-windows-msvc
+  </dd>
+  <dt><strong>target</strong></dt>
+  <dd>the system for which the compiler tools generate code<br/>
+  aarch64-unknown-linux-android<br/>
+  <strong>NOTE</strong> this is not really supported properly in the original
+  build system
+  </dd>
+</dl>
+
+## Desired State
+
+It is preferable to instead consider the full package build as a set of builds
+where you are doing normal builds with a differing set of `build` and `host`
+values.  That is, you can consider the regular host build (e.g. Linux) as:
+
+```Swift
+[
+  /* compiler */ (build: "x86_64-unknown-linux-gnu", host: "x86_64-unknown-linux-gnu"),
+  /* runtime */  (build: "x86_64-unknown-linux-gnu", host: "x86_64-unknown-linux-gnu"),
+  /* stdlib */   (build: "x86_64-unknown-linux-gnu", host: "x86_64-unknown-linux-gnu"),
+]
+```
+
+Or for more complicated scenarios such as Darwin where you may be compiling for
+Darwin and iOS as:
+
+```Swift
+[
+  /* compiler */ (build: "x86_64-apple-macosx10.14", host: "x86_64-apple-macosx10.14"),
+  /* runtime */  (build: "x86_64-apple-macosx10.14", host: "x86_64-apple-macosx10.14"),
+  /* stdlib */   (build: "x86_64-apple-macosx10.14", host: "x86_64-apple-macosx10.14"),
+  /* runtime */  (build: "x86_64-apple-macosx10.14", host: "armv7-apple-ios12.3"),
+  /* stdlib */   (build: "x86_64-apple-macosx10.14", host: "armv7-apple-ios12.3"),
+]
+```
+
+This simplifies the build terminology by having to only deal with the terms
+`build` and `host` which removes some of the confusion caused by the original
+build system's implementation creating multiple terms and being designed around
+the needs of the Darwin build.
+
+This also generalises to allow for multiple cross-compilations in a single build
+invocation which allows the functionality currently available only on Darwin to
+be applied to all the targets that Swift supports (and may support in the
+future).
+
+Doing so also enables the build system to be trimmed significantly as we can use
+CMake as it was designed to while retaining the ability to cross-compile.  The
+cross-compilation model for CMake involves invoking `cmake` multiple times with
+`CMAKE_SYSTEM_NAME` and `CMAKE_SYSTEM_PROCESSOR` set appropriately to the host
+that you would like to build for.  This ensures that host specific behaviour is
+explicitly handled properly (e.g. import libraries on Windows - something which
+was shoehorned into the original CMake implementation in CMake) and corrects the
+behaviour of the cmake `install` command.
+
+Another bit of functional flexibility that this system enables is the ability to
+allow developers to focus entirely on the area that they are working in.  The
+runtime and standard library can be separated and built with a prebuilt
+(nightly) release of the compiler toolchain, or focus entirely on building the
+standard library for a certain set of targets.
+
+By organising the standard library build as a regular library, we enable the
+ability to use the LLVM runtimes build to cross-compile the standard library for
+multiple targets as long as the dependent system libraries are available at
+build time.
+
+The ability to build the runtime components for different hosts allows building
+the Swift SDK for various hosts on a single machine.  This enables the build of
+the android SDK and Linux SDKs on Windows and vice versa.
+
+Note that none of the changes described here prevent the workflows that are
+possible with build-script today.
+