LEDMatrix/docs/DEVELOPMENT.md

# Development Guide

This guide provides information for developers and contributors working on the LEDMatrix project.

## Git Submodules

### rpi-rgb-led-matrix-master Submodule

The `rpi-rgb-led-matrix-master` submodule is a foundational dependency located at the repository root (not in `plugins/`). This submodule provides the core hardware abstraction layer for controlling RGB LED matrices via the Raspberry Pi GPIO pins.

#### Architectural Rationale

**Why at the root?**
- **Core Dependency**: Unlike plugins in the `plugins/` directory, `rpi-rgb-led-matrix-master` is a foundational library required by the core LEDMatrix system, not an optional plugin
- **System-Level Integration**: The `rgbmatrix` Python module (built from this submodule) is imported by `src/display_manager.py`, which is part of the core display system
- **Build Requirements**: The submodule must be compiled to create the `rgbmatrix` Python bindings before the system can run
- **Separation of Concerns**: Keeping core dependencies at the root level separates them from user-installable plugins, maintaining a clear architectural distinction

**Why not in `plugins/`?**
- Plugins are optional, user-installable modules that depend on the core system
- `rpi-rgb-led-matrix-master` is a required build dependency, not an optional plugin
- The core system cannot function without this dependency

#### Initializing the Submodule

When cloning the repository, you must initialize the submodule:

**First-time clone (recommended):**
```bash
git clone --recurse-submodules https://github.com/ChuckBuilds/LEDMatrix.git
cd LEDMatrix
```

**If you already cloned without submodules:**
```bash
git submodule update --init --recursive
```

**To initialize only the rpi-rgb-led-matrix-master submodule:**
```bash
git submodule update --init --recursive rpi-rgb-led-matrix-master
```

#### Building the Submodule

After initializing the submodule, build and install the `rgbmatrix` Python
package from the submodule root. Upstream's `pyproject.toml` builds it with
scikit-build-core, CMake and Ninja; there is no separate `make` step:

```bash
cd rpi-rgb-led-matrix-master
python3 -m pip install --break-system-packages .
```

On a board with 1 GB of RAM or less, cap the compile so it doesn't run out of
memory: `CMAKE_BUILD_PARALLEL_LEVEL=1 python3 -m pip install --break-system-packages .`

**Note:** The `first_time_install.sh` script automates this process during
installation, including the parallelism cap and a temporary swapfile on
low-memory boards.

#### Troubleshooting

**Submodule appears empty:**
If the `rpi-rgb-led-matrix-master` directory exists but is empty or lacks a `Makefile`:
```bash
# Remove the empty directory
rm -rf rpi-rgb-led-matrix-master

# Re-initialize the submodule
git submodule update --init --recursive rpi-rgb-led-matrix-master
```

**Build fails:**
Ensure you have the required build dependencies installed:
```bash
sudo apt install -y build-essential python-dev-is-python3 cmake ninja-build
```

**Import error for `rgbmatrix` module:**
- Verify the submodule is initialized: `ls rpi-rgb-led-matrix-master/Makefile`
- Ensure the Python bindings are built and installed (see "Building the Submodule" above)
- Check that the module is installed: `python3 -c "from rgbmatrix import RGBMatrix; print('OK')"`

**Submodule out of sync:**
If the submodule commit doesn't match what the main repository expects:
```bash
git submodule update --remote rpi-rgb-led-matrix-master
```

#### CI/CD Configuration

When setting up CI/CD pipelines, ensure submodules are initialized before building:

**GitHub Actions Example:**
```yaml
- name: Checkout repository
  uses: actions/checkout@v3
  with:
    submodules: recursive

- name: Build rpi-rgb-led-matrix
  run: |
    cd rpi-rgb-led-matrix-master
    pip install .
```

**GitLab CI Example:**
```yaml
variables:
  GIT_SUBMODULE_STRATEGY: recursive

build:
  script:
    - cd rpi-rgb-led-matrix-master
    - pip install .
```

**Jenkins Example:**
```groovy
stage('Checkout') {
    checkout([
        $class: 'GitSCM',
        branches: [[name: '*/main']],
        doGenerateSubmoduleConfigurations: false,
        extensions: [[$class: 'SubmoduleOption',
                      disableSubmodules: false,
                      parentCredentials: true,
                      recursiveSubmodules: true,
                      reference: '',
                      trackingSubmodules: false]],
        userRemoteConfigs: [[url: 'https://github.com/ChuckBuilds/LEDMatrix.git']]
    ])
}
```

**General CI/CD Checklist:**
- ✓ Use `--recurse-submodules` flag when cloning (or equivalent in your CI system)
- ✓ Initialize submodules before any build steps
- ✓ Build the Python bindings if your tests require the `rgbmatrix` module
- ✓ Note: Emulator mode (using `RGBMatrixEmulator`) doesn't require the submodule to be built

---

## Plugins

Plugins are **not** git submodules of this repository. The plugins
directory (configured by `plugin_system.plugins_directory` in
`config/config.json`, default `plugin-repos/`) is populated at install
time by the plugin loader as users install plugins from the Plugin Store
or from a GitHub URL via the web interface. Plugin source lives in a
separate repository:
[ChuckBuilds/ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins).

To work on a plugin locally without going through the Plugin Store, clone
that repo and symlink (or copy) the plugin directory into your configured
plugins directory — by default `plugin-repos/<plugin-id>/`. The plugin
loader will pick it up on the next display restart. The directory name
must match the plugin's `id` in `manifest.json`.

For more information, see:

- [PLUGIN_DEVELOPMENT_GUIDE.md](PLUGIN_DEVELOPMENT_GUIDE.md) — end-to-end
  plugin development workflow
- [PLUGIN_ARCHITECTURE_SPEC.md](PLUGIN_ARCHITECTURE_SPEC.md) — plugin system
  specification
- [DEV_PREVIEW.md](DEV_PREVIEW.md) — preview plugins on a desktop without a
  Pi