d7af0f7d3b
tools/amalgamate/README.md is the unmodified upstream text and no longer matches how the tool is used here: - It named a Bitbucket origin that no longer exists; CHANGES.md already tracks the GitHub mirror commit this copy is based on. - It asked for Python 2.7, but CI and the Makefile run the script with python3. - It told readers to run ./test.sh (not vendored) and install to /usr/local/bin; in this repository the tool runs through `make amalgamate`. - Its usage synopsis showed `-v` taking no argument, but the script's own argparser requires `choices=["yes", "no"]`, so that form fails with "argument -v/--verbose: expected one argument". The Makefile calls it as `--verbose=yes`. - It pointed at test/source.c.json and test/include.h.json, which are not vendored; the configs actually used are config_json.json and config_json_fwd.json. Rewrote only the Installing and Using sections to match; left the "Here be dragons" caveats and the rest of the vendored code untouched to avoid diverging further from upstream. Overlaps #5615, which edits amalgamate.py, this README and CHANGES.md. #5717 item 6 Signed-off-by: Niels Lohmann <mail@nlohmann.me>
amalgamate.py - Amalgamate C source and header files
Origin: https://github.com/edlund/amalgamate (formerly hosted at
https://bitbucket.org/erikedlund/amalgamate, which no longer exists; see
CHANGES.md for the upstream commit this copy is based on)
amalgamate.py aims to make it easy to use SQLite-style C source and header
amalgamation in projects.
For more information, please refer to: http://sqlite.org/amalgamation.html
Here be dragons
amalgamate.py is quite dumb, it only knows the bare minimum about C code
required in order to be able to handle trivial include directives. It can
produce weird results for unexpected code.
Things to be aware of:
amalgamate.py will not handle complex include directives correctly:
#define HEADER_PATH "path/to/header.h"
#include HEADER_PATH
In the above example, path/to/header.h will not be included in the
amalgamation (HEADER_PATH is never expanded).
amalgamate.py makes the assumption that each source and header file which
is not empty will end in a new-line character, which is not immediately
preceded by a backslash character (see 5.1.1.2p1.2 of ISO C99).
amalgamate.py should be usable with C++ code, but raw string literals from
C++11 will definitely cause problems:
R"delimiter(Terrible raw \ data " #include <sneaky.hpp>)delimiter"
R"delimiter(Terrible raw \ data " escaping)delimiter"
In the examples above, amalgamate.py will stop parsing the raw string literal
when it encounters the first quotation mark, which will produce unexpected
results.
Installing amalgamate.py
Python 3 is required.
In this repository, amalgamate.py is not installed separately; it is run in
place through make amalgamate, which calls it once for json.hpp and once
for json_fwd.hpp (see the root Makefile).
Using amalgamate.py
amalgamate.py -c path/to/config.json -s path/to/source/dir \
[-p path/to/prologue.(c|h)] [--verbose=yes|no]
-
The
-c, --configoption should specify the path to a JSON config file which lists the source files, include paths and where to write the resulting amalgamation.config_json.jsonandconfig_json_fwd.jsonin this directory are the configs used forjson.hppandjson_fwd.hpp; each setstarget,sourcesandinclude_paths. -
The
-s, --sourceoption should specify the path to the source directory. This is useful for supporting separate source and build directories. -
The
-p, --prologueoption should specify the path to a file which will be added to the beginning of the amalgamation. It is optional. -
The
-v, --verboseoption takesyesorno(for example--verbose=yes, as used by the Makefile). It is optional.