diff --git a/README.md b/README.md index e76be14..fa1868b 100644 --- a/README.md +++ b/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 ` 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 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. diff --git a/scripts/dev_commands.py b/scripts/dev_commands.py new file mode 100644 index 0000000..93bdd71 --- /dev/null +++ b/scripts/dev_commands.py @@ -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())