mirror of
https://github.com/nlohmann/json.git
synced 2026-10-03 21:20:30 +00:00
Niels Lohmann
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>
70 lines
2.7 KiB
Markdown
70 lines
2.7 KiB
Markdown
# 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, --config` option 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.json` and `config_json_fwd.json` in this
|
|
directory are the configs used for `json.hpp` and `json_fwd.hpp`; each
|
|
sets `target`, `sources` and `include_paths`.
|
|
|
|
* The `-s, --source` option should specify the path to the source directory.
|
|
This is useful for supporting separate source and build directories.
|
|
|
|
* The `-p, --prologue` option should specify the path to a file which will be
|
|
added to the beginning of the amalgamation. It is optional.
|
|
|
|
* The `-v, --verbose` option takes `yes` or `no` (for example
|
|
`--verbose=yes`, as used by the Makefile). It is optional.
|
|
|