From e1e36add272713ce53ce415c3c6a4ac6d2ba69c6 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 24 Jun 2020 07:49:14 -0600 Subject: Add a new chapter on external tools to User Guide [ci skip] Initial content is the compilation_db material Signed-off-by: Mats Wichmann --- doc/user/MANIFEST | 1 + doc/user/external.xml | 158 ++++++++++++++++++++++++++++++++++++++++++++++++++ doc/user/main.xml | 18 +----- doc/user/misc.xml | 65 --------------------- doc/user/sconf.xml | 24 ++++++++ 5 files changed, 184 insertions(+), 82 deletions(-) create mode 100644 doc/user/external.xml 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 @@ + + + %scons; + + + %builders-mod; + + %functions-mod; + + %tools-mod; + + %variables-mod; + +]> + + +Using SCons with other build tools + + + + + + 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. + + + + + + This chapter shows some techniques for interacting with other + projects and tools effectively from within &SCons;. + + + +
+ Creating a Compilation Database + + + + 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. + + + + + + The Clang project has defined a JSON Compilation Database. + This database is in common use as input into Clang tools + and many IDEs and editors as well. + See + + JSON Compilation Database Format Specification + + 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). + + + + + + 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 + COMPILATIONDB_USE_ABSPATH=(True|False) + which defaults to False. + + + + + + Example of absolute paths for target and source: + + + + +env = Environment(COMPILATIONDB_USE_ABSPATH=True) +env.Tool('compilation_db') +env.CompilationDatabase('compile_commands.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" + } +] + + + + + Example of relative paths for target and source: + + + + +env = Environment() +env.Tool('compilation_db') +env.CompilationDatabase('compile_commands.json') + + +[ + { + "command": "gcc -o test_main.o -c test_main.c", + "directory": "/home/user/sandbox", + "file": "test_main.c", + "target": "test_main.o" + } +] + + +
+ + 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 @@ ]> - - @@ -158,6 +141,7 @@ --> + 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', -
- Creating LLVM Compilation Database - - - - 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. - - - See - - JSON Compilation Database Format Specification - - for complete information - - - - - 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 - COMPILATIONDB_USE_ABSPATH=(True|False) - which defaults to False. - - - Example of absolute paths for target and source - - -env = Environment(COMPILATIONDB_USE_ABSPATH=True) -env.Tool('compilation_db') -env.CompilationDatabase('compile_commands.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" - } -] - - - - Example of relative paths for target and source - - -env = Environment() -env.Tool('compilation_db') -env.CompilationDatabase('compile_commands.json') - - -[ - { - "command": "gcc -o test_main.o -c test_main.c", - "directory": "/home/user/sandbox", - "file": "test_main.c", - "target": "test_main.o" - } -] - - -
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() + 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. + + + + + + Note that &SCons; uses its own dependency mechanism to determine when a check needs to be run--that is, -- cgit v0.12