Initial Commit
This commit is contained in:
@@ -0,0 +1,376 @@
|
||||
===============================================================================
|
||||
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
|
||||
===============================================================================
|
||||
Reference in New Issue
Block a user