使用Urho3D库

项目脚手架

本节假设您希望为自己的下游项目重用Urho3D构建系统。但是，如果您的项目已经有一个不同的构建系统，并且您只是想将Urho3D库用作外部库，那么您可能需要跳到下一节使用pkg配置而不是CMake。

首先，将项目结构与Urho3D项目类似，如下所示。虽然这不是强制性的，但它应该会增加为Urho3D项目设计的CMake模块也能为您的项目开箱即用的机会。CMake和我们的CMake模块区分大小写。建议您的项目遵循与Urho3D项目相同的命名约定，即使主机系统中的文件系统不区分大小写。

<PROJECT_ROOT>/
 ├ bin/
 │  ├ Data/
 │  └ CoreData/
 ├ CMake/
 │  ├ Modules/
 │  └ Toolchains/
 ├ CMakeLists.txt
 ├ *.cpp and *.h
 └ *.bat or *.sh

物理项目根目录也是CMake术语中的逻辑项目源树，您的项目主CMakeLists.txt应该位于该目录中。“bin”目录应包含您自己资产的“Data”和“CoreData”资源子目录。您必须将Urho3D项目根目录（或Urho3D SDK安装，可在“share/Urho3D/CMake”中找到）中的“CMake”子目录复制（或符号链接）到项目根目录。您可能还想将Urho3D项目根目录（或Urho3D SDK安装，可在“share/Urho3D/scripts”中找到）中的构建脚本复制（或符号链接）到项目根目录，除非您只想使用cmake-gui进行自己的项目配置和生成。或者，您可以将Urho3D项目根目录添加到主机系统中的PATH环境变量中，以使构建脚本随处可见。构建脚本与Urho3D CMake模块和工具链一起工作，以配置和生成初始项目构建树。支持源外生成树（推荐）和非源外生成目录树。请注意，当您配置项目时（通过构建脚本之一或通过cmakegui），您只能传递适用于下游项目的build选项。请注意，冲突的构建选项将被忽略。

在您自己的项目根目录中，创建一个主CMakeLists.txt文件，并添加以下行：（用所需的实际名称替换MyProjectName和MyExecutableName）

# Set CMake minimum version
cmake_minimum_required (VERSION 3.10.2)
 
# Set project name
project (MyProjectName)
 
# Set CMake modules search path
set (CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/cmake/Modules)
 
# Include UrhoCommon.cmake module after setting project name
include (UrhoCommon)
 
# Define target name
set (TARGET_NAME MyExecutableName)
 
# Define source files
define_source_files ()
 
# Setup target with resource copying
setup_main_executable ()

设置CMAKE_MODULE_PATH，以便CMAKE可以在您自己的项目中找到Urho3D项目提供的特定于Urho3D的CMAKE模块。UrhoCommon.cmake是定义所有可重用命令和宏的模块。它还提供了类似于Urho3D项目的项目跨平台构建能力。它通过自动查找特定于目标平台的所需软件库组件，并将项目配置为与特定于平台的编译器标志和定义一起使用。它利用CMake提供的以及Urho3D定制的FindXXX模块来完成工作。因此，尽早在项目中正确设置CMAKE_MODULE_PATH非常重要。

您自己的项目自然取决于Urho3D项目，或者更准确地说，它取决于Urho3D库。Urho3D库需要首先构建，以便稍后您自己的项目可以找到它。当使用GCC/Clang或其衍生产品时，Urho3D静态库和共享库都可能在同一位置构建/安装并共存。在这种情况下，FindUrho3D.cmake模块（负责查找Urho3D软件库组件并由UrhoCommon.cmake模块自动调用的模块）优先于首先查找静态库类型而不是共享库类型。但是，可以使用URHO3D_LIB_TYPE构建选项来覆盖此优先级。使用MSVC编译器时，静态库和共享库不能在同一位置生成/安装，因为静态库和导入库具有相同的文件扩展名。但是，对于MSVC，可以在同一位置构建/安装静态或共享库类型的Release和Debug版本。在这种情况下，FindUrho3D.cmake模块将在您的项目中自动使用Release和Debug版本，分别用于Release和Debug构建配置，而无需用户干预。

当您构建Urho3D库时，您可以选择将库安装到文件系统中的安装位置，就像Urho3D是一个SDK一样，或者您可以将库留在其构建树中的位置。因此，有两种方法可以将项目链接到Urho3D库作为外部库。然而，从项目的角度来看，这两种方法确实没有区别。FindUrho3D.cmake模块不仅能够从Urho3D SDK安装中查找Urho3D库，还可以直接从任何Urho3D项目构建树中查找。在安装在系统范围默认位置的Urho3D SDK中搜索时，无需设置其他变量。在非默认SDK安装中搜索或在任何Urho3D项目构建树中搜索时，需要通过Urho3D_HOME环境变量（在主机系统中设置）或Urho3D-HOME构建选项（在命令行或cmakegui中使用-D设置）提供实际位置。也就是说，使用URHO3D_HOME提示构建系统定位库。

define_source_files（）和setup_main_executable（）是特定于Urho3D的宏。define_source_files（）宏是glob当前目录中所有源文件的简写。它相当于以下命令：

file (GLOB CPP_FILES *.cpp)
file (GLOB H_FILES *.h)
set (SOURCE_FILES ${CPP_FILES} ${H_FILES})

setup_main_executable（）宏然后使用SOURCE_FILES和TARGET_NAME变量设置一个新的CMake目标，该目标可以在Urho3D支持的所有平台上运行。请确保您的项目名称和目标名称都不是“Urho3D”，因为此名称仅为Urho3D项目保留。

如果您已经按照上面概述的方式准备了新项目，那么您可以使用Urho3D项目的构建说明来构建自己的项目。

有时，您可能希望有不同的资源目录来包含您的资产，而不是Urho3D项目按惯例使用的资源目录。例如，可以按场景排列它们，如下所示：

<PROJECT_ROOT>/
 ├ bin/
 │  ├ Scene1/
 │  ├ Scene2/
 │  └ Core/
 ├ ...

如果是这种情况，那么您必须告诉构建系统和Urho3D库（更具体地说是Engine类）资源路径的位置。使用上面的示例，您必须通过显式调用define_resource_dir（）宏并向其传递glob资源目录的选项来告诉构建系统。define_resource_dis（）宏实际上是在内部调用的，默认选项是基于Urho3D项目约定的glob目录名，但您的项目可以通过在CMakeLists.txt中显式调用来覆盖该选项。

...
 
# Define source files
define_source_files ()
define_resource_dirs (GLOB_PATTERNS ${CMAKE_SOURCE_DIR}/bin/Scene* ${CMAKE_SOURCE_DIR}/bin/Core)
 
...

您还需要通知Urho3D库您有非常规资源目录路径。通过在编译时以编程方式或在运行时通过“-p”命令行选项设置EP_RESOURCE_PATHS引擎参数，可以做到这一点。在这种情况下，您可以将其设置为“场景1；场景2；核心”，而不是默认的“数据；核心数据”。

您的项目可能还希望将资源目录存储在其他位置，而不是可执行二进制文件所在的“bin”目录中。例如，在创建macOS/iOS/tvOS捆绑包时，所有资产都会自动绑定到可执行二进制文件所在的外部目录中。事实上，您可以将它们放在几个单独的父目录中，而不仅仅是一个。这就是EP_RESOURCE_PREFIX_PATHS引擎参数和“-p”命令行选项出现的地方。使用此选项，您可以定义一个备用资源前缀路径，在查找资产之前，您的资源路径将在该路径前面加上前缀。

使用pkg配置而不是CMake

如果由于某种原因，您无法在项目中使用CMake，您可以在“Urho3D.pc”配置文件（作为SDK安装的一部分安装）的帮助下，使用“pkg配置”工具将项目配置为从SDK安装中编译并链接Urho3D库。如果Urho3D SDK正在安装到本地位置（如/usr/local）或非默认位置，则很可能需要指定PKG_CONFIG_PATH环境变量以指向配置文件的位置，这样才能正常工作。“Urho3D.pc”文件包含有关如何正确配置编译器和链接器的重要信息。即使不使用“pkg配置”工具，也可以将该信息作为配置自己项目的参考。

以下是基于64位RedHat的发行版的几个调用示例，其中包含本地安装：

# To get installed Urho3D version
PKG_CONFIG_PATH=/usr/local/lib64/pkgconfig pkg-config --modversion Urho3D
 
# To compile and link natively in one liner
c++ -o Urho3DPlayer Urho3DPlayer.cpp `PKG_CONFIG_PATH=/usr/local/lib64/pkgconfig pkg-config --cflags --libs Urho3D`
 
# To compile and link natively but in separate steps
export PKG_CONFIG_PATH=/usr/local/lib64/pkgconfig
c++ -c Urho3DPlayer.cpp `pkg-config --cflags Urho3D`
c++ -o Urho3DPlayer Urho3DPlayer.o `pkg-config --libs Urho3D`
 
# To cross-compile and link for Raspberry Pi platform
export CC=${RPI_PREFIX}-c++
export PKG_CONFIG_SYSROOT_DIR=${RPI_SYSROOT}
export PKG_CONFIG_PATH=${RPI_SYSROOT}/usr/local/lib/pkgconfig
$CC -o Urho3DPlayer Urho3DPlayer.cpp `pkg-config --cflags --libs Urho3D`
 
# To cross-compile and link for Windows platform using MinGW cross-compiler (in Debug configuration)
export CC=${MINGW_PREFIX}-c++
export PKG_CONFIG_SYSROOT_DIR=${MINGW_SYSROOT}
export PKG_CONFIG_PATH=${MINGW_SYSROOT}/usr/local/lib/pkgconfig
$CC -o Urho3DPlayer_d.exe Urho3DPlayer.cpp `pkg-config --variable CFLAGS_DEBUG Urho3D` `pkg-config --cflags --libs Urho3D`