-- compat.cpptrace — stack traces for C++11 and up, from source.

--

-- Here because `compat.libassert` cannot exist without it: libassert's whole

-- value proposition is an assertion that prints a stack trace, and upstream

-- gets that by FetchContent-ing this repository at a pinned commit. This index

-- does not run FetchContent, so the dependency becomes an ordinary package —

-- which is better anyway: one cpptrace in the graph rather than one per

-- consumer that vendored it.

--

-- ── Whole-source glob, because every backend guards itself ─────────────────

--

-- Shape E without the config header. cpptrace supports six symbol backends,

-- six unwinders and three demanglers, and CMake compiles only the selected

-- ones. That selection is unnecessary here: EVERY backend file opens with its

-- own `#ifdef` (`symbols_with_libdwarf.cpp` → `#ifdef

-- CPPTRACE_GET_SYMBOLS_WITH_LIBDWARF`, and so on down the list), so an

-- unselected backend compiles to an empty translation unit exactly the way

-- curl's `vtls/gtls.c` does. The source list is therefore a plain glob and the

-- whole configuration lives in the defines below.

--

-- ── The backends chosen, and what they cost ────────────────────────────────

--

-- The criterion is ZERO EXTERNAL DEPENDENCIES on every platform, because a

-- diagnostic library that drags in libdwarf, libunwind or libbacktrace makes

-- itself harder to adopt than the problem it solves.

--

-- unix `_Unwind_Backtrace` from libgcc (always present, it is what the

-- C++ runtime already uses to unwind), `dladdr` for symbols, and

-- `abi::__cxa_demangle` for names.

-- windows DbgHelp for all three. `dbghelp.dll` is part of Windows itself,

-- so `-ldbghelp` needs nothing installed.

--

-- ⚠️ THE COST IS LINE NUMBERS. `dladdr` resolves an address to a symbol name

-- and the object it came from — it does NOT read DWARF, so traces carry

-- function names without file:line. That is the price of not depending on

-- libdwarf, and it is the right trade for this index today: the alternative is

-- vendoring libdwarf (which upstream itself FetchContents) as a fourth

-- package, for information that matters to a developer at a debugger rather

-- than to CI. A future `libdwarf` feature can add it without changing anything

-- a consumer writes.

--

-- ── Two generated pieces ───────────────────────────────────────────────────

--

-- * `cpptrace/version.hpp` is a `configure_file` of `cmake/in/version-hpp.in`

-- whose only inputs are the three version numbers in `project()`. Snapshot,

-- not a build step.

-- * `CPPTRACE_STATIC_DEFINE` is upstream's own switch (it is checked in

-- `include/cpptrace/basic.hpp`, not generated), and it is required: without

-- it every declaration carries `__declspec(dllexport)` /

-- `visibility("default")` for a shared library this package does not build.

--

-- ⚠️ AND A FLAG CANNOT DELIVER IT, WHICH ONLY WINDOWS SAYS OUT LOUD. The

-- macro decorates DECLARATIONS, so it has to reach every TU that INCLUDES

-- the headers — not just this package's own. As `cxxflags` Linux stayed

-- green, because there the difference is `visibility("default")` versus

-- nothing and the link is unaffected. On the MSVC ABI it is `dllimport`

-- versus nothing, which is an ABI difference, and `compat.libassert` —

-- whose TUs include these headers — failed to link:

--

-- lld-link: warning: locally defined symbol imported:

-- cpptrace::v1::runtime_error::runtime_error(...) [LNK4217]

-- lld-link: error: undefined symbol: __declspec(dllimport)

-- cpptrace::v1::stacktrace_frame::operator!=(...) const

--

-- ⚠️⚠️ MOVING IT TO `defines` DOES NOT FIX THAT, and this was measured

-- rather than assumed: `defines` is package-private too. Read the compile

-- database of a build that has both packages in it and libassert's eight

-- TUs carry `-DLIBASSERT_STATIC_DEFINE` (its OWN package define) and zero

-- `-DCPPTRACE_STATIC_DEFINE`, while cpptrace's 45 carry the reverse.

-- `docs/repository-and-schema.md` says the same thing about a feature's

-- `defines`. THERE IS NO INTERFACE-DEFINE KEY IN THIS GRAMMAR.

--

-- So the delivery mechanism is a SHIM, the same lever `compat.gzip-hpp` and

-- `compat.catch2` use: `basic.hpp` is the only header that reads the macro,

-- and every public header funnels through it (`cpptrace.hpp`,

-- `exceptions.hpp`, `formatting.hpp`, `from_current.hpp`, `gdb_jit.hpp`,

-- `io.hpp`, `utils.hpp` — all of them include it), so ONE shim in front of

-- it serves this package's TUs, libassert's, and any consumer's alike.

-- `mcpp_generated` therefore sorts FIRST in include_dirs.

--

-- The BACKEND macros below stay in `cxxflags` on purpose: those select

-- which .cpp compiles to something and are nobody else's business.

--

-- Upstream also ships `src/cpptrace.cppm` (`export module cpptrace;`). It is

-- deliberately NOT built here: this entry is `compat.*`, which in this index

-- promises header consumption and nothing else, and libassert — the reason

-- this package exists — consumes the headers. A module entry under the owning

-- namespace can be added later without disturbing this one.

--

-- CN mirror: `gitcode.com/mcpp-res/cpptrace`, the upstream tarball re-hosted

-- BYTE-IDENTICALLY (verified: the mirror's sha256 equals the one declared

-- here, which is what lets one `sha256` serve both arms). GLOBAL stays the

-- default; CN is the fallback `mcpp self config --mirror CN` selects.

package = {

spec = "1",

namespace = "compat",

name = "cpptrace",

description = "cpptrace — simple, portable stack traces for C++",

licenses = {"MIT"},

repo = "https://github.com/jeremy-rifkin/cpptrace",

type = "package",

xpm = {

linux = {

["1.0.4"] = {

url = {

GLOBAL = "https://github.com/jeremy-rifkin/cpptrace/archive/refs/tags/v1.0.4.tar.gz",

CN = "https://gitcode.com/mcpp-res/cpptrace/releases/download/1.0.4/cpptrace-1.0.4.tar.gz",

},

sha256 = "5c9f5b301e903714a4d01f1057b9543fa540f7bfcc5e3f8bd1748e652e24f9ea",

},

},

macosx = {

["1.0.4"] = {

url = {

GLOBAL = "https://github.com/jeremy-rifkin/cpptrace/archive/refs/tags/v1.0.4.tar.gz",

CN = "https://gitcode.com/mcpp-res/cpptrace/releases/download/1.0.4/cpptrace-1.0.4.tar.gz",

},

sha256 = "5c9f5b301e903714a4d01f1057b9543fa540f7bfcc5e3f8bd1748e652e24f9ea",

},

},

windows = {

["1.0.4"] = {

url = {

GLOBAL = "https://github.com/jeremy-rifkin/cpptrace/archive/refs/tags/v1.0.4.tar.gz",

CN = "https://gitcode.com/mcpp-res/cpptrace/releases/download/1.0.4/cpptrace-1.0.4.tar.gz",

},

sha256 = "5c9f5b301e903714a4d01f1057b9543fa540f7bfcc5e3f8bd1748e652e24f9ea",

},

},

},

mcpp = {

language = "c++23",

import_std = false,

c_standard = "c11",

-- `*/src` carries private headers the sources include as `utils/…`,

-- `binary/…`; `mcpp_generated` carries the version header at the path

-- `<cpptrace/version.hpp>` upstream's public headers open.

-- ORDER MATTERS: mcpp_generated FIRST, so the basic.hpp shim below is

-- found before upstream's, which it then reaches with #include_next.

include_dirs = { "mcpp_generated", "*/include", "*/src" },

generated_files = {

-- Delivers CPPTRACE_STATIC_DEFINE to every TU that opens a cpptrace

-- header, which no descriptor key can do. See the header note.

["mcpp_generated/cpptrace/basic.hpp"] = [==[

// mcpp-index shim: cpptrace is built as objects here, not as a shared library,

// so every declaration must be plain rather than dllimport/visibility-default.

// Upstream reads CPPTRACE_STATIC_DEFINE in this header and nowhere else, and

// every public cpptrace header includes this one.

#ifndef MCPP_COMPAT_CPPTRACE_STATIC_SHIM

#define MCPP_COMPAT_CPPTRACE_STATIC_SHIM

#ifndef CPPTRACE_STATIC_DEFINE

# define CPPTRACE_STATIC_DEFINE

#endif

#include_next <cpptrace/basic.hpp>

#endif

]==],

["mcpp_generated/cpptrace/version.hpp"] = [==[

/* configure_file() of cmake/in/version-hpp.in for cpptrace 1.0.4. */

#ifndef CPPTRACE_VERSION_HPP

#define CPPTRACE_VERSION_HPP

#define CPPTRACE_VERSION_MAJOR 1

#define CPPTRACE_VERSION_MINOR 0

#define CPPTRACE_VERSION_PATCH 4

#define CPPTRACE_TO_VERSION(MAJOR, MINOR, PATCH) ((MAJOR) * 10000 + (MINOR) * 100 + (PATCH))

#define CPPTRACE_VERSION CPPTRACE_TO_VERSION(CPPTRACE_VERSION_MAJOR, CPPTRACE_VERSION_MINOR, CPPTRACE_VERSION_PATCH)

#endif

]==],

},

sources = { "*/src/**/*.cpp" },

targets = { ["cpptrace"] = { kind = "lib" } },

deps = { },

-- Belt and braces for this package's OWN TUs; the shim above is what

-- reaches everyone else's.

defines = { "CPPTRACE_STATIC_DEFINE" },

linux = {

cxxflags = {

"-DCPPTRACE_UNWIND_WITH_UNWIND",

"-DCPPTRACE_GET_SYMBOLS_WITH_LIBDL",

"-DCPPTRACE_DEMANGLE_WITH_CXXABI",

},

-- dladdr lives in libdl on glibc.

ldflags = { "-ldl" },

},

macosx = {

cxxflags = {

"-DCPPTRACE_UNWIND_WITH_UNWIND",

"-DCPPTRACE_GET_SYMBOLS_WITH_LIBDL",

"-DCPPTRACE_DEMANGLE_WITH_CXXABI",

},

},

windows = {

cxxflags = {

"-DCPPTRACE_UNWIND_WITH_DBGHELP",

"-DCPPTRACE_GET_SYMBOLS_WITH_DBGHELP",

"-DCPPTRACE_DEMANGLE_WITH_WINAPI",

},

ldflags = { "-ldbghelp" },

},

},

}