在macOS和Windows上，从源码构建Cesium for Unreal插件 ...

BlaXuan · 发表于 2022-5-6 07:02

4月初，UE5发布了正式版，随后，Cesium也发布了v1.12，支持了UE5的正式版本。
下面是对应release的链接：
Release Cesium for Unreal v1.12.2 (Unreal Engine 5) · CesiumGS/cesium-unreal
“This release includes support for Unreal Engine v5.0 on Windows, Linux, and Android.“ —— 从release note看出来，本次发布并没有包括macOS版本，从虚幻商城的插件页面，也确实只能下载到支持UE5的Windows版本插件，下载不到macOS版的UE5插件。参考论坛的帖子，看到官方的回复是，因为macOS的持续集成环境没有搭建起来，所以没有发布支持macOS的版本，用户可以自行从源码构建。
自己动手，丰衣足食

疫情隔离在家，只有mac笔记本可以用，于是决定动手编译一下macOS版本的CesiumForUnreal。
本文就记录一下自己参考官方《developer setup》文档，从源码构建CesiumForUnreal的过程和遇到的问题。写作日期2022.04.27。
总结下来，其实就是这么正确的编译cesium-native，这一步的问题解决了，就没什么其他问题了。
官方的《developer setup》文档，比较详细的讲述了如何从源码构建的步骤，建议仔细阅读。
通用准备

1. 安装Git Large File Storage (LFS) —— Git Large File Storage

这一步官方文档没有写，不过不安装git-lfs的话，一些文件拉不到。（我没有验证过不安装git-lfs是否会影响编译，主要是以防万一）
2. 安装CMake

CMake是从源码构建的基础工具，官网链接：Installing | CMake
注意：Windows版本，安装的时候，记得勾选添加到PATH对应的选项，否则后续要自己手动添加到PATH中。

The Windows installer has an option to modify the system PATH environment variable. If that is not selected during installation, one may manually add the install directory (e.g.C:\Program Files\CMake\bin) to thePATHin a command prompt.

3. 新建一个空的UE5 C++项目

注意，工程类型一定要选择&#34;C++&#34;，如下图（注意项目路径不要太深，理由下一条会讲）：

4. clone代码

官方文档推荐的方式，是通过git命令行来clone代码库到本地，实测下来，使用GitHub客户端下载代码到本地也是一样的。我就直接用GitHub客户端来将代码clone到本地了。
可以看到，clone下来的代码（含git submodule的第三方库）有1.5G这么多（所以你的网络也得足够好）

有一点需要注意，用于拉取代码的路径不要太长，路径太长在编译的时候，会有问题。
（如上图，我存放代码的路径是D:\Code\GitHub\cesium-unreal\，这个路径长度是OK的）
这点官方文档有提到：

On Windows, it is important that the top-level project directory have a short pathname. Otherwise, you may run into mysterious errors caused by the Windows maximum path length limitation.

5. 拷贝插件代码到新UE5工程的Plugins目录下

新建的项目默认是没有Plugins目录的，需要新建一个Plugins目录，然后拷贝插件代码到Plugins目录中，如下图：

（其实在上面第三步，也可以直接直接clone到Plugins目录下）
（当然也可以先执行后面步骤cesium-native的构建，构建完毕之后，再拷贝到Plugins目录下，结果也是一样的）
（关于目录命名，clone下来的目录名字，是cesium-unreal，UE的商店下载下来的插件名字是CesiumForUnreal，我个人在Plugins目录中，命名的是CesiumForUnreal，和商店里面的命名保持一致）
构建macOS版

主要是参考官方文档：《developer-setup-osx》
1. 添加Cmake到命令行 —— Install CMake for command line use

在通用准备步骤中，已经安装了CMake，现在需要添加CMake到命令行，为后续构建做准备。

打开已经安装的CMake
点击菜单 Tools - How to Install For Command Line Use
弹出的新窗口中，如下图右边部分的对话框，给了3种添加到命令行的方法
我使用的是红框中的方法，将CMake添加到了命令行
验证是否添加成功，在Terminal里面，输入cmake命令，出现&#34;Run &#39;cmake --help&#39; for more information.&#34;等字样，就说明添加到命令行成功了

2. 构建cesium-native

1) 修改CMakeList.txt
修改extern/CMakeList.txt，在下面的位置，插入一行&#34;set(CMAKE_OSX_DEPLOYMENT_TARGET 10.15)&#34;
# On Mac and Linux, Unreal uses -fvisibility-ms-compat.
# On Android, it uses -fvisibility=hidden
if (${CMAKE_SYSTEM_NAME} STREQUAL &#34;Linux&#34; OR ${CMAKE_SYSTEM_NAME} STREQUAL &#34;Darwin&#34;)
  set(CMAKE_CXX_FLAGS &#34;${CMAKE_CXX_FLAGS} -fvisibility-ms-compat -fvisibility-inlines-hidden&#34;)
  # 下面这行是新增的，手动指定了Deployment Target为10.15
  set(CMAKE_OSX_DEPLOYMENT_TARGET 10.15)
elseif (${CMAKE_SYSTEM_NAME} STREQUAL &#34;Android&#34;)解释：
这一步其实是为了解决一个编译插件时的链接报错：
&#34;ld: warning: object file ... was built for newer macOS version (12.0) than being linked (10.15)&#34;，具体如下：
这里省略若干行...
ld: warning: object file (/Users/admin/Code/GitLab/CesiumUE5/CesiumUE5CustomCpp/Plugins/CesiumForUnreal/Source/ThirdParty/lib/Darwin-x64/libdraco.a(attribute_octahedron_transform.cc.o)) was built for newer macOS version (12.0) than being linked (10.15)
ld: fatal warning(s) induced error (-fatal_warnings)
clang: error: linker command failed with exit code 1 (use -v to see invocation)看起来，UE5生成的工程，Deployment Target默认是10.15，如下图：

问题应该是cesium-native构建出来的obj文件，默认的Deployment Target和UE的不匹配（12.0和10.15的区别）。
2) 打开Terminal，cd到extern目录
extern目录里面，至少有一个cesium-native目录，还有一个CMakeList.txt文件
下面是官方文档原文，假设的是你clone下来的源码保存的目录是：~/dev/cesium-unreal-samples/Plugins/cesium-unreal

Change to the~/dev/cesium-unreal-samples/Plugins/cesium-unreal/externdirectory

3) 生成工程
在Ternimal中，执行下面的命令。
意思是通过cmake工具，在&#34;build&#34;目录中，生成用于构建的工程，构建配置是Release（如何构建Debug版，官方文档也给出了）
cmake -B build -S . -DCMAKE_BUILD_TYPE=Release4) 构建代码，等进度条结束
在Ternimal中，执行下面的命令
在上面的指令生成了工程之后，这个指令的意思就是真正执行编译了
cmake --build build --target install3. 构建插件

cesium-native构建完毕之后，就可以构建CesiumForUnreal插件了
右键选中.uproject文件，点击“服务”-&#34;Generate Xcode Project&#34;，就可以生成绿框内的.xcworkspace这个XCode工程文件了。如下图：

然后就可以打开.xcworkspace文件，开始使用XCode编译项目了，这就和普通的UE C++项目的编译一样了。
构建Windows版

1. 构建cesium-native

1) 修改CMakeList.txt
修改extern/CMakeList.txt，在下面的位置，插入一行set(CMAKE_CXX_FLAGS&#34;${CMAKE_CXX_FLAGS} /wd4819&#34;)
elseif (${CMAKE_SYSTEM_NAME} STREQUAL &#34;Windows&#34;)
  # Unreal Engine adds /Zp8 in 64-bit Windows builds to align structs to 8 bytes instead of the
  # default of 16 bytes. There&#39;s this nice note in the documentation for that option:
  # Don&#39;t change the setting from the default when you include the Windows SDK headers, either
  # by using /Zp on the command line or by using #pragma pack. Otherwise, your application may
  # cause memory corruption at runtime.
  # (https://docs.microsoft.com/en-us/cpp/build/reference/zp-struct-member-alignment?view=msvc-160)
  # Yeah that&#39;s not just the Windows SDK, but anything that passes structs across the boundary
  # between compilation units using different versions of that flag. We compile cesium-native
  # with this same option to avoid super-dodgy and hard to debug issues.
  set(CMAKE_CXX_FLAGS &#34;${CMAKE_CXX_FLAGS} /Zp8&#34;)
  # 下面这行是新增的，意思就是，忽略4819这个warning
  set(CMAKE_CXX_FLAGS &#34;${CMAKE_CXX_FLAGS} /wd4819&#34;)
endif()解释：
这一步是为了解决后面的构建步骤中，解决warning C4819（看起来项目是配置了warning as error，所以这个warning会导致编译失败），如下：
warning C4819: 该文件包含不能在当前代码页(936)中表示的字符。请将该文件保存为 Unicode 格式以防止数据丢失（目前没有去研究，为什么中文系统下面，会报上面的warning）
解决方案：
看GitHub上面，有人提了issue(https://github.com/CesiumGS/cesium-unreal/issues/702)，有人建议修改代码。
其实只要在用CMake生成工程的时候，配置忽略指定的warning就可以了。
2) 生成工程&构建cesium-native
在解决了4819这个warning之后，只要参考官方文档《developer-setup-windows》，来构建cesium-native就可以了。
（文档中提到的Visual Studio，VSCode，CMake等方法，应该都可以）
2. 构建插件

cesium-native编译完毕之后，就可以像正常的编译UE C++项目一样来进行编译了：
右键选择.uproject，点击&#34;Generate Visual Studio project files&#34;，然后打开.sln文件，编译即可。

写在最后

直接从Launcher启动，省去在IDE中编译
其实在cesium-native正确编译之后，直接从Epic Games Launcher中，打开我们刚才新建的项目，会提示我们CesiumForUnreal插件需要编译，点击确定，UE也可以自动将插件编译完毕，启动项目。
不过如果发生了编译错误，还是在IDE中查看解决问题是最方便的。
通过命令行参数修改，取代对CMakeList.txt文件的直接修改？
——这里我没有测试是否可以直接通过调用cmake的时候，通过命令行参数是否可以直接指定，就简单粗暴的采取了修改CMakeList.txt文件的方法

		自动登录	找回密码
密码			立即注册

在macOS和Windows上，从源码构建Cesium for Unreal插件 ...

本帖子中包含更多资源