Author SHA1 Message Date
pancake fd7a37946c Recommend r2pm and document manual plugin loading 2026-10-03 09:46:27 +02:00
Elias Bachaalany 2d76b9964a README: load the plugin with L, and correct three stale lines
- r2 -i <plugin> fails on Windows with radare2 6.2.2, which reads a .dll
  given to -i as a script ('Invalid l subcommand'). The examples now load
  it with -c 'L <path>', which works on every platform
- libxsql is pinned to a release tag (v1.0.21) in all three builds, no
  longer 'a current libxsql'
- the core library links radare2's r_util since r_name_check, so it is no
  longer backend-neutral
- 'may lag; see below' pointed at nothing
2026-10-02 10:18:24 -07:00
+30 -14
View File
@@ -52,7 +52,7 @@ create empty struct/union/enum types through the corresponding tables.
# any one of these
r2pm -ci radare2 # radare2's own package manager
git clone https://github.com/radareorg/radare2 && radare2/sys/install.sh
sudo apt install radare2 # distro package (may lag; see below)
sudo apt install radare2 # distro package (may lag behind releases)
brew install radare2 # macOS
```
@@ -61,14 +61,20 @@ the in-process plugin depends on radare2's ABI.
## Using the plugin
Load the built module and analyze a target:
The recommended way to install the plugin is with r2pm:
```sh
r2 -i /absolute/path/core_r2xsql.so -A ./target
r2pm -U
r2pm -ci r2xsql
```
Use the actual `.so`, `.dylib`, or `.dll` path; omit `-i` once the plugin is
installed in radare2's plugin directory. At the radare2 prompt:
The installed plugin loads automatically when radare2 starts:
```sh
r2 -A ./target
```
At the radare2 prompt:
```text
sql SELECT name, size FROM funcs ORDER BY size DESC LIMIT 10
@@ -79,7 +85,7 @@ q
For a one-shot query:
```sh
r2 -q -A -i /absolute/path/core_r2xsql.so \
r2 -q -A \
-c '"sql SELECT name, size FROM funcs WHERE size > 100 LIMIT 5"' ./target
```
@@ -99,6 +105,17 @@ sql,?
Use `sql,:tsv` for tab-separated output. Native tables have no SQL NULL type;
in particular, `sql,:json` omits NULL and empty-string cells.
For a local build, `make user-install` also installs the plugin for automatic
loading. To load a build without installing it, use either `-i` or `L`:
```sh
r2 -i /absolute/path/core_r2xsql.so -A ./target
r2 -A -c 'L /absolute/path/core_r2xsql.so' ./target
```
Use the actual `.so`, `.dylib`, or `.dll` path. Inside an existing radare2
session, use `L /absolute/path/core_r2xsql.so`.
## Build
Linux / macOS:
@@ -123,9 +140,9 @@ default; a missing radare2 installation is a configure error. The plugin is in
`build/bin/` (`build/bin/Release/` for the MSVC Release configuration).
`R2XSQL_BUILD_PLUGIN=OFF` disables the plugin target and
`R2XSQL_BUILD_EXAMPLES=OFF` disables examples. The backend-neutral static
library and r2pipe backend remain available to C++ consumers. The project
also supports being added as a CMake subdirectory.
`R2XSQL_BUILD_EXAMPLES=OFF` disables examples. The static core library (which
links radare2's `r_util`) and the r2pipe backend remain available to C++
consumers. The project also supports being added as a CMake subdirectory.
### Building the in-r2 plugin the radare2 way (Makefile / meson)
@@ -155,7 +172,7 @@ meson setup build-meson -Dr2_user_plugins=true # ... or the per-user dir
Both build the same plugin: the `sql` command. Both
consume [`libxsql`](https://github.com/0xeb/libxsql): the Makefile uses a
sibling `../libxsql` checkout (else clones it), and meson pulls it as a
subproject. A current libxsql is required (same as CMake's `FetchContent`).
subproject. All three builds pin the same libxsql release tag (`v1.0.21`).
### JSON results
@@ -172,15 +189,14 @@ The same command works through r2pipe and radare2's HTTP `/cmd/` endpoint.
## HTTP access through radare2
Load the plugin in a persistent radare2 session and start r2's web server:
With the plugin installed, start r2's web server in a persistent session:
```sh
r2 -N -q -i /absolute/path/core_r2xsql.so \
r2 -N -q \
-e http.bind=127.0.0.1 -e http.port=9090 -c aa -c '=h' ./target
```
Use the plugin's actual `.so`, `.dylib`, or `.dll` path. If it is installed,
omit `-i`. Send a quoted SQL command through r2's `POST /cmd/` endpoint:
Send a quoted SQL command through r2's `POST /cmd/` endpoint:
```sh
curl --data-binary '"sql SELECT name, size FROM funcs WHERE size > 100 LIMIT 5"' \