Troubleshooting

Things that go wrong, in roughly the order people hit them.

make says it cannot find Qt6Test

Package Qt6Test was not found in the pkg-config search path

The original test suite is Qt/C++, so building it needs Qt6 Test and moc. On Debian and Ubuntu:

$ sudo apt install qt6-base-dev qt6-base-dev-tools pkg-config

moc moves around between distributions. If the makefile cannot find it, point at it:

$ make MOC=/usr/lib/qt6/libexec/moc

The library itself does not need Qt for anything. cargo build --release gives you libtinycbor.a with no Qt installed at all. Qt is only there so upstream's tests can run unmodified, which is the entire premise of the project.

make test-tools says it skipped

missing /home/you/tinycbor-upstream/build-test/tools/cbordump
  (skipped: no upstream tools to compare against)

That check compares this port's cbordump and json2cbor against upstream's binaries. Binaries are not vendored the way bench/reference/libtinycbor-upstream.a is, so you need upstream checked out and built:

$ git clone https://github.com/intel/tinycbor ~/tinycbor-upstream
$ cd ~/tinycbor-upstream && git checkout 9441b2ca
$ cmake -B build-test && cmake --build build-test

Point somewhere else with UPSTREAM=/path/to/build/tools.

A skip is not a failure. The rest of make test is unaffected, and a real divergence exits non-zero and stops the build.

The fuzzer will not start

no oracle at .../fuzz/oracle/cbor-oracle -- run fuzz/oracle/build.sh

The differential oracle is upstream's C compiled into a standalone binary, and fuzz/run.sh builds it for you. It does not need the checkout above: without one it compiles fuzz/oracle/cbor-oracle.c against the vendored headers and the committed bench/reference/libtinycbor-upstream.a, and says which of the two it used. A checkout still wins when you have one, since pointing TINYCBOR= at a different upstream commit is the only way to fuzz against one.

You also need nightly Rust and cargo-fuzz:

$ rustup toolchain install nightly
$ cargo install cargo-fuzz

The oracle runs as a subprocess, never linked in. That is not an implementation detail you can optimise away, it is the thing that keeps "this library contains no C" checkable. See Where the C ends.

make bench refuses, or warns about a changed archive

!! rust archive changed since link; rerun bench/build.sh to measure the current tree

The benchmark records the SHA-256 of both archives when it links its drivers. If you rebuild the library afterwards, the recorded numbers no longer describe the code you have, and the harness says so instead of quietly publishing stale figures.

$ ./bench/build.sh && python3 bench/run.py

Also: run it on an idle machine. The numbers in the repository were re-taken because a run went out at load 6.4 on 8 cores, and it was visibly wrong. The recorded load average is in results.json so you can tell whether to believe a given run.

Linker errors about pthread_* or dlsym

undefined reference to `pthread_mutex_lock'

Add -lpthread -ldl. Linking a Rust staticlib pulls in the Rust standard library, which needs both. This is the one thing that is genuinely different from linking the C, and it is not optional.

The suite passes but sha256sum -c fails

Something wrote into tests/original/. Nothing in this repository is supposed to: moc output goes into build/, and the makefile is set up that way deliberately.

$ git status tests/original
$ git checkout tests/original

If it keeps happening, you are probably running upstream's CMake inside the checkout rather than this repository's makefile.

cbor_value_* returns garbage, or crashes

Check the lifetimes first. CborValue holds a pointer back to the CborParser it came from, and nothing enforces that the parser outlives it. A parser declared in an inner scope and a value used after that scope closes is the classic version, and it will usually appear to work for a while.

This is inherited from the C API and cannot be fixed without changing the ABI, which is the one thing that cannot change. Decision 21 says so at more length.

Everything builds but the numbers do not match the docs

Fair. Every figure in these docs comes from a run on one laptop, and the pages that carry numbers say when they were verified. Re-run and trust your own output:

$ make test        # 4,929 / 4,929
$ make symbols     # 44/44, zero diff
$ make lint        # includes the unsafe budget count
$ python3 bench/run.py

If your numbers differ and you think the docs are wrong rather than your machine, that is worth an issue.

Next steps