// file      : BOOTSTRAP-WINDOWS.cli
// copyright : Copyright (c) 2014-2017 Code Synthesis Ltd
// 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, 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.

Note also 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 in your \c{PATH} environment variable when building and using
\c{build2} since they may provide conflicting DLLs.

The \c{build2} toolchain on Windows requires a set of extra utilities
(\c{install}, \c{diff}, \c{wget}, \c{tar}, etc). These are provided by the
\c{build2-baseutils} package (see the \c{README} file inside for details).
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. Note also that MinGW GCC must be configured with the
\c{posix} threading model (this is currently the only configuration that
implements C++11 threads; run \c{g++ -v} to verify).

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}.

Note also that you \b{absolutely must} match the width (32/64-bit) of the
toolchain build to the \c{baseutils} and \c{mingw} packages. They must all be
32-bit or all 64-bit. If you are running 64-bit Windows, it is strongly
recommended that you build the 64-bit (x86_64) version of the toolchain as
well as use the 64-bit versions of the \c{baseutils} and \c{mingw} packages.

To bootstrap on Windows with either MSVC 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 Command Prompt (or wait
for MSVC-specific instructions).
|

\li|\n\b{2. Create Build Directory}\n

Note that you will want to keep this directory around in order to upgrade
to new toolchain versions in the future. In this guide we will use
\c{C:\\build2-build\\} as the build directory and \c{C:\\build2\\} as the
installation directory but you can use other paths.

\
> C:
> cd \
> mkdir build2-build
> cd build2-build
\

|

\li|\n\b{3. Download Archives}\n

Download the following files as well as their \c{.sha256} checksums from
\l{https://download.build2.org}, replacing \i{<arch>} with \c{x86_64} for
64-bin Windows and with \c{i686} for 32-bit.

\
build2-baseutils-X.Y.Z-<arch>-windows.zip
build2-mingw-X.Y.Z-<arch>-windows.tar.xz   (if required)
build2-toolchain-X.Y.Z.tar.xz
\

Place everything into \c{C:\\build2-build\\} (build directory).|

\li|\n\b{4. Verify Archive Checksums}\n

Verify archive checksums match (compare visually):

\
> type *.sha256
> for %f in (*.zip *.xz) do certutil -hashfile %f SHA256
\

|

\li|\n\b{5. Unpack \c{build2-baseutils}}\n

Unpack the \c{build2-baseutils-X.Y.Z-<arch>-windows.zip} archive into \c{C:\\}
using Windows Explorer (for example, copy the archive directory and then paste
it). Rename it to \c{C:\\build2\\}. This will be the toolchain installation
directory.  |

\li|\n\b{6. Set \c{PATH}}\n

Set the \c{PATH} environment variable and verify that the utilities are found
and work:

\
> set PATH=C:\build2\bin;%PATH%
> where tar
> tar --version
\

|

\li|\n\b{7. Unpack \c{build2-mingw}}\n

If required, unpack the \c{build2-mingw-X.Y.Z-<arch>-windows.tar.xz} archive
into \c{C:\\build2\\}:

\
> xz -d build2-mingw-X.Y.Z-<arch>-windows.tar.xz
> tar -xf build2-mingw-X.Y.Z-<arch>-windows.tar ^
  --one-top-level=C:\build2 --strip-components=1
\

Verify that the MinGW GCC is found and works:

\
> where g++
> g++ --version
\

|

\li|\n\b{8. Unpack \c{build2-toolchain}}\n

Unpack the \c{build2-toolchain-X.Y.Z.tar.xz} archive and change to its
directory:

\
> xz -d build2-toolchain-X.Y.Z.tar.xz
> tar -xf build2-toolchain-X.Y.Z.tar
> cd build2-toolchain-X.Y.Z
\

||

If building with MSVC, continue with \l{#BOOTSTRAP-MSVC Bootstrapping with
MSVC}.

If building with MinGW, continue with \l{#BOOTSTRAP-MINGW Bootstrapping with
MinGW}.
"