mirror of https://github.com/nlohmann/json.git synced 2026-09-30 14:05:18 +00:00

Files

Niels Lohmann 33ef25099d Keep external headers as #include when amalgamating

A header that builds on json.hpp (such as the planned json_view.hpp) must
not inline json.hpp: its single-header version would contain a second copy
of the library, and that copy would change with every library change.

The optional config key "external" lists include paths that are kept as
#include directives. Only the first directive per path is kept; repeated
ones are commented out, as the tool already does for inlined headers.
config_json_view.json uses it for json_view.hpp; the existing configs do
not set it, and json.hpp and json_fwd.hpp regenerate byte-identically.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

2026-09-29 03:49:24 +02:00

amalgamate.py

Keep external headers as #include when amalgamating

2026-09-29 03:49:24 +02:00

CHANGES.md

Keep external headers as #include when amalgamating

2026-09-29 03:49:24 +02:00

config_json_fwd.json

Amalgamate the forward declaration header (#3679 )

2022-08-07 13:57:32 +02:00

config_json_view.json

Keep external headers as #include when amalgamating

2026-09-29 03:49:24 +02:00

config_json.json

Amalgamate the forward declaration header (#3679 )

2022-08-07 13:57:32 +02:00

README.md

Keep external headers as #include when amalgamating

2026-09-29 03:49:24 +02:00

README.md

amalgamate.py - Amalgamate C source and header files

Origin: https://bitbucket.org/erikedlund/amalgamate

Mirror: https://github.com/edlund/amalgamate

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 v.2.7.0 or higher is required.

amalgamate.py can be tested and installed using the following commands:

    ./test.sh && sudo -k cp ./amalgamate.py /usr/local/bin/

Using amalgamate.py

    amalgamate.py [-v] -c path/to/config.json -s path/to/source/dir \
            [-p path/to/prologue.(c|h)]

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. Have a look at test/source.c.json and test/include.h.json to see two examples.

The optional external list names include paths that are kept as #include directives instead of being inlined, e.g. ["nlohmann/json.hpp"] for a header that includes another amalgamated header. Only the first directive for each of these paths is kept; the repeated ones are commented out.
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.