diff --git a/README.md b/README.md index 60e95db12..04e4b1da4 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ SUPPORTED PLATFORMS =================== - **Linux** and embedded Linux -- **Windows**, **Windows RT** (Store/Phone) +- **Windows** with MSVC, clang-cl and MinGW, **Windows RT** (Store/Phone) - **macOS**, **iOS** - **Android** - **Web** ([asm.js](http://asmjs.org/) or [WebAssembly](http://webassembly.org/)), diff --git a/doc/building.dox b/doc/building.dox index 932b6d61d..30ff72e63 100644 --- a/doc/building.dox +++ b/doc/building.dox @@ -39,7 +39,7 @@ Minimal set of tools and libraries required for building is: - C++ compiler with good C++11 support. Compilers which are tested to have everything needed are **GCC** >= 4.8.1, **Clang** >= 3.3 and **MSVC** - >= 2015. On Windows you can also use **MinGW-w64**. + >= 2015. On Windows you can also use **Clang-CL** or **MinGW-w64**. - **CMake** >= 3.4 - **Corrade** --- Plugin management and utility library. See @ref building-corrade "Corrade download and installation guide" for more @@ -384,8 +384,8 @@ want to set `CMAKE_INSTALL_RPATH` to `lib/` subdir of given prefix (e.g. @subsection building-windows Building on Windows -On Windows you can use either MSVC or the MinGW-w64 compiler. It's then up to -you whether you will use QtCreator, Visual Studio or another IDE or do the +On Windows you can use MSVC, clang-cl or the MinGW-w64 compiler. It's then up +to you whether you will use QtCreator, Visual Studio or another IDE or do the build from a command line. Note that for most convenient usage it's best use some dedicated directory (e.g. `C:/Sys`) for installing dependencies instead of putting each dependency to its own directory in `C:/Program Files` or diff --git a/doc/changelog.dox b/doc/changelog.dox index 8ccc512a7..b61ba290c 100644 --- a/doc/changelog.dox +++ b/doc/changelog.dox @@ -38,6 +38,9 @@ See also: @section changelog-latest Changes since 2019.10 +- Clang-CL is now a supported compiler on Windows. See also + @ref platforms-windows-clang-cl and [mosra/magnum#227](https://github.com/mosra/magnum/issues/227). + @subsection changelog-latest-new New features @subsubsection changelog-latest-new-gl GL library diff --git a/doc/platforms-windows.dox b/doc/platforms-windows.dox index 2ee73b14e..4fccd0d7c 100644 --- a/doc/platforms-windows.dox +++ b/doc/platforms-windows.dox @@ -143,6 +143,45 @@ console window lurking in the background. This can be fixed by creating your executable with @cmake add_executable(... WIN32 ...) @ce and linking to the @ref main "Corrade::Main" library. See its documentation for more information. +@section platforms-windows-clang-cl Using Clang-CL + +As an alternative to MSVC it's possible to use [Clang-CL](https://clang.llvm.org/docs/UsersManual.html#clang-cl). +Compared to MinGW it is fully ABI-compatible with MSVC, sharing the same STL +implementation, and thus you can freely mix and match libraries built by either +of them. + +If you already have MSVC 2019, clang-cl is available as an optional install +component. Configuring your project to be used with e.g. Ninja could then look +similarly to the following. Custom clang-cl installations work as well of +course, adapt the paths as necessary: + +@code{.bat} +C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Auxiliary/Build/vcvarsall.bat" x64 + +cmake .. ^ + -DCMAKE_C_COMPILER="C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/Llvm/bin/clang-cl.exe" ^ + -DCMAKE_CXX_COMPILER="C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/Llvm/bin/clang-cl.exe" ^ + -DCMAKE_LINKER="C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/Llvm/bin/lld-link.exe" ^ + -DCMAKE_CXX_FLAGS="-m64" ^ + -G Ninja +@endcode + +CMake is currently [having issues propagating correct bitness to clang-cl](https://gitlab.kitware.com/cmake/cmake/issues/16259) +when using Ninja, which means you may need to explicitly pass either `-m64` or +`-m32` to Clang. In the above case, `vcvarsall.bat` was called with the `x64` +parameter but the Clang bundled with Visual Studio is 32-bit and thus defaults +to 32-bit builds. Additionally, if your code needs to use exceptions (Magnum +itself doesn't, but @ref Corrade::TestSuite relies on them to report failures +in tests), you may need to explicitly pass `/EHs` via `CMAKE_CXX_FLAGS` as +exceptions are currently [disabled by default](https://github.com/catchorg/Catch2/issues/1113). + +While Magnum itself is tested to work with this compiler, be prepared that you +might run into exciting new issues that aren't present with MSVC, MinGW or +Clang alone. In dire situations, you can use @ref CORRADE_TARGET_CLANG_CL to +add compiler-specific workarounds. + +More information on [the Microsoft C++ Team Blog](https://devblogs.microsoft.com/cppblog/clang-llvm-support-in-visual-studio/). + @section platforms-windows-rt Windows RT Windows RT is a restricted subset of Windows API, used for UWP / "Metro" /