146 lines
4.6 KiB
Markdown
146 lines
4.6 KiB
Markdown
# Cloud Point RPC Agent Guide
|
|
|
|
This repository contains a C++20 implementation of a JSON RPC protocol for communicating with a Unity Scene.
|
|
Agents working on this codebase must adhere to the following guidelines and conventions.
|
|
|
|
## 1. Build, Lint, and Test
|
|
|
|
The project uses the **Meson** build system.
|
|
|
|
### Build Commands
|
|
- **Setup Build Directory:**
|
|
```bash
|
|
meson setup build
|
|
```
|
|
- **Compile:**
|
|
```bash
|
|
meson compile -C build
|
|
```
|
|
- **Clean:**
|
|
```bash
|
|
meson compile --clean -C build
|
|
```
|
|
|
|
### Testing
|
|
- **Run All Tests:**
|
|
```bash
|
|
meson test -C build
|
|
```
|
|
- **Run Specific Test:**
|
|
To run a single test suite or case, use the test name defined in `meson.build`:
|
|
```bash
|
|
meson test -C build <test_name>
|
|
```
|
|
*Example: `meson test -C build unit_tests`*
|
|
|
|
- **Verbose Output:**
|
|
```bash
|
|
meson test -C build -v
|
|
```
|
|
|
|
### Linting & Formatting
|
|
- **Format Code:**
|
|
Use `clang-format` with the project's configuration (assumed Google style if not present).
|
|
```bash
|
|
ninja -C build clang-format
|
|
# OR manual execution
|
|
find src include tests -name "*.cpp" -o -name "*.hpp" | xargs clang-format -i
|
|
```
|
|
- **Static Analysis:**
|
|
If configured, run clang-tidy:
|
|
```bash
|
|
ninja -C build clang-tidy
|
|
```
|
|
|
|
## 2. Code Style & Conventions
|
|
|
|
Adhere strictly to **Modern C++20** standards.
|
|
|
|
### General Guidelines
|
|
- **Standard:** C++20. Use concepts, ranges, and smart pointers. Avoid raw `new`/`delete`.
|
|
- **Memory Management:** Use `std::unique_ptr` and `std::shared_ptr`.
|
|
- **Const Correctness:** Use `const` (and `constexpr`/`consteval`) whenever possible.
|
|
- **Includes:** Use absolute paths for project headers (e.g., `#include "rpc/server.hpp"`).
|
|
- **Auto:** Use `auto` when the type is obvious from the right-hand side or is a complex template type.
|
|
|
|
### Naming Conventions
|
|
- **Files:** `snake_case.cpp`, `snake_case.hpp`.
|
|
- **Classes/Structs:** `PascalCase`.
|
|
- **Functions/Methods:** `snake_case` (or `camelCase` if adhering strictly to a specific external library style, but default to snake_case).
|
|
- **Variables:** `snake_case`.
|
|
- **Private Members:** `snake_case_` (trailing underscore).
|
|
- **Constants:** `kPascalCase` or `ALL_CAPS` for macros (avoid macros).
|
|
- **Namespaces:** `snake_case`.
|
|
- **Interfaces:** `IPascalCase` (optional, but consistent if used).
|
|
|
|
### Project Structure
|
|
- `include/cloud_point_rpc/`: Public header files.
|
|
- `src/`: Implementation files.
|
|
- `tests/`: Unit and integration tests.
|
|
- `subprojects/`: Meson wrap files for dependencies.
|
|
- `meson.build`: Build configuration.
|
|
|
|
### Error Handling
|
|
- Use **Exceptions** (`std::runtime_error`, `std::invalid_argument`) for invariant violations and logical errors.
|
|
- Use **`std::optional`** or **`std::expected`** for recoverable runtime errors.
|
|
- **JSON RPC Errors:** Ensure all RPC handlers catch exceptions and return valid JSON-RPC error objects containing `code`, `message`, and `data`.
|
|
|
|
### Documentation
|
|
- Use **Doxygen** style comments for public APIs.
|
|
- Document thread safety guarantees.
|
|
|
|
### Example Class
|
|
|
|
```cpp
|
|
namespace cloud_point_rpc {
|
|
|
|
/// @brief Manages camera parameters.
|
|
class CameraController {
|
|
public:
|
|
struct Config {
|
|
int width;
|
|
int height;
|
|
};
|
|
|
|
explicit CameraController(const Config& config);
|
|
|
|
/// @brief Retrieves current intrinsic parameters.
|
|
/// @return A 3x3 matrix.
|
|
[[nodiscard]] std::vector<double> get_intrinsic_params() const;
|
|
|
|
private:
|
|
Config config_;
|
|
mutable std::mutex mutex_;
|
|
std::vector<double> cached_intrinsics_;
|
|
};
|
|
|
|
} // namespace cloud_point_rpc
|
|
```
|
|
|
|
### Implementation Details
|
|
- **JSON Library:** Use `nlohmann/json` (likely via `subprojects/nlohmann_json.wrap`).
|
|
- **Concurrency:** Use `std::jthread` (auto-joining) over `std::thread`.
|
|
- **RPC Methods:**
|
|
- Implement handlers for: `get-cloud-point`, `get-intrinsic-params`, `get-extrinsic-params`.
|
|
- Ensure thread safety if the RPC server is multi-threaded.
|
|
|
|
## 3. Workflow & Git
|
|
|
|
### Commit Messages
|
|
- Use conventional commits format: `<type>(<scope>): <subject>`
|
|
- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`.
|
|
- Example: `feat(rpc): add handler for get-cloud-point`
|
|
|
|
### Pull Requests
|
|
- Ensure `meson test -C build` passes before requesting review.
|
|
- Keep PRs small and focused on a single logical change.
|
|
|
|
## 4. Cursor & Copilot Rules
|
|
|
|
*(No specific rules found in .cursor/rules/ or .github/copilot-instructions.md.)*
|
|
|
|
- **Context:** Always read related header files before modifying source files.
|
|
- **Verification:** Write unit tests for new features in `tests/`.
|
|
- **Refactoring:** When refactoring, ensure existing behavior is preserved via tests.
|
|
- **Dependencies:** Do not introduce new dependencies without updating `meson.build` and `subprojects/`.
|