r2xsql/docs/development.md

Building and testing r2xsql

Build

Linux / macOS:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DRadare2_ROOT=/path/to/radare2/prefix
cmake --build build

Windows (MSVC):

cmake -S . -B build -G "Visual Studio 17 2022" -A x64 `
  -DRadare2_ROOT=C:\path\to\radare2\prefix
cmake --build build --config Release
cmake --build build --config Release --target user-install

Radare2_ROOT is a radare2 install prefix containing include/libr/ and lib/. CMake requires radare2 and builds the libr backend and plugin by default; a missing radare2 installation is a configure error. The plugin is in build/bin/ (build/bin/Release/ for the MSVC Release configuration).

CMake's user-install target installs the plugin in the directory reported by the matching radare2's -NN -H R2_USER_PLUGINS, without administrator access. user-uninstall removes it. Override the destination at configure time with -DR2XSQL_USER_PLUGINS=/path/to/plugins if needed. Both targets also work on Linux/macOS; omit --config Release with a single-configuration generator.

R2XSQL_BUILD_PLUGIN=OFF disables the plugin target and R2XSQL_BUILD_EXAMPLES=OFF disables examples. C++ consumers can embed the library with open_libr and the r2xsql_libr target. The project also supports being added as a CMake subdirectory.

Building the in-r2 plugin the radare2 way (Makefile / meson)

CMake above builds the library, examples, and plugin, including on Windows. If you only want the in-r2 plugin — the core_r2xsql module that adds the sql command inside radare2 — there is also a radare2-native build that needs no CMake, matching how radare2 plugins are usually built (plugin paths from r2 -H, radare2 from pkg-config r_core):

make                 # -> build-make/core_r2xsql.$(r2 -H R2_LIBEXT)
make user-install    # install into the per-user plugin dir (no root)
make install         # install system-wide (R2_LIBR_PLUGINS)
make user-uninstall  # remove the per-user plugin without building
make uninstall       # remove the system-wide plugin without building
make test            # run the command and HTTP regression suite
# only `radare2` (not `r2`) on PATH?  ->  make R2=radare2

make install and make uninstall accept PLUGDIR and DESTDIR for a custom plugin directory or staged install. User targets use R2_USER_PLUGINS; override it on the make command line when needed.

Or with meson (what radare2 itself uses):

meson setup build-meson
meson compile -C build-meson
meson install -C build-meson                 # into R2_LIBR_PLUGINS
meson setup build-meson -Dr2_user_plugins=true   # ... or the per-user dir

Both build the same plugin: the sql command. Both consume libxsql: the Makefile uses a sibling ../libxsql checkout (else clones it), and meson pulls it as a subproject. All three builds pin the same libxsql release tag (v1.0.21).

When published, binary release assets are named r2xsql-<radare2-version>-<R2PM_TRIPLET>.zip, for example r2xsql-6.2.6-linux-x86-64.zip. The first release, v0.0.1, targets radare2 6.2.6 on Linux x86-64, Windows x86-64 and macOS ARM64. The r2pm package uses R2PM_VERSION_MAP "6.2.6:v0.0.1" to select this release. Each archive contains the plugin in plugins/ and dependency license notices. With r2pm 6.2.6 or newer, use r2pm -U followed by r2pm -bi r2xsql; uninstall with r2pm -u r2xsql. Only matching radare2 versions and targets are installed. To install manually, copy the plugin to the directory printed by radare2 -NN -H R2_USER_PLUGINS.

Windows binaries use the dynamic MSVC runtime, matching radare2's MSVC build. Use the matching radare2 distribution and its runtime dependencies; the plugin archive does not bundle another copy of radare2's DLLs.

Tag the release as v0.0.1 after the build workflow passes. Tag builds publish the three ZIPs only after every platform succeeds. CI tests automatic plugin discovery, JSON/CSV output, comment writes, error recovery, and normal/quick process exit on all three platforms, plus the r2r suite on Linux and macOS. CI also builds and checks make user-install on Linux/macOS and CMake's user-install target on Windows before publishing. After publication, CI installs the public binaries with r2pm -bi r2xsql against the official Linux and Windows radare2 distributions and runs the same smoke checks.

Tests

Run the regression suite with radare2, r2r, a C compiler and Python 3 on PATH (Python's standard library is used only for the HTTP transport test):

make test

This builds the plugin and runs the r2r database in tests/db. Each test loads the exact build explicitly, ignoring installed user plugins, and checks its output; SQL exceptions fail the suite even when radare2 exits successfully. The fixture is compiled locally, with no downloaded test binaries or pytest.

To test an existing CMake/Meson build, or select matching radare2 tools:

make -C tests R2XSQL_PLUGIN=/absolute/path/core_r2xsql.so R2=/path/to/r2 R2R=/path/to/r2r
# Only command tests (no Python needed):
make -C tests TESTS=db/cmd

R2R_ARGS accepts r2r options (default -L); for example, R2R_ARGS=-i enables interactive failure review. One small standard-library helper retains real HTTP GET/POST coverage, including server startup and shutdown; r2r checks its result alongside the command tests.

The Make build tracks header dependencies. This prevents stale adapters after C++ interface changes, which could previously cause std::bad_alloc during make test. After updating this Makefile, existing objects are rebuilt once to establish dependency files. For older checkouts, make clean && make test clears those stale objects.

Backends (internal detail)

The plugin uses the host RCore; embedding and tests use these backends:

Backend	Used by	Notes
LibrBackend	core_r2xsql and C++ consumers (open_libr)	Uses radare2 in-process; the plugin wraps its host core.
MockBackend	embedding/tests	Canned {command → response} map, records issued commands — no live radare2.

The in-process backend reads analysis, flags, symbols, binary metadata, IO maps, write caches, types, and runtime catalogs through native libr APIs. The command fallbacks support mock responses where needed. Instruction/operand text rendering and byte/ROP searches still use radare2's command handlers to preserve their rendering, search configuration, and hit behavior.

The internal r2pipe backend was for the removed standalone CLI and servers. It duplicated process management and command-based access without serving the native plugin, so it has been removed. External r2pipe clients can still send sql commands to radare2 with this plugin loaded; radare2 also provides HTTP access through /cmd/.