path: root/BOOTSTRAP-WINDOWS-CLANG.cli

// file      : BOOTSTRAP-WINDOWS-CLANG.cli
// license   : MIT; see accompanying LICENSE file

"
Continuing from \l{#bootstrap-windows Bootstrapping on Windows}, there are 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 --all
\

\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++ -m64 -w

> 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++ \"CXXFLAGS=-m64 -w\"

> 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
a local installation and skip the rest of the steps.

\N|To perform a local installation with the \c{build-clang.bat} batch file,
pass the \c{--local} option.|

To perform a local installation you will need to change the \c{configure} and
\c{install} command lines above along these lines (see also a note on the
following step about only building shared libraries, toolchain executables
prefix/suffix, etc):

\
> build2\build2\b-boot configure ^
  config.config.hermetic=true    ^
  config.cxx=clang++             ^
  \"config.cc.coptions=-m64 -O2\"  ^
  config.bin.lib=shared          ^
  config.install.root=C:\build2

> build2\build2\b-boot install: build2\ bpkg\ bdep\
\

You will also need to build and install the standard build system modules:

\
> b install: !config.install.scope=project libbuild2-*\
\

\N|To verify the build system modules installation you can load them with the
following command:

\
> b noop: tests\libbuild2-*\
\

|

To uninstall such a local installation, run:

\
> b uninstall: build2\ bpkg\ bdep\ libbuild2-*\
\

|

\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.config.hermetic=true   ^
  config.cxx=clang++            ^
  \"config.cc.coptions=-m64 -O2\" ^
  config.bin.lib=shared         ^
  config.install.root=C:\build2
\

\N|The above configuration will only build shared libraries. If you would like
to build both shared and static, remove \c{config.bin.lib=shared}.|

\N|To add a custom prefix/suffix to the toolchain executables names, add
\c{config.bin.exe.prefix=...} and/or \c{config.bin.exe.suffix=...}.|

\N|The \c{config.config.hermetic=true} configuration variable in the above
command makes sure the embedded \c{~host} and \c{~build2} configurations
include the current environment. This is especially important for \c{~build2}
which is used to dynamically build and load ad hoc recipes and build system
modules and must therefore match the environment that was used to build the
build system itself.|

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 --all
\

\N|By default \c{bpkg} will build the latest available version of each
package. You can, however, specify the desired versions explicitly, for
example:

\
> bpkg-stage build --for install build2/X.Y.Z bpkg/X.Y.Z bdep/X.Y.Z
\

|

To verify the result, run:

\
> 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
\

Finally, we build and install the standard build system modules:

\
> bpkg build --for install libbuild2-autoconf libbuild2-kconfig
> bpkg install !config.install.scope=project ^
  --all-pattern=libbuild2-*
\

\N|To get a list of the standard pre-installed build system modules in a
specific version of the toolchain, run:

\
> cd ..\build2-toolchain-X.Y.Z
> dir /B libbuild2-*
\

|

\N|To verify the build system modules installation you can load them with the
following command:

\
> b noop: ..\build2-toolchain-X.Y.Z\tests\libbuild2-*\
\

||

\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\
\

||
"