Urho3D build system


i’m new here, so let me present myself. I’m a 32 years old developer, with 15+ years of experience in various languages (Mostly C++), but with close to no experience in the gaming branch. That’s it :slight_smile:

So i’m trying Urho3D on a Mac OSX based operating system, and i’ve got a few questions / remarks.

1) Generating a reusable framework
When building from source, i’m unable to get something clean / functionnal as a re-usable framework. i tried many different CMake configurations, to finally just remove everything because none of them was usable:

a) When generating XCode project, it’s close to impossible to get a “Release” build of the framework, because the 93 targets are by default using the “Debug” configuration, even when archiving (By default, it should be the “Release” configuration that is used in all target for the “Archive” action). How do you guys generate a “Release” build of the framework that you can then link against from a fresh and from scratch project, itself not necessarily using cmake?

b) When building via the Unix Makefiles, the generated things are spread all around the source tree… Which is confusing, because some binaries replace previously generated ones.

c) In any case, if i start a new project from scratch (Empty XCode project, compiling a single “main.cpp” file), it’s impossible to link against the framework. i have set the headers search path to my built SDK include directory, but the files inside are trying to include more files without using the correct file paths (Eg #include “SDL_Joystick.h” instead of #include “SDL/SDL_Joystick.h”).
This is IMO a design mistake. So one thing leading to another, i have set the include paths to be recursive, but there, it won’t compile, because some classes are missing (Basically, it would probably compile from the source tree because the #include order are correct, but not from my “fresh” project). This denotes a “#include” hell that probably needs to be worked on a bit.
From my code, i get errors also, because some headers from the framework are probably doing some forward-class declaration for some public members pointers. This leads to me being unable to compile the project without having to include the headers file that should have be included in the first place by the framework headers themselve. Eg take the HelloWorld sample along with the Sample parent class, put the files in a fresh project, try to compile.

2) Compiling for iOS
Here, it’s a nightmare to me, there must be something i don’t understand. Again, i have tried every single possibility of combination for CMake variables, with no joy (The XCode projects that are generated by CMake all ask to build a “Debug” version where it should be “Release”). Any pointers please? i really would love to have a clean XCode project that just builds Urho3D along with it’s dependencies, that i can drag&n&drop to my project, and be able to have an iOS target along with a MacX target within the same project (Gameplay3D does that quite nicely).

3) Contributing
Having a very strong background in C / C++ development and project management, i would like to know how to contribute to the project. I believe i would be able to solve this #include hell, and provide with a slicker API for people to link / build against. Any project maintainer around to tell me where to start?
[edit]I have authored many Qt-based projects, all portable, so i’m very familiar with the linking differences when working with VS+nmake vs Unix etc, i have a very good understanding about how to provide a very opaque API with clean headers set for either a static or a dynamic library, etc.[/edit]

Just before trying Urho3D, i tried GamePlay3D, which is not an option for the projects i plan to work on for various reasons that i won’t go into detail here. However, the build system used by GamePlay3D is very concise, i was able to build a project from scratch and play with many of their subsystem in less than 5mn, while i’m still struggling to fix some small issues (Which really are not related to the code itself, but more to how it’s being lay around in the directory structure) in Urho3D. I really think that’s a pity for a framework that appears to be so rich, because it can easily scare newcomers. Do you guys have any remark / suggestions for me regarding this matter?

Thanks a lot,

Welcome to our forum.

I think we have a few new users who come before you also made the same mistake, invoking CMake without using our provided shell/batch scripts or invoking cmake-gui without first reading the documentation. As the main maintainer of the build scripts, I can say our CMake build scripts are not perfect yet and they have been written with assumptions which are only hold true when you use the CMake build scripts as per their original designed or documented use cases. Most new users have mistakenly generated a non out-of-source build tree which is not supported anymore by our CMake build scripts, so the generated project would most likely end up in some kind of build failures (Android build on Windows host system without MKLINK build option is the only exception where a non out-of-source build tree still works). Judging from your post, I reckon you have not read these documentation pages:
The first page explains how to build Urho3D library properly, while the second one how to use the library in your own project. I shall stress it again that our build scripts make certain assumption on the project structure as per documentation. They expect your own project to be the same as Urho3D project structure. That’s the price we have to pay in order to reuse the existing scripts (which by the way were initially only intended for Urho3D project). To put it in another words, if you don’t want to follow the book and want to have your project however you like and want to be able to invoke CMake however you like then you would have to write your own CMakeLists.txt build scripts for your own project instead of reusing our CMakeLists.txt. Now, that approach is perfectly fine if you ask me (just make sure you have set all the compiler definitions, compiler flags, linker flags, compiler header search path, linker library dependency, etc by yourself correctly).

If, however, you choose to spend a few minutes to read the above documentation pages but still cannot get it to work then you are welcome again to post your problem here. BTW, you may want to know that Urho build scripts and source codes are being tested for all the platforms that it supports almost every day (See travis-ci.org/urho3d/Urho3D/builds). So, it could not be that broken as you have described it in your first post.

Regarding the point 1.c. I am not the original author, so you will have to wait to hear from him on this design decision. But, if I may say something about it then I would say there is nothing wrong with it. In fact that is what makes Urho build so fast. Between a convenience of having one huge header that includes all the bits and bytes and an inconvenience of having a set of smaller header files which need to be mixed and matched on demand as required by the code, I would choose the latter any time for the sake of build speed alone. I am an Urho convert so I may be biased :wink: . And the SDL header search path should be set accordingly by our build scripts if you have used the build scripts correctly. Like you say, whether to have a “SDL/” prefix path or not is a design decision, as long as the header search path is being configured correctly and all the headers are found then I don’t think there is anything wrong with that. But then again I am not the original author, so be prepared to get the full rebuke from him (I am joking of course).

When recently using Urho3D as a part of an application, I’ve noticed some problems with include files as well. In my case these had mostly to do with ambiguities, like the application and Urho both defining a file Scene.h, which is a bit nasty and not the general use case.

But in general, it might be beneficial for Urho internal files to either:

  • Include Urho’s own header files through a single root include directory, instead of having each of the sub-directories (Scene, Engine etc.) as required include directories for the project. This will actually make it a bit harder for application developers, as they must also remember to use the sub-directory names, unless they configure their own project differently.
  • Include Urho’s own header files through relative paths when referring to other directories (eg. …/Scene/Scene.h)

As for <SDL/SDL_Joystick.h>, Urho uses its included SDL version directly from the source directories without an install step. Therefore including <SDL_Joystick.h> is proper, as we don’t have a directory named “SDL” in any of the include paths. Rather the directory “ThirdParty/SDL/include” is used as a project-wide include directory. I’m not sure if all third-party libraries could be made to work using a single root include directory. Attempting this would likely require an install step for each of the libraries, so that the headers are installed under a common root.

Maybe some of the CMake setup difficulties could be overcome by having a CMake install step that ensures production of a correctly formed SDK regardless of the CMake output directory.

Hello, and thank you for answering me.

I understand that my post might have gave this impression. In fact, i have read all the documentations pages (Even the very technical ones) at least twice each before even trying the engine.
My first attempt at compiling the engine was “by the books”, but i was very un-happy with the result:

  • CMake is the perfect tool to make shadow builds (Builds that are made from outside the source repository itself), and i use it in many projects to ensure that the code can be shared across a machine with many users without polluting the source code. The best way to try such setup is to try to build with a different user that owns the source. It doesn’t work with Urho3D: files are being created in some initial folders (Bin, Lib, etc). Also, building “by the book” for other targets than the native one produces a non-standard layout (ios-Bin etc) within the source tree.
  • When running make install after building (And having a per-platform target directory, eg /opt/Urho3d/MacOSXShared for one, /opt/Urho3D/iOSShared for another, etc) gives unexpected results: impossible to have a proper Release build for iOS for instance, because the only way to build for iOS seems to build with XCode, which by default is configured by CMake to use the Debug build for the Run / Archive actions. Not an options for me neither :slight_smile:
    That’s why i have dive in the “non-standard” way. Trust me, i don’t post such comment without reading the doc, and trying the “by-the-book” approach first :slight_smile:

Okay. What if i want to integrate Urho3D instead of another engine in an existing (Let’s say QMake based) project?
Also, i have tried the rake script provided with Urho3D. I was not happy with it, because the result expects me (I think) to use the Urho3D player when i want to use a plain C++ empty project. That’s why i’m asking: why would the “SDK” version of Urho expect anything in terms of project layout? Could we change that maybe? I’m willing and able to help here. But i would like to understand exactly why the authors decided this, it can indeed not be an out-of-the-blue decision.

Partially agree: Builds fast, okay. But really, most developers wouldn’t really care about a few seconds more of building the SDK. Regarding user-code using the SDK, most compilers are smart, and if you put the correct guards in headers, they are not “really” included. Because of this, it won’t really matter if you’re including .h files from your files to compensate, because whatever if you include them from your .h or from your .cpp, the thing is that you will have to include them anyway. The result is the same. Having written many libraries (Some of them being very big) with this in mind, i have a few recommendations about this (Also addresses the bizare paths for some headers) :slight_smile:

First let’s take the example of the SDL file.

This is if you’re using Urho3D as a “source-mixed-in-user-sources” way. The proper way (As most library do), is to have an SDK (No source code, it is stripped when going “make install”. And in the case of Urho3D, there are many files in the include/ directory that are themselves nested in subdirectories (SDL/ being just one).
There are possible solutions to this, two of them being:

  • From the Uroh3D source code, try to reference .h file the way they will be after install time. Eg. “#include <SDL/SDL_Joystick.h>”. This is just a matter of setting up properly the include paths of CMake to the directory containing the “SDL/” folder in the original source code, or create it if necessary. This way, any Urho3D referencing the SDL would work in the “SDK” context as well.
  • From what i have read from the documentation, Urho3D tries to abstract third party libraries. This would mean that no third-party header should actually be included and exposed from Urho3D API (.h files). This is most often being done with private implementations (Only the .cpp files, which are not part of the SDK, include third party libs, and encapsulate the functionnality in a structure whose definition is private and hidden in cpp files, not in API-related files).

Right now, i’m writing a tutorial on how to get 1c) working on Mac. It will be published by the end of the day (GMT). Maybe it will help you understand the culprits of the way Urho3D build is a problem for working with it a “SDK way”.

I really feel like i could contribute to the Urho3D build system. The thing is, i’m very new to it, and i don’t really know what would be accepted, and where to start in terms of functionality. Are there any test-coverage / unit-test suite in place, so if i break something i can be aware of it?


My point, exactly. A correctly crafted SDK is very hard to produce right now for Urho3D for instance for iOS (because 93 targets need to be changed in an XCode project that is auto-generated, and hence that will be overwritten the next time another SDK is built from the sources). Ideally, the SDK would:

  • Be easy to build. Use whatever build system is the best for Urho3D (CMake, QMake, or whatever).
  • Make good abstraction of third party libraries. They are compiled and used as static, this means that their API should totally disappear from the end-result Urho3D SDK which makes abtraction of them!
  • Be blue and make coffee for me.

Thank you very much for your time, i appreciate it.

There are some places where SDL will necessarily leak to headers, even though the general wish is to abstract it away.

Understood. So the good option would be to configure Urho3D to either:

  1. When it is possible to make abstraction, only use SDL headers from Urho3D .cpp.
  2. When it is not possible to make abstraction, try to “#include <SDL/*.h>” a way that would work with the end-user SDK setup, without having him set up recursive include paths.

To make 2) happend, it would be as easy as either:

  • Changing the original Urho3D source code, to include <SDL/*.h>, and hence create the correct folder layout in the Urho3D source tree,
  • Having a CMake install step copy all the SDL files in the root of the SDK include directory (Not a fond of this approach).
    What do you think?

To my mind the most critical question is whether all necessary third party libraries can be made to work from a SDK root directory, without modifying the libraries themselves.

Some other libraries that the user might directly interface with are kNet, Bullet, AngelScript.

[quote=“cadaver”]To my mind the most critical question is whether all necessary third party libraries can be made to work from a SDK root directory, without modifying the libraries themselves.

Some other libraries that the user might directly interface with are kNet, Bullet, AngelScript.[/quote]
Understood, thanks for the pointers. I’m refactoring the source code right now to allow a clean-use of the SDK, and i’ve noticed something interesting:

  • SDL headers are in ThirdParty/SDL/include.
  • Some other (Eg. RapidJSON) have their header like ThirdParty/rapidjson/include/rapidjson (Which is correct).
    Having all TP libs headers follow the latest scheme would just be great. That’s what i’m working on. At the end, any Urho3D file referencing a header will do:
#include <LibName/File.h>

instead of:

#include <File.h>

Sounds good to you guys? Just as a side: how do i send pull requests?

You can make pull requests at github.com/urho3d/Urho3D

In theory I don’t see a problem at least in the third party lib use reorganization, but I’m not as deep in the build system as Yao Wei Tjong is. He will no doubt have additional insight, and of course pull requests of this nature need to be evaluated very carefully. The automated build tests (which are also done for PR’s) should catch at least the standard cases of building the library itself, and the samples.

I’m almost done with the refactoring. Right now, i have only worked on TP libraries that have headers installed in the final build of the SDK.
I’m concerned about the kNet library tho, because i had to change it’s source files: their convention about includes is not consistent. Sometimes they references files within the same directory using kNet/…, sometimes not. Maybe the changes i have done in these files (All of them having a comment) will need to be pull-requested to the original maintainers?

We are using a slightly older and modified kNet, so that is practically the most OK library to modify. Syncing changes to upstream for kNet is not an immediate priority, but good to keep in mind.

Ah! As i thought it would be difficult to integrate for people already using the framework, i have reverted all my changes to TP libraries and solved the problem only using the CMake files.

Here are my notes so far (i’ll git diff later to make sure everything is consistent once i’m done testing):
[edit]Updated! i’m done. Every sample C++ app seems to be working on my computer (Except for those that were not working previously). I would like to know how to do a pull request, any pointer please? Attached is the CMakeCache variables of my successfull build (Have enabled / disabled a few things, IMO only LUA needs to be built and tested, against which i’m now able to link / include without recursive headers on MacOSX. YAY!
Pull request is here: github.com/urho3d/Urho3D/commit … 42f57f28c9

Changes in Source/ThirdParty to allow “#include <SomeLib/…>” from sources and user-code:

  1. Moved “AngelScript/include/angelscript.h” to “AngelScript/include/AngelScript/angelscript.h”.
  2. Box2D looked clean and useable both from Source and from SDK the same way.
  3. Moved “Bullet/src/*” to “Bullet/src/Bullet”.
  4. Moved “kNet/include” to “kNet/include/kNet”.
  5. Moved “SDL/include” to “SDL/include/SDL”.
    X) Should do Direct3D9 and OpenGL… Where to find them?

CMake files changed accordingly:

  1. AngelScript:
  • In AngelScript/CMakeLists.txt, the install directive copies things from AngelScript/include/AngelScript since it moved.
  • From the Urho3D source files, replaced any “#include <angelscript.h>” with it’s new counterpart (<AngelScript/angelscript.h>).
  • Other various files changed:
    • “AngelScript/source/as_config.h”: Inclusion fix (From “…/include/angelscript.h” to “AngelScript/angelscript.h”).
      FINAL NOTES: Zero changes done in the library code itself.
  1. Box2D:
    FINAL NOTES: Clean and SDK-compliant, nothing to be done here.

  2. Bullet:

  • In Bullet/CMakeLists.txt, replaced any occurence to “src” to match the new “src/Bullet”.
  • From the Urho3D source files, changed any bullet include reference to it’s proper new counterpart (With the leading “Bullet/” prefix).
    FINAL NOTES: Many of the includes in Bullet were wrong relative to the file they were called.
  1. kNet:
  • In kNet/CMakeLists.txt, replaced any occurence to “include” to match the new “include/kNet”, and added an include directive for it to build properly.
  • From the Urho3D source files, changed any kNet include reference to it’s proper counterpart. Especially, replaced all individual kNet/* include by the global kNet.h or kNetFwd.h when required.
    FINAL NOTES: Most of the kNet includes were wrong… Very bad consistency from it’s maintainer regarding relative paths. Most of them were re-written in the refactoring process, and since i’ve been told it was already a changed library, i hope it doesn’t matters too much.
  1. SDL:
  • In SDL/CMakeLists.txt, changed the install directive to match the new SDL headers path.
  • Added an include directive for SDL itself to be able to compile.
  • Also changed to match the new scheme:
    • “SDL/src/events/SDL_touch_c.h”: Inclusion fix.
  • From the Urho3D source files, changed any reference to include SDL to match the new correct compatible scheme.
    FINAL NOTES: Just one file from the SDL itself was corrected. Easy to maintain.

CMake cache of the successfull build.

# This is the CMakeCache file.
# For build in directory: /opt/Urho3D/git/Source/TmpBuilds/MacOSX
# It was generated by CMake: /Applications/Dev/CMake.app/Contents/bin/cmake
# You can edit this file to change values found and used by cmake.
# If you do not want to change any of the values, simply exit the editor.
# If you do want to change a value, simply edit, save, and exit the editor.
# The syntax for the file is as follows:
# KEY is the name of a variable in the cache.
# TYPE is a hint to GUIs for the type of VALUE, DO NOT EDIT TYPE!.
# VALUE is the current value for the KEY.

# EXTERNAL cache entries

//Setup build for Android platform

//Dependencies for target

//Dependencies for target

//Dependencies for target

//Dependencies for target

//Path to a program.

//Choose the type of build, options are: None(CMAKE_CXX_FLAGS or
// CMAKE_C_FLAGS used) Debug Release RelWithDebInfo MinSizeRel.

//Enable/Disable color output during build.

//CXX compiler

//Flags used by the compiler during all build types.

//Flags used by the compiler during debug builds.

//Flags used by the compiler during release builds for minimum
// size.

//Flags used by the compiler during release builds.

//Flags used by the compiler during release builds with debug info.

//C compiler

//Flags used by the compiler during all build types.

//Flags used by the compiler during debug builds.

//Flags used by the compiler during release builds for minimum
// size.

//Flags used by the compiler during release builds.

//Flags used by the compiler during release builds with debug info.

//Flags used by the linker.

//Flags used by the linker during debug builds.

//Flags used by the linker during release minsize builds.

//Flags used by the linker during release builds.

//Flags used by the linker during Release with Debug Info builds.

//Enable/Disable output of compile commands during generation.

//Path to a program.

//Install path prefix, prepended onto install directories.

//Path to a program.

//Path to a program.

//Flags used by the linker during the creation of modules.

//Flags used by the linker during debug builds.

//Flags used by the linker during release minsize builds.

//Flags used by the linker during release builds.

//Flags used by the linker during Release with Debug Info builds.

//Path to a program.

//Path to a program.

//Path to a program.

//Build architectures for OSX

//Minimum OS X version to target for deployment (at runtime); newer
// APIs weak linked. Set to empty string for default value.

//The product will be built against the headers and libraries located
// inside the indicated SDK.

//Value Computed by CMake

//Path to a program.

//Flags used by the linker during the creation of dll's.

//Flags used by the linker during debug builds.

//Flags used by the linker during release minsize builds.

//Flags used by the linker during release builds.

//Flags used by the linker during Release with Debug Info builds.

//If set, runtime paths are not added when installing shared libraries,
// but are added when building.

//If set, runtime paths are not added when using shared libraries.

//Flags used by the linker during the creation of static libraries.

//Flags used by the linker during debug builds.

//Flags used by the linker during release minsize builds.

//Flags used by the linker during release builds.

//Flags used by the linker during Release with Debug Info builds.

//Path to a program.

//If true, cmake will use relative paths in makefiles and projects.

//If this value is on, makefiles will be generated without the
// .SILENT directive, and all commands will be echoed to the console
// during the make.  This is useful for debugging only. With Visual
// Studio IDE projects all commands are done without /nologo.

//Enable to build TBZ2 source packages

//Enable to build TGZ source packages

//Enable to build TXZ source packages

//Enable to build TZ source packages

//Enable to build ZIP source packages

//Dependencies for the target

//Graphviz Dot tool for using Doxygen

//Doxygen documentation generation tool (http://www.doxygen.org)

//Dependencies for target

//Dependencies for target

//Dependencies for target

//Setup build for iOS platform

//Dependencies for target

//Dependencies for target

//Dependencies for target

//Dependencies for target

//Setup build for Raspberry Pi platform

//Dependencies for target

//Dependencies for the target

//Dependencies for target

//Dependencies for target

//Enable 64-bit build

//Enable AngelScript scripting support

//Generate documentation as part of normal build

//Generate documentation as part of normal build, suppress generation
// process from sending anything to stdout

//Build extras (Desktop and RPI only)

//Enable filewatcher support

//Path to Urho3D project root tree

//Specify Urho3D library type, possible values are STATIC (default)
// and SHARED

//Enable logging support

//Enable additional Lua scripting support

//Enable Lua scripting support using LuaJIT (check LuaJIT's CMakeLists.txt
// for more options)

//Enable navigation support

//Enable networking support

//Enable physics support

//Enable profiling support

//Build sample applications

//Path to Urho3D project source tree

//Enable SSE instruction set

//Enable testing support

//Build standalone tools (Desktop and RPI only; on Android only
// build Lua standalone tools)

//Use HIDDEN visibility support if available.

//Value Computed by CMake

//Value Computed by CMake

//Value Computed by CMake

//Value Computed by CMake

//Value Computed by CMake

//Value Computed by CMake

//Value Computed by CMake

//Value Computed by CMake

//Value Computed by CMake

//Dependencies for the target

//Value Computed by CMake

//Dependencies for the target

# INTERNAL cache entries

//ADVANCED property for variable: CMAKE_AR
//This is the directory where this CMakeCache.txt was created
//Major version of cmake used to create the current loaded cache
//Minor version of cmake used to create the current loaded cache
//Patch version of cmake used to create the current loaded cache
//ADVANCED property for variable: CMAKE_COLOR_MAKEFILE
//Path to CMake executable.
//Path to cpack program executable.
//Path to ctest program executable.
//ADVANCED property for variable: CMAKE_CXX_COMPILER
//ADVANCED property for variable: CMAKE_CXX_FLAGS
//ADVANCED property for variable: CMAKE_CXX_FLAGS_DEBUG
//ADVANCED property for variable: CMAKE_CXX_FLAGS_RELEASE
//ADVANCED property for variable: CMAKE_C_COMPILER
//ADVANCED property for variable: CMAKE_C_FLAGS
//ADVANCED property for variable: CMAKE_C_FLAGS_DEBUG
//ADVANCED property for variable: CMAKE_C_FLAGS_MINSIZEREL
//ADVANCED property for variable: CMAKE_C_FLAGS_RELEASE
//Path to cache edit program executable.
//Executable file format
//ADVANCED property for variable: CMAKE_EXE_LINKER_FLAGS
//Name of external makefile project generator.
//Name of generator.
//Name of generator platform.
//Name of generator toolset.
//Start directory with the top level CMakeLists.txt file for this
// project
//ADVANCED property for variable: CMAKE_INSTALL_NAME_TOOL
//ADVANCED property for variable: CMAKE_LINKER
//ADVANCED property for variable: CMAKE_MAKE_PROGRAM
//ADVANCED property for variable: CMAKE_NM
//number of local generators
//ADVANCED property for variable: CMAKE_OBJCOPY
//ADVANCED property for variable: CMAKE_OBJDUMP
//ADVANCED property for variable: CMAKE_RANLIB
//Path to CMake installation.
//ADVANCED property for variable: CMAKE_SKIP_INSTALL_RPATH
//ADVANCED property for variable: CMAKE_SKIP_RPATH
//ADVANCED property for variable: CMAKE_STRIP
//Suppress Warnings that are meant for the author of the CMakeLists.txt
// files.
//uname command
//ADVANCED property for variable: CMAKE_USE_RELATIVE_PATHS
//ADVANCED property for variable: CMAKE_VERBOSE_MAKEFILE
//Compiler support for a deprecated attribute
//ADVANCED property for variable: CPACK_SOURCE_TBZ2
//ADVANCED property for variable: CPACK_SOURCE_TGZ
//ADVANCED property for variable: CPACK_SOURCE_TXZ
//ADVANCED property for variable: CPACK_SOURCE_TZ
//ADVANCED property for variable: CPACK_SOURCE_ZIP
//URHO3D_OPENGL flag when Doxyfile was last generated
//ADVANCED property for variable: DOXYGEN_DOT_EXECUTABLE
//ADVANCED property for variable: DOXYGEN_EXECUTABLE
//Details about finding Urho3D
//Have include stdint.h
//Lib type when Urho3D export header was last generated
//Lib type when Urho3D library was last found
//ADVANCED property for variable: URHO3D_SOURCE_TREE

Like I have said before (and in fact a few times already in other similar threads) that our existing build scripts are not yet perfect. They make certain assumptions on the project structure (Bin, Lib, Build for native build and their platform-specific variants for the corss-compiling builds). I agree that this restricts the full usefulness of CMake in generating arbitrary out-of-source build tree. At the time I was rewriting the build scripts, it looks like a good idea to let the shell scripts (cmake_gcc.sh and cmake_macosx.sh) determine the build tree location on behalf of the user, based on the environment variable values and shell script parameters. I could, for example, only invoke the cmake_gcc.sh only one time and the shell script would configure and generate one build tree for native (Build) and also the other three build trees for cross-compiling platforms (android-Build, mingw-Build, and raspi-Build) in one go without me repeating myself specifying which build tree for which target platform each time. You would be surprised how many times I had to nuke all my build trees and regenerate them just to verify my changes during that time. There were no Travis CI builds yet then. Thus, it appeared to be a good trade-off at that time (at least to me). Later on we have to move this assumption of the build tree locations further into other logic in our build script (e.g. FindUrho3D.cmake) so that we can support external project referencing to Urho3D library just from its build tree in a cross-platform manner (i.e. without actually forcing user to install the Urho3D library first). Currently all the sample apps and tools in the Urho3D project are configured this way, they depends on Urho3D library from the build tree. Don’t get me wrong here. I am not trying to defend this. If I could go back in time and do it differently then perhaps I would not let the shell scripts to decide the build tree location on user behalf again. So, in my example above I would have to call the shell script four times with some way to pass a different build tree location for each targeted platforms. And perhaps we would have other solution too in order to support external project referencing to Urho3D library in the build tree without making those assumptions, but more like by requiring user to provide the required information one way or another during project configuration of the external project.

“The book” I was referring to is our documentation pages obviously. Correct or wrong, this is the expected result as per my design. I have already explained how it comes to this sorry state above.

EDIT: Despite the location of all the output subdirectories (Bin, Lib, ios-Bin, etc) are being assumed, they are still in fact located outside of the source tree instead of within it. Our source tree is the “Source/” directory where the main CMakeLists.txt located.

The truth is, I don’t know how many of us actually use the SDK installation approach. The term “Urho3D SDK” was even being coined by me after my first attempt to add the “install” target to our build scripts, without actually performing any case study of how external projects would have used Urho3D library or any difficulty that they may face. Most of us know that the Urho3D’s master branch is as stable as any its releases, so we pull, build, and use the newly built lib straight from the build tree. Back to your issue, since you did not explicitly state what were unexpected, I will just try to explain my rationale back then when I cooked this up. Again, I am not defending them but just to give you the insight so you can correct them if there are any mistakes.

[ul][li] The installation directory structure is based on how I would expect them when I install a software package on Fedora or on any Linux system in general. Obviously I didn’t have Apple in my mind when deciding that. The Win and Mac share the same install directory structure simply because they are all configured by a same script.[/li]
[li] On native platform, there is no SYSROOT. The root of install destination is determined by CMAKE_INSTALL_PREFIX variable. The install directory structure is created under this directory.[/li]
[li] On cross-compiling platforms (except iOS on Mac), the SYSROOT is defined. The SYSROOT path is prepended in front of the normal install root. Thus, there is no need to alter our install directory structure. The native and cross-compiling SDK can be installed at the same time without clashing.[/li]
[li] On iOS platform, there is no SYSROOT (actually there is, but not in the same way normally I understood). There is no SYSROOT path to be prepended. So, the iOS install directory structure has to be altered slightly by having an “ios” infix path, in order to let both the native SDK (for MacOSX) and iOS SDK installable at the same time using the same root install location pointed by CMAKE_INSTALL_PREFIX variable.[/li][/ul]
Note that if one uses a non-default CMAKE_INSTALL_PREFIX path (like in your case above) then one needs to set CMAKE_PREFIX_PATH variable accordingly in his/her own project so that CMake knows where to look for the installed Urho3D SDK. This is already documentated in our documentation.

I am not able reproduce this issue on a newly generated iOS build tree and iOS Xcode project file. Archive is defaulted to Release. Run is defaulted to Debug but it can be easily switched to Release configuration with a click of a button in “Edit Scheme”. I still use Xcode 5. Are you happen to use Xcode 6? A few forum users have reported problem with building Urho3D on Xcode 6.

Yes, you can as I said it already in earlier post. Just don’t reuse our build scripts. I understand where you come from and what is your point. Currently it makes using the library difficult in this scenario. It is not a self-contained “Framework” in Apple development world. At the moment we only build static archive and shared dylib (MacOSX only) with a set of headers lying around in some include dirs, instead of a self-contained framework. Now, we welcome you to contribute to make that happens. How much you can make it self-contained is yet to be seen. Note that our build scripts do more than setting the include search path and library dependencies.

I have to disagree with you there. Not on the fact that you are unhappy with it but on the fact that it expects you to use Urho3DPlayer. The documentation has explained that Urho3DPlayer.cpp and Urho3DPlayer.h are placeholders for the source files and normally you should replace them for your own project. See urho3d.github.io/documentation/H … caffolding. You are again welcome to make this rake task works even better than this. As it is, this rake task does not handle all the project scaffolding well in every platforms. For instance, on Android platform it does not know how to generate Android manifest for each new project and a few other things and so the task just leaves them missing in the generated project. The task does not even work on Windows platform. One thing for sure. It is hard to make everyone happy while not getting paid of what we do. (No, it is actually harder if we do get paid :slight_smile:).

Strickly speaking, it is not the SDK that expects a specific project layout but it is our current build scripts. Don’t reuse our build scripts then you can have any layout/structure, although I agree without the help of those scripts then it is quite hard to reference and use our library correctly at the moment.

I think you have gotten acquainted with Travis, our worker with a mustache. You are lucky. Not long ago I had to jump to a number of platforms each time I make changes to the build scripts so that I could verify the changes.

Finally I want to make one point myself. We need to decide whether we still want to support external project referencing Urho3D library from its build tree. Or do we now forcing everyone to install the library (the SDK) before it can be referenced? Personally I think the former is a unique feature of Urho3D project and it would be a pity to remove it just for sake of standard. Should we decide to keep supporting it, I think we can make it aligned with the “cleanup SDK” (whatever that means).

I would not mind external projects having to build/install the SDK, then reference that, as long as the samples & tools are able to build using the build tree as part of the same project. On Windows we could perhaps tweak the default install dir to something like “SDK” inside the Urho checkout, as by default it goes to Program Files which I don’t find terribly intuitive.

Though I’m not sure what that would mean in relation to the Android platform, which is somewhat the odd case.

Also another idea: could the Urho defines specific to the build (like URHO3D_LOGGING) all be placed to the generated Urho3D.h? That would make it impossible for Urho client programs to have wrongly setup defines, and simplify FindUrho3D’s job.

@cadaver Those are indeed good pointers. I am able to work on MacOSX / Linux / Windows versions, as well as iOS and Android. I cannot provide any help for RaPI yet. Do you think we can create some kind of collaborative document for this part of the refactoring?



By “Urho checkout”, do you mean our project root? So that the installed “SDK” will be sibling to “Source” and “Bin” directory? It is technically possible to do so but when the preferred install location is not the default location as per CMake then we need to:
[ol][li] Set CMAKE_INSTALL_PREFIX to the non-default location at the time of SDK installation[/li]
[li] Set CMAKE_PREFIX_PATH to this non-default location again at the time of referencing and looking up for this SDK installation[/li][/ol]
In short, more “magic” ingredient in our build scripts.

The FindUrho3D CMake module actually does not deal with the compiler defines and flags. It only responsible for finding the Urho3D library (and its headers), and populate variables to store where it founds them. The real work horse of setting things up is the Urho3D-CMake-common module. It uses those variables to setup the compiler include search path and linker library search path and dependency. The compiler defines and compiler flags are configured in the latter, based on numerous factors like target platform, chosen compiler, build options, etc. I think a few compiler defines could be “baked” into the generated Urho3D.h, but may be not all of them.

Ah OK, in this case it’s probably not worth it. Yes, I meant the checkout root. On Windows I would be happy though (others may disagree) to have to always specify URHO3D_HOME for external projects, instead of any “system” installation of the library, because I don’t think Urho with its varying build options, is really suited for a system installation in the same sense like Boost, OpenSSL etc. are (You might have different projects that need different builds of Urho.) But I understand that in Unix-like environments people are used to a default system install (eg. goes to /usr/include, /usr/lib)

I can later check the default install behavior of eg. Ogre on Windows.

OK, verified that Ogre’s CMake does this. Of course it doesn’t by any means mean that we should automatically follow.

    # We don't want to install in default system location, install is really for the SDK, so call it that
	  "${OGRE_BINARY_DIR}/sdk" CACHE PATH "OGRE install prefix" FORCE
endif(WIN32 OR APPLE)

windows 10 is rumoured to have a package manager. maybe windows will finally have a convention for this kind of thing.