Miscellaneous how-to's

Linux and macOS specific - How to use ccache to speed up build

ccache is a compiler cache software available on Linux and Mac OS X host systems. It speeds up the build by bypassing the actual compilation and reusing the result from previous compilation when the cache is hit. As such, this is optional in the build process. In order to enable ccache support and make it work correctly when building/using Urho3D library with GCC/Clang precompiled header enabled, the following environment variables must be set:

USE_CCACHE=1
CCACHE_SLOPPINESS=pch_defines,time_macros

Failure to do so would cause the precompiled header cannot be used by ccache. When ccache is setup correctly and with more hits than misses then even clean build can be done as fast as incremental build. The ccache support is available for native compiler toolchains as well as all cross-compiler toolchains supported by Urho3D.

You may also want to set 'CCACHE_COMPRESS' environment variable to 1 to enable the compression of the cached objects. It is a trade-off between cache size and build time.

Ensure the ccache symlinks directory is being added as the first entry in the 'PATH' environment variable so the symlinks of the compiler toolchain is being found first by CMake rather than the actual compiler toolchain. This is especially important for native build. Usually the 'PATH' environment variable has been set correctly for ccache in RedHat-based host system such as Fedora, but it is not the case in Debian-based host system such as Ubuntu nor in Mac OS X host system with homebrew's ccache installation. For the latter case, use "whereis -b ccache" or "brew info ccache" to find out where your ccache symlinks directory is and adjust the 'PATH' environment variable accordingly.

Note that these environment variables are used by ccache itself and not by our CMake build rules, so they must remain set in the host system not only while generating the initial project file using CMake but also while building the project later.

Xcode IDE and its CLI version, xcodebuild, do not work with ccache out of the box. They probably don't need it because internally they already cache the derived build data. However, if you are performing a lot of switching between different checked out versions of the project source tree or performing a lot of clean build similar to continuous integration build then probably it is more beneficial to hack Xcode/xcodebuild to use ccache. As it is a hack, do the following at your own risk.

On Xcode 5:

cd $(dirname $(xcodebuild -find-executable clang))
for compiler in clang clang++; do mv $compiler{,.orig} && ln -sf $(which ccache) $compiler; done

On Xcode 6 or above:

cd $(dirname $(xcodebuild -find-executable clang))
sudo cp -p $(which ccache) .
for compiler in clang clang++; do sudo mv $compiler{,.orig} && sudo ln -sf $(pwd)/clang.orig /usr/local/bin/$compiler && sudo ln -sf ccache $compiler; done

Starting since version 6, Xcode has done something funky internally. It won't build unless the symlink resolves to an executable within its own rooted-'/usr/bin' in Xcode.app package. The 'ccache' executable is physically copied to this location for this reason. But as the result, you have to manually keep this copy up to date when upgrading ccache and also repeat the whole process again as necessary when upgrading Xcode.

macOS specific - How to view/edit AngelScript within Xcode

By default Mac OS X recognizes file having extension .as as 'AppleSingle Archive'. So, even after associating this file type to always open with Xcode, Xcode is still not able to view/edit the content of the file correctly. In order to view/edit the scripts, after launching the Urho3D project in Xcode, select the .as file(s) in the Project Navigator and then in the File Inspector (right panel) change the file type from 'Default - AppleSingle archive' to 'C++ Source' in the File Type drop down list. The current editor view usually does not refresh its content after this change. Selecting another file in the Project Navigator then reselecting the .as file should force the editor to reload and show the .as file correctly afterwards.

The drawback of the above approach is, Xcode does not remember it. The steps need to be carried out each time Xcode is relaunched.

To solve this permanently, we need to 'hack' the system a little bit to 'fool' Xcode to always treat .as file as one of the C++ source files. Execute the following commands in a terminal as normal user. These commands have been verified to work with Xcode 4.x on Lion and Xcode 5.x on Mountain Lion.

$ cd /System/Library/CoreServices/CoreTypes.bundle/Contents
$ plutil -convert xml1 Info.plist -o /tmp/Info.plist.xml
$ sed -i.bak "s/<string>cxx<\/string>/<string>cxx<\/string>\\`echo -e '\n\r'`<string>as<\/string>/g" /tmp/Info.plist.xml
$ sudo cp -p Info.plist{,.ori}
$ sudo plutil -convert binary1 /tmp/Info.plist.xml -o Info.plist
$ find /System/Library/Frameworks -type f -name lsregister -exec {} -kill -r -domain local -domain system -domain user -domain network \;

The last command resets the launch service database and rebuilds it, so the changes should take effect immediately when Xcode restarts.

Windows specific - How to grant non-Administrator user to create symbolic links

If you are building Urho3D library or project under Windows host system then you may have seen the build system complaining about the insufficient user privilege to create symbolic links and falling back to hard-copy setup in the build tree. You should inform your Windows Administrator to grant the “Create symbolic links” (SeCreateSymbolicLinkPrivilege) to your user account to avoid this. However, if you are the Administrator of your own Home or Professional Windows host system then you could perform the following to fix the problem. Login using your Administrator account to create a new non-Administrator user account then grant the "Create symbolic links” privilege to that new account as follows:

  1. Launch "secpol.msc" via Start → Run.
  2. Navigate to Security Settings → Local Policies → User Rights Assignment → Create symbolic links.
  3. Add the account into the security setting.

To build Urho3D you have to use the newly created account instead of your original Administrator account because for some reason Windows OS does not honor the “Create symbolic links” privilege if the account having the privilege is also a member of the Administrator group. If you must use your own original account then you have to remove your account from the Administrator group, which means you need another account to become the Administrator. Either way your host OS will have two accounts and only the non-Administrator account works!