emit build-database: shell-escaped quotes inside the arguments array break consumers

Summary

mcpp emit build-database --format json puts shell-escaped quotes inside the arguments
array. A JSON arguments array is passed to exec without a shell, so its elements must be
unescaped; the backslashes reach the compiler as literal characters.

Consumers that honour arguments (clangd's module scanner, any tool driving the database) then fail
to parse every translation unit that uses a quoted macro define.

Reproduce

In a project whose build defines a macro to a quoted string — openxlings/xlings does, through its
vendored libarchive:

$ mcpp emit build-database --format json > db.json
$ python3 -c "
import json
d = json.load(open('db.json'))
def walk(o):
    if isinstance(o, dict):
        for v in o.values(): yield from walk(v)
    elif isinstance(o, list):
        for v in o: yield from walk(v)
    elif isinstance(o, str): yield o
for s in walk(d):
    if 'PLATFORM_CONFIG_H' in s: print(repr(s)); break
"
'-DPLATFORM_CONFIG_H=\\"mcpp_libarchive_config.h\\"'

The field is arguments, and its type is a list:

字段名: arguments | 类型: list
  元素: '-DPLATFORM_CONFIG_H=\\"mcpp_libarchive_config.h\\"'

So the actual element is:

-DPLATFORM_CONFIG_H=\"mcpp_libarchive_config.h\"

Expected

-DPLATFORM_CONFIG_H="mcpp_libarchive_config.h"

The quotes belong to the macro's value (the source does #include PLATFORM_CONFIG_H, which needs
"..." or <...>). Escaping is a shell concern, and arguments does not go through a shell.

What it breaks

With the backslashes literal, the macro expands to \"mcpp_libarchive_config.h\" and every TU
including it fails:

archive_platform.h:44:10: error: expected "FILENAME" or <FILENAME>
<built-in>:418:27: note: expanded from macro 'PLATFORM_CONFIG_H'
archive_platform.h:164:2: error: No suitable 32-bit unsigned integer type found for this platform
archive_platform.h:173:2: error: No suitable 32-bit signed integer type found for this platform

In openxlings/xlings this is every C file of libarchive, bzip2, lz4, xz, zlib and zstd. For a
language server the consequences are that those files never get an index (no navigation into them),
and the scanner retries and logs the failure repeatedly.

Environment

mcpp 2026.9.16.1
Project: openxlings/xlings (linux x86_64, gcc 16.1.0 profile)
Consumer: mcpp-language-server, which reads arguments as exec-ready per the S1 build database
contract

Note

If arguments is intended to carry shell-quoted text — i.e. consumers are expected to shell-split
and unescape it — then this is a documentation issue instead, and I would like to know, because the
distinction decides whether consumers should unescape defensively. command (a string) and
arguments (a list) usually differ exactly here, which is why we read it as exec-ready.

One reading of a compile-flag element, the databases list what the co…

arguments is exec-ready: each element is one argument the compiler receives, with no shell quoting or escaping. The escaped element in the report was an engine defect, not intended behaviour, so consumers should not unescape defensively. Fixed in #657, which ships in mcpp 2026.9.17.1.

What the investigation found:

Both hosts were affected, beyond \". The databases read flag text with their own splitting rules, which match neither sh nor the MSVCRT rules. Measured on Linux and Windows runners, several spellings disagreed with what the build ran, and 5 of 14 spellings gave different macros on the two hosts.
The build had its own quote bug. defines = ["N=\"x\""] reached the compiler as -DN=x.

What changed in 2026.9.17.1:

One syntax on every host. An element of cflags, cxxflags or asmflags means the same arguments everywhere: the POSIX shell's word syntax without expansions. Outside quotes, a backslash escapes only a blank, a quote or a backslash, so Windows paths keep their backslashes. The rule is in SPEC-004 §8 and docs/04 under "Compile-flag syntax".
Build and databases list the same arguments. The build quotes each argument for its host, and compile_commands.json and mcpp emit build-database list the same arguments. libarchive's element now appears as -DPLATFORM_CONFIG_H="mcpp_libarchive_config.h", and in openxlings/xlings a libarchive unit's arguments run as-is.
defines entries are single values. N="x" arrives as -DN="x".
Compatibility:
- An element that begins with -D or /D and contains a space is still one argument, taken verbatim.
- The first build after upgrading warns (build/flag-words) about any element whose arguments changed.
- No descriptor in the published index is affected.

#655 landed: the ledger, the sandbox table, and the closure

bootstrap from 2026.9.17.1 (#661)

Navigation Menu

Repository navigation

emit build-database: shell-escaped quotes inside the `arguments` array break consumers #655

Summary

Reproduce

Expected

What it breaks

Environment

Note

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

emit build-database: shell-escaped quotes inside the arguments array break consumers #655

Description

Summary

Reproduce

Expected

What it breaks

Environment

Note

Activity

Sunrisepeak commented on Sep 16, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

emit build-database: shell-escaped quotes inside the `arguments` array break consumers #655