CMake build system for Irrlicht

[GrafZahl]

Hello

Update 25.09.2015: I created a github project: https://github.com/ZahlGraf/IrrlichtCMake
All further updates will be released there.

Update: Here is the irrlicht 1.8.3 build system
(Nothing has changed in the CMake build system, except the version number)

Since I need to compile Irrlicht with several different compilers I created for the version 1.8.2 a CMake build system.
You can download it from here: irrlicht-1.8.2.zip
Just merge the directory "irrlicht-1.8.2" with the official download from Irrlicht. No file should be overwritten, it will just add CMakeLists.txt files to the main project, examples and tools and the CMake folder where all module-files are included.
I tried to bring the CMake system as close as possible to the Makefiles, so almost all compiler options should be the same.

What is CMake
CMake is a meta-build system, that generates all kind of different make-files or project-files. You just need to specify the make-system you want to use (gnu make, nmake, ninja mingw-makefiles, msys-makefiles) or an IDE you use (Eclipse project file, Visual Studio project file) and CMake will then generate all necessary files for that.
The big advantage - compared to single Makefiles and project files - is that you just need to maintain the files of CMake and you don't need to maintain all VC-project files and makefiles independently.
Of course you first need to understand how CMake works, but I was able to learn it very fast and I hope I wrote the CMake files in a way that they are easy to maintain.
From my point of view CMake is the only way to have a build-system that is compatible to any compiler and any operating system. I’m always happy when I download an open source project and see that is uses CMake for compiling.

What can this CMake-System do
With my CMake files you can compile the Library itself (as static or shared, debug or release version) and if you want, you can also compile all examples and tools with the same settings. You can start the compilation of "everything" just by entering one command to your shell.
I implemented the CMake-System for Windows, Unix Like systems and MacOSX. It should also support GCC (including MingW 32/64bit), Visual C++, Intel-Compiler (windows/linux) and CLang.

However:
Of course I was not able to test every compiler and operating system. The following tests have been done by myself:

• Windows 7, MSCV2015, 64bit
• Windows 7, Intel 16.0 Compiler (MSCV2015 front end), 64bit
• Windows 7, MinGW 32bit
• Windows 7, MinGW 64bit

My CLang compiler seems to be broken, so I could not test it and since I have no Linux or MacOSX computer available here, I could not test these operating systems. It would be create if someone could test other compilers and operating systems to make the build system stable.

File Description
In the Root, example and tools directory there is always a CMakeLists.txt file. In every directory where you can find such a file, you can start a build.
So when you start the build in the root directory, you can build the library, examples and tools.
When you start in the examples directory, you can build all examples (without library or tools) and of course you can just build one specific example by going into that example sub-directory.
In the CMake directory you can find different Module files, that should help to maintain the build system easily. These module files are included by the main CMakeLists.txt file.

• IrrlichtSource.cmake - contains a list of all source and header files for the Irrlicht library. When you add new file to the project, you must also add it here to the list. The source-files of the examples and tools, are stored in the CMakeLists.txt file of the corresponding subproject, since normally this is just a single file (main.cpp). But for the Irrlicht library there are so many files, that I think it is a good idea to have it in a dedicated module file.
• ExampleBuild.cmake - contains a subfunction for building examples or tools. So when you want to change anything for the examples only (other defines or compiler flags, you can add them here)
• IrrlichtVersion.cmake - contains the version number of the library (1.8.2)
• PrintSettings.cmake and WriteSettings.cmake - a module file, that prints/writes a summary of all settings, when you add new settings, you should add the variables also here.
• Compiler/*.cmake - The files in this directory contain specific settings for every supported compiler. At the moment just MSVC like compilers are supported (compilers that uses the front end and arguments of Visual C++ like Visual Studio and Intel Compiler on Windows) and GCC like compilers (compilers that uses the front-end and arguments of GCC, like MinGW, GCC, CLang, Intel on Linux)
• Dependencies/*.cmake - The files in this directory contain settings that belongs to dependencies like DirectX9 and OpenGL. These files decide if directx or opengl libraries are linked to Irrlicht or not. When you add new dependencies, you can add also new files here for the dependency related settings.
• OperatingSystems/*.cmake - The files in this directory contain settings that are specific to the operating system. (it seems, that MacOSX needs some other settings then Linux or Windows) These files also decide, if - depending on the operating system - specific libraries should be linked to Irrlicht or specific defines should be set.
• Option/*.cmake - I added some options to the build system like enabling profiling or build static library. The logic behind, and if necessary also the settings for those options are stored in the files in this directory.
• Packages/*.cmake - In this directory there are two files that are necessary to find the paths to the directx9 SDK. I did not implement those files, I just copied them from the Ogre3D project ( http://www.ogre3d.org/ ) - Of course the licence allows it and also a developer of the Ogre3D project allowed me to release these files together with the Irrlicht CMake build system.

A small How-To for building Irrlicht with CMake

1. First of all make sure, that CMake is installed on your computer ( http://www.cmake.org/ )
2. The CMake bin directory should be inside your PATH variable when you start your programming shell.
3. Merge the files from my ZIP into your irrlicht 1.8.2 directory.
4. Open your programming shell (like the one where you called “vcvarsall.bat amd64” for Visual C++ 64bit)
5. Goto your Irrlicht directory.
6. Enter in your shell “cmake-gui” (for experts there is also a command line tool without gui)
7. On the top of the windows there is a text field “Where is the source code”. Be sure, that this is the path to the irrlicht-root directory (where the main CMakeLists.txt file is in)
8. Below this line there is a text field “Where to build the binary”. Enter here any path you want, where the temporary files for the build process are stored in. For example <irrlicht-root-dir>/build-vc64/debug/shared (when you want to build the shared library in debug mode)
9. Click on Configure. It asks you, if it should create the build path – click on “Yes” and then you can select the build-system you want to use. For Visual C++ you can use “NMake Makefiles” or you can create a Visual Studio Project file (I have not tested it so far, since my Visual Studio IDE is broken).
   For MingW you can select MingW Makefile or MSYS-Makefile (I prefere MSYS-Makefile). For GCC on Linux just select Unix Makefile.
10. Below the build system selector you can select if you want to use default compiler or if you want to use a different compiler. For example for Intel Compiler on Windows, you select NMake Makefile and “Specify native compilers” where you can now specify the “ICL” command instead of the Visual C++ “CL” command for compiling. In this way you can also define a cross compiler, if necessary. For Visual C++, just select “use default native compiler” together with “NMake Makefiles”.
11. After clicking on Finish, the system searches for the compiler binary and figures out where it can find OpenGL and DirectX. When you build the main project (Irrlicht Library) there should not be any Warning or Error. In the text window on the bottom, it should print a summary of your configuration and you should read the text “Configuration done”. In the middle part of the window, you will see a red list of variables, that have been changed in this configuration step.
12. Edit the variables in the way you want. Make sure, that you set at least the following one:
    • ”CMAKE_BUILD_TYPE = Debug” (or Release)
    • ”CMAKE_INSTALL_PREFIX = <the path where you want to have the binaries and include files>” For example: example <irrlicht-root-dir>/install-vc64/debug/shared
    There are also some options you can select (if examples and tools should be build too, if you want to have DirectX9 support or profiling, if the media files should be installed together with the binaries (it helps to run the examples out of the box) and if you want to build a static library instead of a shared library). The window should now look like that:
    
    
13. If you are happy with your configuration, click again on Configure. All variables should be white now, since they have not changed.
14. Then click on Generate to generate the Makefiles.
15. In the Shell Window go to the build path (<irrlicht-root-dir>/build-vc64/debug/shared – in my example) and enter “nmake install”. This will compile Irrlicht, the Examples and the Tools and afterwards it will install everything to the specified directory.
16. Enjoy Irrlicht

Have a lot of fun,
GrafZahl

[REDDemon]

You should create a github repository, then you can add external tools like travis that at least automate the build on Mac and Linux with a simple build script. You can even run preliminary tests that don't require rendering (null device or software renderer in example), probably now also rendering works in travis since it went under heavy refactorying (effectively breakin my build scripts, but i not guarantee that)

Works on Windows vista here (GCC 32 bit, 4.6, 4.8, 4.9, 5.1).

You can create a simple batch script that build everything for people having installed VS with a simple double click.

[GrafZahl]

Hi

Thanks for the feedback. Good to know, that Windows and MingW seems to work without issues

Regarding github: You are right, maybe I create a github repository for that. I need to think about it.
Basically I hope - when all operation systems and compilers are tested - that the build system will be integrated into the Irrlicht repository. In the end I think this build system will mostly help the Irrlicht developers, since they don't need to maintain all the different project files and Makefiles anymore.

Regarding the batch-files/script-files:
Basically this build system does everything automatically for you. The only think you need to do is to specify, if you want a Debug or Release build or you want to have a Static or Shared library or if you want to disable any special features like DirectX on Windows. And the path where to build the files and where to install the binaries.
These settings could not be set automatically, so even with script files you need a step where the user has to set it manually.
The only solution would be to provide a set of batch-files like "build_mingw_debug_shared.bat", "build_msvc_debug_shared.bat", "build_mingw_release_shared.bat" and "build_msvc_release_shared.bat" that present everything in a meaningful way. So in the end, someone who wants to have the standard settings with a standard compiler, can compile by clicking on a batch file only. And someone who wants to specify other settings than standard, needs to use cmake manually.
Is this what you mean? Or did I misunderstand you?

I could add these 4 batch files for windows. However since I have no Linux and MacOSX available, I cannot provide scripts for these operating systems.

Best regards,
GrafZahl

[CuteAlien]

Thanks for the script.

Basically I hope - when all operation systems and compilers are tested - that the build system will be integrated into the Irrlicht repository. In the end I think this build system will mostly help the Irrlicht developers, since they don't need to maintain all the different project files and Makefiles anymore.

Unfortunately it's not that easy with CMake. The thing is that we want people to be able to use Irrlicht out of the box. Which means - coming with Makefiles and Visual Studio project files. And the way CMake works it's unfortunately not possible to generate project files from it which then just work for users. Because CMake does not allow to use relative paths. It has reasons for that and it's even good reasons (that way you can create builds in any folder the users choses), but it means we can't use it to create easy project files. So adding CMake is a nice feature - but for us developer it means we have to support one more build-system. And one that even becomes slightly confusing because it also generates VS project files and Makefiles - but different ones than the ones coming with Irrlicht.
So not less work but more work for us and potentially confusing to users :-(

I've not figured out a way around that yet unfortunately. (edit: my hope is that premake might allow for it, but I haven't found time yet to learn that)

[GrafZahl]

Hi

I see your point. In the end it is the decision of the developers (your decision CuteAlien) if they want to go this way or another. For me the CMake build-system was necessary, since I saw no other way to compile Irrlicht with the Intel Compiler by using the official Makefiles/Project-Files. So I wrote the CMake build system for my own purpose and just want to share it with the community, if there is someone with the same requirements then me.

I think CMake 3.3 has an experimental option to use relative paths. Maybe this will do the job?
It is the option CMAKE_USE_RELATIVE_PATHS (you can see it when you enable the advanced-check-box in the upper right corner of the GUI).
I generated for test-purposes a project file for Visual Studio 14.0, but I cannot check if it works, since my Visual Studio IDE is broken.
This is the zip file: just extract it to the a directory "build" inside the irrlicht-1.8.3 directory (download project file)
Maybe it works on your system (when I look at the project file, all source files are given with relative paths).

In general I don't understand completely the "compile out of the box" requirement. Because every release of Irrlicht contains a bunch of different binary files for the case you want to use Irrlicht out of the box. For Users without much programming knowledge the Irrlicht binaries are good enough. Just users who want to adapt Irrlicht to their own needs or who want to use uncommon compilers need to compile Irrlicht from scratch. And those users have enough experience to do the (extremely easy and straight forward) intermediate step with the cmake-gui. On top of this they have much more possibilities to adapt the build-configuration for individual requirements, than normal makefiles or project files could ever give them.

Another solution would be to provide batch-files that does the cmake configuration for the users and help them to generate the Visual Studio project files.
Then they first need to click on the batch file and afterwards they can click on the generated project file.

Best regards,
GrafZahl

[CuteAlien]

We also have scons already I think. Which kinda does the same. And tends to be regularly forgotten when we add files *sigh*. And I like it even less than CMake (I use CMake in a few of my projects, while I'm never going to add scons unless forced (or payed) to do so).

I read about CMAKE_USE_RELATIVE_PATHS, but I'm still running an older cmake build here currently.

Well, one day I'll go over the build-system again and try to find a better solution. And cmake will be one of the obvious options. And I'll appreciate to have that thread then. But can't say I'm motivated much to work on that right now. Too much stuff on my todo which is more important to me. And I just spend last two free weekends I had with building releases. That's been enough frustrating tasks for me for a while to do in my spare-time. I want to go back to coding...

[GrafZahl]

Yes I completely understand you. I think the build systems is not the top priority, since for most of the users it works well.
Let's see if the CMake build system I released will help much users or if it just causes new issues.

I will try to update the CMake build system with every new release and when someone has issues with compilers/platforms I don't use, I will give as much support as I can

And BTW: Thanks for all your effort you spent for Irrlicht. It is really a great graphic engine - one of the fastest open source engines out there.

[Darktib]

Oh, nice CMake script ! However, I think the whole script is a little too big to be easily maintainable - Irrlicht is not that complex^^

I also did a CMake script, it is way less complete than yours as it is only for the engine, no example, and some options are not supported, but it has the advantage of using the new cmake way of adding targets, ie not using include_directories, add_definitions, etc... at all. So, for a project using irrlicht, just doing

Code: Select all

target_link_librairies(myproject PUBLIC Irrlicht)

will setup all include paths, libs automagically.
Shameless advertising: http://irrlicht.sourceforge.net/forum/v ... =9&t=50774

Other than that, it's nice that some people make CMake scripts, one day they will probably make their way in the repo !

The problem with CMake 3.3 is that for Linux users it takes decades for packets to get updated (Debian / Ubuntu / Mint / ...), so let's just assume they won't have it before 2017 !

[GrafZahl]

Your script is actually very short. Good to see that one can actually archive the same with less code.
Nevertheless, building the tools and examples and install them together with the library is also a big advantage, since you can very easy check, if everything runs after the build.

[GrafZahl]

I created a github project: https://github.com/ZahlGraf/IrrlichtCMake
So all further releases can found there.

Today I released 0.2.1 that is compatible with Irrlicht 1.8.3
Here I fixed some missing libraries issues with Linux.
Now everything compiles also for GCC under Linux.
However for MacOSX I still have no idea if it works or not...

Have a lot of fun

[CuteAlien]

Thanks, nice to see. Maybe you could change the license to zlib so it's better compatible with Irrlicht (zlib has less restrictions)?
Also not sure, but it looks like it doesn't use any default compile-flags. Or am I just missing those? Irrlicht always compiles without rtti for example.

[GrafZahl]

Hi

of course I can change it to ZLIB. To be honest, I don't care about the license The only reason why I gave a license to it was, that I want to have any legal options in case someone abuses it for criminal stuff.
I will change it to ZLIB license in the next release.

Regarding the compile flags: CMake choses - depending on the compiler - some own default compile flags. Furthermore I added also those compile flags that have been in the Irrlicht Makefile, like switching off rtti and exceptions and -Wall. However MSVC has of course different flags for that than GCC.
If you think something is missing, than give me a hint. If you just want to adapt the flags for a certain build, then you can add them in the GUI, when you switch on the "Advanced" view (then you will see all variables).

Best regards,
GrafZahl

[Kojack]

I've not figured out a way around that yet unfortunately. (edit: my hope is that premake might allow for it, but I haven't found time yet to learn that)

Premake does have relative paths.
I've started using it for my own stuff recently. I can just go to a command prompt and type "premake5 vs2013" to generate projects with both 32 and 64 bit configurations for visual c++ 2013. Or various other compilers of course.
Although the downside of premake is the lack of a gui for setting configuration options.

[Granyte]

Premake is a much better solution at least as far as VS is concerned it's a farless intrusive solution and yes it doe sgenerate both 32 and 64 bit projects.

[Kojack]

Another interesting one is FastBuild. http://www.fastbuild.org/docs/home.html
It can do automatic unity builds (not unity the game engine, I mean the c++ project organisation technique that can dramatically speed up builds), distributed network builds, etc.
I've found it rather tricky to use though (script syntax and documentation). But like premake it's a single exe that doesn't need installing.