Skip to content

AGENTS.md

Latest commit

 

History

History
215 lines (168 loc) · 12.1 KB

AGENTS.md

File metadata and controls

215 lines (168 loc) · 12.1 KB
Raw

Supercell Wx AI Agent Instructions

Supercell Wx is a cross-platform C++20/Qt6 application for visualizing live and archived NEXRAD weather radar data. This guide helps AI agents understand the codebase architecture and development workflow.

Project Architecture

Two-Library Structure

Critical: Keep Qt code isolated to scwx-qt. Never add Qt dependencies to wxdata.

Manager Pattern

Manager classes in scwx-qt/source/scwx/qt/manager/ are singletons that manage global application concerns:

  • RadarProductManager - loads/caches radar products, emits Qt signals for data updates
  • SettingsManager - persistent settings via QSettings
  • AlertManager - weather alert processing
  • PlacefileManager - external placefile integration
  • TimelineManager - time-based product selection

Managers communicate via Qt signals/slots. When data flows from wxdata → scwx-qt, it typically goes through a manager.

Background Task Processing

Background tasks use Boost thread pools and ASIO post for asynchronous operations. This includes network requests, file I/O, and data processing that shouldn't block the UI thread.

Namespace Convention

All code uses nested namespace scwx { namespace X { ... } } structure:

  • scwx::wsr88d - NEXRAD data structures
  • scwx::qt::view - Qt view classes
  • scwx::qt::manager - manager singletons Use fully qualified namespaces in headers; using namespace prohibited in headers per Google C++ Style Guide.

Build System

Conan + CMake Workflow

The project uses Conan 2 for C++ dependency management. CMake integrates Conan via cmake-conan provider.

Setup script usage (recommended path for new developers):

# Windows (from repo root)
.\tools\setup-windows-vs2026-x64-release.bat [BUILD_DIR] [VENV_PATH]

# Linux
./tools/setup-linux-ninja-release.sh [BUILD_DIR] [CONAN_PROFILE] [VENV_PATH] [ASAN_ENABLE]

Manual CMake configuration:

# 1. Install Conan profile
conan config install ./tools/conan/profiles/scwx-windows_vs2026_x64 -tf profiles

# 2. Install dependencies
mkdir build && cd build
conan install ../
  --remote conancenter
  --build missing
  --profile:all scwx-windows_vs2026_x64
  --settings:all build_type=Release
  --output-folder ./conan/

# 3. Configure CMake (Conan provider auto-installs deps if conan/ exists)
cmake ../ -G Ninja
  -DCMAKE_BUILD_TYPE=Release
  -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=../external/cmake-conan/conan_provider.cmake
  -DCONAN_HOST_PROFILE=scwx-windows_vs2026_x64
  -DCONAN_BUILD_PROFILE=scwx-windows_vs2026_x64

# 4. Build
cmake --build . --target supercell-wx

Key Conan profiles: See tools/conan/profiles/

  • Windows: scwx-windows_vs2026_x64[-debug]
  • Linux: scwx-linux_gcc-11[-debug], scwx-linux_clang-17
  • macOS: scwx-macos_clang-18[_armv8][-debug]

CMake Presets: Use CMakePresets.json for IDE integration. Presets like windows-vs2026-x64-release encapsulate toolchain/profile selection.

Python Virtual Environment

Project uses Python for code generation (counties DB, version info). Setup scripts create .venv/ with requirements from requirements.txt. CMake macro scwx_python_setup() in tools/scwx_config.cmake finds the venv Python.

Build Outputs

Per tools/scwx_config.cmake, binaries go to:

  • build/<preset>/<BuildType>/bin/supercell-wx[.exe]
  • build/<preset>/<BuildType>/lib/ for shared libraries

External Dependencies

Vendored vs Conan

  • Conan-managed (conanfile.py): Boost, Qt (via system), GEOS, libcurl, OpenSSL, spdlog, SQLite, etc.
  • Git submodules (external/): MapLibre Native Qt, ImGui, stb, units library
    • Use submodules when heavy customization or unreleased versions needed
    • MapLibre is vendored because Qt bindings require custom build

Qt 6.12.0 Requirement

Qt must be installed separately (not via Conan). Install via Qt online installer or aqtinstall:

aqt install-qt windows desktop 6.12.0 win64_msvc2022_64 -m qtimageformats qtmultimedia qtpositioning qtserialport

Qt version compatibility: patch releases interchangeable (6.12.x), minor versions may break.

Testing

Google Test Framework

Tests in test/ use GTest (from Conan). Run via CMake:

cmake --build . --target wxtest
ctest --output-on-failure

Test files follow *.test.cpp naming. Example from test/source/scwx/wsr88d/nexrad_file_factory.test.cpp:

TEST(NexradFileFactory, Level2V06) {
   std::string filename = std::string(SCWX_TEST_DATA_DIR) + "/data/KLSX20240909_175655_V06";
   // ...
}

Test data stored in test/data/. SCWX_TEST_DATA_DIR macro defined during CMake configuration.

Code Style & Conventions

Formatting

Pimpl Idiom

Many classes use Pimpl (Pointer to Implementation):

// Header
class MyClass {
   class Impl;
   std::unique_ptr<Impl> p;
};

// Source
class MyClass::Impl { /* private state */ };

Reduces recompilation and hides implementation details.

Prohibited Patterns

  • No using namespace in headers
  • No GPL-licensed dependencies (LGPL only if in shared libraries)
  • Avoid Qt includes in wxdata/ headers

Qt Signal/Slot Usage

Critical: Always use Q_EMIT instead of the Qt emit keyword due to a dependency conflict. Example:

Q_EMIT DataReloaded();  // Correct
emit DataReloaded();    // Incorrect - will cause build issues

Qt Designer / .ui Files

Define widgets, layouts, and static properties (labels, ranges, tooltips, suffixes, size policies) in .ui files so they remain editable in Qt Designer. Use C++ for behavior only: signal/slot connections, dynamic enablement, and runtime state. Promote custom widgets in the .ui file (<customwidgets>) rather than constructing them in code. When a dialog already has a .ui file, add new static UI there instead of new QWidget(...) in the .cpp.

Common Tasks

Adding New Radar Product Support

  1. Define product message structure:
    • For NWS Level 3 Product ICD products: use wxdata/include/scwx/wsr88d/rpg/
    • For other product types (custom, experimental, non-ICD): create new directory/namespace under wxdata/include/scwx/
  2. Register in appropriate product factory (e.g., wxdata/source/scwx/wsr88d/rpg/ for Level 3 ICD products)
  3. Create view class in scwx-qt/source/scwx/qt/view/
  4. Wire to RadarProductManager for data loading
  5. Add layer in scwx-qt/source/scwx/qt/map/ for rendering

Updating Dependencies

Modify conanfile.py requires tuple, then re-run Conan install. For Conan profile changes, edit tools/conan/profiles/.

Cross-Platform Considerations

  • Windows uses Schannel for SSL; Linux/macOS use OpenSSL (see conanfile.py configure())
  • Linux requires X11/Wayland libraries (listed in README.md)
  • macOS deployment target 12.0 (set in CMakeLists.txt)

Debugging & Development

Visual Studio Code Setup

Recommended extensions: C/C++ Extension Pack, clangd, CMake Tools, Python. Windows-specific: Launch from x64 Native Tools Command Prompt for VS 2026 or configure shortcut (see developer-setup.rst).

Address Sanitizer

Enable with -DSCWX_ADDRESS_SANITIZER=ON or use presets like linux-gcc-debug-asan. Useful for memory leak/corruption detection.

CI Reference

See .github/workflows/ci.yml for complete build matrix. Mirrors setup scripts but includes AppImage packaging, artifact collection.

Resources

Cursor Cloud specific instructions

The Linux dev environment (Ubuntu 24.04) is refreshed by ./tools/setup-cursor-cloud.sh. Recurring environment builds start from a clean Ubuntu image (not the previous snapshot), so install must provision missing packages itself: python3-venv / python3.12-venv, ninja-build, GCC as cc/c++, and Qt 6.12.0 under /opt/Qt. After that it runs git submodule update --init --recursive and ./tools/setup-linux-ninja-release.sh (venv, Conan, CMake into build-release/). Notes that are not obvious:

  • python3-venv: Cursor's default Ubuntu image does not include ensurepip. python3 -m venv .venv fails without python3.12-venv, and the old setup scripts kept going (conan: command not found, then CMake could not find Ninja).
  • Compiler gotcha: The base image's default cc/c++ alternatives point at Clang, and Clang fails the project's compiler check with cannot find -lstdc++. The project builds with GCC 13, so install sets CC/CXX to gcc-13/g++-13 and update-alternatives to gcc. Don't switch them back to Clang.
  • Qt: Qt 6.12.0 lives at /opt/Qt/6.12.0/gcc_64 (installed via aqt when missing). The setup script already points CMake at it.
  • PATH: If the venv is not active, conan from a --user pip install lives in ~/.local/bin. Setup scripts prepend that directory to PATH.
  • Build: source .venv/bin/activate, then cmake --build build-release --target supercell-wx wxtest (or cd build-release && ninja supercell-wx wxtest). Binaries land in build-release/Release/bin/. The first full build is long (~1300 targets, includes vendored MapLibre).
  • Test: cd build-release && ctest --output-on-failure --exclude-regex "test_mln.*|NtpClient.*|UpdateManager.*" (same exclusions as CI; those tests need network and/or a map API key). Running tests writes into the test/data submodule (e.g. json/settings/*.json) — git checkout those before committing.
  • Running the GUI: Display :1 is a TigerVNC desktop (also used by computer-use) with software OpenGL 4.5 (llvmpipe), which is sufficient. Launch with DISPLAY=:1 build-release/Release/bin/supercell-wx. Headless test/launch also works via xvfb-run -a -s "-screen 0 1920x1080x24" ....
  • Map API key: MAPTILER_API_KEY and MAPBOX_API_KEY are provided as Cloud secrets (injected as env vars). The wxtest MapProviderTest reads them from the environment automatically. The GUI, however, reads the key from its settings file (~/.local/share/Supercell Wx/settings.json, keys maptiler_api_key/mapbox_api_key), not from the environment — enter it in the first-run wizard or write it into that file (then restart) to get a real base map. Without a key the base map renders black, but radar data (reflectivity/velocity from AWS NEXRAD) still downloads and renders normally.
  • Network: Outbound access to AWS S3 (NEXRAD data), NWS, and IEM APIs works from the VM.