From a5c7a9a062049eac4dba46d0a264674fe92ee20b Mon Sep 17 00:00:00 2001 From: Luke Street Date: Tue, 7 Oct 2025 22:42:43 -0600 Subject: [PATCH] Use CMake presets; update README.md/AGENTS.md/.clangd --- .clangd | 1 + AGENTS.md | 21 +++++++++---- CMakePresets.json | 80 +++++++++++++++++++++++++++++++++++++++++++++++ README.md | 10 +++--- 4 files changed, 102 insertions(+), 10 deletions(-) create mode 100644 CMakePresets.json diff --git a/.clangd b/.clangd index b8380c0..02befed 100644 --- a/.clangd +++ b/.clangd @@ -1,4 +1,5 @@ CompileFlags: + CompilationDatabase: build/debug Remove: ["-maccumulate-outgoing-args"] --- If: diff --git a/AGENTS.md b/AGENTS.md index 33cdf3c..b9b3938 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,10 +6,10 @@ - Sample fixtures for exercising the loader live in `test/`. ## Build, Test, and Development Commands -- `cmake -B build -GNinja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=ON` configures a 32-bit toolchain; ensure multilib packages are present. -- `cmake --build build --target wibo` compiles the program and tests. -- `./build/wibo /path/to/program.exe` runs a Windows binary. Use `WIBO_DEBUG=1` (or `--debug`/`-D`) for verbose logging. Use `--chdir`/`-C` to set the working directory. -- `ctest --test-dir build --output-on-failure` runs the self-checking WinAPI fixtures (requires `i686-w64-mingw32-gcc` and `i686-w64-mingw32-windres`). +- `cmake --preset debug` configures a 32-bit toolchain; ensure multilib packages are present. (`--preset release` for optimized builds.) +- `cmake --build --preset debug` compiles the program and tests. +- `./build/debug/wibo /path/to/program.exe` runs a Windows binary. Use `-D` (or `WIBO_DEBUG=1`) for verbose logging. Use `-C` to set the working directory. +- `ctest --preset fixtures` runs the self-checking WinAPI fixtures (requires `i686-w64-mingw32-gcc` and `i686-w64-mingw32-windres`). - `clang-format -i path/to/file.cpp` and `clang-tidy path/to/file.cpp -p build` keep contributions aligned with the repo's tooling. ## Coding Style & Naming Conventions @@ -17,6 +17,7 @@ - Use PascalCase for Win32 entry points, camelCase for internal helpers, SCREAMING_SNAKE_CASE for Win32 constants, kCamelCase for internal constants, g_camelCase for globals, and mPascalCase for member variables. - Put static functions and variables in anonymous namespaces at the top of the file. - Prefer scoping types to the header or source file that uses them; avoid polluting `common.h` unless widely shared. +- Win32 APIs generally do NOT set `ERROR_SUCCESS` on success, though there are a few exceptions; check the docs. ## Shim Implementation Guidelines - Target pre-XP behavior; our binaries are old and don't expect modern WinAPI behavior. @@ -29,11 +30,19 @@ - Keep new repros small and self-contained (`test_.c`). - All fixtures must self-assert; use `test_assert.h` helpers so `ctest` fails on mismatched WinAPI behaviour. - Update `CMakeLists.txt` to add new fixture sources. -- Rebuild, then run tests with `ctest --test-dir build --output-on-failure`. +- Rebuild, then run with `ctest --preset fixtures`. - ALWAYS run tests against `wine` manually to confirm expected behaviour. If `wine` fails, the expected behaviour is VERY LIKELY wrong. (`wine` is not perfect, but we can assume it's closer to Windows than we are.) ## Debugging Workflow - Reproduce crashes under `gdb` (or `lldb`) with `-q -batch` to capture backtraces, register state, and the faulting instruction without interactive prompts. -- Enable `WIBO_DEBUG=1` or `-D` and output to a log (i.e. `&>/tmp/wibo.log`) when running the guest binary; loader traces often pinpoint missing imports, resource lookups, or API shims that misbehave. The answer is usually in the last few dozen lines before the crash. +- Use `-D` (or `WIBO_DEBUG=1`) and output to a log (i.e. `&>/tmp/wibo.log`) when running the guest binary; loader traces often pinpoint missing imports, resource lookups, or API shims that misbehave. The answer is usually in the last few dozen lines before the crash. - Inspect relevant source right away—most issues stem from stubbed shims in `dll/`. - Missing stubs generally do _not_ cause a crash; we return valid function pointers for unknown imports. Only when the missing stub is _called_ do we abort with a message. Therefore, don't preemptively add stubs for every missing import; wait until the binary actually calls it. + +## Implementation Workflow +- Fetch API documentation with `microsoft_docs` +- Create test cases in `test/test_.c` +- Build, then run the test(s) against `wine` (`wine build/debug/test/test_.exe`) to establish baseline behaviour (important!) +- Plan and implement the API +- Build, then run tests against `wibo` (`ctest --preset fixtures`) for validation +- Format with `clang-format` and lint with `clang-tidy` diff --git a/CMakePresets.json b/CMakePresets.json new file mode 100644 index 0000000..82cb3dc --- /dev/null +++ b/CMakePresets.json @@ -0,0 +1,80 @@ +{ + "version": 2, + "configurePresets": [ + { + "name": "ninja-base", + "hidden": true, + "generator": "Ninja", + "cacheVariables": { + "CMAKE_EXPORT_COMPILE_COMMANDS": "ON", + "WIBO_ENABLE_LIBURING": "ON" + } + }, + { + "name": "debug", + "displayName": "Debug", + "inherits": [ + "ninja-base" + ], + "binaryDir": "${sourceDir}/build/debug", + "cacheVariables": { + "CMAKE_BUILD_TYPE": "Debug" + } + }, + { + "name": "release", + "displayName": "Release", + "inherits": [ + "ninja-base" + ], + "binaryDir": "${sourceDir}/build/release", + "cacheVariables": { + "CMAKE_BUILD_TYPE": "Release" + } + } + ], + "buildPresets": [ + { + "name": "debug", + "displayName": "Build (Debug)", + "configurePreset": "debug", + "targets": [ + "wibo", + "wibo_test_fixtures" + ], + "configuration": "Debug" + }, + { + "name": "release", + "displayName": "Build (Release)", + "configurePreset": "release", + "targets": [ + "wibo", + "wibo_test_fixtures" + ], + "configuration": "Release" + } + ], + "testPresets": [ + { + "name": "fixtures", + "displayName": "Run fixture tests (Debug)", + "configurePreset": "debug", + "configuration": "Debug", + "output": { + "outputOnFailure": true, + "shortProgress": true + } + }, + { + "name": "fixtures-release", + "displayName": "Run fixture tests (Release)", + "configurePreset": "release", + "configuration": "Release", + "output": { + "outputOnFailure": true, + "shortProgress": true + } + } + ] +} diff --git a/README.md b/README.md index fbcd99b..82e2ad5 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,13 @@ Download the latest release from [GitHub releases](https://github.com/decompals/ ## Building ```sh -cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -cmake --build build +cmake --preset debug +cmake --build --preset debug ``` -Set `-DCMAKE_BUILD_TYPE=Release` to produce an optimized binary instead. +This will produce a debug binary at `build/debug/wibo`. + +Use `--preset release` to produce an optimized binary at `build/release/wibo`. ## Usage @@ -64,7 +66,7 @@ wibo -- test.exe a b c Self-checking Windows fixtures run through CTest. They require a 32-bit MinGW cross toolchain (`i686-w64-mingw32-gcc` and `i686-w64-mingw32-windres`). ```sh -ctest --test-dir build --output-on-failure +ctest --preset fixtures ``` This will cross-compile the fixture executables, run them through `wibo`, and fail if any WinAPI expectations are not met.