Skip to content

Commit 1e9f442

Browse files
j9liuj9liu
authored
Merge pull request #1684 from CesiumGS/developer-setup-windows-gotchas
Add Windows setup gotchas doc
2 parents e9eee4b + 4c33501 commit 1e9f442

File tree

2 files changed

+134
-0
lines changed

2 files changed

+134
-0
lines changed

‎Documentation/developer-setup-windows-gotchas.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Developer Setup for Windows - Gotchas {#developer-setup-windows-gotchas}
2+
3+
Compiling Cesium for Unreal requires that the vcpkg-based third-party dependencies, the cesium-native code, and the Cesium for Unreal code itself are compiled using the same (or compatible) versions of the MSVC compiler. This is remarkably hard to achieve! This guide will hopefully help you get there.
4+
5+
Some important facts to understand before continuing:
6+
7+
1. "Visual Studio 2022" is not a compiler version. It's an IDE brand name, and may imply any number of compiler versions.
8+
2. Updates to Visual Studio 2022 often come with new versions of the MSVC compiler. For Visual Studio 2022, the MSVC compilers have version numbers like 14.x. Sometimes the compiler version is referred to as a "toolchain" version.
9+
3. Microsoft _does_ allow us to link together .lib files built with different versions of the MSVC compiler. However, the compiler version used to _link_ must be the same or newer than the _newest_ compiler that built any of the .libs (or any object files they contain).
10+
4. You can install any number of toolchain versions simultaneously. Go to "Add / Remove Programs" and Modify "Visual Studio Professional 2022". Then click the "Individual Components" tab and scroll down to "Compilers, build tools, and runtimes". Tick the box next to the "MSVC v143 - VS2022 C++ x64/x86 build tools" version that you want to install.
11+
12+
## Cesium for Unreal
13+
14+
The Cesium for Unreal plugin code includes and links with a great deal of Unreal Engine code. It is built by the Unreal Build Tool, even when you compile from within Visual Studio.
15+
16+
The MSVC compiler version that Epic used to build a release version of Unreal Engine can be found in that version's release notes. For example, the [release notes for Unreal Engine 5.3](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5.3-release-notes) include this information:
17+
18+
> * IDE Version the Build farm compiles against
19+
> * Visual Studio: Visual Studio 2022 17.4 14.34.31933 toolchain and Windows 10 SDK (10.0.18362.0)
20+
21+
For maximum compatibility, released versions of Cesium for Unreal should be built with _exactly_ this version, v14.34.31933, and this is what we do on CI.
22+
23+
However, when compiling for your own development purposes, you can use this version or any compatible newer one. In general, newer compilers work just fine, but not always. A change in the v14.42 compiler (and later versions) means that some Unreal Engine 5.3 header files cannot be compiled with it. So, on development systems, we usually use the v14.38 toolchain, because this version works with all currently-supported versions of Unreal Engine: 5.4, 5.5, and 5.6. Install it from Add/Remove Programs by following the instructions in the top section.
24+
25+
The Unreal Build Tool will use the latest compiler version that you have installed. So even after installing v14.38, Cesium for Unreal will likely attempt to compile with a later version like v14.44, and fail. It's possible to uninstall all the newer versions, but this is a huge hassle if you need the newer compiler for other projects.
26+
27+
The solution is to explicitly tell the Unreal Build Tool to use v14.38. To do that, open <!--! \cond DOXYGEN_EXCLUDE !-->`%AppData%\Unreal Engine\UnrealBuildTool\BuildConfiguration.xml`<!--! \endcond --><!--! `%%AppData%\Unreal Engine\UnrealBuildTool\BuildConfiguration.xml` --> and add this to it:
28+
29+
```xml
30+
<?xml version="1.0" encoding="utf-8" ?>
31+
<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
32+
<WindowsPlatform>
33+
<CompilerVersion>14.38.33130</CompilerVersion>
34+
</WindowsPlatform>
35+
</Configuration>
36+
```
37+
38+
> [!note]
39+
> The environment variable <!--! \cond DOXYGEN_EXCLUDE !-->`%AppData%`<!--! \endcond --><!--! `%%AppData%` --> resolves to something like `C:\Users\UserName\AppData\Roaming`. In PowerShell, use `$env:AppData` instead.
40+
41+
With that, all builds invoked by Unreal Build Tool should use the chosen compiler version. You should see a message near the start of the build log confirming this:
42+
43+
> Using Visual Studio 2022 14.38.33144 toolchain (C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.38.33130) and Windows 10.0.22621.0 SDK (C:\Program Files (x86)\Windows Kits\10).
44+
45+
## vcpkg
46+
47+
If you've followed the instructions above, and Unreal Build Tool is now building Cesium for Unreal with v14.38 of the compiler, then you will likely get linker errors because the cesium-native and third-party dependencies are both still built with the newer version of the compiler.
48+
49+
vcpkg has hard-coded logic to choose the very latest version of the compiler that you have installed. It completely ignores all the usual ways that different compiler versions can be selected, such as setting the defaults file (`"C:\Program Files\Microsoft Visual Studio\2022\Professional\VC\Auxiliary\Build\Microsoft.VCToolsVersion.default.props"`), setting environment variables or running the `vcvarsall` script. The _only_ way to choose a compiler for vcpkg to use, as far as we know, is by explicitly specifying it in a vcpkg triplet file. So, to build with 14.38, edit the `extern/vcpkg-overlays/triplets/x64-windows-unreal.cmake` file in the `cesium-unreal` repo and add this line to the end of it:
50+
51+
```
52+
set(VCPKG_PLATFORM_TOOLSET_VERSION "14.38")
53+
```
54+
55+
Be careful not to commit this change!
56+
57+
vcpkg won't always automatically rebuild everything it needs to rebuild after making this change. To force a rebuild, delete the following:
58+
59+
* The entire `.ezvcpkg` directory. It's usually found at `c:\.ezvcpkg` or `%userprofile%\.ezvcpkg`. If you're not sure, look for where ezvcpkg prints `local dir: d:/.ezvcpkg/dbe35ceb30c688bf72e952ab23778e009a578f18` or similar during the cesium-native CMake configure.
60+
* The vcpkg [binary cache](https://learn.microsoft.com/en-us/vcpkg/users/binarycaching) directory. It's usually found at `%LOCALAPPDATA%\vcpkg\archives` (or `$env:LOCALAPPDATA\vcpkg\archives` in PowerShell).
61+
62+
## cesium-native
63+
64+
cesium-native chooses compilers in the normal CMake way. That means that, by default, it will use the compiler version that you installed most recently (which is _not_ necessarily the latest). So if you installed 14.38 following the instructions above, the cesium-native build should automatically start using it. You may need to delete your `build` directory.
65+
66+
To specify a particular compiler, you can use `vcvarsall.bat`:
67+
68+
```
69+
"C:\Program Files\Microsoft Visual Studio\2022\Professional\VC\Auxiliary\Build\vcvarsall.bat" x64 -vcvars_ver=14.38
70+
```
71+
72+
Note that you must do this from a CMD prompt, _not_ from PowerShell. But you can run PowerShell afterward by invoking `pwsh` or `powershell`.
73+
74+
You can also specify the compiler version on the CMake command-line:
75+
76+
```
77+
cmake -B build -S . -T "version=14.38"
78+
```
79+
80+
A common scenario is that you've followed the instructions in this document and installed v14.38, and your Cesium for Unreal build is working fine. Then, you try to compile some _other_ CMake-based project that should be using the newer compiler, and it doesn't work anymore. The other project's build is unexpectedly using the v14.38 compiler. It makes sense that 14.38 would be the default, because that's the one you installed most recently. But even following either one or both of the suggestions above doesn't help. CMake continues to insist on using 14.38. What's the deal?
81+
82+
The solution here is to explicitly install the version of the build tools that you're trying to use. In "Add / Remove Programs" -> Modify "Visual Studio Professional 2022" -> "Invididual Components" tabs, you'll probably see that the box next to the "MSVC v143 - VS2022 C++ x64/x86 build tools (Latest)" is ticked. But the specific version that actually is the latest (14.44 as of this writing) is _not_ ticked. If you install that one, you will now be able to explicitly select it in CMake builds using either of the techniques above. It is very frustating that this kind of thing is required.
83+
84+
## Visual Studio Code
85+
86+
You may have different projects that need to use different compiler versions. If you use Visual Studio Code, the easiest way to deal with this is to set up custom "kits" for the different versions.
87+
88+
Open the command palette (Ctrl-Shift-P) and choose `CMake: Edit User-Local CMake Kits`. Make two copies of the JSON object for the existing `amd64` kit. It will have a name similar to `Visual Studio Professional 2022 Release - amd64`. Name the two copies for the compiler version you want each to use, such as `14.38 - Visual Studio Professional 2022 Release - amd64`. Then, do the following:
89+
90+
* Add the `version=14.38` or similar to the `preferredGenerator.toolset` property.
91+
* Create an entry for the `VCToolsVersion` environment variable with the full three-part version. You can find the three-part version for your installed toolsets by looking in `C:\Program Files\Microsoft Visual Studio\2022\Professional\VC\Tools\MSVC` or similar.
92+
93+
It should look like this (though your names and `visualStudio` properties may be different):
94+
95+
```json
96+
[
97+
{
98+
"name": "14.38 - Visual Studio Professional 2022 Release - amd64",
99+
"visualStudio": "7d903395",
100+
"visualStudioArchitecture": "x64",
101+
"isTrusted": true,
102+
"preferredGenerator": {
103+
"name": "Visual Studio 17 2022",
104+
"platform": "x64",
105+
"toolset": "host=x64,version=14.38"
106+
},
107+
"environmentVariables": {
108+
"VCToolsVersion": "14.38.33130"
109+
}
110+
},
111+
{
112+
"name": "14.44 - Visual Studio Professional 2022 Release - amd64",
113+
"visualStudio": "7d903395",
114+
"visualStudioArchitecture": "x64",
115+
"isTrusted": true,
116+
"preferredGenerator": {
117+
"name": "Visual Studio 17 2022",
118+
"platform": "x64",
119+
"toolset": "host=x64,version=14.44"
120+
},
121+
"environmentVariables": {
122+
"VCToolsVersion": "14.44.35207"
123+
}
124+
},
125+
...
126+
]
127+
```
128+
129+
You can now choose your compiler by invoking `CMake: Select a kit` from the command palette.
130+
131+
If this doesn't work (your build uses the wrong compiler), check that you've explicitly installed both compiler versions, as described at the end of the [cesium-native](#cesium-native) section above.

‎Documentation/developer-setup-windows.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,9 @@ Detailed instructions for setting up a Cesium for Unreal development environment
1616
- For best JPEG-decoding performance, you must have [nasm](https://www.nasm.us/) installed so that CMake can find it. Everything will work fine without it, just slower.
1717
- Install the Unreal Engine (version 5.3 or newer) from https://www.unrealengine.com/en-US/download
1818

19+
> [!note]
20+
> In newer versions of Visual Studio 2022, it can be tricky to get everything building using compatible versions of the Visual C++ compiler. See <!--! \cond DOXYGEN_EXCLUDE !-->[Developer Setup for Windows - Gotchas](developer-setup-windows-gotchas.md)<!--! \endcond --><!--! \subpage developer-setup-windows-gotchas --> for details and solutions, particularly if you run into compiler or linker errors following the instructions below.
21+
1922
## To Cross Compile Android on Windows
2023

2124
- Follow the [Unreal Engine setup guide for Android](https://docs.unrealengine.com/SharingAndReleasing/Mobile/Android/Setup/AndroidStudio/).

0 commit comments

Comments
 (0)