 |
U3D
Open-source, cross-platform 2D and 3D game engine built in C++
|
|
U3D
Open-source, cross-platform 2D and 3D game engine built in C++
|
Although all required third-party libraries are included as source code, there are system-level dependencies that must be satisfied before Urho3D can be built successfully:
To run Urho3D, the minimum system requirements are:
SIMD requirement can be eliminated by disabling the use of SIMD instruction set, see URHO3D_SSE build option below. For Linux platform using GCC/Clang compiler toolchain, the MMX and 3DNow! extensions can be enabled for older CPUs by using URHO3D_MMX and URHO3D_3DNOW build options when the option is available (they are disabled by default). The MMX and SSE extensions on x86_64 ABI are always enabled, so the URHO3D_MMX and URHO3D_SSE build option do not exist on x86_64 ABI (they are always on). Also note that MMX extension is effectively enabled when 3DNow! or SSE extension is enabled, so disabling URHO3D_MMX build option in this case has no effect.
The NEON instruction set will be used by default whenever it is available. See the ANDROID_ABI and RPI_ABI build options for more detail for Android and Raspberry-Pi platforms, respectively. The NEON instruction set is always used on iOS and tVOS platforms.
CMake (https://www.cmake.org) is required to configure and generate the Urho3D project build tree. The minimum required version is 3.10.2. However, it is recommended to use the latest CMake version available, especially when targeting Apple platforms using its latest Xcode version available. This is because Apple is known to change the internal working of Xcode with little regards to other third party build tools, such as CMake.
As this is a cross-platform project, we have provided a number of build scripts in the "script" directory for the most common use cases, with the exception for Android platform. The shell scripts end with extension *.sh are meant for building Urho3D project in a Unix-like host system (Linux, Mac, and even Raspberry Pi), while the batch files end with *.bat are meant for Windows host system only. They only provide a convenient way to invoke CMake to process our CMakeLists.txt files. Their usage is not a must as you can also invoke CMake to do the same via cmake-gui or via your IDE when your IDE supports that.
The basic usage is as follows:
<script-name> /path/to/build-tree [build-options]
Where the <script-name> is one of the provided build script. The /path/to/build-tree is where CMake will be generating the build tree for the project. Both out-of-source build tree and non out-of-source build tree path are now supported. The build options are described in detail in the next section below.
After the build tree has been generated, you can use the build script again to reconfigure it by passing different build options. You can do so as the basic usage above; or by first change the working directory to the already generated build tree and use the following syntax:
<script-name> [build-options]
Naturally you have to specify a fully qualified path to the build script for this to work. Alternatively, you can add the path to the Urho3D project root to the PATH environment variable in order to make the build scripts available everywhere.
Our CMakeLists.txt files are designed to work with most of the generators supported by CMake: Makefile, Xcode, VS, and even Ninja. Which build script to use is determined by which CMake generator (and toolchain) you intend to use in your build tree. For native build, you can just use cmake_generic.sh or cmake_generic.bat to let CMake to detect and decide which generator to use automatically. CMake should default to use "Unix Makefiles" generator on Linux and Mac host systems and it should default to use 32-bit "Visual Studio" generator on Windows host system when it is installed.
Since Urho3D version 1.8 we have integrated with Gradle build system for Android platform. We have provided Gradle wrapper script and batch file at the project root directory to interface with Gradle build system. Currently it is the only platform that does not allow user to interface with CMake build system directly. See Android build process for more detail.
A number of build options can be defined when invoking the build scripts or when configuring the project interactively using cmake-gui. To use one of these build options on the command line interface, pass it in this format "-DOPTION=VALUE" without the quotes. Most of the build options are boolean variables where setting their values to 0 means disabling a feature or setting an option to false, while 1 means enabling a feature or setting an option to true. The table below shows all the available build options and their default values. Non-boolean build options generally do not have any default values and are marked with '-' in the table. However, a few build options marked with '*' have their default values set differently based on the value of other variables or external factors.
| Build Option | Value | Description |
|---|---|---|
| ARM | 0 | Configure project using ARM cross-compiler toolchain (cmake_generic.sh only), cmake-gui users need to specify ARM toolchain file for cross-compiling explicitly |
| RPI | 0 | Configure project using Raspberry Pi cross-compiler toolchain (cmake_generic.sh only), cmake-gui users need to specify RPI toolchain file for cross-compiling explicitly |
| MINGW | 0 | Configure project using MinGW (32-bit or 64-bit) cross-compiler toolchain (cmake_generic.bat and cmake_generic.sh only), cmake-gui users need to specify MinGW toolchain file for cross-compiling explicitly |
| WEB | 0 | Configure project using Emscripten cross-compiler toolchain (cmake_generic.bat and cmake_generic.sh only), cmake-gui users need to specify Emscripten toolchain file for cross-compiling explicitly |
| IOS | 0 | Configure project for targeting iOS platform (cmake_generic.sh and cmake-gui only) |
| TVOS | 0 | Configure project for targeting tvOS platform (cmake_generic.sh and cmake-gui only) |
| URHO3D_64BIT | * | Enable 64-bit build, the default is set based on the native ABI of the chosen compiler toolchain |
| URHO3D_ANGELSCRIPT | 1 | Enable AngelScript scripting support |
| URHO3D_FORCE_AS_MAX_PORTABILITY | 0 | Use generic calling convention for AngelScript on any platform |
| URHO3D_LUA | 1 | Enable Lua scripting support |
| URHO3D_LUAJIT | 1 | Enable Lua scripting support using LuaJIT (check LuaJIT's CMakeLists.txt for more options) |
| URHO3D_LUAJIT_AMALG | * | Enable LuaJIT amalgamated build (LuaJIT only); default to true when LuaJIT is enabled |
| URHO3D_SAFE_LUA | 0 | Enable Lua C++ wrapper safety checks (Lua/LuaJIT only) |
| URHO3D_LUA_RAW_SCRIPT_LOADER | 0 | Prefer loading raw script files from the file system before falling back on Urho3D resource cache. Useful for debugging (e.g. breakpoints), but less performant (Lua/LuaJIT only) |
| URHO3D_IK | 1 | Enable inverse kinematics support |
| URHO3D_NETWORK | 1 | Enable Networking support |
| URHO3D_SSL | 0 | Enable HTTPS support for HttpRequest. Requires URHO3D_NETWORK build option to be enabled |
| URHO3D_SSL_DYNAMIC | 0 | Enables dynamic SSL library loading, requires URHO3D_SSL build option to be enabled |
| URHO3D_PHYSICS | 1 | Enable Physics support |
| URHO3D_PHYSICS2D | 1 | Enable Physics2D support |
| URHO3D_NAVIGATION | 1 | Enable Navigation support |
| URHO3D_URHO2D | 1 | Enable 2D rendering support |
| URHO3D_PLAYER | 1 | Build Urho3D script player |
| URHO3D_SAMPLES | 1 | Build sample applications |
| URHO3D_TOOLS | 1 | Build tools (native, RPI, and ARM on Linux only) |
| URHO3D_EXTRAS | 0 | Build extras (native, RPI, and ARM on Linux only) |
| URHO3D_DOCS | 0 | Generate documentation as part of normal build (the 'doc' builtin target can be used to generate documentation regardless of this option's value) |
| URHO3D_DOCS_QUIET | 0 | Generate documentation as part of normal build, suppress generation process from sending anything to stdout |
| URHO3D_PCH | 1 | Enable PCH support |
| URHO3D_DATABASE_ODBC | 0 | Enable Database support with ODBC, requires vendor-specific ODBC driver |
| URHO3D_DATABASE_SQLITE | 0 | Enable Database support with SQLite embedded |
| URHO3D_WEBP | 1 | Enable WebP image support |
| URHO3D_MMX | 0 | Enable MMX instruction set (32-bit Linux platform only); the MMX is effectively enabled when 3DNow! or SSE is enabled; should only be used for older CPU with MMX support |
| URHO3D_3DNOW | 0 | Enable 3DNow! instruction set (Linux platform only); should only be used for older CPU with (legacy) 3DNow! support |
| URHO3D_SSE | * | Enable SIMD instruction set (32-bit Web and Intel platforms only, including Android on Intel Atom); default to true on Intel and false on Web platform; the effective SSE level could be higher, see also URHO3D_DEPLOYMENT_TARGET and CMAKE_OSX_DEPLOYMENT_TARGET build options |
| URHO3D_MINIDUMPS | 1 | Enable minidumps on crash (VS only) |
| URHO3D_FILEWATCHER | 1 | Enable filewatcher support |
| URHO3D_HASH_DEBUG | 0 | Enable StringHash reversing and hash collision detection at the expense of memory and performance penalty |
| URHO3D_PACKAGING | 0 | Enable resources packaging support |
| URHO3D_PROFILING | 1 | Enable default profiling support |
| URHO3D_TRACY_PROFILING | 0 | Enable extended profiling support using Tracy Profiler; overrides URHO3D_PROFILING option |
| URHO3D_LOGGING | 1 | Enable logging support |
| URHO3D_THREADING | * | Enable thread support, on Web platform default to 0, on other platforms default to 1 |
| URHO3D_TESTING | 0 | Enable testing support |
| URHO3D_TEST_TIMEOUT | * | Number of seconds to test run the executables (when testing support is enabled only), default to 10 on Web platform and 5 on other platforms |
| URHO3D_OPENGL | 0 | Use OpenGL instead of Direct3D (Windows platform only) |
| URHO3D_D3D11 | 0 | Use Direct3D11 instead of Direct3D9 (Windows platform only); overrides URHO3D_OPENGL option |
| URHO3D_STATIC_RUNTIME | 0 | Use static C/C++ runtime libraries and eliminate the need for runtime DLLs installation (VS only) |
| URHO3D_WIN32_CONSOLE | 0 | Use console main() instead of WinMain() as entry point when setting up Windows executable targets (Windows platform only) |
| URHO3D_MACOSX_BUNDLE | 0 | Use MACOSX_BUNDLE when setting up macOS executable targets (macOS platform only) |
| URHO3D_LIB_TYPE | STATIC | Specify Urho3D library type, possible values are STATIC (default) and SHARED (not available for Emscripten) |
| URHO3D_SCP_TO_TARGET | - | Use scp to transfer executables to target system (RPI and generic ARM cross-compiling build only), SSH digital key must be setup first for this to work, typical value has a pattern of usr@tgt:remote-loc |
| URHO3D_UPDATE_SOURCE_TREE | 0 | Enable commands to copy back some of the generated build artifacts from build tree to source tree to facilitate devs to push them as part of a commit (for library devs with push right only) |
| URHO3D_GENERATEBINDINGS | 0 | Enable script API binding generation |
| URHO3D_USE_LIB64_RPM | 0 | Enable 64-bit RPM CPack generator using /usr/lib64 and disable all other generators (Debian-based host only, which uses /usr/lib by default) |
| URHO3D_USE_LIB_DEB | 0 | Enable 64-bit DEB CPack generator using /usr/lib and disable all other generators (Redhat-based host only, which uses /usr/lib64 by default) |
| URHO3D_HOME | - | Path to Urho3D build tree or SDK installation location (downstream project only) |
| URHO3D_DEPLOYMENT_TARGET | native | Specify the minimum CPU type on which the target binaries are to be deployed (non-ARM platform only), see GCC/Clang's -march option for possible values; Use 'generic' for targeting a wide range of generic processors |
| CMAKE_BUILD_TYPE | Release | Specify CMake build configuration (single-configuration generator only), possible values are Release (default), RelWithDebInfo, and Debug |
| CMAKE_INSTALL_PREFIX | * | Install path prefix, prepended onto install directories; default to 'c:/Program Files/Urho3D' on Windows host and '/usr/local' on all other non-Windows hosts |
| CMAKE_OSX_DEPLOYMENT_TARGET | - | Specify macOS deployment target (macOS platform only); default to current running macOS if not specified, the minimum supported target is 10.9 |
| IPHONEOS_DEPLOYMENT_TARGET | - | Specify iOS deployment target (iOS platform only); default to latest installed iOS SDK if not specified, the minimum supported target is 3.0 due to constraint from SDL library |
| APPLETVOS_DEPLOYMENT_TARGET | - | Specify AppleTV OS deployment target (tvOS platform only); default to latest installed tvOS SDK if not specified, the minimum supported target is 9.0 |
| MINGW_PREFIX | - | Prefix path to MinGW cross-compiler tools (MinGW cross-compiling build only) |
| MINGW_SYSROOT | - | Path to MinGW system root (MinGW only); should only be used when the system root could not be auto-detected |
| DIRECTX_INC_SEARCH_PATHS | - | Additional search paths to find DirectX headers (MinGW only) |
| DIRECTX_LIB_SEARCH_PATHS | - | Additional search paths to find DirectX libraries (MinGW only) |
| DIRECT3D_DLL_REDIST_SEARCH_PATHS | - | Additional search paths to find DirectX runtime DLL (MinGW only); should only be used for older MinGW version that still uses 'd3dcompiler_43.dll' or 'd3dcompiler_42.dll'. |
| RPI_PREFIX | - | Prefix path to Raspberry Pi cross-compiler tools (RPI cross-compiling build only) |
| RPI_SYSROOT | - | Path to Raspberry Pi system root (RPI cross-compiling build only) |
| RPI_ABI | * | Specify target ABI (RPI platform only), possible values are RPI0, RPI1, RPI2, RPI3, RPI4 |
| ARM_PREFIX | - | Prefix path to ARM cross-compiler tools (ARM on Linux cross-compiling build only) |
| ARM_SYSROOT | - | Path to ARM system root (ARM on Linux cross-compiling build only) |
| ARM_ABI_FLAGS | - | Specify ABI compiler flags (ARM on Linux platform only); e.g. Orange-Pi Mini 2 could use '-mcpu=cortex-a7 -mfpu=neon-vfpv4' |
| EMSCRIPTEN_ROOT_PATH | - | Root path to Emscripten cross-compiler tools (Emscripten only) |
| EMSCRIPTEN_SYSROOT | - | Path to Emscripten system root (Emscripten only) |
| EMSCRIPTEN_AUTO_SHELL | 1 | Auto adding a default HTML shell-file when it is not explicitly specified (Emscripten only) |
| EMSCRIPTEN_ALLOW_MEMORY_GROWTH | 1 | Enable memory growing based on application demand, default to true as there should be little or no overhead (Emscripten only) |
| EMSCRIPTEN_TOTAL_MEMORY | * | Specify the total size of memory to be used (Emscripten only); default to 128 MB, must be in multiple of 64 KB |
| EMSCRIPTEN_SHARE_DATA | 0 | Enable sharing data file support (Emscripten only) |
| EMSCRIPTEN_EMRUN_BROWSER | firefox | Specify the particular browser to be spawned by emrun during testing (Emscripten only), use 'emrun –list_browsers' command to get the list of possible values |
| OPENSSL_ROOT_DIR | - | Root path to OpenSSL directory |
Note that the specified build option values are cached by CMake after the initial configuration step. The cached values will be used by CMake in the subsequent configuration. The same build options are not required to be specified again and again. But once a non-default build option value is being cached, it can only be reverted back to its default value by explicitly resetting it. That is, simply by not passing the corresponding build option would not revert it back to its default. One way to revert all the build options to their default values is by clearing the CMake cache by executing cmake_clean.bat or cmake_clean.sh with the location of the build tree as the first argument or by executing it in the build tree itself.
A native build of Urho3D has two steps:
Note that Eclipse requires CDT plugin to build a C/C++ project.
On Windows platform Urho3D can use either Direct3D 9 (default), Direct3D 11 or OpenGL rendering. Other platforms always use OpenGL. Use the CMake options "-DURHO3D_D3D11=1" or "-DURHO3D_OPENGL=1" to choose the non-default APIs.
If using MinGW to compile, DirectX headers may need to be acquired separately. They can be copied to the MinGW installation eg. from the following package: https://www.libsdl.org/extras/win32/common/directx-devel.tar.gz. These will be missing some of the headers related to shader compilation, so a MinGW build will use OpenGL by default. To build in Direct3D mode, the MinGW-w64 port is necessary: http://mingw-w64.sourceforge.net/. Using it, Direct3D can be enabled with the "-DURHO3D_OPENGL=0" build option.
After the build is complete, the programs can be run from the bin subdirectory in the build tree. These include the Urho3D player application, which can run application scripts, the tools, and C++ sample applications if they have been enabled.
The macOS executables can be built with all the resources bundled into a single app directory. In order to enable this, set the URHO3D_MACOSX_BUNDLE build option when configuring the build tree for the macOS platform. The bundled app can be launched just by double-clicking from the Finder without worrying about setting the 'resource prefix path'. This is because the URHO3D_PREFIX_PATH environment variable has been set internally to point to the resources directory that is already bundled in the app. Note, however, if you do not launch the app via the Apple "Launch Services" (such as when you are debugging or by calling the executable directly inside the bundled app directory via CLI) then you still need to set the 'resource prefix path' manually as described in the previous paragraph. Note that the Mach-O universal binary targets can only be built when Xcode generator is used. All the other generators only build single-arch binary targets.
The Windows executables are by default built as Windows application instead of console application. You can set the URHO3D_WIN32_CONSOLE build option to override this. As console application, the standard output and standard error streams of the executable are redirected to console.
To run the Urho3D player application from the Visual Studio debugger, set the Urho3DPlayer project as the startup project and enter its relative path and filename into Properties -> Debugging -> Command: ../../../bin/Urho3DPlayer.exe. Additionally, entering -w into Debugging -> Command Arguments is highly recommended. This enables startup in windowed mode: without it running into an exception or breakpoint will be obnoxious as the mouse cursor will likely be hidden. To actually make the Urho3DPlayer application do something useful, it must be supplied with the name of the script file it should load and run. You can try for example the following arguments:
Scripts/NinjaSnowWar.as -w
To run from Eclipse on Linux, locate and select the Urho3DPlayer executable in the Project Explorer. From the menu, choose "Run Configurations" to create a new launch configuration for "C/C++ Application". Switch to "Arguments" tab, specify the argument required by Urho3DPlayer executable.
To run from Xcode on Mac OS X, edit the Product Scheme to set "Run" setting to execute "Urho3DPlayer" in the "Info" tab. In the "Arguments" tab, specify the arguments required by Urho3DPlayer executable. Ensure the check boxes are ticked on the argument entries that you want to be active.
First, if you are building under Windows host then after checking out the project you need to prepare the "assets" directory of both the "urho3d-lib" and "launcher-app" modules. Due to a bug in Android plugin of the version we are currently using, where it does not honor custom source set with filter setting, we are forced to use asset symlink with the default source set. So in Windows host system, the asset symlinks must be replaced with an equivalent directory link created with MKLINK command. If your account does not allow you to use MKLINK command then use copy command instead to copy the content of the linked directory directly to the "assets" directory. Ensure you have preserved the directory structure, i.e. "urho3d-lib" assets directory has one subdir called "CoreData", while "launcher-app" assets directory has two subdirs: "Data" and "Autoload".
Set the ANDROID_CCACHE environment variable to where your "ccache" build tool has been installed. It is highly recommended when it is available for your host system. Set the ANDROID_NDK environment variable to point to your Android NDK, if it is not installed in the default Android SDK location.
For CLI user, build the Gradle modules with the following command:
./gradlew build
or on Windows host:
gradlew.bat build
After the command finishes successfully, the AAR (Android library) and the APK (Android application) should have been generated in the "build/output" directory of the respective Gradle modules.
For Android Studio and IntelliJ IDEA users, open the project using the IDE. It should prompt you to auto-import the Gradle project, accept the default. After the “gradle sync” completes without any error (you may have to retry a few times to get the IDE sync-ed up with the Gradle), press Ctrl+F9 to build the project or Shift+F10 to run the launcher app in the Android device or emulator.
The Gradle build script has been setup to automatically pass the matching environment variable as CMake build options, e.g.: "URHO3D_LIB_TYPE=SHARED ./gradlew build". Additionally, it also supports the following Gradle properties.
| Gradle Property | Description |
|---|---|
| ANDROID_ABI | A comma-separated list of ABIs for split build configuration; when not specified defaults to universal build |
The Gradle properties can be passed by using "-P" Gradle option, e.g.: "./gradlew -P ANDROID_ABI=x86 build".
Run cmake_ios.sh or cmake_tvos.sh, respectively. This generates an Xcode project named Urho3D.xcodeproj.
Open the Xcode project and check the properties for the Urho3D project (topmost in the Project Navigator). In Code Signing, enter your developer identity as necessary. Also ensure you have changed the built-in target to ALL_BUILD to build all the targets. Edit its build scheme to choose debug or release mode. All the samples will be built as Application Bundle, i.e. with all the resources bundled. The library and samples will be built as Mach-O universal binary consisting of multiple archs depending on the chosen platforms.
You can choose one of the provided simulator to run the samples directly from the Xcode.
For native build on Raspberry Pi itself, use the similar process for Native build process described above for Linux platform.
For cross-compiling build on a Linux host system, firstly set the RPI_PREFIX environment variable or build option to point to your Raspberry Pi cross-compiling tool are located. You can setup the tool using crosstool-NG or just clone one from https://github.com/raspberrypi/tools. Secondly, set the RPI_SYSROOT environment variable or build option to point to your Raspbian or Pidora system root. You must install the Urho3D prerequisites software development packages for Raspberry Pi (see Building prerequisites) in the system root before attempting to do the Urho3D cross-compiling build. You are recommended to download the Raspbian system root with Urho3D prerequisite software installed from https://github.com/urho3d/rpi-sysroot. Alternatively, if you have a fast LAN connection then you can also opt to mount the system root on your actual Raspberry Pi device to your host system via SSHFS and set the RPI_SYSROOT to use the mount point.
Execute cmake_raspi.sh then go to the build tree to execute make command. You may pass the optional RPI_ABI build option to specifically target for the Raspberry Pi 2. After the build is complete, the ARM executables can be found in the build tree's "bin" subdirectory.
You can also build, deploy, run/debug (as C/C++ Remote Application) using Eclipse IDE. To do that, execute cmake_eclipse.sh with "-DRPI=1" build option set. Import the CMake generated Eclipse project in the build tree into Eclipse's workspace. Build the project as usual. Optionally, use the "URHO3D_SCP_TO_TARGET" build option to automatically deploy the ARM executables to target Raspberry Pi device as part of build process; or configure Eclipse to perform a "download to target path" in the Run/Debug configuration for C/C++ Remote Application. Either way, you have to configure the Run/Debug configuration to let it know how to reach your target Raspberry Pi device.
For native build on ARM board itself, use the similar process for Native build process described above for Linux platform.
At the moment we only support generic ARM on Linux platform. Other platforms/OSes are not supported yet.
For cross-compiling build on a Linux host system, firstly set the ARM_PREFIX environment variable or build option to point to your ARM cross-compiling tools are located. You can setup the tool using crosstool-NG or just download one from http://www.linaro.org/downloads/. You need to obtain the little-endian version of the armhf or aarch64 compiler toolchains for setting up a 32-bit or 64-bit build environment, respectively. Secondly, set the ARM_SYSROOT environment variable or build option to point to your generic ARM system root. Similarly you need to obtain the armhf (hard float) sysroot for 32-bit or arm64 (aarch64) sysroot for 64-bit. You must install the Urho3D prerequisites software development packages for Linux platform (see Building prerequisites) in the system root before attempting to do the Urho3D cross-compiling build. There are a few ways to obtain and prepare the sysroots yourself but the easiest way is to download the already prepared one from https://github.com/urho3d/armhf-sysroot or https://github.com/urho3d/arm64-sysroot. Alternatively, if you have a fast LAN connection then you can also opt to mount the system root on your actual ARM board to your host system via SSHFS and set the ARM_SYSROOT to use the mount point.
Execute cmake_arm.sh then go to the build tree to execute make command. You may pass the optional ARM_ABI_FLAGS build option to specifically target the CPU and FPU on your ARM board. For example: "-mcpu=cortex-a9 -mfpu=neon-fp16" for ODROID-X2, "-mcpu=cortex-a53" for ODROID-C2, "-mcpu=cortex-a7 -mfpu=neon-vfpv4" for Orange Pi, etc. After the build is complete, the ARM executables can be found in the build tree's "bin" subdirectory.
You can also build, deploy, run/debug (as C/C++ Remote Application) using Eclipse IDE. To do that, execute cmake_eclipse.sh with "-DARM=1" build option set. Import the CMake generated Eclipse project in the build tree into Eclipse's workspace. Build the project as usual. Optionally, use the "URHO3D_SCP_TO_TARGET" build option to automatically deploy the ARM executables to target ARM board as part of build process; or configure Eclipse to perform a "download to target path" in the Run/Debug configuration for C/C++ Remote Application. Either way, you have to configure the Run/Debug configuration to let it know how to reach your target ARM board.
It is possible to cross-compile Urho3D for Windows using a Linux host system. The process is largely the same as the Linux native build process described above.
To cross-compile, the MinGW compiler toolchain development software package ("mingw-w64" for Debian-based distro; "mingw64-gcc-c++" and "mingw64-winpthreads-static.noarch" for Redhat-based distro) needs to be installed on the system. For activating the MinGW compiler toolchain, and to allow it to find the correct compiler, the MINGW_PREFIX environment variable needs to be set. This variable should be set to the prefix of the compiler name, e.g. /usr/bin/x86_64-w64-mingw32 where it would be used to find /usr/bin/x86_64-w64-mingw32-gcc and /usr/bin/x86_64-w64-mingw32-g++, etc. Optionally you can also set MINGW_SYSROOT environment variable or build option to point to your MinGW system root, if it is not installed in a normal expected location. Adjust the software package name and the path accordingly for mingw32. It is recommended to use mingw64, when it is available for your host system, because it is multilib capable (can target both 32-bit and 64-bit).
Execute cmake_mingw.sh then go to the build tree to execute make command. After the build is complete, the Windows executables can be found in the build tree's "bin" subdirectory.
WHAT DOESN'T WORK:
- Networking. Javascript can only use http and websockets protocols and at the moment it's not supported.
This section assumes you have already updated, installed, and activated the latest Emscripten cross-compiler toolchain with upstream LLVM WASM backend on your host system as per described in https://emscripten.org/docs/getting_started/downloads.html.
Set the EMSCRIPTEN_ROOT_PATH environment variable or build option to point to the root path of Emscripten cross-compiler tools. Alternatively, call the emsdk_env script to set the EMSCRIPTEN environment variable for you. The Emscripten sysroot path will be derived from the root path, usually from 'system' subdir relative to the root path. However, you can optionally set the EMSCRIPTEN_SYSROOT environment variable or build option to point to another system root path.
On Windows host, execute cmake_emscripten.bat. On MacOS or Linux host, execute cmake_emscripten.sh. Then go to the build tree and execute the 'make' command to start the build as usual. You may want to set the URHO3D_SAMPLES build option to build all the samples. You may also optionally set the URHO3D_LUA build option to enable Lua scripting support. If you encounter "Too many open files" warning when archiving the Urho3D static library, follow by "Unresolved symbol" errors on MacOS then you have to increase the soft-limit in your host system before rebuilding the library and all the main targets.
For example, to double the limit (which normally defaults to 256 on MacOS):
ulimit -Sn 512
After the commands finish successfully, the HTMLs and its corresponding data files should have been generated in the build tree's "bin" subdirectory, from where it can be launched in a browser.
On Windows building with Emscripten requires a MinGW toolchain. The one that can be installed through emsdk may not work correctly, but for example https://sourceforge.net/projects/mingw-w64/ with the default install settings has been known to work.
If CMake complains that emcc is not able to compile a test program, try reactivating your current Emscripten cross-compiler tools with 'emsdk activate <sdk-version>', clear all generated *.cmake files as well as the CMake cache, and retry running CMake.
When using MSVC compiler, Urho3D common CMake module configures the build tree to target a 32-bit platform by default. When using other non-MSVC compilers (like GCC or Clang), the module sets the default to 32-bit or 64-bit based on the chosen toolchain in the build tree. You can, however, use the "URHO3D_64BIT" build option to override the default, i.e. by setting the option to '0' (for 32-bit) and '1' (for 64-bit) explicitly.
This section is not applicable for Android platform, which publishes the Android library (AAR) among other artifacts using maven-publish Gradle plugin.
The build process first builds the Urho3D library target (either static or shared). The library is then linked against by other targets like tools and samples that reference Urho3D as one of the external libraries. The Urho3D library type is defaulted to static, so the build process would generate standalone executables as previous releases. The Urho3D library type can be changed using "URHO3D_LIB_TYPE" build option.
To install the Urho3D library as an SDK, use the usual 'make install' command. There is an equivalent built-in target called "install" in Visual Studio solution and Xcode project to perform the SDK installation. This could be useful when you want your application to always link against a 'stable' installed version of the Urho3D library, while keeping your Urho3D project root tree in sync with origin/master; or when you want other users in the same host system to use the installed Urho3D SDK instead of them building from source again.
The default install prefix is 'c:/Program Files/Urho3D' on Windows host and '/usr/local' on all other non-Windows hosts. You can use the CMAKE_INSTALL_PREFIX build option to alter this prefix path. However, when cross-compiling you may actually want to alter the final installation destination by supplying DESTDIR environment variable instead of altering the CMAKE_INSTALL_PREFIX variable directly, especially when using Urho3D library as shared library type because the installed executables have their RPATH adjusted relative to CMAKE_INSTALL_PREFIX. The DESTDIR environment variable is not applicable for installation on Windows host, i.e. it can only use CMAKE_INSTALL_PREFIX variable to alter the final installation destination. This is not a lost, however, because there is no RPATH adjustment for Windows platform, but as the result the Urho3D.dll will be installed in a same directory as the installed executables.
If the Urho3D SDK is installed to a system-wide default location then the Urho3D library can be found by FindUrho3D CMake module automatically without the help of URHO3D_HOME environment variable or build option. When cross-compiling, the system-wide default location is usually in the system root of the cross-compiling target. To get a corresponding system root path for a cross-compiling build tree, you can use SYSROOT internal variable stored in the CMake cache. You can then use the system root path to set the DESTDIR environment variable in order to stage the Urho3D SDK installation in the corresponding system root. For example:
cd /path/to/your/Urho3D/build-tree DESTDIR=$(grep SYSROOT CMakeCache.txt |cut -d'=' -f2) make install
Note that SYSROOT variable is empty when the build tree is not setup for cross-compiling.
Refer to Using Urho3D library on how to setup your own project to use Urho3D library.
Urho3D should be built as a shared library if your application consists of multiple modules (main executable + other shared libraries) that all link to Urho3D. The reason for this is that Urho3D contains a few sensitive static data values, such as the main thread's ID, which will not work properly if they are duplicated due to multiple static linkage.
If "URHO3D_DOCS" or "URHO3D_DOCS_QUIET" build option is set then a normal build would not only build Urho3D binaries but also Urho3D documentation automatically. If the option is not set then the documentation can still be built by manually invoking 'make doc' command or using its equivalent built-in target in IDE.
The additional prerequisite for documentation build is Doxygen. Also Graphviz (optional) if you wish to generate graphical diagrams in the documentation. MSVC users on Windows host system may install HTML Help Workshop (optional) in order to get the compressed help file (*.chm). When optional tool is not available in the host system, the corresponding build process is skipped accordingly. The internal host tools to dump the AngelScript API for the default scripting subsystem and the LuaScript API (when the LuaScript subsystem is also enabled) are being built at the same time when all the native tools are built. When the build tree is being configured not to build any host tools then the 'doc' target will simply instruct Doxygen to process the existing API dump files that are already pre-generated in the repository.
If "URHO3D_CLANG_TOOLS" build option is set then CMake would generate a special build tree for the purpose of developing the Clang-tools. Before doing this, the development software package of LLVM/Clang version 3.9.0 must be already installed in the host system. Alternatively, you can download LLVM/Clang source files from Clang's SVN repo, build and install it into the host system. If it is not installed in a system-wide installation location then use the LLVM_CLANG_ROOT environment variable to point to the root path of this custom location (the root is the parent directory containing the bin, lib, include and share subdirectories). You may want to follow the Clang's Getting Started instruction to guide you through this.
Perhaps the easiest way to get Clang installed is by using Emscripten-SDK. If you have already built Emscripten-SDK in your host system then you can also use the SDK to install the Fastcomp/Clang by navigating to the Fastcomp/Clang build tree (e.g. emsdk_portable/clang/fastcomp/build_master_64) and issuing a 'make install' command. However, Emscripten-SDK does not automatically checkout "extra Clang tools", so before issuing a 'make install' you may want to take a step back to manually checkout the "extra Clang tools" into the corresponding subdirectory in the Fastcomp/Clang source tree (e.g. emsdk_portable/clang/fastcomp/src/tools/clang/tools/extra), then rebuild and install as usual. Using Fastcomp/Clang is fine for our purpose because we are only interested in using Clang as 3rd-party library instead of as compiler.
A special note to Linux users, install the development software package for 'libedit' when you want full command line interface features like command history and command editing in clang-query tool. Install it before generating any of the LLVM/Clang or Fastcomp/Clang build tree.
Check the Source/Clang-Tools/CMakeLists.txt to get the list of targets currently available or under development. Normal build targets won't work properly in this special build tree. See also https://github.com/urho3d/Urho3D/issues/887 to find out more about the current development plan and leave a comment there if you would like to help to contribute the development.
When building for Direct3D9 with the Windows 8 SDK (Visual Studio 2012+), copy d3dcompiler_46.dll from "C:\Program Files (x86)\Windows Kits\8.0\bin\x86" to build tree's "bin" directory so that Urho3D executables will run correctly. When building for Direct3D11, copy d3dcompiler_47.dll from "C:\Program Files (x86)\Windows Kits\8.1\bin\x86" to the "bin" directory. In both cases, if compiling Urho3D as 64-bit, copy from the "bin\x64" directory instead.
OpenGL does not depend on a separate shader compiler DLL.
The building prerequisites are understandably different for each target platform. If you want to target multiple platforms with a single build/host system then you have to not only install all of the prerequisites in your host system, but also have to be able to configure your build environment properly so that they do not interfere with each other. Rather than configuring the build environment manually, we have now provided a new build mechanism that we called "dockerized build environment" which addresses both hurdles above. Currently the dockerized build environment, or DBE for short, supports the following platforms: Linux, MinGW (Windows), Android, Raspberry-Pi, generic ARM, and Web.
The DBE requires podman (from repository provided by your distro, recommended) or Docker-CE (from https://docs.docker.com/install/) to be installed in the host system and that's all it needs.
To use the DBE, execute script/dockerized.sh in the project root directory, specify the platform name (linux|mingw|android|rpi|arm|web) as the mandatory parameter, and optionally followed by an alternative command to be invoked in the docker container. By default the command is to generate a build tree for the specified target platform and then build it. The Urho3D build options can be specified by using environment variables in the host system before executing the dockerized.sh. It could be done just in time as well, e.g. "URHO3D_LIB_TYPE=SHARED script/dockerized.sh mingw". The build artifact from DBE can be found in the usual location as the normal build environment. In fact the build artifacts should function and work as if they are built using conventional way too.
The DBE is designed to be used by Urho3D project and its downstream projects which reuse Urho3D build system.
1.9.5