doc/user/external.xml

   1 <?xml version='1.0'?>
   2
   3 <!--
   4 SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
   5 SPDX-License-Identifier: MIT
   6 SPDX-FileType: DOCUMENTATION
   7
   8 This file is processed by the bin/SConsDoc.py module.
   9 -->
  10
  11 <!DOCTYPE sconsdoc [
  12         <!ENTITY % scons SYSTEM "../scons.mod">
  13         %scons;
  14
  15         <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
  16         %builders-mod;
  17         <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
  18         %functions-mod;
  19         <!ENTITY % tools-mod SYSTEM "../generated/tools.mod">
  20         %tools-mod;
  21         <!ENTITY % variables-mod SYSTEM "../generated/variables.mod">
  22         %variables-mod;
  23
  24         ]>
  25
  26 <chapter id="chap-external"
  27          xmlns="http://www.scons.org/dbxsd/v1.0"
  28          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  29          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  30     <title>Using SCons with other build tools</title>
  31
  32     <para>
  33
  34         Sometimes a project needs to interact with other projects
  35         in various ways. For example, many open source projects
  36         make use of components from other open source projects,
  37         and want to use those in their released form, not recode
  38         their builds into &SCons;. As another example, sometimes
  39         the flexibility and power of &SCons; is useful for managing the
  40         overall project, but developers might like faster incremental
  41         builds when making small changes by using a different tool.
  42
  43     </para>
  44
  45     <para>
  46
  47         This chapter shows some techniques for interacting with other
  48         projects and tools effectively from within &SCons;.
  49
  50     </para>
  51
  52     <section>
  53         <title>Creating a Compilation Database</title>
  54
  55         <para>
  56
  57             Tooling to perform analysis and modification
  58             of source code often needs to know not only the source code
  59             itself, but also how it will be compiled, as the compilation line
  60             affects the behavior of macros, includes, etc. &SCons; has a
  61             record of this information once it has run, in the form of
  62             Actions associated with the sources, and can emit this information
  63             so tools can use it.
  64
  65         </para>
  66
  67         <para>
  68
  69             The Clang project has defined a <firstterm>JSON Compilation Database</firstterm>.
  70             This database is in common use as input into Clang tools
  71             and many IDEs and editors as well.
  72             See
  73             <ulink url="https://clang.llvm.org/docs/JSONCompilationDatabase.html">
  74                 <citetitle>JSON Compilation Database Format Specification</citetitle>
  75             </ulink>
  76             for complete information. &SCons; can emit a
  77             compilation database in this format
  78             by enabling the &t-link-compilation_db; tool
  79             and calling the &b-link-CompilationDatabase; builder
  80             (<emphasis>available since &scons; 4.0</emphasis>).
  81
  82         </para>
  83
  84         <para>
  85
  86             The compilation database can be populated with
  87             source and output files either with paths relative
  88             to the top of the build, or using absolute paths.
  89             This is controlled by
  90             <envar>COMPILATIONDB_USE_ABSPATH=(True|False)</envar>
  91             which defaults to <constant>False</constant>.
  92             The entries in this file can be filtered by using
  93
  94             <envar>COMPILATIONDB_PATH_FILTER='pattern'</envar>
  95             where the filter pattern is a string following the &Python;
  96             <ulink url="https://docs.python.org/3/library/fnmatch.html">
  97                 <systemitem>fnmatch</systemitem>
  98             </ulink>
  99             syntax.
 100             This filtering can be used for outputting different
 101             build variants to different compilation database files.
 102
 103         </para>
 104
 105         <para>
 106
 107             The following example illustrates generating a compilation
 108             database containing absolute paths:
 109
 110         </para>
 111
 112         <scons_example name="external_cdb_ex1">
 113             <file name="SConstruct" printme="1">
 114 env = Environment(COMPILATIONDB_USE_ABSPATH=True)
 115 env.Tool('compilation_db')
 116 env.CompilationDatabase()
 117 env.Program('hello.c')
 118             </file>
 119             <file name="hello.c">
 120                 int main(int argc, char* argv[])
 121                 {
 122                 return 0;
 123                 }
 124             </file>
 125         </scons_example>
 126
 127         <scons_output example="external_cdb_ex1" suffix="1">
 128             <scons_output_command>scons -Q</scons_output_command>
 129         </scons_output>
 130
 131         <para>
 132             <filename>compile_commands.json</filename>
 133             contains:
 134         </para>
 135
 136         <programlisting language="json">
 137 [
 138     {
 139         "command": "gcc -o hello.o -c hello.c",
 140         "directory": "/home/user/sandbox",
 141         "file": "/home/user/sandbox/hello.c",
 142         "output": "/home/user/sandbox/hello.o"
 143     }
 144 ]
 145         </programlisting>
 146
 147         <para>
 148
 149             Notice that the generated database contains only an entry for
 150             the <filename>hello.c/hello.o</filename> pairing,
 151             and nothing for the generation of the final executable
 152             <filename>hello</filename>
 153             - the transformation of
 154             <filename>hello.o</filename>
 155             to
 156             <filename>hello</filename>
 157             does not have any information that affects interpretation
 158             of the source code,
 159             so it is not interesting to the compilation database.
 160
 161         </para>
 162
 163         <para>
 164
 165             Although it can be a little surprising at first glance,
 166             a compilation database target is, like any other target,
 167             subject to &scons; target selection rules.
 168             This means if you set a default target (that does not
 169             include the compilation database), or use command-line
 170             targets, it might not be selected for building.
 171             This can actually be an advantage, since you don't
 172             necessarily want to regenerate the compilation database
 173             every build.
 174             The following example
 175             shows selecting relative paths (the default)
 176             for output and source,
 177             and also giving a non-default name to the database.
 178             In order to be able to generate the database separately from building,
 179             an alias is set referring to the database,
 180             which can then be used as a target - here we are only
 181             building the compilation database target, not the code.
 182
 183         </para>
 184
 185         <scons_example name="external_cdb_ex2">
 186             <file name="SConstruct" printme="1">
 187 env = Environment()
 188 env.Tool('compilation_db')
 189 cdb = env.CompilationDatabase('compile_database.json')
 190 Alias('cdb', cdb)
 191 env.Program('test_main.c')
 192             </file>
 193             <file name="test_main.c">
 194                 #include "test_main.h"
 195                 int main(int argc, char* argv[])
 196                 {
 197                 return 0;
 198                 }
 199             </file>
 200             <file name="test_main.h">
 201                 /* dummy include file */
 202             </file>
 203         </scons_example>
 204
 205         <scons_output example="external_cdb_ex2" suffix="1">
 206             <scons_output_command>scons -Q cdb</scons_output_command>
 207         </scons_output>
 208
 209         <para>
 210             <filename>compile_database.json</filename> contains:
 211         </para>
 212
 213         <programlisting language="json">
 214 [
 215     {
 216         "command": "gcc -o test_main.o -c test_main.c",
 217         "directory": "/home/user/sandbox",
 218         "file": "test_main.c",
 219         "output": "test_main.o"
 220     }
 221 ]
 222         </programlisting>
 223
 224         <para>
 225             The following (incomplete) example shows using filtering
 226             to separate build variants.
 227             In the case of using variants,
 228             you want different compilation databases for each,
 229             since the build parameters differ, so the code analysis
 230             needs to see the correct build lines for the 32-bit build
 231             and 64-bit build hinted at here.
 232             For simplicity of presentation,
 233             the example omits the setup details of the variant directories:
 234         </para>
 235
 236         <sconstruct>
 237 env = Environment()
 238 env.Tool("compilation_db")
 239
 240 env1 = env.Clone()
 241 env1["COMPILATIONDB_PATH_FILTER"] = "build/linux32/*"
 242 env1.CompilationDatabase("compile_commands-linux32.json")
 243
 244 env2 = env.Clone()
 245 env2["COMPILATIONDB_PATH_FILTER"] = "build/linux64/*"
 246 env2.CompilationDatabase('compile_commands-linux64.json')
 247         </sconstruct>
 248
 249         <para>
 250             <filename>compile_commands-linux32.json</filename>
 251             contains:
 252         </para>
 253
 254         <programlisting language="json">
 255 [
 256     {
 257         "command": "gcc -o hello.o -c hello.c",
 258         "directory": "/home/mats/github/scons/exp/compdb",
 259         "file": "hello.c",
 260         "output": "hello.o"
 261     }
 262 ]
 263         </programlisting>
 264
 265         <para>
 266             <filename>compile_commands-linux64.json</filename> contains:
 267         </para>
 268
 269         <programlisting language="json">
 270 [
 271     {
 272         "command": "gcc -m64 -o build/linux64/test_main.o -c test_main.c",
 273         "directory": "/home/user/sandbox",
 274         "file": "test_main.c",
 275         "output": "build/linux64/test_main.o"
 276     }
 277 ]
 278         </programlisting>
 279
 280     </section>
 281
 282     <section>
 283         <title>Ninja Build Generator</title>
 284 <note>
 285     <para>
 286                 This is an experimental new feature.
 287                 It is subject to change and/or removal without a depreciation cycle.
 288     </para>
 289
 290     <para>
 291             Loading the &t-link-ninja; tool into SCons will make significant changes
 292             in SCons' normal functioning.
 293     </para>
 294     <itemizedlist>
 295         <listitem>
 296             <para>
 297         SCons will no longer execute any commands directly and will only create the <filename>build.ninja</filename> and
 298         run ninja.
 299             </para>
 300         </listitem>
 301         <listitem>
 302             <para>
 303         Any targets specified on the command line will be passed along to &ninja;
 304             </para>
 305         </listitem>
 306     </itemizedlist>
 307
 308     <para>
 309                 To enable this feature you'll need to use one of the following:
 310     </para>
 311     <!--        NOTE DO NOT INDENT example_commands CONTENTS AS IT WILL ALTER THE FORMATTING-->
 312     <example_commands>
 313 # On the command line --experimental=ninja
 314
 315 # Or in your SConstruct
 316 SetOption('experimental', 'ninja')
 317     </example_commands>
 318 </note>
 319
 320         <para>
 321             Ninja is a small build system that tries to be fast
 322             by not making decisions. &SCons; can at times be slow
 323             because it makes lots of decisions to carry out its goal
 324             of "correctness".  The two tools can be paired to benefit
 325             some build scenarios: by using the &t-link-ninja; tool,
 326             &SCons; can generate the build file &ninja; uses (basically
 327             doing the decision-making ahead of time and recording that
 328             for &ninja;), and can invoke &ninja; to perform a build.
 329             For situations where relationships are not changing, such
 330             as edit/build/debug iterations, this works fine and should
 331             provide considerable speedups for more complex builds.
 332             The implication is if there are larger changes taking place,
 333             &ninja; is not as appropriate - but you can always use &SCons;
 334             to regenerate the build file.  You are NOT advised to use
 335             this for production builds.
 336         </para>
 337
 338         <para>
 339             To use the &t-link-ninja; tool you'll need to first install the
 340             &Python; &ninja; package, as the tool depends on being able to do an
 341             <systemitem>import</systemitem> of the package.
 342             This can be done via:
 343         </para>
 344
 345         <example_commands>
 346 # In a virtualenv, or "python" is the native executable:
 347 python -m pip install ninja
 348
 349 # Windows using Python launcher:
 350 py -m pip install ninja
 351
 352 # Anaconda:
 353 conda install -c conda-forge ninja
 354         </example_commands>
 355
 356         <para>
 357             Reminder that like any non-default tool, you need to initialize it before use
 358             (e.g. <code>env.Tool('ninja')</code>).
 359         </para>
 360
 361         <para>
 362             It is not expected that the &b-link-Ninja; builder will work for all builds at this point. It is still under active
 363             development. If you find that your build doesn't work with &ninja; please bring this to the <ulink url="https://pairlist4.pair.net/mailman/listinfo/scons-users">users mailing list</ulink>
 364             or <ulink url="https://discord.gg/bXVpWAy">
 365             <literal>#scons-help</literal>
 366             </ulink> channel on our Discord server.
 367         </para>
 368
 369         <para>
 370             Specifically if your build has many (or even any) &Python; function actions you may find that the &ninja; build
 371             will be slower as it will run &ninja;, which will then run SCons for each target created by a &Python; action.
 372             To alleviate some of these, especially those &Python; based actions built into SCons there is special logic to
 373             implement those actions via shell commands in the &ninja; build file.
 374         </para>
 375
 376         <para>
 377             When &ninja; runs the generated &ninja; build file, &ninja; will launch &scons; as a daemon and feed commands
 378             to that &scons; process which &ninja; is unable to build directly.  This daemon will stay alive until
 379             explicitly killed, or it times out. The timeout is set by &cv-link-NINJA_SCONS_DAEMON_KEEP_ALIVE; .
 380         </para>
 381
 382         <para>
 383             The daemon will be restarted if any &SConscript; file(s) change or the build changes in a way that &ninja; determines
 384             it needs to regenerate the build.ninja file
 385         </para>
 386
 387         <para>See:</para>
 388
 389         <simplelist type="vert">
 390             <member>
 391             <ulink url="https://ninja-build.org/">
 392                 <citetitle>Ninja Build System</citetitle>
 393             </ulink>
 394             </member>
 395             <member>
 396             <ulink url="https://ninja-build.org/manual.html#ref_ninja_file">
 397                 <citetitle>Ninja File Format Specification</citetitle>
 398             </ulink>
 399             </member>
 400         </simplelist>
 401     </section>
 402 </chapter>