C++ examples and docs

Author: DraTeots

.github/workflows/cpp-examples.yml

@@ -0,0 +1,62 @@
+name: C++ examples verification
+
+# Builds the C++ examples with CMake and smoke-tests the simplest one against a
+# fixture SQLite database. Mirrors python-examples.yml, but for the header-only
+# C++ API. The fixture DB is built with the `rcdb` CLI (the canonical way to
+# initialize an RCDB database) so there is no checked-in binary to drift.
+
+on:
+  push:
+    branches: ['*']
+  pull_request:
+    branches: [main]
+
+env:
+  # 4-slash form: SQLAlchemy (used to seed) and the C++ SqLiteProvider parser
+  # (strips the leading "sqlite:///") both resolve this to the same absolute path.
+  RCDB_TEST_CONNECTION: "sqlite:////${{ github.workspace }}/cpp_examples.sqlite"
+
+jobs:
+  cpp-examples:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install build dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake g++ libsqlite3-dev
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install rcdb (provides the `rcdb db init` test fixture)
+        run: |
+          python -m pip install --upgrade pip
+          pip install --editable $GITHUB_WORKSPACE/python
+
+      # The C++ examples read from a real RCDB database. We seed a SQLite one
+      # with the cpp test fixture, then add an `event_count` value for run 1 so
+      # the `simple` example (which looks up event_count) has data to read.
+      - name: Create the example SQLite database
+        run: |
+          rcdb -c "$RCDB_TEST_CONNECTION" db init --add-cpp-tests --confirm
+          rcdb -c "$RCDB_TEST_CONNECTION" add condition 1 event_count 12345
+
+      - name: Configure and build C++ examples (SQLite only)
+        run: |
+          cmake -S $GITHUB_WORKSPACE/cpp -B $GITHUB_WORKSPACE/cpp/build -DWITH_SQLITE=ON -DWITH_MYSQL=OFF
+          cmake --build $GITHUB_WORKSPACE/cpp/build -j
+
+      # ── Smoke-test the examples ───────────────────────────────────
+      # Each example that can run against the fixture DB gets its own step so
+      # failures are visible per-binary.
+
+      - name: "Example: simple (read event_count)"
+        run: |
+          OUT=$("$GITHUB_WORKSPACE/cpp/build/examples_simple" "$RCDB_TEST_CONNECTION" 1)
+          echo "$OUT"
+          echo "$OUT" | grep -q "event_count is: 12345"

cpp/CMakeLists.txt

@@ -7,7 +7,7 @@
 #   RCDB_TEST_CONNECTION="sqlite:///<path-to>.sqlite" ./build/test_rcdb_cpp
 # Create the test database with:  rcdb -c sqlite:///<path-to>.sqlite db init --add-cpp-tests --confirm
 
-cmake_minimum_required(VERSION 3.4)
+cmake_minimum_required(VERSION 3.5)
 project(rcdb_cpp)
 
 option(WITH_MYSQL  "Compile with MySQL support" OFF)
@@ -96,6 +96,7 @@ if(WITH_SQLITE)
 endif()
 
 add_executable(test_rcdb_cpp ${TEST_SOURCE_FILES})
+add_executable(examples_simple            examples/simple.cpp)
 add_executable(examples_trigger_params    examples/get_trigger_params.cpp)
 add_executable(examples_fadc_masks        examples/get_fadc_masks.cpp)
 add_executable(examples_write_conditions  examples/write_conditions.cpp)
@@ -104,6 +105,7 @@ add_executable(examples_write_objects_to_json examples/write_objects_to_json.cpp
 
 target_link_libraries(test_rcdb_cpp ${DB_REQIRED_LIBRARIES} dl pthread sqlite3)
 target_link_libraries(examples_trigger_params ${DB_REQIRED_LIBRARIES} dl pthread)
+target_link_libraries(examples_simple            ${DB_REQIRED_LIBRARIES} dl pthread)
 target_link_libraries(examples_fadc_masks ${DB_REQIRED_LIBRARIES} dl pthread)
 target_link_libraries(examples_write_conditions ${DB_REQIRED_LIBRARIES} dl pthread)
 target_link_libraries(examples_write_array_to_json ${DB_REQIRED_LIBRARIES} dl pthread)

docs/Cpp.md

@@ -13,76 +13,64 @@ C++ API code is located in [$RCDB_HOME/cpp](https://github.com/JeffersonLab/rcdb
 
 ## Installation
 
-TL; DR; version:  
+RCDB C++ API is **header-only** (since v0.03) — there is no separate library build step.
+The CMake project in `$RCDB_HOME/cpp` builds the unit tests and examples, and handles
+all compiler flags and library linkage for you.
 
-**Just include headers and:**
-
-* define ```RCDB_MYSQL``` for MySQL,  ```RCDB_SQLITE``` for SQLite
-* Ensure libs and headers are included. 
+### Dependencies
 
-Compile and run the simplest example for SQLite
+#### Ubuntu / Debian
 
-```bash 
-> gcc $RCDB_HOME/cpp/examples/simple.cpp -o simple -I$RCDB_HOME/cpp/include/ -std=c++11 -lstdc++ -lsqlite3 -DRCDB_SQLITE 
+```bash
+# SQLite
+sudo apt-get install libsqlite3-dev
 
-> ./simple sqlite:////path/to/db/rcdb.sqlite 10452
+# MySQL (either one)
+sudo apt-get install libmysqlclient-dev
+# or
+sudo apt-get install libmariadbclient-dev
 ```
 
-with MySQL support:
-```
-> gcc $RCDB_HOME/cpp/examples/simple.cpp -o simple -I$RCDB_HOME/cpp/include/ -std=c++11 -lstdc++ -DRCDB_MYSQL `mysql_config --libs --cflags --include`
+#### CentOS / Fedora
 
-> ./simple mysql://rcdb@hallddb.jlab.org/rcdb 10452
+```bash
+sudo dnf install sqlite-devel mysql-devel
 ```
 
-Combine both to have MySQL and SQLite working together
-
----
-
-RCDB C++ API is a header only since 0.03. Which means there is no more librcdb and separate step for RCDB. 
-That also means that MySQL and SQLite libraries should be linked to the application which includes RCDB headers. 
-
-In order for your code to build ensure flags/configuration:
-
-* There is at least C++11 support enabled and stdc++ library linked. This means that probably minimum GCC version to be used is 4.8:
-  
-    ```-std=c++11 -lstdc++```
-
-* For MySQL:
-
-     * Define ```RCDB_MYSQL``` 
-     * Add mysql-connector includes and libs. There is useful ```mysql_config``` script:
-
-     ``` -DRCDB_MYSQL `mysql_config --libs --cflags --include` ```
-
-* For SQLite:
-
-     * Define ```RCDB_SQLITE```:
-     * Link libsqlite3 
-
-     ``` -DRCDB_SQLITE -lsqlite3 ```
-
-
-** Defining RCDB_MYSQL or RCDB_SQLITE **
+### SQLite only
 
+```bash
+cd $RCDB_HOME/cpp
+cmake -S . -B build -DWITH_SQLITE=ON -DWITH_MYSQL=OFF
+cmake --build build --target examples_simple
 
-​* Code ```#define RCDB_MYSQL```
-* Compiler arguments ```-DRCDB_MYSQL```
-* CMake ```-DWITH_MYSQL=ON``` (which does ```add_definitions(-DRCDB_MYSQL)```)
+./build/examples_simple sqlite:////path/to/db/rcdb.sqlite 10452
+```
 
+### MySQL only
 
-### Dependencies
+```bash
+cd $RCDB_HOME/cpp
+cmake -S . -B build -DWITH_SQLITE=OFF -DWITH_MYSQL=ON
+cmake --build build --target examples_simple
 
-#### Ubuntu
+./build/examples_simple mysql://rcdb@hallddb.jlab.org/rcdb 10452
+```
 
-* MySQL ```libmysqlclient-dev``` or ```libmariadbclient-dev```
-* SQLite ```libsqlite3-dev```
+### MySQL + SQLite (both)
 
-```sudo apt-get install libmariadbclient-dev libsqlite3-dev -y```
+```bash
+cd $RCDB_HOME/cpp
+cmake -S . -B build -DWITH_SQLITE=ON -DWITH_MYSQL=ON
+cmake --build build --target examples_simple
 
-#### CentOS/Fedora
+# use either connection string:
+./build/examples_simple sqlite:////path/to/db/rcdb.sqlite 10452
+./build/examples_simple mysql://rcdb@hallddb.jlab.org/rcdb 10452
+```
 
-... please add, somebody ...
+> CMake sets the required compile definitions (`-DRCDB_SQLITE`, `-DRCDB_MYSQL`) and links
+> the correct libraries automatically based on the `-DWITH_*` options.
 
 <br/>
 <br/>
@@ -151,7 +139,7 @@ targets (e.g. `examples_trigger_params`). There is no separate install step or c
 
 **List of examples:**
 
-* [simple.cpp](https://github.com/JeffersonLab/rcdb/blob/main/cpp/examples/simple.cpp) - Simple condition readout. Note: this example has no CMake target and is not built by `cmake --build build`; compile it manually with `gcc` as shown in the Installation section.
+* [simple.cpp](https://github.com/JeffersonLab/rcdb/blob/main/cpp/examples/simple.cpp) (target `examples_simple`) - Simple condition readout. Used as the introductory build example in the Installation section above.
 * [get_trigger_params.cpp](https://github.com/JeffersonLab/rcdb/blob/main/cpp/examples/get_trigger_params.cpp) (target `examples_trigger_params`) - Versatile data readout example. It includes:  
      * Reading conditions
      * Working with JSON serialized objects

docs/get-started/installation.md

@@ -5,10 +5,10 @@ or setup data updating scripts. Reconstruction frameworks in C++ or JAVA would l
 RCDB API and use it. Developers and system administrators - install RCDB development database, 
 install website on hosting etc. We can split installation into chapters: 
 
-1. ***Python (library, command line interface, user GUI (local website))***
-2. C++ library compilation - see C++ section
-3. Java library compilation - see Java section
-4. Development install (git clone, MySQL setup, server management) - see Development section
+1. [**Python** (library, command line interface, user GUI (local website))](./python)
+2. [**C++ library** compilation](../Cpp)
+3. [**Java library** compilation](../Java)
+4. [**Development install** (git clone, MySQL setup, server management)](../development/development)
 
 
 ## Python

docs/get-started/select-values.md

@@ -1,13 +1,19 @@
 - [TL;DR; aka Too long didn't read](#tl-dr)
+- [CLI: rcdb select](#cli-rcdb-select)
 - [Select and filter](#select-and-filter)
 - [All options](#all-options)
 - [Result details](#result-details)
 - [Performance](#performance)
-- [From shell](#from-shell)
+- [Shell one-liner](#shell-one-liner)
 
 ## TLDR
 
-Fastest way to select values in 3 lines (using HallD rcdb as example):
+The two ways to select run values from RCDB:
+
+- **Python API** — `db.select_values(...)` — best for scripts and analysis workflows (see below)
+- **CLI** — `rcdb select` — great for quick interactive queries and shell scripts (see [CLI: rcdb select](#cli-rcdb-select))
+
+Fastest way to select values in 3 lines using the Python API (using HallD rcdb as example):
 
 ```python
 # import RCDB
@@ -30,6 +36,24 @@ table = db.select_values(['polarization_angle','beam_current'], "@is_production"
 
 <br>
 
+## CLI: rcdb select
+
+The `rcdb select` command lets you query runs and view condition values directly from the terminal without writing a Python script:
+
+```bash
+rcdb select "@is_production and event_count>1000" 30000-31000
+```
+
+The first argument is a [selection query](query-syntax), the optional second argument is a run range (`30000-31000`). You can also specify which condition columns to display, use `--dump`/`-d` for an export-friendly output without table borders, and `--desc`/`--asc` to control the sort order:
+
+```bash
+rcdb select "@is_production" 30000-31000 "event_count beam_current" --dump --desc
+```
+
+See [`rcdb-cli`](../rcdb-cli) for the full reference.
+
+<br>
+
 ## Select and filter
 
 The fastest designed way to get values from RCDB is by using ```select_values``` function. 
@@ -139,26 +163,12 @@ More info about old select runs && get values API: [Select runs & get values DEP
 
 <br>
 
-## From shell  
-(Shell one liner)
-
-Suppose one wants to select values in a bash script but doesn't want to create a separate python script.
-It is possible to call ```python -c "semicolon;separated;commands"```
+## Shell one-liner
 
-Combining everything in such one-liner:
+For embedding a quick value fetch in a bash script without a separate file, you can also use the Python one-liner form:
 
 ```bash
 python -c "import rcdb.provider;t=rcdb.provider.RCDBProvider('mysql://rcdb@hallddb.jlab.org/rcdb2').select_values(['polarization_angle','polarization_direction'], run_min=30000, run_max=31000);print('\n'.join([' '.join(map(str, r)) for r in t]))"
 ```
 
-Shouldn't be there an easier way? There is the ```rcdb select``` command doing it:
-
-```bash
-rcdb select "@is_production and event_count>1000" 30000-31000
-```
-
-The first argument is a selection query, and the optional second argument is a run range (e.g. ```30000-31000```). You can also pass view columns to display, use ```--dump```/```-d``` for an export-friendly output without table borders, and ```--desc```/```--asc``` to control the run number sort order:
-
-```bash
-rcdb select "@is_production" 30000-31000 "event_count beam_current" --dump --desc
-```
+For most shell use cases `rcdb select` (see [above](#cli-rcdb-select)) is simpler.

docs/python.md

@@ -2,6 +2,26 @@
 
 Below is a high-level overview of RCDB’s Python API
 
+```python
+from rcdb import RCDBProvider
+
+# Connect (MySQL or SQLite)
+db = RCDBProvider("mysql://rcdb@hallddb.jlab.org/rcdb2")
+
+# Select run values with a query
+table = db.select_values(["beam_current", "event_count"],
+                         "@is_production and beam_current > 100",
+                         run_min=30000, run_max=31000)
+
+for row in table:
+    run_number, beam_current, event_count = row
+    print(run_number, beam_current, event_count)
+```
+
+See [Select Values](get-started/select-values) for more on querying, or read on for a full API reference.
+
+---
+
 ## Core Aspects
 
 1. **SQLAlchemy ORM**