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/boost/toolchain.py | 132 +-------------------------------------------- 1 file changed, 1 insertion(+), 131 deletions(-) (limited to 'project/boost/toolchain.py') diff --git a/project/boost/toolchain.py b/project/boost/toolchain.py index 37f24ea..08bc49c 100644 --- a/project/boost/toolchain.py +++ b/project/boost/toolchain.py @@ -3,137 +3,7 @@ # For details, see https://github.com/egor-tensin/cmake-common. # Distributed under the MIT License. -# 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). -# -# 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. -# -# Three kinds of toolsets -# ----------------------- -# -# 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). -# -# bootstrap.sh and bootstrap.bat are completely different (of course!), and -# accept different arguments for their toolset parameters. -# -# 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 -# -# using gcc : : : 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. -# -# We also cannot put -# -# using gcc : custom : : ; -# -# 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. -# -# Windows & Clang -# --------------- -# -# Building Boost using Clang on Windows is a sad story. As of 2020, there're -# three main ways to install the native Clang toolchain on Windows: -# -# * download the installer from llvm.org (`choco install llvm` does this) -# a.k.a. the upstream, -# * 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. -# -# 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 -# 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? -# -# 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 -# something like this in the config: -# -# using clang : custom : clang++.exe : llvm-ar llvm-ranlib.exe ; -# -# 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. -# -# 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 -# 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. -# -# Cygwin & Clang -# -------------- -# -# Now, a few words about Clang on Cygwin. When building 1.65.0, I encountered -# the following error: -# -# /usr/include/w32api/synchapi.h:127:26: error: conflicting types for 'Sleep' -# WINBASEAPI VOID WINAPI Sleep (DWORD dwMilliseconds); -# ^ -# ./boost/smart_ptr/detail/yield_k.hpp:64:29: note: previous declaration is here -# extern "C" void __stdcall Sleep( unsigned long ms ); -# ^ -# -# 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 -# -# * 4 for MSVC and MinGW-born GCCs, -# * 8 for Clang (and, strangely, Cygwin GCC; why don't we get runtime -# errors?). -# -# The fix is to add `define=BOOST_USE_WINDOWS_H`. I don't even know what's the -# point of not having it as a default. +# See docs/boost.md for a more thorough description of my pain. import abc from contextlib import contextmanager -- cgit v1.2.3