376 lines
13 KiB
Plaintext
376 lines
13 KiB
Plaintext
===============================================================================
|
|
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
|
|
=============================================================================== |