Author: ken
Date: Sat Mar 30 14:36:23 2019
New Revision: 21415
Log:
Start to document some of the differences in cmake and ninja.
Modified:
trunk/BOOK/general.ent
trunk/BOOK/introduction/important/building-notes.xml
trunk/BOOK/introduction/welcome/changelog.xml
Modified: trunk/BOOK/general.ent
==============================================================================
--- trunk/BOOK/general.ent Fri Mar 29 12:27:25 2019 (r21414)
+++ trunk/BOOK/general.ent Sat Mar 30 14:36:23 2019 (r21415)
@@ -1,12 +1,12 @@
<!-- $LastChangedBy$ $Date$ -->
-<!ENTITY day "29"> <!-- Always 2 digits -->
+<!ENTITY day "30"> <!-- Always 2 digits -->
<!ENTITY month "03"> <!-- Always 2 digits -->
<!ENTITY year "2019">
<!ENTITY copyrightdate "2001-&year;">
<!ENTITY copyholder "The BLFS Development Team">
<!ENTITY version "&year;-&month;-&day;">
-<!ENTITY releasedate "March 29th, &year;">
+<!ENTITY releasedate "March 30th, &year;">
<!ENTITY pubdate "&year;-&month;-&day;"> <!-- metadata req. by TLDP -->
<!ENTITY blfs-version "svn"> <!-- svn|[release #] -->
<!ENTITY lfs-version "development"> <!-- x.y|development -->
Modified: trunk/BOOK/introduction/important/building-notes.xml
==============================================================================
--- trunk/BOOK/introduction/important/building-notes.xml Fri Mar 29
12:27:25 2019 (r21414)
+++ trunk/BOOK/introduction/important/building-notes.xml Sat Mar 30
14:36:23 2019 (r21415)
@@ -453,4 +453,190 @@
</sect2>
-->
+ <sect2 id="buildsystems">
+ <title>Working with different build systems</title>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ If there are contradictory flags (e.g. multiple different -O values),
+ the <emphasis>last</emphasis> 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'.
+ </para>
+
+ <para>
+ 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 <xref linkend="mesa"/> 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.
+ </para>
+
+ <bridgehead renderas="sect3">Autotools with Make</bridgehead>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ Sometimes, running <command>./configure --help</command> 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.
+ </para>
+
+ <para>
+ 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 (<emphasis>variously</emphasis>:
+ ignored, used to replace the programmer's suggestion, used before the
+ programmer's suggestion, used after the programmer's suggestion).
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <bridgehead renderas="sect3">CMake</bridgehead>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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 <command>cmake -LAH</command> and look at the output for that
+ default configuration.
+ </para>
+
+ <para>
+ 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 <emphasis>after</emphasis> any flags in the
+ environment and therefore take precedence.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Debug : '-g'</para>
+ </listitem>
+ <listitem>
+ <para>Release : '-O3 -DNDEBUG'</para>
+ </listitem>
+ <listitem>
+ <para>RelWithDebInfo : '-O2 -g -DNDEBUG'</para>
+ </listitem>
+ <listitem>
+ <para>MinSizeRel : '-Os -DNDEBUG'</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ CMake tries to produce quiet builds. To see the details of the commands
+ which are being run, use 'make VERBOSE=1' or 'ninja -v'.
+ </para>
+
+ <bridgehead renderas="sect3">Meson</bridgehead>
+
+ <para>
+ 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:
+ </para>
+
+<screen><userinput>meson ..
+meson configure | less</userinput></screen>
+
+ <para>
+ After identifying what to set, meson then needs to be reconfigured:
+ </para>
+
+<screen><userinput>meson --prefix=/usr -Dsome_option=true -Dother_option=false
--reconfigure</userinput></screen>
+
+ <para>
+ Alternatively, you could remove the build directory where you did this,
+ recreate it, and then run meson with the desired switches.
+ </para>
+
+ <para>
+ Meson provides the following buildtype values, and the flags they
enable
+ come <emphasis>after</emphasis> any flags supplied in the environment
and
+ therefore take precedence.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ <listitem>
+ <para>debug : '-g'</para>
+ </listitem>
+ <listitem>
+ <para>debugoptimized : '-O2 -g' - this is the default if nothing is
+ specified, it leaves assertions enabled.</para>
+ </listitem>
+ <listitem>
+ <para>release : '-O3 -DNDEBUG'</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ 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 <xref linkend="mesa"/>. That suggests that it might
+ only be used when there are debug assertions present.
+ </para>
+
+ <para>
+ The -DNDEBUG flag can also be provided by passing
+ <command>-Db_ndebug=true</command>.
+ </para>
+
+ <para>
+ To see the details of the commands which are being run in a package
using
+ meson, again use 'ninja -v'.
+ </para>
+
+ </sect2>
+
</sect1>
Modified: trunk/BOOK/introduction/welcome/changelog.xml
==============================================================================
--- trunk/BOOK/introduction/welcome/changelog.xml Fri Mar 29 12:27:25
2019 (r21414)
+++ trunk/BOOK/introduction/welcome/changelog.xml Sat Mar 30 14:36:23
2019 (r21415)
@@ -45,6 +45,17 @@
<para>March 29th, 2019</para>
<itemizedlist>
<listitem>
+ <para>[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.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>March 29th, 2019</para>
+ <itemizedlist>
+ <listitem>
<para>[timtas] - Update to dovecot-2.3.5.1. Fixes
<ulink url="&blfs-ticket-root;11874">#11874</ulink>.</para>
</listitem>
--
http://lists.linuxfromscratch.org/listinfo/blfs-book
FAQ: http://www.linuxfromscratch.org/blfs/faq.html
Unsubscribe: See the above information page
