diff --git a/general.ent b/general.ent index b12f947dbe..861d751f2a 100644 --- a/general.ent +++ b/general.ent @@ -1,12 +1,12 @@ - + - + diff --git a/introduction/important/building-notes.xml b/introduction/important/building-notes.xml index 1d34cff7a5..9467dcf35a 100644 --- a/introduction/important/building-notes.xml +++ b/introduction/important/building-notes.xml @@ -453,4 +453,190 @@ chmod 755 blfs-yes-test2 --> + + Working with different build systems + + + There are now three different build systems in common use for + converting C or C++ source code into compiled programs or + libraries, and their details (particularly, finding out about available + options and their default values) differ. It may be easiest to understand + the issues caused by some choices (typically, slow execution, or + unexpected use of, or omission of, optimizatons) by starting with the item + which drew attention to this, the CFLAGS and CXXFLAGS. + + + + Most LFS and BLFS builders are probably aware of the basics of CFLAGS + and CXXFLAGS for altering how a program is compiled. Typically, some + form of optimization is used for a released program (-O2 or -O3), + sometimes with the creation of debug symbols (-g) when using -O2. + + + + If there are contradictory flags (e.g. multiple different -O values), + the last value will be used. Sometimes this means + that flags specifiedi in environment variables will be picked up before + values hardcoded in the Makefile, and therefore ignored. For example, + where a user specifies '-O2' and that is followed by '-O3' the build will + use '-O3'. + + + + There are various other things which can be passed in CFLAGS or + CXXFLAGS, such as forcing compilation for a specific microarchitecture + (e.g. -march=amdfam10, -march=native) or specifying a specific standard + for C or C++ (-std=c++17 for example). But one thing which has now come + to light is that programmers might include debug assertions in their + code, expecting them to be disabled in releases by using -DNDEBUG. + Specifically, if is built with these assertions + enabled, some activities such as loading levels of games can take + extremely long times, even on high-class video cards. + + + Autotools with Make + + + This combination is often described as 'CMMI' (configure, make, make + install) and is used here to also cover the few packages which have a + configure script that is not generated by autotools. + + + + Sometimes, running ./configure --help will produce + useful options about switches which might be used. At other times, + after looking at the output from a run of configure you may need to look + at the details of the script to find out what it was actually searching + for. + + + + Many configure scripts will pick up any CFLAGS or CXXFLAGS from the + environment, but CMMI packages vary about how these will be mixed with + any flags which would otherwise be used (variously: + ignored, used to replace the programmer's suggestion, used before the + programmer's suggestion, used after the programmer's suggestion). + + + + In most CMMI packages, running 'make' will list each command and run + it, interspersed with any warnings. But some packages try to be 'silent' + and only show which file they are compiling or linking instead of showing + the command line. If you need to inspect the command, either because of + an error, or just to see what options and flags are being used, adding + 'V=1' to the make invocation may help. + + + CMake + + + CMake works in a very different way, and it has two backends which can + be used on BLFS: 'make' and 'ninja'. The default backend is make, but + ninja can be faster on large packages with multiple processors. To + use ninja, specify '-G Ninja' in the cmake command. + + + + The hardest part of using CMake is knowing what options you might wish + to specify. The only way to get a list of what the package knows about + is to run cmake -LAH and look at the output for that + default configuration. + + + + Perhaps the most-important thing about CMake is that it has a variety + of CMAKE_BUILD_TYPE values, and these affect the flags. The default + is that this is not set and no flags are generated. Any CFLAGS or + CXXFLAGS in the environment will be used. If the programmer has coded + any debug assertions, those will be enabled unless -DNDEBUG is used. + The following CMAKE_BUILD_TYPE values will generate the flags shown, + and these will come after any flags in the + environment and therefore take precedence. + + + + + Debug : '-g' + + + Release : '-O3 -DNDEBUG' + + + RelWithDebInfo : '-O2 -g -DNDEBUG' + + + MinSizeRel : '-Os -DNDEBUG' + + + + + CMake tries to produce quiet builds. To see the details of the commands + which are being run, use 'make VERBOSE=1' or 'ninja -v'. + + + Meson + + + Meson has some similarities to CMake, but many differences. To get + details of the definesthat you may wish to change is slightly involved + using meson-0.49.2: + + +meson .. +meson configure | less + + + After identifying what to set, meson then needs to be reconfigured: + + +meson --prefix=/usr -Dsome_option=true -Dother_option=false --reconfigure + + + Alternatively, you could remove the build directory where you did this, + recreate it, and then run meson with the desired switches. + + + + Meson provides the following buildtype values, and the flags they enable + come after any flags supplied in the environment and + therefore take precedence. + + + + + plain : no added flags. This is for distributors to supply their + own CLFAGS, CXXFLAGS and LDFLAGS. There is no obvious reason to use + this in BLFS. + + + debug : '-g' + + + debugoptimized : '-O2 -g' - this is the default if nothing is + specified, it leaves assertions enabled. + + + release : '-O3 -DNDEBUG' + + + + + Although the release buildtype is described as enabling -DNDEBUG, and all + CMake Release builds pass that, it has so far only been observed (in + verbose builds) for . That suggests that it might + only be used when there are debug assertions present. + + + + The -DNDEBUG flag can also be provided by passing + -Db_ndebug=true. + + + + To see the details of the commands which are being run in a package using + meson, again use 'ninja -v'. + + + + diff --git a/introduction/welcome/changelog.xml b/introduction/welcome/changelog.xml index d45eef437c..90c421c7fa 100644 --- a/introduction/welcome/changelog.xml +++ b/introduction/welcome/changelog.xml @@ -41,6 +41,17 @@ --> + + March 29th, 2019 + + + [ken] - Add "Working with different build systems" to the end of + "Notes on Building Software", to start to document some of the + differences in CMake and Meson. + + + + March 29th, 2019