diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/boost.md | 119 | ||||
| -rw-r--r-- | docs/cmake.md | 50 |
2 files changed, 86 insertions, 83 deletions
diff --git a/docs/boost.md b/docs/boost.md index ead2103..37ff3bb 100644 --- a/docs/boost.md +++ b/docs/boost.md @@ -1,20 +1,23 @@ Library naming -------------- -The way Boost names library files by default is insane. It's absolutely not compatible between -OSs, compilers, Boost versions, etc. On Linux, for example, it would create -stage/lib/libboost_filesystem.a, while on Windows it would become something insane like -stage\lib\libboost_filesystem-vc142-mt-s-x64-1_72.lib. More than that, older Boost versions -wouldn't include architecture information (the "x64" part) in the file name, so you couldn't -store libraries for both x86 and x64 in the same directory. On Linux, on the other hand, you -can't even store debug/release binaries in the same directory. What's worse is that older CMake -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 -can't have libraries with different runtime-link values in the same directory, but I don't really -care. +The way Boost names library files by default is insane. It's absolutely not +compatible between OSs, compilers, Boost versions, etc. On Linux, for example, +it would create stage/lib/libboost_filesystem.a, while on Windows it would +become something insane like stage\lib\libboost_filesystem-vc142-mt-s-x64-1_72.lib. +More than that, older Boost versions wouldn't include architecture information +(the "x64" part) in the file name, so you couldn't store libraries for both x86 +and x64 in the same directory. On Linux, on the other hand, you can't even +store debug/release binaries in the same directory. What's worse is that older +CMake 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 can't have +libraries with different runtime-link values in the same directory, but I don't +really care. Hate speech ----------- @@ -22,27 +25,27 @@ Hate speech Is there a person who doesn't hate Boost.Build? I'm not sure, I'm definitely _not_ one of these people. Maybe it's the lack of adoption (meaning that learning it is useless outside of Boost), maybe it's the incomprehensible -syntax. Maybe it's the absolutely insane compiler-specific configuration -files (tools/build/src/tools/*.jam), which are impossible to figure out. -Maybe it's the fact that the implementation switched from C to C++ while some -half-baked Python implementation has been there since at least 2015 (see the -marvelous memo "Status: mostly ported." at the top of tools/build/src/build_system.py). +syntax. Maybe it's the absolutely insane compiler-specific configuration files +(tools/build/src/tools/*.jam), which are impossible to figure out. Maybe it's +the fact that the implementation switched from C to C++ while some half-baked +Python implementation has been there since at least 2015 (see the marvelous +memo "Status: mostly ported." at the top of tools/build/src/build_system.py). What I hate the most though is how its various subtle, implicit and invisible -decision-making heuristics changed thoughout the release history of Boost. -You have a config and a compiler that will happily build version 1.65.0? -Great! Want to use the same config and the same compiler to build version -1.72.0? Well, too fucking bad, it doesn't work anymore. This I really do -hate the most. +decision-making heuristics changed thoughout the release history of Boost. You +have a config and a compiler that will happily build version 1.65.0? Great! +Want to use the same config and the same compiler to build version 1.72.0? +Well, too fucking bad, it doesn't work anymore. This I really do hate the +most. Three kinds of toolsets ----------------------- -b2 accepts the toolset= parameter. What about building b2 itself though? +b2 accepts the `toolset=` parameter. What about building b2 itself though? Well, this is what the bootstrap.{sh,bat} scripts do. They also accept a -toolset argument, but it is _completely_ different to that of b2. That's -sort of OK, since e.g. cross-compiling b2 is something we rarely want to do -(and hence there must typically be a native toolset available). +toolset argument, but it is _completely_ different to that of b2. That's sort +of OK, since e.g. cross-compiling b2 is something we rarely want to do (and +hence there must typically be a native toolset available). bootstrap.sh and bootstrap.bat are completely different (of course!), and accept different arguments for their toolset parameters. @@ -51,27 +54,27 @@ Config file insanity -------------------- Say, we're building Boost on Windows using the GCC from a MinGW-w64 -distribution. We can pass toolset=gcc and all the required flags on the -command line no problem. What if we want to make a user configuration file -so that 1) the command line is less polluted, and 2) it can possibly be -shared? Well, if we put +distribution. We can pass `toolset=gcc` and all the required flags on the +command line no problem. What if we want to make a user configuration file so +that 1) the command line is less polluted, and 2) it can possibly be shared? +Well, if we put using gcc : : : <name>value... ; there, Boost 1.65.0 will happily build everything, while Boost 1.72.0 will -complain about "duplicate initialization of gcc". This is because when we -ran `bootstrap.bat gcc` earlier, it wrote `using gcc ;` in project-config.jam. -And while Boost 1.65.0 detects that toolset=gcc means we're going to use the -MinGW GCC, and magically turns toolset=gcc to toolset=gcc-mingw, Boost 1.72.0 -does no such thing, and chokes on the "duplicate" GCC declaration. +complain about "duplicate initialization of gcc". This is because when we ran +`bootstrap.bat gcc` earlier, it wrote `using gcc ;` in project-config.jam. And +while Boost 1.65.0 detects that `toolset=gcc` means we're going to use the +MinGW GCC, and magically turns `toolset=gcc` to `toolset=gcc-mingw`, Boost +1.72.0 does no such thing, and chokes on the "duplicate" GCC declaration. We also cannot put using gcc : custom : : <options> ; without the executable path, since Boost insists that `g++ -dumpversion` must -equal to "custom" (which makes total sense, lol). So we have to force it, -and do provide the path. +equal to "custom" (which makes total sense, lol). So we have to force it, and +do provide the path. Windows & Clang --------------- @@ -84,19 +87,19 @@ three main ways to install the native Clang toolchain on Windows: * install it as part of a MSYS2 installation (`pacman -S mingw-w64-x86_64-clang`), * install as part of a Visual Studio installation. -Using the latter method, you can switch a project to use the LLVM toolset -using Visual Studio, but that's stupid. The former two, on the other hand, -give us the the required clang/clang++/clang-cl executables, so everything -seems to be fine. +Using the latter method, you can switch a project to use the LLVM toolset using +Visual Studio, but that's stupid. The former two, on the other hand, give us +the the required clang/clang++/clang-cl executables, so everything seems to be +fine. Except it's not fine. Let's start with the fact that prior to 1.66.0, -toolset=clang is completely broken on Windows. It's just an alias for +`toolset=clang` is completely broken on Windows. It's just an alias for clang-linux, and it's hardcoded to require the ar & ranlib executables to create static libraries. Which is fine on Linux, since, and I'm quoting the source, "ar is always available". But it's not fine on Windows, since -ar/ranlib are not, in fact, available there by default. Sure, you can -install some kind of MinGW toolchain, and it might even work, but what the -hell, honestly? +ar/ranlib are not, in fact, available there by default. Sure, you can install +some kind of MinGW toolchain, and it might even work, but what the hell, +honestly? Luckily, both the upstream distribution and the MSYS2 mingw-w64-x86_64-llvm package come with the llvm-ar and llvm-ranlib utilities. So we can put @@ -108,21 +111,21 @@ and later call b2 toolset=clang-custom --user-config=path/to/config.jam ... -But, as I mentioned, prior to 1.66.0, toolset=clang is _hardcoded_ to use ar -& ranlib, these exact utility names. So either get them as part of some -MinGW distribution or build Boost using another toolset. +But, as I mentioned, prior to 1.66.0, `toolset=clang` is _hardcoded_ to use ar +& ranlib, these exact utility names. So either get them as part of some MinGW +distribution or build Boost using another toolset. Now, it's all fine, but building stuff on Windows adds another thing into the equation: debug runtimes. When you build Boost using MSVC, for example, it -picks one of the appropriate /MT[d] or /MD[d] flags to build the Boost -libraries with. Emulating these flags with toolset=clang is complicated and +picks one of the appropriate `/MT[d]` or `/MD[d]` flags to build the Boost +libraries with. Emulating these flags with `toolset=clang` is complicated and inconvenient. Luckily, there's the clang-cl.exe executable, which aims to provide command line interface compatible with that of cl.exe. -Boost.Build even supports toolset=clang-win, which should use clang-cl.exe. -But alas, it's completely broken prior to 1.69.0. It just doesn't work at -all. So, if you want to build w/ clang-cl.exe, either use Boost 1.69.0 or -later, or build using another toolset. +Boost.Build even supports `toolset=clang-win`, which should use clang-cl.exe. +But alas, it's completely broken prior to 1.69.0. It just doesn't work at all. +So, if you want to build w/ clang-cl.exe, either use Boost 1.69.0 or later, or +build using another toolset. Cygwin & Clang -------------- @@ -138,8 +141,8 @@ the following error: ^ GCC doesn't emit an error here because /usr/include is in a pre-configured -"system" include directories list, and the declaration there take precedence, -I guess? The root of the problem BTW is that sizeof(unsigned long) is +"system" include directories list, and the declaration there take precedence, I +guess? The root of the problem BTW is that sizeof(unsigned long) is * 4 for MSVC and MinGW-born GCCs, * 8 for Clang (and, strangely, Cygwin GCC; why don't we get runtime diff --git a/docs/cmake.md b/docs/cmake.md index e4724b0..cd8a149 100644 --- a/docs/cmake.md +++ b/docs/cmake.md @@ -13,26 +13,26 @@ 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, +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]). 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. 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 +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. `cmake --build` uses msbuild with Visual Studio generators. You can pass the @@ -40,8 +40,8 @@ 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 +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 @@ -51,12 +51,12 @@ 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. -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. +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 ----------------- @@ -81,18 +81,18 @@ 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 ([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]). 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]). +-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]). I recommend using Clang (either clang-cl or clang++ since 3.15) using the "NMake Makefiles" generator. |