From 53701adc9afa2d31020a9306a54c5ed58f71b948 Mon Sep 17 00:00:00 2001 From: Egor Tensin Date: Sun, 14 Mar 2021 19:03:20 +0300 Subject: move large in-code comments to docs/ --- project/cmake/toolchain.py | 114 +-------------------------------------------- 1 file changed, 1 insertion(+), 113 deletions(-) (limited to 'project/cmake/toolchain.py') diff --git a/project/cmake/toolchain.py b/project/cmake/toolchain.py index c2e54a6..14197aa 100644 --- a/project/cmake/toolchain.py +++ b/project/cmake/toolchain.py @@ -3,119 +3,7 @@ # For details, see https://github.com/egor-tensin/cmake-common. # Distributed under the MIT License. -# 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]. -# -# 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 -# 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]. -# -# 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. -# -# 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 -# 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 -# too lazy to learn exactly which version supports which toolsets. -# -# 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 -# parameter. -# -# mingw32-make vs make -# -------------------- -# -# No idea what the actual differences are. The explanation in the FAQ [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. -# -# 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 mingw32-make.exe included). Personally, I don't see any difference -# between using either make.exe or mingw32-make.exe w/ CMake on Windows. But, -# since MinGW-w64 distributions do include mingw32-make.exe and not make.exe, -# we'll try to detect that. -# -# Cross-compilation -# ----------------- -# -# If you want to e.g. build x86 binary on x64 and vice versa, the easiest way -# seems to be to make a CMake "toolchain file", which initializes the proper -# compiler flags (like -m64/-m32, etc.). Such file could look like this: -# -# set(CMAKE_C_COMPILER gcc) -# set(CMAKE_C_FLAGS -m32) -# set(CMAKE_CXX_COMPILER g++) -# set(CMAKE_CXX_FLAGS -m32) -# -# 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". -# -# 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. -# -# 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++, -# CMake would stil pass MSVC-style command line options to the compiler (like -# /MD, /nologo, etc.), which clang++ doesn't like [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]. -# -# 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 -# [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 +# See docs/cmake.md for a more thorough description of my pain. import abc import os.path -- cgit v1.2.3