===============================================================================
 THE NUMBRELLA PROJECT — Developer Walkthrough
===============================================================================

 Copyright (C) 2026 Sixten Björling
 All rights reserved.

 This document explains how to set up, build, and contribute to the Numbrella
 ecosystem using Python, C/C++ (Clang, Clang++), and Go.

===============================================================================
 TABLE OF CONTENTS
===============================================================================
 1.  Prerequisites
 2.  Cloning & First-Time Setup
 3.  Project Layout
 4.  Building (C / C++)
 5.  Working with Go
 6.  Working with Python
 7.  Adding a New Library
 8.  Adding a New Application
 9.  Adding a New Tool
10.  Coding Conventions
11.  Troubleshooting
12.  Quick Reference

===============================================================================
 1. PREREQUISITES
===============================================================================

    Required:
      • CMake          ≥ 3.20
      • Clang / Clang++ (any version supporting C17 / C++20)
      • Ninja          (or Make, but Ninja is recommended)
      • Go             ≥ 1.21
      • Python         ≥ 3.10
      • Git            (with submodule support)

    Optional but recommended:
      • ccache         (speeds up recompilation)
      • clang-format   (consistent code style)
      • clang-tidy     (static analysis)

    Platform support:
      • Windows   (MSVC or Clang-cl; Ninja is strongly preferred)
      • macOS     (Clang via Xcode CLT)
      • Linux     (Clang via system package manager)

===============================================================================
 2. CLONING & FIRST-TIME SETUP
===============================================================================

    # Clone with submodules
    git clone --recurse-submodules <repo-url> Numbrella
    cd Numbrella

    # If you already cloned without --recurse-submodules:
    git submodule update --init --recursive

    # Verify everything is in place:
    ls Libraries/   # Should show FilesLib, PathsLib, MathsLib, etc.
    ls Foreign/     # Should show SDL, SDL_image, SDL_ttf, SDL_mixer, fonts
    ls Software/    # Should show AuthSide, DevIO, NetBud, etc.

===============================================================================
 3. PROJECT LAYOUT
===============================================================================

    Numbrella/
    ├── CMakeLists.txt          ← Root build definition
    ├── cmake/                  ← CMake modules
    │   ├── Foreign.cmake       ← SDL3 submodule inclusion
    │   ├── Libraries.cmake     ← Auto-discovers Libraries/
    │   └── Project.cmake       ← Auto-discovers Software/ & Tools/
    ├── Libraries/              ← Static libraries (C / C++)
    │   ├── FilesLib/
    │   ├── PathsLib/
    │   ├── MathsLib/
    │   ├── MidsLib/
    │   ├── NetsLib/
    │   └── LangsLib/           ← Language bindings (C/, Go/, Python/)
    ├── Software/               ← Application executables
    │   ├── AuthSide/
    │   ├── DevIO/
    │   ├── FileSync/
    │   ├── InterLingo/
    │   ├── Kompis/
    │   ├── NetBud/
    │   ├── NuCLI/
    │   └── Nudel/
    ├── Tools/                  ← Utility executables
    ├── Foreign/                ← Git submodules (SDL3, fonts)
    ├── Assets/                 ← Audio, Graphic, Shaders
    ├── Development/            ← Out-of-source build tree (gitignored)
    ├── Documentation/          ← You are here
    ├── Rules/                  ← Project rules & allowed tech
    └── Project/                ← Planning & tracking documents

===============================================================================
 4. BUILDING (C / C++)
===============================================================================

    The project uses out-of-source builds inside the Development/ directory.
    All build artifacts stay there; compiled binaries are exported back to
    their respective source directories.

    ---- Configure (do this once) ----
    cd Development
    cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Debug

    # Release build:
    cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Release

    # Use ccache (faster rebuilds):
    cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Debug \
      -DCMAKE_C_COMPILER_LAUNCHER=ccache \
      -DCMAKE_CXX_COMPILER_LAUNCHER=ccache

    ---- Build everything ----
    cmake --build .

    # Or build a single target:
    cmake --build . --target FilesLib
    cmake --build . --target AuthSide
    cmake --build . --target NetBud

    ---- Output locations ----
    Static libraries:  Libraries/<name>/lib<name>.a
    Applications:      Software/<name>/<name>[.exe]
    Tools:             Tools/<name>/<name>[.exe]

    ---- Clean ----
    cmake --build . --target clean
    # Or nuke everything:
    rm -rf Development/*

===============================================================================
 5. WORKING WITH GO
===============================================================================

    Go modules inside the project are self-contained. They import Numbrella
    C libraries via cgo when needed.

    ---- Initialize a new Go module inside a Software/ or Tools/ directory ----
    cd Software/MyService
    go mod init numbrella/myservice

    ---- Build ----
    go build -o MyService .
    # Or for a binary placed in the project root toolchain:
    go build -o ../../Software/MyService/MyService .

    ---- Using cgo to call Numbrella C libraries ----
    /*
    #cgo CFLAGS: -I${SRCDIR}/../../Libraries
    #cgo LDFLAGS: -L${SRCDIR}/../../Libraries/FilesLib -lFilesLib
    #include "FilesLib/some_header.h"
    */
    import "C"

    ---- Recommended Go layout inside a Software/ directory ----
    Software/MyService/
    ├── main.go
    ├── go.mod
    ├── go.sum
    ├── internal/        ← Private packages
    └── cmd/             ← Sub-commands (if CLI)

    ---- Testing ----
    go test ./...

===============================================================================
 6. WORKING WITH PYTHON
===============================================================================

    Python scripts live alongside other source or inside Tools/.
    No virtual environment is enforced, but using one is recommended
    for isolation.

    ---- Quick script layout ----
    Tools/MyTool/
    ├── __init__.py
    ├── __main__.py       ← Entry point (python -m MyTool)
    ├── mytool.py
    └── requirements.txt  ← Dependencies (if any)

    ---- Running a Python tool ----
    cd Tools/MyTool
    python -m MyTool

    # Or directly:
    python mytool.py

    ---- Calling Numbrella binaries from Python ----
    Use subprocess to invoke compiled C/Go executables:

    import subprocess
    result = subprocess.run(
        ["../../Software/SomeService/SomeService", "--flag"],
        capture_output=True, text=True
    )

    ---- LangsLib Python bindings ----
    Libraries/LangsLib/Python/ contains shared Python utilities.
    Add the Libraries path to PYTHONPATH when using them:

    export PYTHONPATH="${PYTHONPATH}:$(pwd)/Libraries"
    python -m LangsLib.Python.some_module

===============================================================================
 7. ADDING A NEW LIBRARY
===============================================================================

    C/C++ static libraries are auto-discovered. Just create the directory.

    mkdir Libraries/MyNewLib
    # Add your .cpp, .c, and .h files inside.
    # The build system picks them up automatically on next configure.

    Libraries/MyNewLib/
    ├── MyNewLib.h
    ├── MyNewLib.cpp
    └── internal/
        └── helpers.h

    # Re-configure to register the new target:
    cd Development
    cmake ..

    # Build just your library:
    cmake --build . --target MyNewLib

    The library target name = directory name (MyNewLib).
    Other targets can use #include "MyNewLib/MyNewLib.h" via the
    global Libraries/ include path.

===============================================================================
 8. ADDING A NEW APPLICATION
===============================================================================

    Applications live under Software/. Same auto-discovery principle.

    mkdir Software/MyApp
    # Add sources (.cpp, .c, .h).

    Software/MyApp/
    ├── main.cpp
    ├── App.h
    └── App.cpp

    # Re-configure and build:
    cd Development
    cmake ..
    cmake --build . --target MyApp

    # Run:
    ../Software/MyApp/MyApp

    Every Software/ application automatically links against:
      • All Numbrella libraries
      • SDL3, SDL3_image, SDL3_ttf, SDL3_mixer

===============================================================================
 9. ADDING A NEW TOOL
===============================================================================

    Tools follow the same pattern as Software/. The only difference is
    the output directory (Tools/ instead of Software/).

    mkdir Tools/MyTool
    # Add sources.

    cd Development
    cmake ..
    cmake --build . --target MyTool

    # Run:
    ../Tools/MyTool/MyTool

===============================================================================
10. CODING CONVENTIONS
===============================================================================

    ---- C / C++ ----
    • Standard:  C17 & C++20
    • Compiler:  Clang / Clang++
    • Style:     Keep it clean; prefer readability over cleverness.
    • Headers:   Use #pragma once.
    • Warnings:  -Wall -Wextra -Wpedantic (treat warnings as errors in CI).
    • Naming:    PascalCase for types, camelCase for functions/variables.
    • Includes:  Use quotes for project headers, angle brackets for system.

    ---- Go ----
    • Standard:  Latest stable Go.
    • Style:     gofmt (mandatory).
    • Linting:   golangci-lint.
    • Modules:   One go.mod per Software/ subdirectory.
    • Naming:    Standard Go conventions (MixedCaps, not underscores).

    ---- Python ----
    • Standard:  Python ≥ 3.10.
    • Style:     PEP 8.
    • Formatting: black or ruff.
    • Typing:    Use type hints everywhere.
    • Docstrings: Google or NumPy style.

    ---- General ----
    • Cross-platform code only (no platform-specific #ifdefs unless necessary).
    • Prefer standard libraries over third-party dependencies.
    • Document public APIs.
    • Write tests.

===============================================================================
11. TROUBLESHOOTING
===============================================================================

    Q: "CMake can't find SDL3"
    A: Did you clone with --recurse-submodules? Run:
       git submodule update --init --recursive

    Q: "No targets found in Libraries/"
    A: The directories exist but are empty. Add source files.

    Q: "My new directory is not picked up"
    A: After creating the directory, re-run cmake .. inside Development/.

    Q: "compile_commands.json is missing"
    A: Set CMAKE_EXPORT_COMPILE_COMMANDS=ON (it is on by default).
       Check Development/compile_commands.json. Symlink it to root:
       ln -s Development/compile_commands.json .

    Q: "clangd doesn't recognize my headers"
    A: Ensure compile_commands.json is symlinked to the project root.

    Q: "Build is slow"
    A: Install ccache and pass the launcher flags shown in Section 4.
       Also, build only the target you need: cmake --build . --target MyApp

===============================================================================
12. QUICK REFERENCE
===============================================================================

    Clone:
      git clone --recurse-submodules <url> && cd Numbrella

    Configure:
      cd Development
      cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Debug

    Build all:
      cmake --build .

    Build one target:
      cmake --build . --target <Name>

    Re-configure (pick up new directories):
      cmake ..

    Clean:
      rm -rf Development/*

    Add a library:
      mkdir Libraries/<Name>      # Add .cpp/.c/.h
      cd Development && cmake .. && cmake --build . --target <Name>

    Add an app:
      mkdir Software/<Name>       # Add .cpp/.c/.h
      cd Development && cmake .. && cmake --build . --target <Name>

    Add a tool:
      mkdir Tools/<Name>          # Add .cpp/.c/.h
      cd Development && cmake .. && cmake --build . --target <Name>

===============================================================================
 END OF WALKTHROUGH
===============================================================================