From 7bfa512ad2a416c746b383ad27809e3864f64099 Mon Sep 17 00:00:00 2001 From: Mike Meerschaert Date: Thu, 27 Aug 2026 09:24:36 -0700 Subject: [PATCH 1/2] Document the required ATL and MFC build components --- docs/BUILDING.md | 16 ++++++++++++++++ manual/content/using/build-and-run.md | 2 +- 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/BUILDING.md b/docs/BUILDING.md index cbd9fe2..5642b26 100644 --- a/docs/BUILDING.md +++ b/docs/BUILDING.md @@ -12,6 +12,7 @@ | Host and architecture | Windows, 32-bit (`Win32`) target | | Processor | SSE2, so a Pentium 4 or Athlon 64 onward | | Generator and compiler | Visual Studio 2022 MSVC 19.30 or newer | +| ATL and MFC | The Visual Studio C++ ATL and C++ MFC components | | Windows SDK | A Visual Studio-installed Windows SDK | | CMake | 3.23 or newer | | C++ language level | C++20 | @@ -23,6 +24,14 @@ supported by the current tree. Install Visual Studio 2022 with the **Desktop development with C++** workload, a Windows SDK, CMake 3.23 or newer, and Git for Windows. +The workload alone is not sufficient, even with its recommended components: the +engine includes `atlbase.h` and its resource scripts include `afxres.h`, so the +**C++ ATL** and **C++ MFC** components for the current build tools must be +selected as well. In an unattended install, these are +`Microsoft.VisualStudio.Component.VC.ATL` and +`Microsoft.VisualStudio.Component.VC.ATLMFC`. Without them the build fails at +`code/wonline.cpp` and `code/Sun.rc`. + ## Dependencies The renderer is built on [bgfx](https://github.com/bkaradzic/bgfx), vendored as the @@ -147,6 +156,13 @@ Studio 2022 Community 17.14.37328.6, MSVC 19.44.35228, and Windows SDK builds retain inherited MSVC warnings; warnings are not treated as errors, but contributions should not add new warnings. +The ATL and MFC requirement was established on August 27, 2026 with MSVC +19.44.35228, Windows SDK 10.0.26100, and CMake 4.4.2: a fresh Visual Studio +2022 Build Tools install with only the **Desktop development with C++** +workload and its recommended components failed to build, first at +`code/wonline.cpp` on the missing `atlbase.h` and, with ATL added, at +`code/Sun.rc` on the missing `afxres.h`. + Build verification establishes that the supported toolchain compiles and links the configured targets and produces the listed artifacts. Runtime behavior is established separately, by play testing, and is outside this build-support diff --git a/manual/content/using/build-and-run.md b/manual/content/using/build-and-run.md index 5ec42db..86d7ed2 100644 --- a/manual/content/using/build-and-run.md +++ b/manual/content/using/build-and-run.md @@ -13,7 +13,7 @@ related: id: developer-build-troubleshooting --- -Install Visual Studio 2022 with the **Desktop development with C++** workload, a Windows SDK, CMake 3.23 or newer, and Git for Windows. The repository's `docs/BUILDING.md` covers toolchain details and options. +Install Visual Studio 2022 with the **Desktop development with C++** workload, its **C++ ATL** and **C++ MFC** components — the workload does not select them on its own — a Windows SDK, CMake 3.23 or newer, and Git for Windows. The repository's `docs/BUILDING.md` covers toolchain details and options. The renderer is a vendored dependency, so a clone that did not fetch submodules has to fetch them before configuring. Configuration stops with instructions if they are missing. From 9462abf4d583e9e23734b35b982a423aa52195a2 Mon Sep 17 00:00:00 2001 From: Mike Meerschaert Date: Thu, 27 Aug 2026 14:28:02 -0700 Subject: [PATCH 2/2] Ship a .vsconfig selecting the required build components --- .vsconfig | 8 ++++++++ docs/BUILDING.md | 6 ++++++ 2 files changed, 14 insertions(+) create mode 100644 .vsconfig diff --git a/.vsconfig b/.vsconfig new file mode 100644 index 0000000..423101f --- /dev/null +++ b/.vsconfig @@ -0,0 +1,8 @@ +{ + "version": "1.0", + "components": [ + "Microsoft.VisualStudio.Workload.VCTools", + "Microsoft.VisualStudio.Component.VC.ATL", + "Microsoft.VisualStudio.Component.VC.ATLMFC" + ] +} diff --git a/docs/BUILDING.md b/docs/BUILDING.md index 5642b26..c3b35a9 100644 --- a/docs/BUILDING.md +++ b/docs/BUILDING.md @@ -32,6 +32,12 @@ selected as well. In an unattended install, these are `Microsoft.VisualStudio.Component.VC.ATLMFC`. Without them the build fails at `code/wonline.cpp` and `code/Sun.rc`. +`.vsconfig` at the repository root records the workload and both components in +the Visual Studio installation configuration format. Importing it in the Visual +Studio Installer, or passing it to an unattended install with `--config`, +selects them in one step, and Visual Studio offers to install missing listed +components when it detects the file near an open solution or folder. + ## Dependencies The renderer is built on [bgfx](https://github.com/bkaradzic/bgfx), vendored as the