|
1 | | -# DuckDB Rust extension template |
2 | | -This is an **experimental** template for Rust based extensions based on the C Extension API of DuckDB. The goal is to |
3 | | -turn this eventually into a stable basis for pure-Rust DuckDB extensions that can be submitted to the Community extensions |
4 | | -repository |
| 1 | +# DuckDB Pyroscope Extension |
5 | 2 |
|
6 | | -Features: |
7 | | -- No DuckDB build required |
8 | | -- No C++ or C code required |
9 | | -- CI/CD chain preconfigured |
10 | | -- (Coming soon) Works with community extensions |
11 | | - |
12 | | -## Cloning |
13 | | - |
14 | | -Clone the repo with submodules |
15 | | - |
16 | | -```shell |
17 | | -git clone --recurse-submodules <repo> |
| 3 | +### Build |
18 | 4 | ``` |
19 | | - |
20 | | -## Dependencies |
21 | | -In principle, these extensions can be compiled with the Rust toolchain alone. However, this template relies on some additional |
22 | | -tooling to make life a little easier and to be able to share CI/CD infrastructure with extension templates for other languages: |
23 | | - |
24 | | -- Python3 |
25 | | -- Python3-venv |
26 | | -- [Make](https://www.gnu.org/software/make) |
27 | | -- Git |
28 | | - |
29 | | -Installing these dependencies will vary per platform: |
30 | | -- For Linux, these come generally pre-installed or are available through the distro-specific package manager. |
31 | | -- For MacOS, [homebrew](https://formulae.brew.sh/). |
32 | | -- For Windows, [chocolatey](https://community.chocolatey.org/). |
33 | | - |
34 | | -## Building |
35 | | -After installing the dependencies, building is a two-step process. Firstly run: |
36 | | -```shell |
37 | 5 | make configure |
38 | | -``` |
39 | | -This will ensure a Python venv is set up with DuckDB and DuckDB's test runner installed. Additionally, depending on configuration, |
40 | | -DuckDB will be used to determine the correct platform for which you are compiling. |
41 | | - |
42 | | -Then, to build the extension run: |
43 | | -```shell |
44 | 6 | make debug |
45 | 7 | ``` |
46 | | -This delegates the build process to cargo, which will produce a shared library in `target/debug/<shared_lib_name>`. After this step, |
47 | | -a script is run to transform the shared library into a loadable extension by appending a binary footer. The resulting extension is written |
48 | | -to the `build/debug` directory. |
49 | | - |
50 | | -To create optimized release binaries, simply run `make release` instead. |
51 | | - |
52 | | -## Testing |
53 | | -This extension uses the DuckDB Python client for testing. This should be automatically installed in the `make configure` step. |
54 | | -The tests themselves are written in the SQLLogicTest format, just like most of DuckDB's tests. A sample test can be found in |
55 | | -`test/sql/<extension_name>.test`. To run the tests using the *debug* build: |
56 | | - |
57 | | -```shell |
58 | | -make test_debug |
59 | | -``` |
60 | 8 |
|
61 | | -or for the *release* build: |
62 | | -```shell |
63 | | -make test_release |
64 | | -``` |
65 | | - |
66 | | -### Version switching |
67 | | -Testing with different DuckDB versions is really simple: |
68 | | - |
69 | | -First, run |
70 | | -``` |
71 | | -make clean_all |
72 | | -``` |
73 | | -to ensure the previous `make configure` step is deleted. |
74 | | - |
75 | | -Then, run |
76 | | -``` |
77 | | -DUCKDB_TEST_VERSION=v1.1.2 make configure |
78 | | -``` |
79 | | -to select a different duckdb version to test with |
80 | | - |
81 | | -Finally, build and test with |
82 | | -``` |
83 | | -make debug |
84 | | -make test_debug |
85 | | -``` |
| 9 | +### Test |
86 | 10 |
|
87 | | -### Known issues |
88 | | -This is a bit of a footgun, but the extensions produced by this template may (or may not) be broken on windows on python3.11 |
89 | | -with the following error on extension load: |
90 | | -```shell |
91 | | -IO Error: Extension '<name>.duckdb_extension' could not be loaded: The specified module could not be found |
| 11 | +```sql |
| 12 | +D LOAD './build/debug/pyroscope.duckdb_extension'; |
| 13 | +---- Start the tracer, requires backend URL |
| 14 | +D SELECT * FROM trace_start('https://pyroscope:4000'); |
| 15 | +---- Stop the tracer |
| 16 | +D SELECT * FROM trace_stop(); |
92 | 17 | ``` |
93 | | -This was resolved by using python 3.12 |
0 commit comments