diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/cmake.md | 97 |
1 files changed, 54 insertions, 43 deletions
diff --git a/docs/cmake.md b/docs/cmake.md index aac40e0..d101dc7 100644 --- a/docs/cmake.md +++ b/docs/cmake.md @@ -1,55 +1,74 @@ Default generator ----------------- -As of CMake 3.18, the default generator (unless set explicitly) is: +As of CMake 3.26, the default generator (unless set explicitly) is: * the newest Visual Studio or "NMake Makefiles" on Windows, * "Unix Makefiles" otherwise. -This is regardless of whether any executables like gcc, cl or make are -available ([1][1]). +This is [regardless] of whether any executables like gcc, cl or make are +available. + +[regardless]: https://github.com/Kitware/CMake/blob/v3.26.4/Source/cmake.cxx#L2484 Makefile generators ------------------- -CMake has a number of "... Makefiles" generators. "Unix Makefiles" uses -gmake/make/smake, whichever is found first, and cc/c++ for compiler detection -([2][2]). "MinGW Makefiles" looks for mingw32-make.exe in a number of -well-known locations, uses gcc/g++ directly, and is aware of windres ([3][3]). -In addition, "Unix Makefiles" uses /bin/sh as the SHELL value in the Makefile, -while the MinGW version uses cmd.exe. I don't think it matters on Windows -though, since the non-existent /bin/sh is ignored anyway ([4][4]). "NMake -Makefiles" is similar, except it defaults to using cl ([5][5]). +CMake has a number of "... Makefiles" generators. "Unix Makefiles" [uses +gmake/make/smake], whichever is found first, and [prefers cc]/[c++] symlinks +for compiler detection. "MinGW Makefiles" [looks for mingw32-make.exe] in a +number of well-known locations instead. In addition, "Unix Makefiles" [uses +/bin/sh] as the SHELL value in the Makefile, while the MinGW version [uses +cmd.exe]. I don't think it matters on Windows though, since the non-existent +/bin/sh is [ignored anyway]. "NMake Makefiles" is similar, except it defaults +to [using cl]. + +[uses gmake/make/smake]: https://github.com/Kitware/CMake/blob/v3.26.4/Modules/CMakeUnixFindMake.cmake +[prefers cc]: https://github.com/Kitware/CMake/blob/v3.26.4/Modules/CMakeDetermineCCompiler.cmake +[c++]: https://github.com/Kitware/CMake/blob/v3.26.4/Modules/CMakeDetermineCXXCompiler.cmake +[looks for mingw32-make.exe]: https://github.com/Kitware/CMake/blob/v3.26.4/Modules/CMakeMinGWFindMake.cmake +[uses /bin/sh]: https://github.com/Kitware/CMake/blob/v3.26.4/Source/cmLocalUnixMakefileGenerator3.cxx#L651 +[uses cmd.exe]: https://github.com/Kitware/CMake/blob/v3.26.4/Source/cmLocalUnixMakefileGenerator3.cxx#L644 +[ignored anyway]: https://www.gnu.org/software/make/manual/html_node/Choosing-the-Shell.html +[using cl]: https://github.com/Kitware/CMake/blob/v3.26.4/Source/cmGlobalNMakeMakefileGenerator.cxx#L41 It's important to _not_ use the -A parameter with any of the Makefile generators - it's an error. This goes for "NMake Makefiles" also. "NMake -Makefiles" doesn't attempt to search for installed Visual Studio compilers, you -need to use it from one of the Visual Studio-provided shells. +Makefiles" [doesn't attempt] to search for installed Visual Studio compilers, +you need to use it from one of the Visual Studio-provided shells. + +[doesn't attempt]: https://github.com/Kitware/CMake/blob/v3.26.4/Source/cmGlobalNMakeMakefileGenerator.cxx#L93 Visual Studio generators ------------------------ -These are special. They ignore the CMAKE_\<LANG\>_COMPILER parameters and use -cl by default ([9][9]). They support specifying the toolset to use via the -T -parameter (the "Platform Toolset" value in the project's properties) since 3.18 -([10][10]). The toolset list varies between Visual Studio versions, and I'm -too lazy to learn exactly which version supports which toolsets. +These are special. They ignore the CMAKE_\<LANG\>_COMPILER parameters and [use +cl by default]. They support specifying the toolset to use via the -T +parameter (the "Platform Toolset" value in the project's properties) [since +3.8]. The toolset list varies between Visual Studio versions, and I'm too lazy +to learn exactly which version supports which toolsets. + +[use cl by default]: https://gitlab.kitware.com/cmake/cmake/-/issues/19174 +[since 3.8]: https://cmake.org/cmake/help/v3.8/release/3.8.html `cmake --build` uses msbuild with Visual Studio generators. You can pass the path to a different cl.exe by doing something like msbuild ... /p:CLToolExe=another-cl.exe /p:CLToolPath=C:\parent\dir -It's important that the generators for Visual Studio 2017 or older use Win32 as -the default platform ([12][12]). Because of that, we need to pass the -A -parameter. +It's important that the generators for Visual Studio 2017 or older [use Win32] +as the default platform. Because of that, we need to pass the -A parameter. + +[use Win32]: https://cmake.org/cmake/help/v3.18/generator/Visual%20Studio%2015%202017.html mingw32-make vs make -------------------- -No idea what the actual differences are. The explanation in the FAQ ([6][6]) -about how GNU make "is lacking in some functionality and has modified -functionality due to the lack of POSIX on Win32" isn't terribly helpful. +No idea what the actual differences are. The [explanation] in the FAQ about +how GNU make "is lacking in some functionality and has modified functionality +due to the lack of POSIX on Win32" isn't terribly helpful. + +[explanation]: http://mingw.org/wiki/FAQ It's important that you can install either on Windows (`choco install make` for GNU make and `choco install mingw` to install a MinGW-w64 distribution with @@ -80,31 +99,23 @@ Ubuntu, you need to install the gcc-multilib package. Windows & Clang --------------- -Using Clang on Windows is no easy task, of course. Prior to 3.15, there was no -support for building things using the clang++.exe executable, only clang-cl.exe -was supported ([7][7]). If you specified `-DCMAKE_CXX_COMPILER=clang++`, CMake -would stil pass MSVC-style command line options to the compiler (like `/MD`, -`/nologo`, etc.), which clang++ doesn't like ([8][8]). +Using Clang on Windows is no easy task, of course. Prior to 3.15, there was +[no support] for building things using the clang++.exe executable, only +clang-cl.exe was supported. If you specified `-DCMAKE_CXX_COMPILER=clang++`, +CMake [would still] pass MSVC-style command line options to the compiler (like +`/MD`, `/nologo`, etc.), which clang++ doesn't like. + +[no support]: https://cmake.org/cmake/help/v3.15/release/3.15.html#compilers +[would still]: https://github.com/Kitware/CMake/blob/v3.14.7/Modules/Platform/Windows-Clang.cmake So, in summary, you can only use clang++ since 3.15. clang-cl doesn't work with Visual Studio generators unless you specify the proper toolset using the -T parameter. You can set the ClToolExe property using msbuild, but while that might work in practice, clang-cl.exe needs to map some unsupported options for everything to work properly. For an example of how this is done, see the -LLVM.Cpp.Common.* files at ([11][11]). +[LLVM.Cpp.Common.* files]. + +[LLVM.Cpp.Common.* files]: https://github.com/llvm/llvm-project/tree/e408935bb5339e20035d84307c666fbdd15e99e0/llvm/tools/msbuild I recommend using Clang (either clang-cl or clang++ since 3.15) using the "NMake Makefiles" generator. - -[1]: https://github.com/Kitware/CMake/blob/v3.18.4/Source/cmake.cxx#L1697 -[2]: https://github.com/Kitware/CMake/blob/v3.18.4/Source/cmGlobalUnixMakefileGenerator3.cxx -[3]: https://github.com/Kitware/CMake/blob/v3.18.4/Source/cmGlobalMinGWMakefileGenerator.cxx -[4]: https://www.gnu.org/software/make/manual/html_node/Choosing-the-Shell.html -[5]: https://github.com/Kitware/CMake/blob/v3.18.4/Source/cmGlobalNMakeMakefileGenerator.cxx -[6]: http://mingw.org/wiki/FAQ -[7]: https://cmake.org/cmake/help/v3.15/release/3.15.html#compilers -[8]: https://github.com/Kitware/CMake/blob/v3.14.7/Modules/Platform/Windows-Clang.cmake -[9]: https://gitlab.kitware.com/cmake/cmake/-/issues/19174 -[10]: https://cmake.org/cmake/help/v3.8/release/3.8.html -[11]: https://github.com/llvm/llvm-project/tree/e408935bb5339e20035d84307c666fbdd15e99e0/llvm/tools/msbuild -[12]: https://cmake.org/cmake/help/v3.18/generator/Visual%20Studio%2015%202017.html |