Thank you for your interest in contributing to Draconis++! This document provides guidelines and information to help you get started.

• Getting Started
• Architecture Overview
• Custom Type System
• Platform-Specific Implementation Guide
• Code Style Guidelines
• Submitting Changes

• C++26 compiler (Clang 17+, GCC 13+, or MSVC 19.36+)
• Meson (1.1+) and Ninja
• just (optional, for simplified commands)

# Using just (recommended)
just setup    # Configure the build
just build    # Build the project
just test     # Run tests
just run      # Build and run

# Using Meson directly
meson setup build
meson compile -C build
meson test -C build

Key build options can be set via meson configure:

Headers exposed to consumers of the library. These define the stable interface.

• Core/: System data structures (System.hpp, Package.hpp)
• Services/: Service interfaces for external data (weather, packages)
• Utils/: Type aliases, error handling, macros

The core library containing all platform-agnostic and platform-specific code.

• Core/: Cross-platform implementations
• OS/: Platform-specific code (Windows, Linux, macOS, BSD, etc.)
• Services/: External service integrations
• Wrappers/: Thin wrappers around third-party libraries

The user-facing application that consumes the library.

• Config/: TOML configuration parsing and management
• Core/: SystemInfo class that aggregates all system data
• UI/: Terminal output formatting and theming

Draconis++ uses custom type aliases defined in include/Drac++/Utils/Types.hpp to improve code readability and express intent more clearly.

1. Consistency: Uniform naming across the codebase
2. Expressiveness: Types like Option<T> and Result<T> convey meaning
3. Safety: Wrapper types prevent common errors
4. Rust-like ergonomics: Familiar patterns for developers from other languages

// Create an Option with a value
Option<int> x = Some(42);

// Create an empty Option
Option<int> y = None;

// Return success from a function returning Result
return Result<String>{"success"};

// Return error from a function returning Result
return Err(DracError("something went wrong"));

1. Always use custom types in new code
2. Import types in .cpp files using:

   using namespace draconis::utils::types;

3. Avoid using namespace in header files — use fully qualified names
4. Prefer Result<T> over exceptions for error handling

Platform-specific code lives in src/Lib/OS/. Each platform has its own implementation file.

1. Check for existing abstraction in include/Drac++/Core/
2. Implement the function in the appropriate OS/*.cpp file
3. Use preprocessor guards when necessary:

#ifdef __linux__
// Linux-specific implementation
#elifdef _WIN32
// Windows-specific implementation
#elifdef __APPLE__
// macOS-specific implementation
#endif

The build system defines these macros:

1. Declare in header (include/Drac++/Core/System.hpp):

   namespace draconis::core {
     auto GetBatteryLevel() -> Result<u8>;
   }

2. Implement per-platform (src/Lib/OS/Windows.cpp):

   namespace draconis::core {
     auto GetBatteryLevel() -> Result<u8> {
       SYSTEM_POWER_STATUS status;
       if (!GetSystemPowerStatus(&status))
         return Err(DracError("Failed to get power status"));
       return status.BatteryLifePercent;
     }
   }

3. Implement for other platforms or provide a fallback:

   // Linux.cpp
   auto GetBatteryLevel() -> Result<u8> {
     // Read from /sys/class/power_supply/...
   }

• Use WString for Windows API calls requiring wchar_t*
• Convert with ConvertWStringToUTF8() / ConvertUTF8ToWString()
• Link against: dwmapi, windowsapp, setupapi, dxgi

• Objective-C++ code goes in src/Lib/OS/macOS/
• Use .mm extension for Objective-C++ files
• Link frameworks via appleframeworks dependency

• Optional dependencies: xcb, wayland-client, dbus-1, pugixml
• Check feature flags: DRAC_USE_XCB, DRAC_USE_WAYLAND
• Read system info from /proc/, /sys/, /etc/

• C++26 standard
• 2-space indentation (configured in .clang-format)
• constexpr/consteval where possible
• noexcept for non-throwing functions
• [[nodiscard]] for functions whose return value matters

// Use trailing return type with 'fn' macro (defined as 'auto')
fn GetSystemName() -> Result<String>;

// Mark pure functions as [[nodiscard]]
[[nodiscard]] fn CalculateHash(StringView input) -> u64;

// Use noexcept when appropriate
fn SafeOperation() noexcept -> bool;

// Prefer Result<T> over exceptions
fn ReadFile(StringView path) -> Result<String> {
  std::ifstream file(path);
  if (!file)
    return Err(DracError("Failed to open file"));
  // ...
  return content;
}

// Propagate errors explicitly
fn ProcessData() -> Result<Data> {
  auto content = ReadFile("config.toml");
  if (!content)
    return Err(content.error());
  // Process content...
}

1. Fork the repository
2. Create a branch for your feature/fix
3. Make changes following the style guidelines
4. Test your changes: just test
5. Format code: just format
6. Submit a pull request

Use Conventional Commits:

feat: add battery level monitoring
fix: correct memory leak in cache manager
docs: update contributing guide
refactor: simplify OS detection logic
perf: optimize string conversion on Windows

• Descriptive title summarizing the change
• Reference issues if applicable (Fixes #123)
• Include tests for new functionality
• Update documentation if adding public API
• Keep changes focused — one feature/fix per PR

If you have questions or need help, feel free to open an issue or discussion on the repository.

Thank you for contributing to Draconis++!