From 209a0cd261ddfb9c82fe921286c49333bd60371e Mon Sep 17 00:00:00 2001 From: Egor Tensin Date: Sun, 14 Mar 2021 20:19:09 +0300 Subject: docs: markdownify --- docs/boost.md | 4 ++-- docs/cmake.md | 42 ++++++++++++++++++++---------------------- 2 files changed, 22 insertions(+), 24 deletions(-) diff --git a/docs/boost.md b/docs/boost.md index 6e91d42..ead2103 100644 --- a/docs/boost.md +++ b/docs/boost.md @@ -11,8 +11,8 @@ can't even store debug/release binaries in the same directory. What's worse is versions don't support the architecture suffix, choking on the Windows example above. With all of that in mind, I decided to bring some uniformity by sacrificing some flexibility. -b2 is called with --layout=system, and libraries are put to stage///lib, -where is x86/x64 and is CMake's CMAKE_BUILD_TYPE. That means that I +b2 is called with --layout=system, and libraries are put to stage/\/\/lib, +where \ is x86/x64 and \ is CMake's CMAKE_BUILD_TYPE. That means that I can't have libraries with different runtime-link values in the same directory, but I don't really care. diff --git a/docs/cmake.md b/docs/cmake.md index 17a1d34..e4724b0 100644 --- a/docs/cmake.md +++ b/docs/cmake.md @@ -2,22 +2,24 @@ Default generator ----------------- As of CMake 3.18, 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]. +available ([1][1]). 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]. "MinGW Makefiles" looks for mingw32-make.exe in a number of -well-known locations, uses gcc/g++ directly, and is aware of windres [3]. In +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]. "NMake -Makefiles" is similar, except it defaults to using cl [5]. +though, since the non-existent /bin/sh is ignored anyway ([4][4]). "NMake +Makefiles" is similar, except it defaults to using cl ([5][5]). 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 @@ -27,25 +29,25 @@ you need to use it from one of the Visual Studio-provided shells. Visual Studio generators ------------------------ -These are special. They ignore the CMAKE__COMPILER parameters and use -cl by default [9]. They support specifying the toolset to use via the -T +These are special. They ignore the CMAKE_\_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]. The toolset list varies between Visual Studio versions, and I'm +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. -cmake --build uses msbuild with Visual Studio generators. You can pass the +`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 -Win32 as the default platform [12]. Because of that, we need to pass the -A +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. mingw32-make vs make -------------------- -No idea what the actual differences are. The explanation in the FAQ [6] +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. @@ -70,8 +72,8 @@ compiler flags (like -m64/-m32, etc.). Such file could look like this: You can then pass the path to it using the CMAKE_TOOLCHAIN_FILE parameter. -If you use the Visual Studio generators, just use the -A parameter, like "-A -Win32". +If you use the Visual Studio generators, just use the -A parameter, like `-A +Win32`. As a side note, if you want to cross-compile between x86 and x64 using GCC on Ubuntu, you need to install the gcc-multilib package. @@ -81,25 +83,21 @@ 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]. If you specified -DCMAKE_CXX_COMPILER=clang++, +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]. +/MD, /nologo, etc.), which clang++ doesn't like ([8][8]). 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]. +see the LLVM.Cpp.Common.* files at ([11][11]). I recommend using Clang (either clang-cl or clang++ since 3.15) using the "NMake Makefiles" generator. -References ----------- - -[1]: cmake::EvaluateDefaultGlobalGenerator - https://github.com/Kitware/CMake/blob/v3.18.4/Source/cmake.cxx +[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 -- cgit v1.2.3