Building Urho3D library

Building Urho3D library

Table of Contents

Building prerequisites

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:

  • For Windows, the June 2010 DirectX SDK needs to be installed. This is not necessary if building on Visual Studio 2012 or newer, which install the Windows SDK with the necessary DirectX files.
  • For Linux, install one or more of the development packages from each software component category below. Building as 32-bit on a 64-bit system requires installing also the 32-bit versions of the development libraries.
    • Database server (optional). Disabled by default even when the development package is installed, use URHO3D_DATABASE_ODBC=1 to enable. The two packages below are mutually exclusive. The ODBC driver manager is the recommended package.
      • libiodbc2-dev (Debian-based) or libiodbc-devel (RedHat-based) for iODBC driver manager.
      • unixodbc-dev (Debian-based) or unixODBC-devel (RedHat-based) for ODBC driver manager.
    • Display server (essential). One or more of these can be installed at the same time. When multiple display servers are available, X11 takes precedence (overridable using SDL_VIDEODRIVER environment variable during application runtime).
      • libdirectfb-dev (Debian-based only) for Direct Frame Buffer (DirectFB). Disabled by default even when installed, use VIDEO_DIRECTFB=1 to enable.
      • libegl1-mesa-dev, libwayland-dev, and wayland-protocols (Debian-based) or libwayland-client-devel, libwayland-cursor-devel, libxkbcommon-devel, mesa-libEGL-devel, mesa-libwayland-egl-devel, and wayland-protocols-devel (RedHat-based) for Wayland.
      • libx11-dev, libxcursor-dev, libxext-dev, libxi-dev, libxinerama-dev, libxrandr-dev, libxrender-dev, libxss-dev, and libxxf86vm-dev (Debian-based) or libX11-devel, libXcursor-devel, libXext-devel, libXi-devel, libXinerama-devel, libXrandr-devel, libXrender-devel, libXScrnSaver-devel, and libXxf86vm-devel (RedHat-based) for X11 and its extensions. Alternatively, you can use xorg-devel meta package on Debian-based system, but it would install other unneeded packages as well.
    • Sound server (essential). One or more of these can be installed at the same time. When multiple sound servers are available, PulseAudio takes precedence (overridable using SDL_AUDIODRIVER environment variable during application runtime).
      • libasound2-dev (Debian-based) or alsa-lib-devel (RedHat-based) for Advanced Linux Sound Architecture (ALSA).
      • arts-devel (RedHat-based only) for Analog Real Time Synthesizer (aRts).
      • libaudio-dev (Debian-based only) for Network Audio System (NAS).
      • libesd0-dev (Debian-based) or esound-devel (RedHat-based) for Enlightened Sound Daemon (ESounD).
      • libfusionsound-dev (Debian-based only, not available on Ubuntu) for FusionSound. Disabled by default even when installed, use FUSIONSOUND=1 to enable.
      • libpulse-dev (Debian-based) or pulseaudio-libs-devel (RedHat-based) for PulseAudio.
      • libroar-dev (Debian-based only) for RoarAudio (SNDIO).
    • Input method editor (optional). One or both of these can be installed at the same time to enable the IME support in the game engine. When both frameworks are installed on user's host system, the application uses XMODIFIFIERS environment variable to determine which one is active.
      • libibus-1.0-dev (Debian-based) or ibus-devel (RedHat-based) for Intelligent Input Bus (ibus).
      • fcitx-libs-dev (Debian-based) or fcitx-devel (RedHat-based) for Flexible Input Method Framework (fcitx).
    • Miscellaneous (optional).
      • libdbus-1-dev (Debian-based) or dbus-devel (Redhat-based) for system-wide messaging (e.g. inhibiting screen-saver).
      • libreadline6-dev (Debian-based) or readline-devel (Redhat-based) for easy editing of command lines in interactive standalone host tools, e.g. isql and lua interpreter.
      • libts-dev (Debian-based) or tslib-devel (RedHat-based) for resistive, single-touch touchscreen input for embedded Linux device, e.g. Pandora and Wiz. Modern multi-touch touchscreen does not need this.
      • libudev-dev (Debian-based) or systemd-devel (Redhat-based) for input device hot-plugging.
    • HTTPS support (optional).
      • libssl-dev (Debian-based)
      • openssl (OS X using homebrew)
  • For Raspberry Pi, follow the building prerequisite for Linux above, with the exception for display server. Raspberry Pi operating system usually already comes with Broadcom Video Core display server preinstalled. On top of that, you must also install this package: libevdev2 (Raspbian) or libevdev (Pidora).
  • For macOS, iOS, and tvOS, the Xcode developer tools package should include everything necessary. Make sure that the Xcode command line tools are also installed. Homebrew is required to install 'cmake' and some of the optional development packages, such as ccache, doxygen, graphviz, and readline.
  • For Android, the Android Studio (version 4.0 or later) should include everything necessary. Make sure the Android NDK r21d is installed with the Android SDK Manager and CMake version 3.17.3 is installed on the host machine. Adjust the "buildSrc/src/main/kotlin/UrhoCommon.kt" accordingly if your host has different NDK and CMake version.
  • For Web, the Emscripten SDK (version 1.39.0 or later) needs to be installed with the upstream LLVM WASM backend is activated. On Windows host also MinGW-W64 compiler toolchain is required.

To run Urho3D, the minimum system requirements are:

  • Windows: CPU with SSE2 instructions support, Windows XP or newer, DirectX 9.0c, GPU with Shader Model 3 support.
  • macOS: CPU with SSE2 instructions support, GPU with OpenGL 2.0 support, EXT_framebuffer_object and EXT_packed_depth_stencil extensions, OS version 10.9 or newer.
  • Linux: any CPU (MMX, 3DNow!, and SSE/SSE2 instructions will be used if supported), GPU with OpenGL 2.0 support, EXT_framebuffer_object and EXT_packed_depth_stencil extensions.
  • Raspberry Pi: Model B revision 2.0 with at least 128 MB of 512 MB SDRAM allocated for GPU.
  • Android: Jelly Bean 4.1 (API level 16) or newer, OpenGL ES 2.0 capable GPU.
  • iOS: armv7, iPhone 3GS or newer including iPad, OS version 3 or newer.
  • tvOS: arm64, OS version 9 or newer.
  • Web: modern HTML5 browsers with fast JavaScript engine and WebGL support. Nightly built browsers are required for running WebAssembly target.

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.

Build scripts

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.

Build options

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_LUA 1 Enable Lua scripting support
URHO3D_LUAJIT 0 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_NAVIGATION 1 Enable Navigation support
URHO3D_URHO2D 1 Enable 2D rendering & physics 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 profiling support
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.

Native build process

A native build of Urho3D has two steps:

  1. Run CMake in the root directory (which is also CMake's source tree) with your preferred generator and toolchain specified to generate the build tree. You can use cmake-gui or the provided batch files or shell scripts on the respective host system. All the batch files and shell scripts expect the build tree location to be passed as the first argument, or to execute them in the build tree itself when reconfiguring the existing build tree.
    • 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
  2. Use the IDE of your choice to open the CMake's generated project file or solution file in the build tree. Change the build configuration (Debug/Release) and change the built-in target to ALL_BUILD to build all the targets.
    • 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

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.

Android build process

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 user, 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, 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 Gradle properties as CMake build options. The following is the list of supported Gradle properties.

Gradle Property Description
ANDROID_ABI A comma-separated list of ABIs for split build configuration; when not specified defaults to universal build
URHO3D_ANGELSCRIPT Pass-through as CMake build option
URHO3D_DATABASE_SQLITE Pass-through as CMake build option
URHO3D_FILEWATCHER Pass-through as CMake build option
URHO3D_IK Pass-through as CMake build option
URHO3D_LIB_TYPE Pass-through as CMake build option
URHO3D_LUA Pass-through as CMake build option
URHO3D_LUAJIT Pass-through as CMake build option
URHO3D_LUAJIT_AMALG Pass-through as CMake build option
URHO3D_LOGGING Pass-through as CMake build option
URHO3D_NAVIGATION Pass-through as CMake build option
URHO3D_NETWORK Pass-through as CMake build option
URHO3D_PCH Pass-through as CMake build option
URHO3D_PLAYER Pass-through as CMake build option
URHO3D_PHYSICS Pass-through as CMake build option
URHO3D_PROFILING Pass-through as CMake build option
URHO3D_SAMPLES Pass-through as CMake build option
URHO3D_THREADING Pass-through as CMake build option
URHO3D_URHO2D Pass-through as CMake build option
URHO3D_WEBP Pass-through as CMake build option

The Gradle properties can be passed by using "-P" Gradle option, e.g.: "./gradlew -P URHO3D_LUA=0 build" to build without Lua subsystem.

iOS and tvOS build process (tvOS is still EXPERIMENTAL)

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.

Raspberry Pi build process

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.

Generic ARM build process (EXPERIMENTAL)

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.

MinGW cross-compile build process

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.

Emscripten build process

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.

Native 64bit build

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.

Library build

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.

Documentation build

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.

Clang-tools build (EXPERIMENTAL)

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.

Compiling Direct3D shaders

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.

Dockerized build environment (EXPERIMENTAL on *nix host only)

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 prequisites 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: native (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 (native|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.