Update installation instructions with Clang on Windows

9 files changed, 286 insertions, 32 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/
+\
+
+||
+"
diff --git a/BOOTSTRAP-WINDOWS-MSVC.cli b/BOOTSTRAP-WINDOWS-MSVC.cli
index 4283340..586aaf6 100644
--- a/BOOTSTRAP-WINDOWS-MSVC.cli
+++ b/BOOTSTRAP-WINDOWS-MSVC.cli
@@ -5,11 +5,12 @@
 "
 Continuing from \l{#bootstrap-windows Bootstrapping on Windows}, if you have
 already started an appropriate Visual Studio command prompt, then you can
-continue using it. Otherwise, start the \"x64 Native Tools Command Prompt\".
-Also set the \c{PATH} environment variable:
+continue using it. Otherwise, start the Visual Studio \"x64 Native Tools
+Command Prompt\". Also set the \c{PATH} environment variable as on the
+previous steps:
 
 \
-> set PATH=C:\build2\bin;%PATH%
+> set \"PATH=C:\build2\bin;%PATH%\"
 \
 
 To build with MSVC you can either perform the following steps manually or, if
diff --git a/BOOTSTRAP-WINDOWS.cli b/BOOTSTRAP-WINDOWS.cli
index c99ffc7..b013d3b 100644
--- a/BOOTSTRAP-WINDOWS.cli
+++ b/BOOTSTRAP-WINDOWS.cli
@@ -3,11 +3,12 @@
 // license   : MIT; see accompanying LICENSE file
 
 "
-The following instructions are for bootstrapping \c{build2} with either MSVC
-or MinGW using the Windows command prompt. If you are using any kind of UNIX
-emulation layer (for example, WSL, MSYS, or Cygwin) and already have a UNIX
-shell with standard utilities, then you most likely should follow
-\l{#bootstrap-unix Bootstrapping on UNIX} instead.
+The following instructions are for bootstrapping \c{build2} from the Windows
+command prompt with either MSVC, Clang (targeting the MSVC runtime), or
+MinGW. If you are using any kind of UNIX emulation layer (for example, WSL,
+MSYS, or Cygwin) and already have a UNIX shell with standard utilities, then
+you most likely should follow \l{#bootstrap-unix Bootstrapping on UNIX}
+instead.
 
 \N|Note that if you continue with these instructions but you already have your
 own installation of MSYS and/or MinGW, then make sure that their paths are not
@@ -20,11 +21,12 @@ The \c{build2} toolchain on Windows requires a set of extra utilities
 Normally, the \c{build2} toolchain itself is installed into the same directory
 as the utilities in order to produce the  combined installation.
 
-To build on Windows you will need either MSVC 14 Update 3 or later or MinGW
-GCC 4.9 or later. If you don't already have a suitable C++ compiler, then you
-can use the \c{build2-mingw} package which provides a minimal MinGW-W64 GCC
-distribution (see the \c{README} file inside for details). If used, then it
-should be unpacked into the same directory as \c{build2-baseutils}.
+To build on Windows you will need either MSVC 14 Update 3 or later, Clang 8 or
+later (either bundled with MSVC or installed separately), or MinGW GCC 4.9 or
+later. If you don't already have a suitable C++ compiler, then you can use the
+\c{build2-mingw} package which provides a minimal MinGW-W64 GCC distribution
+(see the \c{README} file inside for details). If used, then it should be
+unpacked into the same directory as \c{build2-baseutils}.
 
 \N|If using your own MinGW GCC installation, make sure it is configured with
 the \c{posix} threading model (this is currently the only configuration that
@@ -35,16 +37,17 @@ provided and they \b{must} match the width of the \c{build2} toolchain. Note
 also that the 64-bit \c{build2} toolchain can be used to build 32-bit
 applications without any restrictions.|
 
-To bootstrap on Windows with either MSVC or MinGW start with the following
-common steps:
+To bootstrap on Windows with either MSVC, Clang, or MinGW start with the
+following common steps:
 
 \dl|
 
 \li|\b{1. Open Command Prompt}\n
 
-Start the standard Windows Command Prompt. If you plan to build with MSVC,
-then you may go ahead and start the Visual Studio \"x64 Native Tools Command
-Prompt\" (or wait for MSVC-specific instructions).|
+Start the standard Windows Command Prompt. If you plan to build with MSVC or
+Clang bundled with MSVC, then you may go ahead and start the Visual Studio
+\"x64 Native Tools Command Prompt\" (or wait for MSVC/Clang-specific
+instructions).|
 
 \li|\n\b{2. Create Build Directory}\n
 
@@ -98,7 +101,7 @@ Set the \c{PATH} environment variable and verify that the utilities are found
 and work:
 
 \
-> set PATH=C:\build2\bin;%PATH%
+> set \"PATH=C:\build2\bin;%PATH%\"
 > where tar
 > tar --version
 \
@@ -141,6 +144,9 @@ directory:
 If building with MSVC, continue with \l{#bootstrap-windows-msvc Bootstrapping
 on Windows with MSVC}.
 
+If building with Clang, continue with \l{#bootstrap-windows-clang Bootstrapping
+on Windows with Clang}.
+
 If building with MinGW, continue with \l{#bootstrap-windows-mingw
 Bootstrapping on Windows with MinGW}.
 "
diff --git a/INSTALL.cli b/INSTALL.cli
index b361164..c4b7009 100644
--- a/INSTALL.cli
+++ b/INSTALL.cli
@@ -32,7 +32,7 @@ of these compilers should work.
 and the one that you will use to build your projects need not be the same. For
 example, if you are using MSVC 12 (2013) (which cannot build \c{build2}), it
 is perfectly fine to get a minimal MinGW toolchain and use that to build
-\c{build2}; you will still be able to use MSVC to build your own code.|
+\c{build2}; you will still be able to use MSVC 12 to build your own code.|
 
 At the high level, the bootstrap process involves the following 5 steps.
 
@@ -57,21 +57,21 @@ libraries and then staged.|
 \li|\n\b{4. Install}\n
 
 Next, the staged tools are used to build and install the entire toolchain
-from the package repository with the \cb{bpkg} package manager.|
+from the package repository with the package manager.|
 
 \li|\n\b{5. Clean}\n
 
 Finally, the staged at step 3 tools are uninstalled.||
 
 The end result of the bootstrap process is the installed toolchain as well as
-the \c{bpkg} configuration (created at step 4) that can be used to upgrade to
-newer versions.
+the package manager configuration (created at step 4) that can be used to
+upgrade to newer versions.
 
 \N|You can skip step 4 and instead install at step 3 if for some reason you
 prefer not to build from packages (for example, because the machine is
 offline).|
 
-For Windows, if you are using either MSVC or MinGW, continue with
+For Windows, if you are using either MSVC, Clang, or MinGW, continue with
 \l{#bootstrap-windows Bootstrapping on Windows}. If using WSL, MSYS, or
 Cygwin, then instead refer to \l{#bootstrap-unix Bootstrapping on UNIX}.
 
diff --git a/UPGRADE.cli b/UPGRADE.cli
index 7bdba6c..c23b26b 100644
--- a/UPGRADE.cli
+++ b/UPGRADE.cli
@@ -179,18 +179,33 @@ $ bpkg-stage create             \
 cc                              \
 config.cxx=g++                  \
 config.cc.coptions=-O3          \
+config.bin.lib=shared           \
 config.bin.rpath=/usr/local/lib \
 config.install.root=/usr/local  \
 config.install.sudo=sudo
 \
 
-For Windows with MSVC (from the Visual Studio command prompt):
+For Windows with MSVC (from the Visual Studio \"x64 Native Tools Command
+Prompt\"):
 
 \
 > bpkg-stage create             ^
   cc                            ^
   config.cxx=cl                 ^
   config.cc.coptions=/O2        ^
+  config.bin.lib=shared         ^
+  config.install.root=C:\build2
+\
+
+For Windows with Clang (from a suitable command prompt, see
+\l{#bootstrap-windows-clang Bootstrapping on Windows with Clang} for details):
+
+\
+> bpkg-stage create             ^
+  cc                            ^
+  config.cxx=clang++            ^
+  \"config.cc.coptions=-m64 -O3\" ^
+  config.bin.lib=shared         ^
   config.install.root=C:\build2
 \
 
@@ -201,6 +216,7 @@ For Windows with MinGW (from the command prompt):
   cc                            ^
   config.cxx=g++                ^
   config.cc.coptions=-O3        ^
+  config.bin.lib=shared         ^
   config.install.root=C:\build2
 \
 "
diff --git a/build-clang.bat b/build-clang.bat
index e6c4c93..735eba8 100644
--- a/build-clang.bat
+++ b/build-clang.bat
@@ -32,7 +32,7 @@ echo additional make options, for example:
 echo.
 echo %0 --make mingw32-make --make -j8
 echo.
-echo See the BOOTSTRAP-CLANG file for details.
+echo See the BOOTSTRAP-WINDOWS-CLANG file for details.
 echo.
 goto end
 
diff --git a/buildfile b/buildfile
index fd343d0..5c319ca 100644
--- a/buildfile
+++ b/buildfile
@@ -14,8 +14,9 @@ UPGRADE                 \
 BOOTSTRAP-UNIX          \
 BOOTSTRAP-MACOSX        \
 BOOTSTRAP-WINDOWS       \
-BOOTSTRAP-WINDOWS-MINGW \
-BOOTSTRAP-WINDOWS-MSVC
+BOOTSTRAP-WINDOWS-MSVC  \
+BOOTSTRAP-WINDOWS-CLANG \
+BOOTSTRAP-WINDOWS-MINGW
 
 ./: $d doc{$i README CONTRIBUTING.md} cli{$i} file{build.sh build-*} manifest
 
diff --git a/doc/cli.sh b/doc/cli.sh
index a520898..6d16c7b 100755
--- a/doc/cli.sh
+++ b/doc/cli.sh
@@ -81,5 +81,6 @@ gen_txt UPGRADE
 gen_txt BOOTSTRAP-UNIX
 gen_txt BOOTSTRAP-MACOSX
 gen_txt BOOTSTRAP-WINDOWS
-gen_txt BOOTSTRAP-WINDOWS-MINGW
 gen_txt BOOTSTRAP-WINDOWS-MSVC
+gen_txt BOOTSTRAP-WINDOWS-CLANG
+gen_txt BOOTSTRAP-WINDOWS-MINGW
diff --git a/doc/install.cli b/doc/install.cli
index 09e3679..7b8e3f7 100644
--- a/doc/install.cli
+++ b/doc/install.cli
@@ -17,10 +17,10 @@
 The recommended way to install and upgrade the \c{build2} toolchain in most
 circumstances is using the automated install scripts as described on the
 \l{https://build2.org/install.xhtml Install} page. This document describes the
-manual installation and upgrade process which offers greater control can be
-helpful in situations where the automated scripts cannot be used (offline
+manual installation and upgrade process which offers greater control that can
+be helpful in situations where the automated scripts cannot be used (offline
 installation, packaging for system package managers, unsupported
-platform/compiler, etc).
+by the install scripts platform/compiler, etc).
 "
 
 // NOTE: The following ids must correspond to the file names (used in
@@ -42,6 +42,11 @@ source "../BOOTSTRAP-WINDOWS.cli";
 source "../BOOTSTRAP-WINDOWS-MSVC.cli";
 
 "
+\h2#bootstrap-windows-clang|Bootstrapping on Windows with Clang|
+"
+source "../BOOTSTRAP-WINDOWS-CLANG.cli";
+
+"
 \h2#bootstrap-windows-mingw|Bootstrapping on Windows with MinGW|
 "
 source "../BOOTSTRAP-WINDOWS-MINGW.cli";