Start to document some of the differences in cmake and ninja.

git-svn-id: svn://svn.linuxfromscratch.org/BLFS/trunk/BOOK@21415 af4574ff-66df-0310-9fd7-8a98e5e911e0

general.ent

@@ -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 -->

introduction/important/building-notes.xml

@@ -453,4 +453,190 @@ chmod 755 blfs-yes-test2</userinput></screen>
 
   </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>

introduction/welcome/changelog.xml

@@ -41,6 +41,17 @@
       </itemizedlist>
     </listitem>
 -->
+    <listitem>
+      <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>