如何编译Urho3D引擎

构建先决条件

尽管所有必需的第三方库都包含在源代码中，但在成功构建Urho3D之前，必须满足系统级依赖关系：

• 对于Windows，需要安装2010年6月的DirectX SDK。如果在Visual Studio 2012或更高版本上构建，则无需执行此操作，因为该版本安装了带有必要DirectX文件的Windows SDK。
• 对于Linux，请从下面的每个软件组件类别中安装一个或多个开发包。在64位系统上构建为32位还需要安装32位版本的开发库。

• 对于Raspberry Pi，请遵循上述Linux的构建前提条件，显示服务器除外。复盆子Pi操作系统通常已预装Broadcom视频核心显示服务器。除此之外，还必须安装此软件包：libevdev2（Raspbian）或libevdev（Pidora）。

• 对于macOS、iOS和tvOS，Xcode开发人员工具包应包含所有必要的内容。确保还安装了Xcode命令行工具。Homebrew需要安装“cmake”和一些可选的开发包，如ccache、doxygen、graphviz和readline。

• 对于Android，Android Studio（4.0版或更高版本）应包含所有必要的内容。确保Android NDK r21d与Android SDK管理器一起安装，并且主机上安装了CMake 3.17.3版。如果您的主机具有不同的NDK和CMake版本，请相应地调整“buildSrc/src/main/kotlin/UrhoCommon.kt”。

• 对于Web，Emscripten SDK（1.39.0或更高版本）需要在激活上游LLVM WASM后端的情况下安装。在Windows主机上，还需要MinGW-W64编译器工具链。

要运行Urho3D，最低系统要求如下：

• Windows:CPU支持SSE2指令，Windows XP或更高版本，DirectX 9.0c，GPU支持Shader Model 3。
• macOS：支持SSE2指令的CPU，支持OpenGL 2.0的GPU，EXT_framebuffer_object和EXT_packed_depth_template扩展，OS版本10.9或更高版本。
• Linux：任何CPU（如果支持，将使用MMX、3DNow！和SSE/SSE2指令）、支持OpenGL 2.0的GPU、EXT_framebuffer_object和EXT_packed_depth_template扩展。
• 树莓派：型号B版本2.0，至少128 MB 512 MB SDRAM分配给GPU。
• Android:Jelly Bean 4.1（API级别16）或更高版本，支持OpenGL ES 2.0的GPU。iOS:armv7、iPhone 3GS或更高版本，包括iPad、OS版本3或更高。
• tvOS:arm64，操作系统版本9或更高版本。
• Web：具有快速JavaScript引擎和WebGL支持的现代HTML5浏览器。运行WebAssembly目标需要夜间构建的浏览器。

通过禁用SIMD指令集，可以消除SIMD需求，请参阅下面的URHO3D_SSE构建选项。对于使用GCC/Clang编译器工具链的Linux平台，MMX和3DNow！当选项可用时，可以使用URHO3D_MMX和URHO3D_3DNOW构建选项为较旧的CPU启用扩展（默认情况下禁用）。x86_64 ABI上的MMX和SSE扩展始终处于启用状态，因此在x86_64 ABI上不存在URHO3D_MMX和URHO3D_SSE构建选项（它们始终处于打开状态）。还要注意，当3DNow！或SSE扩展已启用，因此在这种情况下禁用URHO3D_MMX构建选项无效。

NEON指令集在可用时默认使用。请参阅ANDROID_ABI和RPI_ABI构建选项，分别了解ANDROID和Raspberry Pi平台的更多详细信息。NEON指令集始终用于iOS和tVOS平台。

CMake公司(https://www.cmake.org)需要配置和生成Urho3D项目构建树。最低要求版本为3.10.2。但是，建议使用最新的CMake版本，尤其是在针对使用最新Xcode版本的苹果平台时。这是因为众所周知，苹果会改变Xcode的内部工作，而很少考虑其他第三方构建工具，如CMake。

编译脚本

由于这是一个跨平台项目，我们在“script”目录中为最常见的用例提供了许多构建脚本，Android平台除外。shell脚本以扩展名*.sh结尾，用于在类Unix主机系统（Linux、Mac甚至复盆子Pi）中构建Urho3D项目，而批处理文件以*.bat结尾，仅用于Windows主机系统。它们只提供了一种方便的方法来调用CMake来处理CMakeLists.txt文件。它们的使用不是必须的，因为您也可以通过cmakegui或IDE（如果IDE支持）调用CMake来执行同样的操作。

基本用法如下：

<script-name> /path/to/build-tree [build-options]

其中＜script name＞是提供的构建脚本之一。/path/to/build树是CMake为项目生成生成树的位置。现在支持源外构建树和非源外构建路径。下一节将详细介绍构建选项。

生成生成树后，可以再次使用生成脚本，通过传递不同的生成选项来重新配置它。你可以按照上面的基本用法来做；或者首先将工作目录更改为已生成的构建树并使用以下语法：

<script-name> [build-options]

当然，您必须为构建脚本指定一个完全限定的路径，这样才能正常工作。或者，您可以将Urho3D项目根目录的路径添加到path环境变量，以使构建脚本在任何地方都可用。

我们的CMakeLists.txt文件设计用于CMake支持的大多数生成器：Makefile、Xcode、VS，甚至Ninja。要使用的构建脚本取决于您打算在构建树中使用的CMake生成器（和工具链）。对于本机构建，您可以只使用cmake_generic.sh或cmake_gneric.bat来让cmake检测并决定自动使用哪个生成器。CMake应默认在Linux和Mac主机系统上使用“Unix Makefile”生成器，安装时应默认在Windows主机系统上安装32位“Visual Studio”生成器。

自Urho3D 1.8版以来，我们已与Gradle Android平台构建系统集成。我们在项目根目录中提供了Gradle包装脚本和批处理文件，以与Gradle构建系统交互。目前，它是唯一一个不允许用户直接与CMake构建系统交互的平台。有关详细信息，请参阅Android构建过程。

编译选项

在调用构建脚本或使用cmakegui交互配置项目时，可以定义许多构建选项。要在命令行界面上使用这些构建选项之一，请以不带引号的“-DOPTION=VALUE”格式传递。大多数构建选项都是布尔变量，其中将其值设置为0表示禁用功能或将选项设置为false，而1表示启用功能或将其设置为true。下表显示了所有可用的构建选项及其默认值。非布尔构建选项通常没有任何默认值，并且在表中用“-”标记。但是，一些标记为“*”的构建选项会根据其他变量或外部因素的值设置不同的默认值。

注意，CMake在初始配置步骤后缓存指定的构建选项值。CMake将在后续配置中使用缓存的值。不需要反复指定相同的生成选项。但是，一旦缓存了非默认的构建选项值，则只能通过显式重置该值将其还原为默认值。也就是说，仅通过不传递相应的构建选项不会将其还原回默认值。将所有构建选项还原为默认值的一种方法是，通过以构建树的位置作为第一个参数执行CMake_clean.bat或CMake_clean.sh，或者在构建树本身中执行它，来清除CMake缓存。

本机生成过程

Urho3D的本地构建有两个步骤：

1.在根目录（也是CMake的源树）中运行CMake，并指定生成构建树的首选生成器和工具链。您可以在各自的主机系统上使用cmakegui或提供的批处理文件或shell脚本。所有批处理文件和shell脚本都希望构建树位置作为第一个参数传递，或者在重新配置现有构建树时在构建树本身中执行它们。

• Windows: cmake_vs20xx.bat, cmake_mingw.bat, cmake_codeblock.bat, cmake_codelite.bat cmake_ninja.bat, or cmake_generic.bat
• macOS: cmake_xcode.sh, cmake_codeblocks.sh, cmake_codelite.sh, cmake_ninja.sh, or cmake_generic.sh
• Linux: cmake_eclipse.sh, cmake_codeblocks.sh, cmake_codelite.sh, cmake_ninja.sh, or cmake_generic.sh
• Raspberry Pi: cmake_rpi.sh, cmake_eclipse.sh, cmake_codeblocks.sh, cmake_codelite.sh, cmake_ninja.sh, or cmake_generic.sh

使用您选择的IDE在构建树中打开CMake生成的项目文件或解决方案文件。更改构建配置（调试/发布）并将内置目标更改为ALL_build以构建所有目标。

• Visual Studio: open Urho3D.sln
• Xcode: open Urho3D.xcodeproj
• CodeBlocks: open Urho3D.cbp
• Eclipse: import project using File|Import "Existing Projects into Workspace"
• Alternatively, on make-based toolchains like GCC / MinGW, execute make in the build tree

注意，Eclipse需要CDT插件来构建C/C++项目。

在Windows平台上，Urho3D可以使用Direct3D 9（默认）、Direct3D 11或OpenGL渲染。其他平台始终使用OpenGL。使用CMake选项“-DURHO3D_D3D11=1”或“-DURRHO3D_OPENGL=1”选择非默认API。

如果使用MinGW进行编译，则可能需要单独获取DirectX标头。可以将它们复制到MinGW安装中，例如从以下包中复制：https://www.libsdl.org/extras/win32/common/directx-devel.tar.gz.这些将丢失一些与着色器编译相关的头文件，因此MinGW构建将默认使用OpenGL。要在Direct3D模式下构建，需要MinGW-w64端口：http://mingw-w64.sourceforge.net/.使用它，可以使用“-DURHO3D_OPENGL=0”构建选项启用Direct3D。

构建完成后，可以从构建树中的bin子目录运行程序。其中包括Urho3D播放器应用程序，它可以运行应用程序脚本、工具和C++示例应用程序（如果已启用）。

macOS可执行文件可以使用绑定到单个应用程序目录中的所有资源来构建。为了启用此功能，请在为macOS平台配置构建树时设置URHO3D_MOSX_BUNDLE构建选项。只需从Finder双击即可启动捆绑应用程序，无需担心设置“资源前缀路径”。这是因为URHO3D_PREFIX_PATH环境变量已在内部设置为指向应用程序中已绑定的资源目录。但是，请注意，如果您没有通过Apple“启动服务”启动应用程序（例如，在调试时或通过CLI直接在捆绑的应用程序目录中调用可执行文件），则仍需要如前一段所述手动设置“资源前缀路径”。注意，Mach-O通用二进制目标只能在使用Xcode生成器时构建。所有其他生成器只构建单拱二进制目标。

默认情况下，Windows可执行文件构建为Windows应用程序，而不是控制台应用程序。可以设置URHO3D_WIN32_CONSOLE生成选项以覆盖此选项。作为控制台应用程序，可执行文件的标准输出和标准错误流被重定向到控制台。

要从Visual Studio调试器运行Urho3D播放器应用程序，请将Urho3DPlayer项目设置为启动项目，并在“Properties财产”->“调试”->“命令”中输入其相对路径和文件名：../..//此外，强烈建议在调试->命令参数中输入-w。这允许在窗口模式下启动：如果它不运行到异常或断点，则会令人讨厌，因为鼠标光标可能会被隐藏。要真正让Urho3DPlayer应用程序做一些有用的事情，必须向它提供应该加载和运行的脚本文件的名称。例如，可以尝试以下参数：

Scripts/NinjaSnowWar.as -w

要在Linux上从Eclipse运行，请在Project Explorer中找到并选择Urho3DPlayer可执行文件。从菜单中，选择“运行配置”为“C/C++应用程序”创建新的启动配置。切换到“Arguments”选项卡，指定Urho3DPlayer可执行文件所需的参数。

要在Mac OS X上从Xcode运行，请编辑Product Scheme以在“Info”选项卡中设置“run”设置以执行“Urho3DPlayer”。在“Arguments”选项卡中，指定Urho3DPlayer可执行文件所需的参数。确保选中要激活的参数条目上的复选框。

本机64位版本

当使用MSVC编译器时，Urho3D通用CMake模块将构建树配置为默认目标32位平台。当使用其他非MSVC编译器（如GCC或Clang）时，模块会根据构建树中选择的工具链将默认值设置为32位或64位。但是，您可以使用“URHO3D_64BIT”构建选项覆盖默认值，即显式将选项设置为“0”（对于32位）和“1”（对于64位）。

库建设

本节不适用于Android平台，该平台使用maven publish Gradle插件发布Android库（AAR）以及其他工件。

构建过程首先构建Urho3D库目标（静态或共享）。然后，该库与其他目标（如引用Urho3D作为外部库之一的工具和样本）链接。Urho3D库类型默认为静态，因此构建过程将生成与先前版本相同的独立可执行文件。可以使用“Urho3D_LIB_type”构建选项更改Urho3D库类型。

要将Urho3D库安装为SDK，请使用通常的“makeinstall”命令。Visual Studio解决方案和Xcode项目中有一个名为“install”的等效内置目标来执行SDK安装。当您希望应用程序始终链接到Urho3D库的“稳定”安装版本，同时保持Urho3D项目根目录树与原始/主目录同步时，这可能很有用；或者当您希望同一主机系统中的其他用户使用已安装的Urho3D SDK，而不是再次从源代码构建时。

Windows主机上的默认安装前缀为“c:\Program Files\Urho3D”，所有其他非Windows主机上为“/usr/local”。您可以使用CMAKE_INSTALL_PPREFIX构建选项来更改此前缀路径。但是，在交叉编译时，您可能实际上希望通过提供DESTDIR环境变量来更改最终安装目标，而不是直接更改CMAKE_INSTALL_PPREFIX变量，特别是当使用Urho3D库作为共享库类型时，因为已安装的可执行文件的RPATH相对于CMAKE_INSTOLL_PPREIX进行了调整。DESTDIR环境变量不适用于Windows主机上的安装，即它只能使用CMAKE_INSTALL_PPREFIX变量来更改最终安装目标。然而，这并不是一个损失，因为Windows平台没有RPATH调整，但因此Urho3D.dll将安装在与安装的可执行文件相同的目录中。

如果您的应用程序由多个模块（主可执行文件+其他共享库）组成，并且所有模块都链接到Urho3D，那么Urho3D应该构建为共享库。这是因为Urho3D包含一些敏感的静态数据值，例如主线程的ID，如果由于多个静态链接而复制这些值，则这些值将无法正常工作。

文档构建

如果设置了“URHO3D_DOCS”或“URHO3D _DOCS_QUIET”构建选项，则正常构建不仅会自动构建URHO3D二进制文件，而且还会自动生成URHO3D文档。如果未设置该选项，则仍然可以通过手动调用“makedoc”命令或在IDE中使用其等效的内置目标来构建文档。

文档构建的附加先决条件是Doxygen。如果希望在文档中生成图形图，也可以使用Graphviz（可选）。Windows主机系统上的MSVC用户可以安装HTML Help Workshop（可选）以获取压缩的帮助文件（*.chm）。如果主机系统中没有可选工具，则相应地跳过相应的生成过程。用于转储默认脚本子系统的AngelScript API的内部主机工具和LuaScript API（当LuaScript子系统也处于启用状态时）是在构建所有本机工具的同时构建的。当构建树被配置为不构建任何主机工具时，“doc”目标将简单地指示Doxygen处理已在存储库中预先生成的现有API转储文件。

Clang工具构建（实验）

如果设置了“URHO3D_CLANG_TOOLS”构建选项，那么CMake将生成一个特殊的构建树，用于开发CLANG工具。在执行此操作之前，必须在主机系统中安装LLVM/Crang版本3.9.0的开发软件包。或者，您可以从Clang的SVN repo下载LLVM/Crang源文件，构建并安装到主机系统中。如果它未安装在系统范围的安装位置，则使用LLVM_CLANG_ROOT环境变量指向此自定义位置的根路径（根目录是包含bin、lib、include和share子目录的父目录）。您可能需要遵循克兰的入门指南来指导您完成这一过程。

也许安装Clang最简单的方法是使用Emscripten SDK。如果您已经在主机系统中构建了Emscripten SDK，则还可以通过导航到Fastcomp/Crang构建树（例如emsdk_portable/crang/Fastcomp/build_master_64）并发出“make install”命令，使用SDK安装Fastcomp/Clang。然而，Emscripten SDK不会自动签出“额外的Clang工具”，因此在发出“make install”之前，您可能需要后退一步，手动将“额外的Clang工具”签入Fastcomp/Crang源树中的相应子目录（例如emsdk_portable/crang/Fastcomp/src/tools/Clang/tools/extra），然后照常重建和安装。使用Fastcomp/Crang对我们来说很好，因为我们只想将Clang用作第三方库而不是编译器。

对于Linux用户来说，如果您需要完整的命令行界面功能（如命令历史记录和clang查询工具中的命令编辑），请安装“libedit”的开发软件包。在生成任何LLVM/Crang或Fastcomp/Crang构建树之前安装它。

检查Source/Clamg Tools/CMakeLists.txt以获取当前可用或正在开发的目标列表。普通生成目标在这个特殊的生成树中无法正常工作。另请参见https://github.com/urho3d/Urho3D/issues/887了解更多关于当前发展计划的信息，并在那里留下评论，如果您想帮助促进发展。

编译Direct3D 着色器

使用Windows 8 SDK（Visual Studio 2012+）为Direct3D9构建时，请将d3dcompiler_46.dll从“C:\Program Files（x86）\Windows Kits\8.0\bin\x86”复制到构建树的“bin”目录，以便Urho3D可执行文件正确运行。为Direct3D11构建时，将d3dcompiler_47.dll从“C:\Program Files（x86）\Windows Kits\8.1\bin\x86”复制到“bin”目录。在这两种情况下，如果将Urho3D编译为64位，请改为从“bin\x64”目录复制。

OpenGL不依赖于单独的着色器编译器DLL。

Dock化构建环境（仅在*nix主机上进行实验）

每个目标平台的构建前提都是不同的，这是可以理解的。如果您希望使用单个构建/主机系统以多个平台为目标，那么您不仅必须在主机系统中安装所有必备组件，还必须能够正确配置构建环境，使它们不会相互干扰。我们现在提供了一种新的构建机制，我们称之为“码头化构建环境”，它解决了上述两个障碍，而不是手动配置构建环境。目前，dockerized构建环境（简称DBE）支持以下平台：Linux、MinGW（Windows）、Android、Raspberry Pi、通用ARM和Web。

DBE需要podman（来自发行版提供的存储库，推荐）或Docker CE（来自https://docs.docker.com/install/)安装在主机系统中，这就是它所需要的。

要使用DBE，请在项目根目录中执行script/dockerized.sh，指定平台名称（linux|mingw|android|rpi|arm|web）作为强制参数，然后可选地在docker容器中调用另一个命令。默认情况下，该命令是为指定的目标平台生成生成树，然后生成它。在执行dockerized.sh之前，可以通过使用主机系统中的环境变量来指定Urho3D生成选项。这也可以及时完成，例如“Urho3D_LIB_TYPE=SHARED script/dokerized.sh-mingw”。来自DBE的构建工件可以在正常构建环境的通常位置找到。事实上，构建工件的功能和工作方式也应该与使用传统方式构建的一样。

DBE设计用于Urho3D项目及其重用Urho3D构建系统的下游项目。