Add a new chapter on external tools to User Guide [ci skip]

Initial content is the compilation_db material

Signed-off-by: Mats Wichmann <mats@linux.com>

5 files changed, 184 insertions, 82 deletions

diff --git a/doc/user/MANIFEST b/doc/user/MANIFEST
index 3110c2a..10b79f6 100644
--- a/doc/user/MANIFEST
+++ b/doc/user/MANIFEST
@@ -18,6 +18,7 @@ depends.xml
 environments.xml
 errors.xml
 example.xml
+external.xml
 factories.xml
 file-removal.xml
 functions.xml
diff --git a/doc/user/external.xml b/doc/user/external.xml
new file mode 100644
index 0000000..a72fa54
--- /dev/null
+++ b/doc/user/external.xml
@@ -0,0 +1,158 @@
+<?xml version='1.0'?>
+<!DOCTYPE sconsdoc [
+    <!ENTITY % scons SYSTEM "../scons.mod">
+    %scons;
+
+    <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
+    %builders-mod;
+    <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
+    %functions-mod;
+    <!ENTITY % tools-mod SYSTEM "../generated/tools.mod">
+    %tools-mod;
+    <!ENTITY % variables-mod SYSTEM "../generated/variables.mod">
+    %variables-mod;
+
+]>
+
+<chapter id="chap-external"
+         xmlns="http://www.scons.org/dbxsd/v1.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
+<title>Using SCons with other build tools</title>
+
+<!--
+
+  __COPYRIGHT__
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of this software and associated documentation files (the
+  "Software"), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to
+  permit persons to whom the Software is furnished to do so, subject to
+  the following conditions:
+
+  The above copyright notice and this permission notice shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+  <para>
+
+  Sometimes a project needs to interact with other projects
+  in various ways.  For example, many open source projects
+  make use of components from other open source projects,
+  and want to use those in their released form, not recode
+  their builds into &SCons;.  As another example, sometimes
+  the flexibility and power of &SCons; is useful for managing the
+  overall project, but developers might like faster incremental
+  builds when making small changes by using a different tool.
+
+  </para>
+
+  <para>
+
+  This chapter shows some techniques for interacting with other
+  projects and tools effectively from within &SCons;.
+
+  </para>
+
+  <section>
+    <title>Creating a Compilation Database</title>
+
+    <para>
+
+    Tooling which wants to perform analysis and modification 
+    of source code often needs to know not only the source code
+    itself, but also how it will be compiled, as the compilation line
+    affects the behavior of macros, includes, etc. &SCons; has a
+    record of this information once it has run, in the form of
+    Actions associated with the sources, and can emit this information
+    so tools can use it.
+
+    </para>
+
+    <para>
+
+    The Clang project has defined a <firstterm>JSON Compilation Database</firstterm>.
+    This database is in common use as input into Clang tools
+    and many IDEs and editors as well.
+    See
+    <ulink url="https://clang.llvm.org/docs/JSONCompilationDatabase.html">
+      <citetitle>JSON Compilation Database Format Specification</citetitle>
+    </ulink>
+    for complete information. &SCons; can emit a 
+    compilation database in this format
+    by enabling the &t-link-compilation_db; tool
+    and calling the &b-link-CompilationDatabase; builder
+    (available since 4.0).
+
+    </para>
+
+    <para>
+
+    The compilation database can be populated with
+    source and target files either with paths relative
+    to the top of the build, or using absolute paths.
+    This is controlled by
+    <envar>COMPILATIONDB_USE_ABSPATH=(True|False)</envar>
+    which defaults to <constant>False</constant>.
+
+    </para>
+
+    <para>
+
+    Example of absolute paths for target and source:
+
+    </para>
+
+    <sconstruct>
+env = Environment(COMPILATIONDB_USE_ABSPATH=True)
+env.Tool('compilation_db')
+env.CompilationDatabase('compile_commands.json')
+    </sconstruct>
+
+    <programlisting language="json">
+[
+    {
+        "command": "gcc -o test_main.o -c test_main.c",
+        "directory": "/home/user/sandbox",
+        "file": "/home/user/sandbox/test_main.c",
+        "target": "/home/user/sandbox/test_main.o"
+    }
+]
+    </programlisting>
+
+    <para>
+
+    Example of relative paths for target and source:
+
+    </para>
+
+    <sconstruct>
+env = Environment()
+env.Tool('compilation_db')
+env.CompilationDatabase('compile_commands.json')
+    </sconstruct>
+    <programlisting language="json">
+[
+    {
+        "command": "gcc -o test_main.o -c test_main.c",
+        "directory": "/home/user/sandbox",
+        "file": "test_main.c",
+        "target": "test_main.o"
+    }
+]
+    </programlisting>
+
+  </section>
+
+</chapter>
diff --git a/doc/user/main.xml b/doc/user/main.xml
index 19d7071..49fef75 100644
--- a/doc/user/main.xml
+++ b/doc/user/main.xml
@@ -43,23 +43,6 @@
 
 ]>
 
-  <!--
-
-  XXX Platform()
-  XXX Tools()
-
-  XXX GetOption('duplicate')
-  XXX SetOption('duplicate')
-  XXX - - duplicate=
-
-  XXX CheckTypeSize()
-
-  XXX - - diskcheck=
-
-  XXX - - warn=
-
-  -->
-
 <book xmlns="http://www.scons.org/dbxsd/v1.0"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
@@ -158,6 +141,7 @@
   -->
 
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="misc.xml"/>
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="external.xml"/>
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="troubleshoot.xml"/>
 
 <!--   Appendix below here -->
diff --git a/doc/user/misc.xml b/doc/user/misc.xml
index 3a2713a..b093629 100644
--- a/doc/user/misc.xml
+++ b/doc/user/misc.xml
@@ -675,69 +675,4 @@ env.Command('directory_build_info',
 
   </section>
 
-    <section>
-        <title>Creating LLVM Compilation Database</title>
-
-        <para>
-
-            LLVM has defined a JSON Compilation Database Format. This file is in common use as input into LLVM tools
-            and many IDE's and editors as well.
-        </para>
-        <para>
-            See
-            <ulink url="https://clang.llvm.org/docs/JSONCompilationDatabase.html">
-                <citetitle>JSON Compilation Database Format Specification</citetitle>
-            </ulink>
-            for complete information
-        </para>
-
-        <para>
-
-            The compilation database can be populated with source and target files either with paths relative to the
-            top of the build, or using absolute paths.
-        </para>
-        <para>This is controlled by
-            <envar>COMPILATIONDB_USE_ABSPATH=(True|False)</envar>
-            which defaults to False.
-        </para>
-
-        <para>Example of absolute paths for target and source</para>
-
-        <sconstruct>
-env = Environment(COMPILATIONDB_USE_ABSPATH=True)
-env.Tool('compilation_db')
-env.CompilationDatabase('compile_commands.json')
-        </sconstruct>
-
-        <programlisting language="json">
-[
-    {
-        "command": "gcc -o test_main.o -c test_main.c",
-        "directory": "/home/user/sandbox",
-        "file": "/home/user/sandbox/test_main.c",
-        "target": "/home/user/sandbox/test_main.o"
-    }
-]
-        </programlisting>
-
-
-        <para>Example of relative paths for target and source</para>
-
-        <sconstruct>
-env = Environment()
-env.Tool('compilation_db')
-env.CompilationDatabase('compile_commands.json')
-        </sconstruct>
-        <programlisting language="json">
-[
-    {
-        "command": "gcc -o test_main.o -c test_main.c",
-        "directory": "/home/user/sandbox",
-        "file": "test_main.c",
-        "target": "test_main.o"
-    }
-]
-        </programlisting>
-
-    </section>
 </chapter>
diff --git a/doc/user/sconf.xml b/doc/user/sconf.xml
index 8961606..5611bbf 100644
--- a/doc/user/sconf.xml
+++ b/doc/user/sconf.xml
@@ -97,6 +97,30 @@ env = conf.Finish()
 
     <para>
 
+    There are a few possible strategies for failing
+    configure checks.  Some checks may be for features without
+    which you cannot proceed.  The simple approach here is
+    just to exit &SCons; at that point - a number of the
+    examples in this chapter are coded that way.  If there
+    are multiple hard requirements, however, it may be
+    friendlier to the user to set a flag in case of any
+    fails of hard requirements and accumulate a record of them,
+    so that on the completion of the &configure_context; they can
+    all be listed prior to failing the build - as it can be frustrating
+    to have to iterate through the setup, fixing one new
+    requirement each iteration.  Other checks may be for
+    features which you can do without, and here the strategy
+    will usually be to set a construction variable which the
+    rest of the build can examine for its absence/presence,
+    or to set particular compiler flags, library lists, etc.
+    as appropriate for the circumstances, so you can proceed
+    with the build appropriately based on available features.
+
+    </para>
+
+
+    <para>
+
     Note that &SCons; uses its own dependency
     mechanism to determine when a check
     needs to be run--that is,