Update installation instructions with Clang on Windows

1 files changed, 224 insertions, 0 deletions

diff --git a/BOOTSTRAP-WINDOWS-CLANG.cli b/BOOTSTRAP-WINDOWS-CLANG.cli
new file mode 100644
index 0000000..56ac443
--- /dev/null
+++ b/BOOTSTRAP-WINDOWS-CLANG.cli
@@ -0,0 +1,224 @@
+// file      : BOOTSTRAP-WINDOWS-CLANG.cli
+// copyright : Copyright (c) 2014-2019 Code Synthesis Ltd
+// license   : MIT; see accompanying LICENSE file
+
+"
+Continuing from \l{#bootstrap-windows Bootstrapping on Windows}, there two
+common ways to obtain Clang on Windows: bundled with the MSVC installation or
+as a separate installation. If you are using a separate installation, then the
+Clang compiler is most likely already in your \c{PATH} environment variable
+and, after confirming this is the case, you can continue using the command
+prompt started on the previous step:
+
+\
+> where clang++
+\
+
+Otherwise, if you are using Clang that is bundled with MSVC (and haven't
+manually added its compiler to \c{PATH}), start the Visual Studio \"x64 Native
+Tools Command Prompt\" and set the \c{PATH} environment variable:
+
+\
+> set \"PATH=C:\build2\bin;%VCINSTALLDIR%Tools\Llvm\bin;%PATH%\"
+> where clang++
+\
+
+To build with Clang you can either perform the following steps manually or, if
+after reviewing the steps you are happy with using the defaults, run the
+\c{build-clang.bat} batch file. It performs (and echoes) the same set of steps
+as outlined below but only allows you to customize the installation directory
+and a few other things (run \c{build-clang.bat /?} for usage).
+
+For example, you could run this batch file (from the above-mentioned command
+prompt) like this:
+
+\
+> .\build-clang.bat
+\
+
+\N|Note that at about half way through (\c{bpkg fetch} at step 4 below) the
+script will stop and prompt you to verify the authenticity of the repository
+certificate. To run the script unattended you can specify the certificate
+fingerprint with the \c{--trust} option (see \c{build-clang.bat /?} for
+details).|
+
+The end result of the bootstrap process (performed either with the script or
+manually) is the installed toolchain as well as the \c{bpkg} configuration in
+\c{build2-toolchain-X.Y\\} that can be used to \l{#upgrade upgrade} to newer
+versions. It can also be used to uninstall the toolchain:
+
+\
+> cd build2-toolchain-X.Y
+> bpkg uninstall build2 bpkg bdep
+\
+
+\N|Note that in both cases (manual or scripted bootstrap), if something goes
+wrong and you need to restart the process, you \b{must} start with a clean
+toolchain source by unpacking it afresh from the archive.|
+
+The rest of this section outlines the manual bootstrap process.
+
+\dl|
+
+\li|\b{1. Bootstrap, Phase 1}\n
+
+First, we build a minimal build system with the provided
+\c{bootstrap-clang.bat} batch file. Normally, the only argument you will pass
+to this script is the C++ compiler to use but there is also a way to specify
+compile options; run \c{bootstrap-clang.bat /?} and see the
+\c{build2\\INSTALL} file for details.
+
+\
+> cd build2
+> .\bootstrap-clang.bat clang++
+
+> build2\b-boot --version
+\
+
+Alternatively, we can use the \c{bootstrap.gmake} GNU makefile to bootstrap
+in parallel:
+
+\
+> cd build2
+> mingw32-make -f bootstrap.gmake -j 8 CXX=clang++
+
+> build2\b-boot --version
+\
+
+|
+
+\li|\n\b{2. Bootstrap, Phase 2}\n
+
+Then, we rebuild the build system with the result of Phase 1 linking libraries
+statically.
+
+\
+> build2\b-boot           ^
+  config.cxx=clang++      ^
+  config.cc.coptions=-m64 ^
+  config.bin.lib=static   ^
+  build2\exe{b}
+
+> move /y build2\b.exe build2\b-boot.exe
+
+> build2\b-boot --version
+\
+
+|
+
+\li|\n\b{3. Stage}\n
+
+At this step the build system and package manager are built with shared
+libraries and then staged:
+
+\
+> cd ..  # Back to build2-toolchain-X.Y.Z\
+
+> build2\build2\b-boot configure      ^
+  config.cxx=clang++                  ^
+  config.cc.coptions=-m64             ^
+  config.bin.lib=shared               ^
+  config.bin.suffix=-stage            ^
+  config.install.root=C:\build2       ^
+  config.install.data_root=root\stage
+
+> build2\build2\b-boot install: build2/ bpkg/
+\
+
+The strange-looking \c{config.install.data_root=root\\stage} means install
+data files (as opposed to executable files) into the \c{stage\\} subdirectory
+of wherever \c{config.install.root} points to (so in our case it will be
+\c{C:\\build2\\stage\\}). This subdirectory is temporary and will be removed
+in a few steps.
+
+Verify that the toolchain binaries can be found and work (this relies on the
+\c{PATH} environment variable we have set earlier):
+
+\
+> where b-stage
+C:\build2\bin\b-stage.exe
+
+> where bpkg-stage
+C:\build2\bin\bpkg-stage.exe
+
+> b-stage --version
+> bpkg-stage --version
+\
+
+At the next step we will use \c{bpkg} to build and install the entire
+toolchain. If for some reason you prefer not to build from packages (for
+example, because the machine is offline), then you can convert this step into
+the \"final\" installation and skip the rest. For this you will need to change
+the \c{configure} and \c{install} command lines above along these lines:
+
+\
+> build2\build2\b-boot configure ^
+  config.cxx=clang++             ^
+  \"config.cc.coptions=-m64 -O3\"  ^
+  config.bin.lib=shared          ^
+  config.install.root=C:\build2
+
+> build2\build2\b-boot install: build2/ bpkg/ bdep/
+\
+
+|
+
+\li|\n\b{4. Install}\n
+
+Next, we use the staged tools to build and install the entire toolchain from
+the package repository with the \c{bpkg} package manager. First, we create
+the \c{bpkg} configuration. The configuration values are pretty similar to the
+previous step and you may want/need to make similar adjustments.
+
+\
+> cd ..  # Back to build2-build\
+> md build2-toolchain-X.Y
+> cd build2-toolchain-X.Y
+
+> bpkg-stage create             ^
+  cc                            ^
+  config.cxx=clang++            ^
+  \"config.cc.coptions=-m64 -O3\" ^
+  config.bin.lib=shared         ^
+  config.install.root=C:\build2
+\
+
+Next, we add the package repository, build, and install:
+
+\
+> bpkg-stage add https://pkg.cppget.org/1/alpha
+> bpkg-stage fetch
+> bpkg-stage build --for install build2 bpkg bdep
+> bpkg-stage install build2 bpkg bdep
+\
+
+Finally, we verify the result:
+
+\
+> where b
+C:\build2\bin\b.exe
+
+> where bpkg
+C:\build2\bin\bpkg.exe
+
+> where bdep
+C:\build2\bin\bdep.exe
+
+> b --version
+> bpkg --version
+> bdep --version
+\
+
+|
+
+\li|\n\b{5. Clean}\n
+
+The last thing we need to do is uninstall the staged tools:
+
+\
+> cd ..\build2-toolchain-X.Y.Z  # Back to bootstrap.
+> b uninstall: build2/ bpkg/
+\
+
+||
+"