mirror of
https://github.com/johndoe6345789/SDL3CPlusPlus.git
synced 2026-04-24 13:44:58 +00:00
add dev commands
This commit is contained in:
Richard Ward
78
README.md
78
README.md
@@ -1,71 +1,25 @@
|
||||
# SDL3CPlusPlus
|
||||
A minimal SDL3 + Vulkan spinning cube demo.
|
||||
Minimal SDL3 + Vulkan spinning cube demo.
|
||||
|
||||
## Build
|
||||
## Cheat sheet
|
||||
|
||||
1. **Dependencies**
|
||||
- Install or update [Conan 2.x](https://docs.conan.io/en/latest/installation.html).
|
||||
- Run:
|
||||
```
|
||||
conan profile detect
|
||||
conan install . -of build -b missing -s compiler=msvc -s compiler.version=194 -s compiler.cppstd=17 -c tools.cmake.cmaketoolchain:generator="Visual Studio 17 2022"
|
||||
```
|
||||
so Conan pulls in `lua`, SDL3, Vulkan, and the rest of the graph defined in `conanfile.py`.
|
||||
### Dependencies
|
||||
- `python scripts/dev_commands.py dependencies` installs the Conan graph in `build`.
|
||||
|
||||
2. **Configure**
|
||||
- Default (Visual Studio): `cmake -B build -S .`
|
||||
* This uses the Visual Studio 2022 generator.
|
||||
- Ninja (clang/MinGW): configure into a clean folder, e.g., `cmake -G Ninja -B build-ninja -S .`
|
||||
* CMake already appends `C:\ProgramData\chocolatey\bin` to `CMAKE_PROGRAM_PATH`, so Ninja and Chocolatey LLVM tools are discoverable without extra `PATH` edits.
|
||||
* Ninja is a single-config generator. When no multi-config generator has been used, the project defaults `CMAKE_BUILD_TYPE=Release`; override it with `-DCMAKE_BUILD_TYPE=Debug` if you need another configuration in that folder.
|
||||
- Ninja with MSVC: open a Developer Command Prompt (call `"%VSINSTALLDIR%VC\\Auxiliary\\Build\\vcvarsall.bat" x64` or run that batch file from PowerShell) and configure with
|
||||
```
|
||||
cmake -G Ninja -B build-ninja-msvc -S . -DCMAKE_BUILD_TYPE=Release
|
||||
```
|
||||
Keep using the same prompt (so `cl.exe` carries the SDK/CRT paths) and build with `cmake --build build-ninja-msvc --config Release`.
|
||||
* Quick one-liner that initializes the MSVC environment and runs the Release build from a regular shell:
|
||||
```
|
||||
cmd /c "call \"%VSINSTALLDIR%VC\Auxiliary\Build\vcvarsall.bat\" x64 && cmake --build build-ninja-msvc --config Release"
|
||||
```
|
||||
When you run the command from PowerShell wrap the `cmd` invocation in single quotes so the embedded double quotes stay intact:
|
||||
```
|
||||
cmd /c 'call "%VSINSTALLDIR%VC\Auxiliary\Build\vcvarsall.bat" x64 && cmake --build build-ninja-msvc --config Release'
|
||||
```
|
||||
- Optional clang-tidy: add `-DENABLE_CLANG_TIDY=ON`
|
||||
* CMake searches both `C:\Program Files\LLVM\bin` and `C:\ProgramData\chocolatey\bin`, so standard LLVM/Chocolatey installs are found automatically.
|
||||
* The wrapped clang-tidy binary prints `[clang-tidy] starting .` and `[clang-tidy] finished (exit .)` markers so you can spot linting in verbose logs even when no diagnostics appear.
|
||||
### Configure & build
|
||||
- `python scripts/dev_commands.py configure` runs Ninja with the default `build-ninja` directory and `Release` build type; add `--generator vs` for the Visual Studio generator or `--generator ninja-msvc` when you want the MSVC-aware Ninja folder.
|
||||
- `python scripts/dev_commands.py build` targets `build-ninja` by default (change `--build-dir` if you configured elsewhere).
|
||||
- `python scripts/dev_commands.py msvc-quick` invokes the VC vars + Ninja one-liner (pass `--bat-path` to point at another Visual Studio layout).
|
||||
- Combine `--dry-run` with any subcommand to inspect the alias-driven shell invocation without executing it.
|
||||
- `python scripts/dev_commands.py run` launches `spinning_cube` from the configured Ninja output; pass `--build-dir` when you configured elsewhere.
|
||||
|
||||
3. **Build**
|
||||
- `cmake --build build --config Release --target sdl3_app` (or point at `build-ninja` if you used Ninja).
|
||||
- Shaders land in `build/shaders` or `build-ninja/shaders`, so the executable can load `cube.{vert,frag}.spv`.
|
||||
|
||||
## Run
|
||||
|
||||
```
|
||||
cmake --build build --target spinning_cube
|
||||
./build/spinning_cube
|
||||
```
|
||||
|
||||
If you rely on the Conan runtime environment (some dependencies export env vars), source `build/conanrun.sh` on Linux/macOS or run `build\\conanrun.bat` on Windows before launching the binary.
|
||||
### Run
|
||||
- `python scripts/dev_commands.py run [--build-dir ...]` to launch `spinning_cube`; source `build/conanrun.sh` / `build\\conanrun.bat` if Conan exports env vars before running the helper.
|
||||
|
||||
## Runtime configuration
|
||||
|
||||
1. `main.cpp` now uses a JSON-driven entrypoint.
|
||||
- Pass `sdl3_app --json-file-in <path>` to load runtime settings such as the Lua script path, window size, and `lua_debug`.
|
||||
- The loader enforces valid types and resolves relative scripts next to the configuration file.
|
||||
2. Generate a starter JSON with the shipped script locations:
|
||||
```
|
||||
sdl3_app --create-seed-json config/seed_runtime.json
|
||||
```
|
||||
The helper assumes `scripts/cube_logic.lua` lives beside the executable and writes normalized paths.
|
||||
3. Store or override the app-wide config with `sdl3_app --set-default-json [path]`.
|
||||
- Windows uses `%APPDATA%/sdl3cpp`; other platforms use `$XDG_CONFIG_HOME/sdl3cpp/default_runtime.json`, falling back to `~/.config/sdl3cpp`.
|
||||
- Providing a `path` duplicates that JSON into the platform default without editing the runtime values.
|
||||
- When the default file exists the executable reads it automatically; otherwise it falls back to the built-in script discovery logic.
|
||||
1. sdl3_app --json-file-in <path> loads JSON configs (script path, window size, lua_debug, etc.).
|
||||
2. sdl3_app --create-seed-json config/seed_runtime.json writes a starter file assuming scripts/cube_logic.lua sits beside the binary.
|
||||
3. sdl3_app --set-default-json [path] stores or overrides the default runtime JSON; Windows writes %APPDATA%/sdl3cpp, other OSes use $XDG_CONFIG_HOME/sdl3cpp/default_runtime.json (fallback ~/.config/sdl3cpp).
|
||||
|
||||
### GUI Demo
|
||||
`scripts/gui_demo.lua` shows off the Lua GUI framework (buttons, text boxes, list views, and SVG icons) rendered on top of the Vulkan scene. Launch it with `./build/sdl3_app --json-file-in config/gui_runtime.json` (or use that config via `sdl3_app --set-default-json`) to run the interactive overlay in the window.
|
||||
|
||||
## Dependency automation
|
||||
|
||||
This project ships a `renovate.json` configuration so Renovate can open PRs that bump the Conan packages listed in `conanfile.py`. Either install Renovate locally (`npm install -g renovate` or `npx renovate`) and run it from the repo root, or enable the Renovate bot on your GitHub/GitLab install to pick up the configuration automatically.
|
||||
scripts/gui_demo.lua paints the Lua GUI framework on top of the Vulkan scene. Launch it as ./build/sdl3_app --json-file-in config/gui_runtime.json or register that config via sdl3_app --set-default-json.
|
||||
|
||||
156
scripts/dev_commands.py
Normal file
156
scripts/dev_commands.py
Normal file
@@ -0,0 +1,156 @@
|
||||
"""Helper CLI that mirrors the commands documented in README.md."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import shlex
|
||||
import subprocess
|
||||
|
||||
|
||||
def run_commands(commands: list[str], dry_run: bool) -> None:
|
||||
for cmd in commands:
|
||||
print(f"\n> {cmd}")
|
||||
if dry_run:
|
||||
continue
|
||||
subprocess.run(cmd, shell=True, check=True)
|
||||
|
||||
|
||||
ALIASES = {
|
||||
"conan_detect": "conan profile detect",
|
||||
"conan_install": (
|
||||
"conan install . -of build -b missing "
|
||||
"-s compiler=msvc -s compiler.version=194 -s compiler.cppstd=17 "
|
||||
'-c tools.cmake.cmaketoolchain:generator="Visual Studio 17 2022"'
|
||||
),
|
||||
"msvc_quick": (
|
||||
'cmd /c "call \\"C:\\Program Files\\Microsoft Visual Studio\\2022\\Professional\\VC\\Auxiliary\\Build\\vcvarsall.bat\\" x64 '
|
||||
"&& cmake --build build-ninja-msvc --config Release\""
|
||||
),
|
||||
"spinning_cube": "./build-ninja/spinning_cube",
|
||||
}
|
||||
|
||||
|
||||
def dependencies(args: argparse.Namespace) -> None:
|
||||
commands = [ALIASES["conan_detect"], ALIASES["conan_install"]]
|
||||
run_commands(commands, args.dry_run)
|
||||
|
||||
|
||||
def configure(args: argparse.Namespace) -> None:
|
||||
defaults = {"vs": "build", "ninja": "build-ninja", "ninja-msvc": "build-ninja-msvc"}
|
||||
build_dir = args.build_dir or defaults.get(args.generator, "build")
|
||||
if args.generator == "vs":
|
||||
cmd = f"cmake -B {build_dir} -S ."
|
||||
else:
|
||||
cmd = (
|
||||
f'cmake -G Ninja -B {build_dir} -S . -DCMAKE_BUILD_TYPE={args.build_type}'
|
||||
)
|
||||
run_commands([cmd], args.dry_run)
|
||||
|
||||
|
||||
def build(args: argparse.Namespace) -> None:
|
||||
cmd = (
|
||||
f"cmake --build {args.build_dir} --config {args.config}"
|
||||
+ (f" --target {args.target}" if args.target else "")
|
||||
)
|
||||
run_commands([cmd], args.dry_run)
|
||||
|
||||
|
||||
def msvc_quick(args: argparse.Namespace) -> None:
|
||||
if args.bat_path:
|
||||
alias = ALIASES["msvc_quick"].replace(
|
||||
r'"C:\Program Files\Microsoft Visual Studio\2022\Professional\VC\Auxiliary\Build\vcvarsall.bat"',
|
||||
args.bat_path,
|
||||
)
|
||||
else:
|
||||
alias = ALIASES["msvc_quick"]
|
||||
if args.dry_run:
|
||||
print("\n> " + alias)
|
||||
else:
|
||||
subprocess.run(alias, shell=True, check=True)
|
||||
|
||||
|
||||
def run_demo(args: argparse.Namespace) -> None:
|
||||
base = ALIASES["spinning_cube"]
|
||||
if args.build_dir:
|
||||
prefix = args.build_dir.rstrip("\\/")
|
||||
alias = base.replace("./build-ninja", prefix)
|
||||
else:
|
||||
alias = base
|
||||
if args.dry_run:
|
||||
print("\n> " + alias)
|
||||
else:
|
||||
subprocess.run(alias, shell=True, check=True)
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(description="Run build helper commands.")
|
||||
parser.add_argument(
|
||||
"--dry-run",
|
||||
action="store_true",
|
||||
help="print commands without executing them",
|
||||
)
|
||||
subparsers = parser.add_subparsers(dest="command", required=True)
|
||||
|
||||
deps = subparsers.add_parser("dependencies", help="run Conan setup from README")
|
||||
deps.set_defaults(func=dependencies)
|
||||
|
||||
conf = subparsers.add_parser("configure", help="configure CMake projects")
|
||||
conf.add_argument(
|
||||
"--generator",
|
||||
choices=["vs", "ninja", "ninja-msvc"],
|
||||
default="ninja",
|
||||
help="which generator to invoke (default: Ninja)",
|
||||
)
|
||||
conf.add_argument(
|
||||
"--build-dir",
|
||||
help="override the directory where CMake writes build files",
|
||||
)
|
||||
conf.add_argument(
|
||||
"--build-type",
|
||||
default="Release",
|
||||
help="single-config builds need an explicit CMAKE_BUILD_TYPE",
|
||||
)
|
||||
conf.set_defaults(func=configure)
|
||||
|
||||
build_parser = subparsers.add_parser("build", help="run cmake --build")
|
||||
build_parser.add_argument(
|
||||
"--build-dir", default="build-ninja", help="which directory to build"
|
||||
)
|
||||
build_parser.add_argument(
|
||||
"--config", default="Release", help="configuration for multi-config builders"
|
||||
)
|
||||
build_parser.add_argument(
|
||||
"--target",
|
||||
default="sdl3_app",
|
||||
help="target to build (README mentions sdl3_app and spinning_cube)",
|
||||
)
|
||||
build_parser.set_defaults(func=build)
|
||||
|
||||
msvc = subparsers.add_parser(
|
||||
"msvc-quick", help="run the documented VS Developer Prompt one-liner"
|
||||
)
|
||||
msvc.add_argument(
|
||||
"--bat-path",
|
||||
help="full path to vcvarsall.bat (defaults to the VS 2022 Professional path from README)",
|
||||
)
|
||||
msvc.set_defaults(func=msvc_quick)
|
||||
|
||||
run_parser = subparsers.add_parser(
|
||||
"run", help="execute the spinning_cube binary from the build folder"
|
||||
)
|
||||
run_parser.add_argument(
|
||||
"--build-dir",
|
||||
help="where the binary lives (defaults to the Ninja folder from configure)",
|
||||
)
|
||||
run_parser.set_defaults(func=run_demo)
|
||||
|
||||
args = parser.parse_args()
|
||||
try:
|
||||
args.func(args)
|
||||
except subprocess.CalledProcessError as exc:
|
||||
return exc.returncode
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Reference in New Issue
Block a user