From d3dda7af7d3f62530514a7cbde0fd8fc28ffa844 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Rombauts?= Date: Mon, 2 Feb 2026 21:16:09 +0100 Subject: [PATCH 1/3] Add a set of granular SKILLs extracted from the monolithic copilot instructions Created in .claude/skills/ to be compatible with Cursor and Claude Code Re-purpose and rename the load-github-copilot-instructions rule since we don't want to always load the monolithic copilot instructions file, now that we have more granular SKILLs --- .claude/skills/sqlitecpp-build-cmake/SKILL.md | 41 +++++++++++++++++++ .claude/skills/sqlitecpp-build-meson/SKILL.md | 35 ++++++++++++++++ .../skills/sqlitecpp-ci-workflows/SKILL.md | 38 +++++++++++++++++ .../sqlitecpp-coding-standards/SKILL.md | 31 ++++++++++++++ .../skills/sqlitecpp-git-branching/SKILL.md | 26 ++++++++++++ .../skills/sqlitecpp-sqlite-flags/SKILL.md | 29 +++++++++++++ .../skills/sqlitecpp-troubleshooting/SKILL.md | 30 ++++++++++++++ .claude/skills/sqlitecpp-workflow/SKILL.md | 26 ++++++++++++ .../load-github-copilot-instructions.mdc | 34 --------------- .cursor/rules/sqlitecpp-skills-routing.mdc | 23 +++++++++++ .github/copilot-instructions.md | 4 +- 11 files changed, 282 insertions(+), 35 deletions(-) create mode 100644 .claude/skills/sqlitecpp-build-cmake/SKILL.md create mode 100644 .claude/skills/sqlitecpp-build-meson/SKILL.md create mode 100644 .claude/skills/sqlitecpp-ci-workflows/SKILL.md create mode 100644 .claude/skills/sqlitecpp-coding-standards/SKILL.md create mode 100644 .claude/skills/sqlitecpp-git-branching/SKILL.md create mode 100644 .claude/skills/sqlitecpp-sqlite-flags/SKILL.md create mode 100644 .claude/skills/sqlitecpp-troubleshooting/SKILL.md create mode 100644 .claude/skills/sqlitecpp-workflow/SKILL.md delete mode 100644 .cursor/rules/load-github-copilot-instructions.mdc create mode 100644 .cursor/rules/sqlitecpp-skills-routing.mdc diff --git a/.claude/skills/sqlitecpp-build-cmake/SKILL.md b/.claude/skills/sqlitecpp-build-cmake/SKILL.md new file mode 100644 index 00000000..976f092c --- /dev/null +++ b/.claude/skills/sqlitecpp-build-cmake/SKILL.md @@ -0,0 +1,41 @@ +--- +name: sqlitecpp-build-cmake +description: Builds SQLiteCpp with CMake on Windows, Linux, or macOS. Use when configuring CMake builds, tests, options, or build scripts. +--- + +# SQLiteCpp CMake Build + +## Quick builds +- Windows (VS 2022): + - `mkdir build` + - `cd build` + - `cmake -G "Visual Studio 17 2022" -DSQLITECPP_BUILD_TESTS=ON -DSQLITECPP_BUILD_EXAMPLES=ON ..` + - `cmake --build . --config Release` +- Unix/macOS: + - `mkdir build && cd build` + - `cmake -DCMAKE_BUILD_TYPE=Debug -DSQLITECPP_BUILD_TESTS=ON -DSQLITECPP_BUILD_EXAMPLES=ON ..` + - `cmake --build .` + +## Build scripts +- `build.bat` (Windows) enables shared libs, tests, examples, and runs `ctest`. +- `build.sh` (Unix) enables ASAN, shared libs, tests, examples, and runs `ctest`. + +## Common options +- `SQLITECPP_BUILD_TESTS` (OFF): build unit tests. +- `SQLITECPP_BUILD_EXAMPLES` (OFF): build examples. +- `BUILD_SHARED_LIBS` (OFF): build shared libs (DLLs). +- `SQLITECPP_INTERNAL_SQLITE` (ON): use bundled sqlite3 source. +- `SQLITE_ENABLE_COLUMN_METADATA` (ON): enable `getColumnOriginName()`. +- `SQLITECPP_RUN_CPPLINT` (ON): run cpplint target. +- `SQLITECPP_RUN_CPPCHECK` (ON): run cppcheck target. +- `SQLITECPP_RUN_DOXYGEN` (OFF): generate docs. +- `SQLITECPP_USE_ASAN` (OFF): address sanitizer. +- `SQLITECPP_USE_GCOV` (OFF): GCov coverage. + +## Tests +- `ctest --output-on-failure` +- `ctest --output-on-failure -V` +- `ctest --output-on-failure -R "Database"` + +## Notes +- Tests require the `googletest` submodule: `git submodule update --init --recursive`. diff --git a/.claude/skills/sqlitecpp-build-meson/SKILL.md b/.claude/skills/sqlitecpp-build-meson/SKILL.md new file mode 100644 index 00000000..9e1ee337 --- /dev/null +++ b/.claude/skills/sqlitecpp-build-meson/SKILL.md @@ -0,0 +1,35 @@ +--- +name: sqlitecpp-build-meson +description: Builds SQLiteCpp with Meson. Use when configuring Meson builds, tests, or Meson options. +--- + +# SQLiteCpp Meson Build + +## Quick builds +- Default build: + - `meson setup builddir` + - `meson compile -C builddir` +- With tests and examples: + - `meson setup builddir -DSQLITECPP_BUILD_TESTS=true -DSQLITECPP_BUILD_EXAMPLES=true` + - `meson compile -C builddir` + - `meson test -C builddir` + +## CI-style setup (GitHub Actions) +- `meson setup builddir -DSQLITECPP_BUILD_TESTS=true -DSQLITECPP_BUILD_EXAMPLES=true --force-fallback-for=sqlite3` +- `meson compile -C builddir` +- `meson test -C builddir` + +## Options +- `SQLITECPP_BUILD_TESTS`: build unit tests. +- `SQLITECPP_BUILD_EXAMPLES`: build examples. +- `SQLITE_ENABLE_COLUMN_METADATA`: enable column origin metadata. +- `SQLITE_ENABLE_ASSERT_HANDLER`: enable assert handler. +- `SQLITE_HAS_CODEC`: enable codec API (requires SQLCipher). +- `SQLITE_USE_LEGACY_STRUCT`: legacy `sqlite3_value` struct. +- `SQLITECPP_DISABLE_STD_FILESYSTEM`: disable std::filesystem. +- `SQLITECPP_DISABLE_SQLITE3_EXPANDED_SQL`: disable sqlite3_expanded_sql. +- `SQLITE_OMIT_LOAD_EXTENSION`: omit load extension. + +## Notes +- Meson defaults to `cpp_std=c++17` to support newer gtest versions. +- On Windows, Meson enforces at least C++14 if needed by headers. diff --git a/.claude/skills/sqlitecpp-ci-workflows/SKILL.md b/.claude/skills/sqlitecpp-ci-workflows/SKILL.md new file mode 100644 index 00000000..1436310b --- /dev/null +++ b/.claude/skills/sqlitecpp-ci-workflows/SKILL.md @@ -0,0 +1,38 @@ +--- +name: sqlitecpp-ci-workflows +description: SQLiteCpp CI workflow patterns (GitHub Actions, AppVeyor, Travis). Use when updating CI configs, build matrices, or test steps. +--- + +# SQLiteCpp CI Workflows + +## Common steps +- Checkout code. +- Initialize submodules: `git submodule update --init --recursive`. +- Configure build directory (`build` or `builddir`). +- Build and run tests with verbose output. + +## GitHub Actions (CMake) +- Matrix across Windows (MSVC/MinGW), Ubuntu, macOS. +- CMake config includes: + - `-DBUILD_SHARED_LIBS=ON` + - `-DSQLITECPP_BUILD_TESTS=ON` + - `-DSQLITECPP_BUILD_EXAMPLES=ON` + - `-DSQLITECPP_RUN_CPPCHECK=OFF` + - `-DSQLITECPP_RUN_CPPLINT=OFF` +- Tests: `ctest --verbose --output-on-failure`. + +## GitHub Actions (Meson) +- Use `pipx install meson ninja`. +- Set `CC`, `CXX`, and optional linkers. +- Setup: `meson setup builddir -DSQLITECPP_BUILD_TESTS=true -DSQLITECPP_BUILD_EXAMPLES=true --force-fallback-for=sqlite3`. +- Build: `meson compile -C builddir`. +- Test: `meson test -C builddir`. + +## AppVeyor +- Visual Studio 2022/2015, Debug/Release, Win32/x64. +- CMake config: `-DSQLITECPP_BUILD_EXAMPLES=ON -DSQLITECPP_BUILD_TESTS=ON -DSQLITECPP_RUN_CPPCHECK=OFF`. +- Build and run `ctest --output-on-failure`. + +## Travis CI +- Multiple GCC/Clang versions across Linux and macOS. +- Variants for ASAN, GCov, Valgrind, shared libs, external sqlite3. diff --git a/.claude/skills/sqlitecpp-coding-standards/SKILL.md b/.claude/skills/sqlitecpp-coding-standards/SKILL.md new file mode 100644 index 00000000..1dea9e60 --- /dev/null +++ b/.claude/skills/sqlitecpp-coding-standards/SKILL.md @@ -0,0 +1,31 @@ +--- +name: sqlitecpp-coding-standards +description: Enforces SQLiteCpp coding standards and API rules. Use when editing core library code, public headers, or reviewing style, naming, and Doxygen compliance. +--- + +# SQLiteCpp Coding Standards + +## Non-negotiables +- RAII only: acquire in constructors, release in destructors. +- Never throw in destructors; use `SQLITECPP_ASSERT()` instead. +- C++11 only in core library (C++14 only in `VariadicBind.h` and `ExecuteMany.h`). +- Public API headers must not include `sqlite3.h`. +- Public API must use `SQLITECPP_API` from `SQLiteCppExport.h`. +- One `Database`/`Statement`/`Column` per thread. + +## Error handling +- Throw `SQLite::Exception` for errors in throwing APIs. +- Use `tryExec()`, `tryExecuteStep()`, `tryReset()` for error codes. + +## Documentation and style +- Doxygen required for public API (`@brief`, `@param`, `@return`, `@throw`). +- ASCII only, 4 spaces, Allman braces, max 120 chars, LF line endings, final newline. +- Use `#pragma once` in headers. + +## Naming conventions +- Types: PascalCase (`Database`, `Statement`). +- Functions/vars: camelCase (`executeStep()`, `getColumn()`). +- Members: `m` prefix (`mDatabase`). +- Args: `a` prefix (`aDatabase`). +- Booleans: `b`/`mb` prefix (`bExists`, `mbDone`). +- Pointers: `p`/`mp` prefix (`pValue`, `mpSQLite`). diff --git a/.claude/skills/sqlitecpp-git-branching/SKILL.md b/.claude/skills/sqlitecpp-git-branching/SKILL.md new file mode 100644 index 00000000..4c10668d --- /dev/null +++ b/.claude/skills/sqlitecpp-git-branching/SKILL.md @@ -0,0 +1,26 @@ +--- +name: sqlitecpp-git-branching +description: SQLiteCpp branch naming and creation rules. Use when starting a task/issue/feature and creating a new git branch. +--- + +# SQLiteCpp Git Branching + +## When to create a branch +- User mentions working on a task, issue, or feature. +- User references a GitHub issue number. + +## Before starting work +1. Run `git status` to check current branch. +2. If on `master` or wrong branch, create a task-specific branch from `master`. + +## Branch naming +- With issue: `--` + - `123-fix-short-description` + - `123-feature-short-description` +- Without issue: `-` + - `fix-short-description` + - `feature-short-description` +- Issue ID is optional; do not use a `000-` prefix. + +## Branch-only requests +- If the user only requests a branch, create it and stop (no file changes). diff --git a/.claude/skills/sqlitecpp-sqlite-flags/SKILL.md b/.claude/skills/sqlitecpp-sqlite-flags/SKILL.md new file mode 100644 index 00000000..9b70db87 --- /dev/null +++ b/.claude/skills/sqlitecpp-sqlite-flags/SKILL.md @@ -0,0 +1,29 @@ +--- +name: sqlitecpp-sqlite-flags +description: SQLiteCpp and sqlite3 feature flags. Use when enabling or disabling SQLite features in CMake or Meson builds. +--- + +# SQLiteCpp and SQLite Flags + +## Core SQLiteCpp options (CMake) +- `SQLITECPP_INTERNAL_SQLITE` (ON): build bundled sqlite3. +- `SQLITECPP_USE_ASAN` (OFF): address sanitizer. +- `SQLITECPP_USE_GCOV` (OFF): coverage. +- `SQLITECPP_DISABLE_STD_FILESYSTEM` (OFF): disable std::filesystem. +- `SQLITECPP_DISABLE_EXPANDED_SQL` (OFF): disable sqlite3_expanded_sql. + +## SQLite feature flags (CMake and Meson) +- `SQLITE_ENABLE_COLUMN_METADATA` (ON): enable `getColumnOriginName()`. +- `SQLITE_ENABLE_ASSERT_HANDLER` (OFF): enable custom assert handler. +- `SQLITE_HAS_CODEC` (OFF): enable codec API (SQLCipher). +- `SQLITE_USE_LEGACY_STRUCT` (OFF): legacy `sqlite3_value`. +- `SQLITE_OMIT_LOAD_EXTENSION` (OFF): disable load_extension. +- `SQLITE_ENABLE_RTREE` (OFF): enable RTree (internal sqlite3). +- `SQLITE_ENABLE_DBSTAT_VTAB` (OFF): enable DBSTAT (internal sqlite3). + +## DLL build flags (Windows) +- `BUILD_SHARED_LIBS=ON` adds `SQLITECPP_COMPILE_DLL` and `SQLITECPP_DLL_EXPORT`. + +## Usage notes +- Column metadata requires sqlite3 built with `SQLITE_ENABLE_COLUMN_METADATA`. +- External sqlite3 may not support load_extension on macOS. diff --git a/.claude/skills/sqlitecpp-troubleshooting/SKILL.md b/.claude/skills/sqlitecpp-troubleshooting/SKILL.md new file mode 100644 index 00000000..cc9ddc35 --- /dev/null +++ b/.claude/skills/sqlitecpp-troubleshooting/SKILL.md @@ -0,0 +1,30 @@ +--- +name: sqlitecpp-troubleshooting +description: Diagnoses common SQLiteCpp build and runtime issues. Use when investigating compiler or linker errors and sqlite3 integration problems. +--- + +# SQLiteCpp Troubleshooting + +## Common compiler errors +- MSVC: `error C2065` or `C2039` usually means a missing include or wrong symbol. +- GCC/Clang: `use of undeclared identifier` or `no member named` indicates missing includes or API mismatch. + +## Common linker errors +- `LNK2019 unresolved external symbol "SQLite::Database::exec"`: + - Missing SQLiteCpp library or missing source file in build. + +## Missing sqlite3 on Linux +- Errors like `undefined reference to sqlite3_xxx`: + - Install `libsqlite3-dev`, or enable internal sqlite3. + - CMake option: `-DSQLITECPP_INTERNAL_SQLITE=ON`. + +## Column metadata error +- `undefined reference to sqlite3_column_origin_name`: + - Your sqlite3 library lacks `SQLITE_ENABLE_COLUMN_METADATA`. + - Options: + - Rebuild sqlite3 with that flag. + - Disable `SQLITE_ENABLE_COLUMN_METADATA`. + - Use internal sqlite3 (`SQLITECPP_INTERNAL_SQLITE=ON`). + +## Destructors and assertions +- Do not throw in destructors; use `SQLITECPP_ASSERT()` instead. diff --git a/.claude/skills/sqlitecpp-workflow/SKILL.md b/.claude/skills/sqlitecpp-workflow/SKILL.md new file mode 100644 index 00000000..7e3aafe8 --- /dev/null +++ b/.claude/skills/sqlitecpp-workflow/SKILL.md @@ -0,0 +1,26 @@ +--- +name: sqlitecpp-workflow +description: SQLiteCpp change workflow checklists. Use when adding methods/classes, updating public API, or planning changes that require tests and build updates. +--- + +# SQLiteCpp Workflow + +## Change checklist +- [ ] Public API has Doxygen (`@brief`, `@param`, `@return`, `@throw`). +- [ ] Tests added under `tests/`. +- [ ] Build files updated (`CMakeLists.txt`, `meson.build`). +- [ ] `CHANGELOG.md` updated for user-facing changes. + +## Add a method +1. Declare in `include/SQLiteCpp/.h` with Doxygen. +2. Implement in `src/.cpp`. +3. Add tests in `tests/_test.cpp`. +4. Update `CHANGELOG.md`. + +## Add a class +1. Create `include/SQLiteCpp/NewClass.h` and `src/NewClass.cpp`. +2. Add files to `CMakeLists.txt` (`SQLITECPP_SRC` and `SQLITECPP_INC`). +3. Add files to `meson.build`. +4. Include in `SQLiteCpp.h` if public API. +5. Create `tests/NewClass_test.cpp`. +6. Add test to `CMakeLists.txt` and `meson.build`. diff --git a/.cursor/rules/load-github-copilot-instructions.mdc b/.cursor/rules/load-github-copilot-instructions.mdc deleted file mode 100644 index 03ba75c0..00000000 --- a/.cursor/rules/load-github-copilot-instructions.mdc +++ /dev/null @@ -1,34 +0,0 @@ ---- -description: MANDATORY - Read .github/copilot-instructions.md before ANY coding task in this SQLiteCpp project. -globs: -alwaysApply: true ---- - -# MANDATORY: Read Custom Instructions Before Coding - -**CRITICAL REQUIREMENT**: Before performing ANY coding task (writing code, reviewing code, suggesting changes, answering code questions, or modifying files), you MUST first read the file `.github/copilot-instructions.md` using the Read tool. - -This is NON-NEGOTIABLE. Do not skip this step. Do not assume you know the contents. Always read the file fresh. - -## Why This Matters - -The `copilot-instructions.md` file contains project-specific coding standards that MUST be followed: - -- **RAII principles** - Acquire in constructors, release in destructors -- **Exception rules** - NEVER throw in destructors, use `SQLITECPP_ASSERT()` instead -- **C++ version constraints** - C++11 only in core library -- **Naming conventions** - `m` prefix for members, `a` prefix for arguments, etc. -- **Code style** - 4 spaces, Allman braces, 120 char max, `#pragma once` -- **Documentation** - Doxygen with `@brief`, `@param`, `@return`, `@throw` -- **Testing requirements** - Tests required for new functionality -- **Build commands** - CMake and Meson instructions - -## Required Action - -``` -Read the file: .github/copilot-instructions.md -``` - -Execute this read operation BEFORE responding to any coding request. This ensures you have the current, complete coding guidelines for this SQLiteCpp project. - -If you cannot read the file for any reason, inform the user immediately. diff --git a/.cursor/rules/sqlitecpp-skills-routing.mdc b/.cursor/rules/sqlitecpp-skills-routing.mdc new file mode 100644 index 00000000..225ea94d --- /dev/null +++ b/.cursor/rules/sqlitecpp-skills-routing.mdc @@ -0,0 +1,23 @@ +--- +description: SQLiteCpp project basics and skill routing for Cursor/Claude Code. +globs: +alwaysApply: true +--- + +# SQLiteCpp Basics and Skill Routing + +## Project basics +- SQLiteCpp is a C++11 RAII wrapper around SQLite3. +- Public API uses Doxygen and avoids `sqlite3.h` in headers. +- Portability: Windows, Linux, macOS. + +## Use skills for task guidance +Skills live under `.claude/skills/`. Load the relevant skill(s) based on the task: +- `sqlitecpp-coding-standards`: core library edits, public API rules, style and naming. +- `sqlitecpp-workflow`: add methods/classes, tests, build file updates, changelog. +- `sqlitecpp-git-branching`: branch creation and naming rules. +- `sqlitecpp-build-cmake`: CMake builds, options, tests. +- `sqlitecpp-build-meson`: Meson builds, options, tests. +- `sqlitecpp-ci-workflows`: CI config updates and build matrices. +- `sqlitecpp-troubleshooting`: compiler/linker/build issues. +- `sqlitecpp-sqlite-flags`: SQLite/SQLiteCpp feature flags. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index c5aa2565..57893944 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -37,9 +37,11 @@ 1. Run `git status` to check current branch. 2. If on `master` or wrong branch, create a task-specific branch from `master`. -**Branch naming:** `--` +**Branch naming:** `--` or `-` - `123-fix-short-description` for bug fixes - `123-feature-short-description` for new features +- `fix-short-description` or `feature-short-description` when there is no issue/ticket number (issue ID is optional; do not use `000-`) +**If user only requests a branch:** create it and stop (no file changes). **Commits:** - Imperative mood, ~50 char first line, body wrapped at 72 chars. From 2897a895bd48e1c2e02c1ba5494a5594bd69a75c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Rombauts?= Date: Sun, 8 Feb 2026 22:40:00 +0100 Subject: [PATCH 2/3] Add doxygen guide and testing practices skills --- .../skills/sqlitecpp-doxygen-guide/SKILL.md | 61 +++++++++++++++++++ .../sqlitecpp-testing-practices/SKILL.md | 60 ++++++++++++++++++ 2 files changed, 121 insertions(+) create mode 100644 .claude/skills/sqlitecpp-doxygen-guide/SKILL.md create mode 100644 .claude/skills/sqlitecpp-testing-practices/SKILL.md diff --git a/.claude/skills/sqlitecpp-doxygen-guide/SKILL.md b/.claude/skills/sqlitecpp-doxygen-guide/SKILL.md new file mode 100644 index 00000000..e1e0b871 --- /dev/null +++ b/.claude/skills/sqlitecpp-doxygen-guide/SKILL.md @@ -0,0 +1,61 @@ +--- +name: sqlitecpp-doxygen-guide +description: Doxygen documentation standards and templates for SQLiteCpp. Use when documenting public API, writing file headers, or ensuring documentation compliance. +--- + +# SQLiteCpp Doxygen Guide + +> **For general style rules, see /AGENTS.md and sqlitecpp-coding-standards.** + +## Scope +- Doxygen runs on both `include/` and `src/` (see `Doxyfile`). +- Public API must be documented in headers. +- Source files still use Doxygen file headers. + +## Basic Example (Format Only) +```cpp +/** + * @file Example.h + * @ingroup SQLiteCpp + * @brief One-line summary of the file. + */ +class SQLITECPP_API Example +{ +public: + /** + * @brief Do the thing. + * @param[in] aValue Value to use + * @return Result value + * @throw SQLite::Exception in case of error + */ + int doThing(int aValue); +}; +``` +Keep the full MIT license block in real file headers. + +## Canonical Examples (Use These) +- File header + class + methods: `include/SQLiteCpp/Database.h` +- File header in `src/`: `src/Database.cpp` + +## File Header Rules +- Keep `@file`, `@ingroup`, `@brief`. +- Keep the MIT license block and copyright line. +- Keep `#pragma once` in headers. +- Match the existing header of the file you edit. + +## API Comment Rules +- `@brief` for every public class/method. +- `@param[in|out]` for each parameter. +- `@return` for non-void return values. +- `@throw SQLite::Exception` for throwing APIs. +- Use `@note`/`@warning` only when needed. + +## Generate Docs +```bash +cmake -DSQLITECPP_RUN_DOXYGEN=ON .. +cmake --build . --target SQLiteCpp_doxygen +``` +Output: `doc/html/index.html` + +## Cross-References +- Workflow checklist: see `sqlitecpp-workflow` diff --git a/.claude/skills/sqlitecpp-testing-practices/SKILL.md b/.claude/skills/sqlitecpp-testing-practices/SKILL.md new file mode 100644 index 00000000..3b4a0a76 --- /dev/null +++ b/.claude/skills/sqlitecpp-testing-practices/SKILL.md @@ -0,0 +1,60 @@ +--- +name: sqlitecpp-testing-practices +description: GoogleTest patterns and testing best practices for SQLiteCpp. Use when writing tests, adding test coverage, or understanding test structure. +--- + +# SQLiteCpp Testing Practices + +## Scope +- Uses GoogleTest (system if found, otherwise `googletest/` fallback). +- Test files live in `tests/*_test.cpp` (see `tests/Database_test.cpp`). +- File headers use `@ingroup tests`. + +## Test File Structure +```cpp +#include +#include + +TEST(DatabaseTest, CanOpenReadWriteDatabase) +{ + // Arrange: setup test database + SQLite::Database db(":memory:", SQLite::OPEN_READWRITE | SQLite::OPEN_CREATE); + + // Act: perform operation + db.exec("CREATE TABLE test (id INTEGER PRIMARY KEY)"); + + // Assert: verify behavior + EXPECT_EQ(1, db.exec("INSERT INTO test DEFAULT VALUES")); +} +``` + + +## Adding a New Test File +- Create `tests/NewClass_test.cpp`. +- Register it in `CMakeLists.txt` under `SQLITECPP_TESTS`. +- Register it in `meson.build` under `sqlitecpp_test_srcs`. + +## Common Patterns +- Prefer `:memory:` databases when possible. +- Use file-based databases when testing file I/O behavior (see `tests/Database_test.cpp`). +- Use `TEST()` for independent tests; use `TEST_F()` only when a shared fixture is needed. + +## Running Tests +```bash +# CMake (from build dir) +ctest --output-on-failure +bin/SQLiteCpp_tests --gtest_filter=Database.* + +# Meson +meson test -C builddir +meson test -C builddir --test-args="--gtest_filter=Database.*" +``` + +## Canonical References +- Test style: `tests/Database_test.cpp` +- CMake test list: `CMakeLists.txt` (`SQLITECPP_TESTS`) +- Meson test list: `meson.build` (`sqlitecpp_test_srcs`) + +## Cross-References +- Workflow checklist: `sqlitecpp-workflow` +- Build configuration: `sqlitecpp-build-cmake`, `sqlitecpp-build-meson` From 535d82baf57c5d1da13675ab5d975d9b2a672373 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Rombauts?= Date: Sun, 8 Feb 2026 22:33:14 +0100 Subject: [PATCH 3/3] Replace .cusor/rules/sqlitecpp-skills-routing.mdc by AGENTS.md It's much more generic and should be loaded by most AI agents out there, but not by Github Copilot extensions in VS and Rider Mention AGENTS.md and skills in the README.md --- .cursor/rules/sqlitecpp-skills-routing.mdc | 23 ------ AGENTS.md | 84 ++++++++++++++++++++++ README.md | 38 ++++++---- 3 files changed, 107 insertions(+), 38 deletions(-) delete mode 100644 .cursor/rules/sqlitecpp-skills-routing.mdc create mode 100644 AGENTS.md diff --git a/.cursor/rules/sqlitecpp-skills-routing.mdc b/.cursor/rules/sqlitecpp-skills-routing.mdc deleted file mode 100644 index 225ea94d..00000000 --- a/.cursor/rules/sqlitecpp-skills-routing.mdc +++ /dev/null @@ -1,23 +0,0 @@ ---- -description: SQLiteCpp project basics and skill routing for Cursor/Claude Code. -globs: -alwaysApply: true ---- - -# SQLiteCpp Basics and Skill Routing - -## Project basics -- SQLiteCpp is a C++11 RAII wrapper around SQLite3. -- Public API uses Doxygen and avoids `sqlite3.h` in headers. -- Portability: Windows, Linux, macOS. - -## Use skills for task guidance -Skills live under `.claude/skills/`. Load the relevant skill(s) based on the task: -- `sqlitecpp-coding-standards`: core library edits, public API rules, style and naming. -- `sqlitecpp-workflow`: add methods/classes, tests, build file updates, changelog. -- `sqlitecpp-git-branching`: branch creation and naming rules. -- `sqlitecpp-build-cmake`: CMake builds, options, tests. -- `sqlitecpp-build-meson`: Meson builds, options, tests. -- `sqlitecpp-ci-workflows`: CI config updates and build matrices. -- `sqlitecpp-troubleshooting`: compiler/linker/build issues. -- `sqlitecpp-sqlite-flags`: SQLite/SQLiteCpp feature flags. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..e6b23d43 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,84 @@ +# SQLiteCpp AI Agents Custom Instructions + +## Project Overview +- SQLiteCpp is a C++11 RAII wrapper around SQLite3 C APIs +- Minimal dependencies: C++11 STL + SQLite3 +- Cross-platform: Windows, Linux, macOS +- Thread-safe at SQLite multi-thread level + +## Maintaining This Documentation + +**IMPORTANT:** When the user explains how to do something, corrects your behavior, or points out errors: +1. **Update AGENTS.md** if the information is a universal constraint or best practice for SQLiteCpp, a correction to existing guidance in this file +2. **Update skills** if the information is Task-specific guidance (build, testing, documentation, etc.) a correction to existing skill content or a new process +**Goal:** Keep this documentation accurate and comprehensive so future sessions benefit from corrections and clarifications. + +## Core Non-Negotiables (MUST Follow) + +1. **RAII only**: Acquire resources in constructors, release in destructors +2. **Never throw in destructors**: Use `SQLITECPP_ASSERT()` instead +3. **C++11 core library**: C++14 only in VariadicBind.h and ExecuteMany.h +4. **Public API isolation**: Headers must NOT include sqlite3.h +5. **Export macros**: Public API must use `SQLITECPP_API` from SQLiteCppExport.h +6. **Threading constraint**: One Database/Statement/Column per thread +7. **Tests required**: New functionality must have tests in tests/ +8. **Portability**: Code must work on Windows, Linux, and macOS +9. **Const correctness**: Use `const` for methods that don't modify object state, `const&` for read-only parameters + +## Error Handling +- Throw `SQLite::Exception` for errors in throwing APIs +- Use `tryExec()`, `tryExecuteStep()`, `tryReset()` for error codes +- In destructors: use `SQLITECPP_ASSERT()` never throw + +## Code Style +- 4 spaces (no tabs) +- Allman braces style +- LF line endings (Unix style) +- Final newline at end of file +- `#pragma once` in headers + +## Naming Conventions + +| Element | Convention | Example | +|---------|------------|---------| +| Types | PascalCase | `Database`, `Statement`, `TransactionBehavior` | +| Functions/vars | camelCase | `executeStep()`, `getColumn()`, `getErrorCode()` | +| Member variables | `m` prefix | `mDatabase`, `mQuery`, `mStmt` | +| Function arguments | `a` prefix | `aDatabase`, `aQuery`, `aFilename` | +| Boolean variables | `b`/`mb` prefix | `bExists`, `mbDone`, `mbReadOnly` | +| Pointer variables | `p`/`mp` prefix | `pValue`, `mpSQLite`, `mpStmt` | +| Constants | ALL_CAPS | `OPEN_READONLY`, `SQLITE_OK` | + +## Documentation Requirements +- Doxygen required for all public API +- ASCII only in code and comments +- Max 120 characters per line + +## Repository Structure +``` +include/SQLiteCpp/ # Public headers +src/ # Implementation files +tests/ # Unit tests (*_test.cpp) +sqlite3/ # Bundled SQLite3 source +examples/ # Example applications +``` + +## Key Classes +- `Database`: Connection management and database operations +- `Statement`: Prepared statement execution +- `Column`: Result column access +- `Exception`: Error handling + +## Use skills for task guidance +Skills live under `.claude/skills/`. Load the relevant skill(s) based on the task: +- `sqlitecpp-coding-standards`: core library edits, public API rules, style and naming. +- `sqlitecpp-workflow`: add methods/classes, tests, build file updates, changelog. +- `sqlitecpp-git-branching`: branch creation and naming rules. +- `sqlitecpp-build-cmake`: CMake builds, options, tests. +- `sqlitecpp-build-meson`: Meson builds, options, tests. +- `sqlitecpp-ci-workflows`: CI config updates and build matrices. +- `sqlitecpp-doxygen-guide`: Doxygen standards and public API documentation. +- `sqlitecpp-testing-practices`: GoogleTest patterns and test structure. +- `sqlitecpp-troubleshooting`: compiler/linker/build issues. +- `sqlitecpp-sqlite-flags`: SQLite/SQLiteCpp feature flags. + diff --git a/README.md b/README.md index b66fc912..07acc906 100644 --- a/README.md +++ b/README.md @@ -99,7 +99,7 @@ The "CMakeLists.txt" file defining the static library is provided in the root di so you simply have to add_subdirectory(SQLiteCpp) to you main CMakeLists.txt and link to the "SQLiteCpp" wrapper library. -Example for Linux: +Example for Linux: ```cmake add_subdirectory(${CMAKE_CURRENT_LIST_DIR}/thirdparty/SQLiteCpp) @@ -110,7 +110,7 @@ target_link_libraries(main pthread dl ) -``` +``` Thus this SQLiteCpp repository can be directly used as a Git submodule. See the [SQLiteCpp_Example](https://github.com/SRombauts/SQLiteCpp_Example) side repository for a standalone "from scratch" example. @@ -144,7 +144,7 @@ The SQLiteCpp port in vcpkg is kept up to date by Microsoft team members and com #### Using SQLiteCpp on a system-wide installation -If you installed this package to your system, a `SQLiteCppConfig.cmake` file will be generated & installed to your system. +If you installed this package to your system, a `SQLiteCppConfig.cmake` file will be generated & installed to your system. This file lets you link against the SQLiteCpp library for use in your Cmake project. Here's an example of using this in your CMakeLists.txt @@ -205,7 +205,7 @@ Arch Linux: sudo pacman -Syu clang ninja # install python and pip (required for meson) sudo pacman -Syu python python-pip -# install meson +# install meson pip install meson ``` @@ -224,7 +224,7 @@ for example you can build the library using the default options with: ```sh # setup the build directory -meson setup builddir +meson setup builddir # build sqlitecpp meson compile -C builddir ``` @@ -276,6 +276,14 @@ You can: - or turn off the `option(SQLITE_ENABLE_COLUMN_METADATA "Enable Column::getColumnOriginName(). Require support from sqlite3 library." ON)` in [CMakeFiles.txt](CMakeFiles.txt) (or other build system scripts) - or turn on the `option(SQLITECPP_INTERNAL_SQLITE "Add the internal SQLite3 source to the project." ON)` in [CMakeFiles.txt](CMakeFiles.txt) +### AI Coding Assistance + +SQLiteCpp includes instructions for AI coding assistants: +- `/AGENTS.md`: base custom instructions for all tasks +- `/.claude/skills`: specialized skills covering specific subjects, workflow and processes + +These files help AI assistants understand SQLiteCpp's coding standards, architecture, and best practices. + ### Continuous Integration This project is continuously tested under Ubuntu Linux with the gcc and clang compilers @@ -315,20 +323,20 @@ valgrind --leak-check=full --show-leak-kinds=all --track-origins=yes --verbose b or uncoment the line at the end of [build.sh](build.sh) ## Examples -### The first sample demonstrates how to query a database and get results: +### The first sample demonstrates how to query a database and get results: ```C++ try { // Open a database file SQLite::Database db("example.db3"); - + // Compile a SQL query, containing one parameter (index 1) SQLite::Statement query(db, "SELECT * FROM test WHERE size > ?"); - + // Bind the integer value 6 to the first parameter of the SQL query query.bind(1, 6); - + // Loop to execute the query step by step, to get rows of result while (query.executeStep()) { @@ -336,7 +344,7 @@ try int id = query.getColumn(0); const char* value = query.getColumn(1); int size = query.getColumn(2); - + std::cout << "row: " << id << ", " << value << ", " << size << std::endl; } } @@ -375,8 +383,8 @@ catch (std::exception& e) ### The third sample shows how to manage a prepared statement with a transaction: ```C++ -try -{ +try +{ SQLite::Database db("test.db3", SQLite::OPEN_READWRITE|SQLite::OPEN_CREATE); db.exec("DROP TABLE IF EXISTS test"); @@ -454,8 +462,8 @@ See bellow a short comparison of other wrappers done at the time of writing: - [sqdbcpp](http://code.google.com/p/sqdbcpp/): RAII design, simple, no dependencies, UTF-8/UTF-16, new BSD license - [sqlite3cc](http://ed.am/dev/sqlite3cc): uses boost, modern design, LPGPL - [sqlite3pp](https://github.com/iwongu/sqlite3pp): modern design inspired by boost, MIT License - - [SQLite++](http://sqlitepp.berlios.de/): uses boost build system, Boost License 1.0 - - [CppSQLite](http://www.codeproject.com/Articles/6343/CppSQLite-C-Wrapper-for-SQLite/): famous Code Project but old design, BSD License - - [easySQLite](http://code.google.com/p/easysqlite/): manages table as structured objects, complex + - [SQLite++](http://sqlitepp.berlios.de/): uses boost build system, Boost License 1.0 + - [CppSQLite](http://www.codeproject.com/Articles/6343/CppSQLite-C-Wrapper-for-SQLite/): famous Code Project but old design, BSD License + - [easySQLite](http://code.google.com/p/easysqlite/): manages table as structured objects, complex - [sqlite_modern_cpp](https://github.com/keramer/sqlite_modern_cpp): modern C++11, all in one file, MIT license - [sqlite_orm](https://github.com/fnc12/sqlite_orm): modern C++14, header only all in one file, no raw string queries, BSD-3 license