aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/docs
diff options
context:
space:
mode:
authorEgor Tensin <Egor.Tensin@gmail.com>2021-03-14 20:19:09 +0300
committerEgor Tensin <Egor.Tensin@gmail.com>2021-03-14 20:29:44 +0300
commit209a0cd261ddfb9c82fe921286c49333bd60371e (patch)
treee937ae4ae777f7a44e37fd289d7a7c87f4e9960f /docs
parentmove large in-code comments to docs/ (diff)
downloadcmake-common-209a0cd261ddfb9c82fe921286c49333bd60371e.tar.gz
cmake-common-209a0cd261ddfb9c82fe921286c49333bd60371e.zip
docs: markdownify
Diffstat (limited to 'docs')
-rw-r--r--docs/boost.md4
-rw-r--r--docs/cmake.md42
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/<platform>/<configuration>/lib,
-where <platform> is x86/x64 and <configuration> is CMake's CMAKE_BUILD_TYPE. That means that I
+b2 is called with --layout=system, and libraries are put to stage/\<platform\>/\<configuration\>/lib,
+where \<platform\> is x86/x64 and \<configuration\> 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_<LANG>_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_\<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]. 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