docs: add some documentation for building on Windows
This covers how to build libc++ for Windows. This allows others to
replicate the MS ABI style build for libc++. It only depends on msvcrt
as it uses the Windows threading model and the Windows ABI and can serve
as an ABI compatible replacement for msvcprt.
llvm-svn: 294705
Cr-Mirrored-From: sso://chromium.googlesource.com/_direct/external/github.com/llvm/llvm-project
Cr-Mirrored-Commit: fb9ae0e3fe98c7fb8e8c2f956c0907b437cb7c48
diff --git a/docs/BuildingLibcxx.rst b/docs/BuildingLibcxx.rst
index b00bbdd..c7b5e96 100644
--- a/docs/BuildingLibcxx.rst
+++ b/docs/BuildingLibcxx.rst
@@ -92,6 +92,57 @@
$ make check-libcxx # optional
+Experimental Support for Windows
+--------------------------------
+
+The Windows support requires building with clang-cl as cl does not support one
+required extension: `#include_next`. Furthermore, VS 2015 or newer (19.00) is
+required. In the case of clang-cl, we need to specify the "MS Compatibility
+Version" as it defaults to 2014 (18.00).
+
+CMake + Visual Studio
+~~~~~~~~~~~~~~~~~~~~~
+
+Building with Visual Studio currently does not permit running tests. However,
+it is the simplest way to build.
+
+.. code-block:: batch
+
+ > cmake -G "Visual Studio 14 2015" ^
+ -T "LLVM-vs2014" ^
+ -DLIBCXX_ENABLE_SHARED=YES ^
+ -DLIBCXX_ENABLE_STATIC=NO ^
+ -DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO ^
+ \path\to\libcxx
+ > cmake --build .
+
+CMake + ninja
+~~~~~~~~~~~~~
+
+Building with ninja is required for development to enable tests.
+Unfortunately, doing so requires additional configuration as we cannot
+just specify a toolset.
+
+.. code-block:: batch
+
+ > cmake -G Ninja ^
+ -DCMAKE_MAKE_PROGRAM=/path/to/ninja ^
+ -DCMAKE_SYSTEM_NAME=Windows ^
+ -DCMAKE_C_COMPILER=clang-cl ^
+ -DCMAKE_C_FLAGS="-fms-compatibility-version=19.00 --target=i686--windows" ^
+ -DCMAKE_CXX_COMPILER=clang-c ^
+ -DCMAKE_CXX_FLAGS="-fms-compatibility-version=19.00 --target=i686--windows" ^
+ -DLLVM_PATH=/path/to/llvm/tree ^
+ -DLIBCXX_ENABLE_SHARED=YES ^
+ -DLIBCXX_ENABLE_STATIC=NO ^
+ -DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO ^
+ \path\to\libcxx
+ > /path/to/ninja cxx
+ > /path/to/ninja check-cxx
+
+Note that the paths specified with backward slashes must use the `\\` as the
+directory separator as clang-cl may otherwise parse the path as an argument.
+
.. _`libc++abi`: http://libcxxabi.llvm.org/