Skip to content

Latest commit

 

History

History
138 lines (95 loc) · 10 KB

developer-setup-windows.md

File metadata and controls

138 lines (95 loc) · 10 KB

Please see the Developer Setup page for an overview of the process.

Prerequisities

  • Install CMake (version 3.15 or newer) from https://cmake.org/install/
  • Install Visual Studio 2019 v16.11+ (or Visual Studio 2017 v15.6+)
    • Under Workloads, check Desktop development with C++
    • Under Workloads, check Game development with C++
    • Under Individual components, check .NET Framework 4.8 SDK (or newer)

Note: Visual Studio options are derived from Unreal Engine's recommended setup

  • Install the .NET Core 3.1 Runtime, link
  • For best JPEG-decoding performance, you must have nasm installed so that CMake can find it. Everything will work fine without it, just slower.
  • Install the Unreal Engine (version 5.0 or newer) from https://www.unrealengine.com/en-US/download

Clone the git repos

This can be set up with the following sequence of commands, on the console, starting in the C:\Dev directory:

    git clone https://github.com/CesiumGS/cesium-unreal-samples.git
    cd cesium-unreal-samples
    mkdir Plugins
    cd Plugins
    git clone --recursive https://github.com/CesiumGS/cesium-unreal.git

Build cesium-native

The cesium-native libraries and their dependencies use CMake and must be built separately from Cesium for Unreal. There are a number of ways to do this, depending on your preferred environment:

Visual Studio 2019

Launch Visual Studio 2019 and "Open a local folder". Select C:\Dev\cesium-unreal-samples\Plugins\cesium-unreal\extern.

Be sure to select the extern directory, not the cesium-native subdirectory.

Find the "Solution Explorer - Folder View".

To build a "Debug" build of cesium-native,

  • Right-click on the root CMakeLists.txt and select "Install".
  • This will compile and "install" it to the place in the project that Cesium for Unreal expects to find it
  • c:\Dev\cesium-unreal-samples\Plugins\cesium-unreal\Source\ThirdParty.

To build a "Release" build of cesium-native,

  • Right click on CMakeLists.txt and select "CMake Settings for cesium-unreal-extern".
  • Add a new configuration by clicking the + and choose x64-Release.
  • Select the new "x64-Release" from the Solution Configuration dropdown.
  • Right-click on CMakeLists.txt again and choose "Install".

In Visual Studio, this defaults to the "RelWithDebInfo" configuration type. You can change this at any time

CMake GUI

  • Start cmake-gui
  • In the "Where is the source code" text field, enter C:\Dev\cesium-unreal-samples\Plugins\cesium-unreal\extern Note: This must be the extern directory, and not the cesium-native subdirectory!
  • In the "Where to build the binaries" text field, enter C:\Dev\cesium-unreal-samples\Plugins\cesium-unreal\extern\build
  • Press "Configure" (and confirm the creation of the directory and the default generator for the project)
  • Press "Generate"

This will generate the project file called cesium-unreal-extern.sln in the directory C:\Dev\cesium-unreal-samples\Plugins\cesium-unreal\extern\build. You can open this solution file in the Visual Studio IDE and compile as normal. To install cesium-native to the project - which is required for use with Cesium for Unreal - right-click on INSTALL in Solution Explorer, and choose Build. INSTALL may be found inside a folder called CMakePredefinedTargets. Use the Solution Configuration dropdown to change between the Debug and Release configurations.

CMake command-line

First, configure the CMake project in the C:\Dev\cesium-unreal-samples\Plugins\cesium-unreal\extern directory by following the instructions below. Note: The following steps must be done in the extern directory, and not the cesium-native subdirectory!

To configure for Visual Studio 2022, open "x64 Native Tools Command Prompt for VS 2022" and execute the following command:

cmake -B build -S . -G "Visual Studio 17 2022" -A x64

With either compiler, the commands above will generate the project file called cesium-unreal-extern.sln in the directory C:\Dev\cesium-unreal-samples\Plugins\cesium-unreal\extern\build. You can open this solution file in the Visual Studio IDE and compile as normal. To install cesium-native to the project - which is required for use with Cesium for Unreal - right-click on INSTALL in Solution Explorer, and choose Build. INSTALL may be found inside a folder called CMakePredefinedTargets. Use the Solution Configuration dropdown to change between the Debug and Release configurations.

You can also build the Release version entirely from the command-line:

cmake --build build --config Release --target install

Or the debug version:

cmake --build build --config Debug --target install

You can also build and install the debug version by using Debug or RelWithDebInfo instead of Release.

Create the Visual Studio project files for cesium-unreal-samples

The project files for the samples project, including the actual Cesium for Unreal plugin, can be created with the Unreal Engine.

Convert the Unreal project into a C++ project

  • Copy the \cesium-unreal-samples\Plugins\cesium-unreal\Documentation\Source folder to \cesium-unreal-samples
  • Using Windows Explorer, browse into the \cesium-unreal-samples directory
  • Right-click on the CesiumForUnrealSamples.uproject file
  • Select "Generate Visual Studio project files"

This will generate the CesiumForUnrealSamples.sln file that can be opened, compiled, and debugger with Visual Studio. Be sure to switch the "Solution Platform" to "Win64".

If you have both Visual Studio 2017 and Visual Studio 2019 installed, the Visual Studio project files generated above may build with VS2017 even if they're opened with VS2019. This will still be true even if you allow VS2019 to upgrade the project files to the VS2019 toolchain. That's because the project files simply invoke the Unreal Build Tool, which plays by its own rules. This is generally not a problem, except if you used Visual Studio 2019 to build cesium-native. In that case, you will get linker errors when you try to compile Cesium for Unreal.

To switch the Unreal Build Tool to use VS2019 instead, launch the Unreal Editor and open a project that does not use Cesium for Unreal. Go to Edit -> Editor Preferences. Go to the General -> Source Code section and change Source Code Editor to Visual Studio 2019. Click "Set as Default" so that this change applies to all projects that don't override it.

Solution Configurations

During development, you will typically use the "DebugGame Editor" or "Development Editor" Solution Configuration in the Visual Studio solution created above. "DebugGame Editor" is easier to debug, but "Development Editor" will be a bit faster. In either case, but sure that "Win64" is selected as the Solution Platform.

When you build "DebugGame Editor", the build process will first look for an installed Debug build of cesium-native. If it finds one, it will use it. If not, it will try to use an installed Release build of cesium-native instead. The "Development Editor" configuration, on the other hand, will always use an installed Release build of cesium-native, and will fail to build if one does not exist.

So, when you make changes to cesium-native code, make sure you are building and installing the correct configuration of cesium-native for the Cesium for Unreal configuration that you're using:

  • Development Editor -> Release
  • DebugGame Editor -> Debug

See the sections above to learn how to build the Debug and Release configurations of cesium-native in your preferred environment.

While actively making changes to cesium-native, it is usually convenient to have two copies of Visual Studio open: one for cesium-native, and one for Cesium for Unreal.

Debugging

In the Cesium for Unreal solution in Visual Studio, press F5 (or select "Debug->Start Debugging" from the menu) to start in debug mode.

Starting in debug mode makes it possible to set breakpoints, inspect variables with the debugger, or receive stack trace information in the case of crashes. For pure feature tests, it is also possible to press CTRL-F5 (or select "Debug->Start Without Debugging" from the menu) to start.

When using the "DebugGame Editor" solution configuration and the Debug configuration of cesium-native, it is also possible to debug through cesium-native code. First, make sure "Just my Code" is disabled:

  • Go to Tools -> Options.
  • Navigate to Debugging -> General.
  • Verify that Enable Just My Code is unchecked.

Once that is done, it is possible to set breakpoints in Cesium for Unreal plugin code and step from there straight into cesium-native code. It's also possible to set breakpoints in cesium-native code directly, but it can be a bit of a hassle to navigate to those files because they aren't in the Cesium for Unreal solution. There are two ways to open cesium-native files from the Cesium for Unreal solution for debugging purposes:

  • Switch the Solution Explorer to Folder View, turn on "Show All Files", and then navigate to the cesium-native code in Plugins\cesium-unreal\extern\cesium-native. Getting back to the default Solution Explorer view can be a pain. The trick is to double-click the .sln file in Folder View.
  • Find the file you want to debug in another copy of Visual Studio which is open on the cesium-native solution. Then, right-click on the file's tab and choose "Copy Full Path". Go back to the Cesium for Unreal solution, go to File -> Open -> File, and paste in the copied file path.

If you find the debugger refuses to step into cesium-native code, check that you're using the "DebugGame Editor" configuration of Cesium for Unreal and the Debug configuration of cesium-native, and that you've built and installed cesium-native.