Skip to content

Document the required ATL and MFC build components #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mikemeerschaert wants to merge 2 commits into
base: main
Choose a base branch
from
+31 −1
Open

Document the required ATL and MFC build components #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7bfa512
Document the required ATL and MFC build components
mikemeerschaert Aug 27, 2026
9462abf
Ship a .vsconfig selecting the required build components
mikemeerschaert Aug 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .vsconfig
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"version": "1.0",
"components": [
"Microsoft.VisualStudio.Workload.VCTools",
"Microsoft.VisualStudio.Component.VC.ATL",
"Microsoft.VisualStudio.Component.VC.ATLMFC"
]
}
22 changes: 22 additions & 0 deletions docs/BUILDING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -23,6 +24,20 @@ 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`.

`.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
Expand Down Expand Up @@ -147,6 +162,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
Expand Down
2 changes: 1 addition & 1 deletion manual/content/using/build-and-run.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down