[build] CMake build system & better building docs

[define-private-public]

I'm working right now on a branch of this that will build all of the stuff in this repository using CMake. Working on issues #332 and #328, alongside problems with linking dynamic vs. static GLFW have prompted this. I've been doing the work here: https://github.com/define-private-public/raylib/tree/cmake_test

Right now, it's at a state where you can do this and have raylib working with examples:

1. mkdir build
2. cd build
3. cmake .. or cmake -DSHARED_RAYLIB=ON ..
4. make -k

And you're good to go!

I primarily work on a Linux machine (Ubuntu), and have very limited knowledge of OS X, so any help with Windows is appreciated. For the moment, I'm working on the desktop targets, but Android, Raspberry Pi, and Web will be added in for completeness.

Build TODO List:

• Linux static library
• Linux .so
• OS X static library
• OS X .dylib
• Windows static library
• Windows DLL
• RPi static
• RPi dynamic
• Android
• Web
• examples
• simple games
• complex games (the ones that have their on subdirectories in games/)

We also need to update the documentation for dependencies to build, and how use the .a and .so/.dylib/.dll files that are made.

Docs TODO:

• CMake dependency (should be very simple: install it)
• GLFW dependency (static or shared)
• Linking libraylib.a
• Linking libraylib.so on Linux (w/ run.sh shell script)
• Linking libraylib.dylib on OS X (-Xlinker -rpath .)
• Linking raylib.dll on Windows
• Building the libraylib.bc for web (need to activate the emsdk first)

Other TODO:

• the linking/building process is quite the same for both examples and games, figure out a way how to reduce the duplication of code?
• Cleaning the .gitignore file. I have already had to touch it. Some files were being skipped over that shouldn't have!!
• Remove the old Makefiles
• List of all current compilation flags
• Compile options to build (or not) the games and examples
• Test building games & examples for web with the generated libraylib.bc

Questions I have for others (right now):

• For the RPi, are we only supporting raspbian?
• Explanation of the building for Android

[raysan5]

About RPI, only supporting Raspbian for the moment, actually only tested on that platform, and not using X window system, OpenGL ES runs directly at hardware level through EGL, that's different than other Linux distros (Desktop Linux). It could work over X windows with the newly included (experimental?) OpenGL driver but not configured for that and it only works on RPI 2 and 3.

[RDR8]

Awesome work! I've yet to sit down with this stuff but it looks great. Thanks!

[define-private-public]

@RDR8 What I could use help with most at the moment might be the non-Desktop targets. All the necessary stuff for them should be in the Makefiles, but I could use some help pulling them out and figuring out the exact build steps.

[define-private-public]

@raysan5 Could you tell me more about your build environment? I'm having a real hard time on Windows trying to get GLFW setup and for CMake to place nice here (something about how it can't find g++ for MinGW).

[RDR8]

I have a Pi to play with. It'll be the weekend or after before I can punch in. I would like to tinker with Android also but am not set up with adb or any sacrificial hardware. I am especially interested in alternative ARM SBCs. I need to research the toolchains before diving in. Anyway, yeah, I'll look into this. Thanks

[define-private-public]

I don't think the RPi target should be too much different from the Linux one. Since... well... it's also Linux.

[define-private-public]

Good news. All of the games are done! This includes the more complex ones.

[define-private-public]

@raysan5 Aside from your Windows dev environment, can you get me a list of all possible compilation flags e.g. SOFT_AL, GRAPHICS_API_OPENGL_*, etc.

[raysan5]

To all of you, just say thanks for such an amazing work, despite CMake is not my preferred build system, undoubtely, this addition will represent a huge boost for raylib project.

About internal flags to configure raylib, just check #200

[define-private-public]

Oh man, that's going to be a lot of flags to mess with. What do you think are the most important ones to be able to configure?

So far I've got:

• GRAPHICS_API_*

I don't think adding options for all of the SUPPORT_FILEFORMAT_* ones are that necessary, since I think most people would want support for as many image formats as possible.

[define-private-public]

Can anyone else comment on how building for Android is supposed to work? Last time I ever toyed with Android development was back before university, and that is when the API was at 2.x. Does the NDK create a .jar of raylib where we can write the raylib game in Java? Or does it compile the whole game (written in C) to the .apk?

I have no idea what I'm doing when it comes to Android.

[define-private-public]

Does this look useful to us: https://github.com/taka-no-me/android-cmake ?

Once again, I have absolutely no idea what I'm doing when I'm working with Android.

[RDR8]

From "Getting Started with the NDK"
"Android Studio's default build tool to compile native libraries is CMake. Android Studio also supports ndk-build due to the large number of existing projects that use the build toolkit. However, if you are creating a new native library, you should use CMake. "

[raysan5]

About configuration flags, they are exposed only for advance users to allow them to have full control over library requirements. No need to support all of them, with PLATFORM_* and GRAPHICS_API_* is ok.

About Android building, first raylib needs to be build as a .so library, to do that a standalone Android toolchain is required.

To build the final .apk it's not that simple, detailed explanation here: #278

[define-private-public]

Okay, latest update is now there is a way to configure the build platform and OpenGL version of choice. I'm a little hesitant to say that it offers "drop down," method, but it lets the user (if they're using the CMake GUI or ncurses one) to cycle though valid options. It also selects OpenGL ES if on a non-desktop platform.

As per issue #337 should I have it disable GL ES 2.0 on desktop?

[define-private-public]

Latest update is that I've gotten the web library libraylib.bc to compile using CMake. I haven't tested it yet with compiling the examples/games for web, but checking the .bc that's provided in the repo it looks fairly similar.

[tazdij]

@raysan5, do you plan on developing using makefiles directly? I would hate to lose them. And be forced to create them using cmake, which gives you super bloated and overly complicated makefiles, in my experience.

[raysan5]

@tazdij, no plans to replace/remove direct Makefiles. I like them, I think they are pretty easy to read and Makefiles are still the only build system I feel I have full control over it. I've analyzed most of the build systems out there and Makefiles are probably the simplest option (aside of plain command-line scripts).

But it's true that lots of users feel comfortable with CMake so I think it could be a great support this alternative build system.

[define-private-public]

@raysan5 How do you feel about the CMake files I've written so far? If you don't think you understand what's going on, I wouldn't mind sitting down with you in IRC (or IM) to run it through you step by step. It's pretty simple so far. (Still don't have the Windows though....)

[define-private-public]

@RDR8 Any headway made on the Pi platform?

[RDR8]

Negative, sorry. Playing an impromptu game of Frogger in real life and don't have any study time. A return to normalcy is likely some days away. I have been following your progress and I do really appreciate your efforts here. Your keyboard is on fire.

[tazdij]

@raysan5 thank you for the response, I am also more comfortable with Makefiles. And having both build systems should allow for more people to have the build environment they enjoy, also enabling developer to use their preferred IDE as an actual IDE instead of a glorified text editor. (I code in GNU Edit and vi so this doesn't appeal to me)

@define-private-public This is some amazing work so far, I would like to see CMake as an alternative build system included in the release builds of raylib. I would most likely not use it myself though.

[raysan5]

@define-private-public, thanks for all your work, it's impressive. CMake code is pretty clear to me.

Excuse me if I haven't been too active lately, I should took care of some personal matters and next Monday I'm going on holiday for 15 days.

Lots of pending things... I'll try to get it done by September to release a new version, before academic course starts; this year there are several universities using raylib.

[define-private-public]

Hey @raysan5, my interest in working on this is starting to wane. a few reasons:

1. I have no idea really how to do Windows development, or development on that platform.
2. Same goes for Android
3. I don't think I have my RPi with me, so I'm a little stuck there when it comes to testing. I'm sure someone could go off of the Linux branch and do stuff there
4. I originally worked on this, so whoever could use the Nim bindings I was working on could have a simple time to get raylib working on their machine. But an odd issue has popped up, where I have no clear solution: https://forum.nim-lang.org/t/3059/2
5. I'm already juggling too many things in my free time right now. I need to scale back a bit.

If you're interested in merging what I have right now, I'm still willing to write up docs for how to use the CMake files.

[raysan5]

Hi @define-private-public, you get so far on CMake implementation, don't worry, just send a pull request and I'll integrate it into main repo to let other people continue with it.

About your doubts, Windows and RPI shouldn't be an big issue, Android is a bit more complex, I'm also dealing with it to build examples into APK.

I saw you did a great work with the Nim binding, about your issue, I faced some similar problem with Lua binding and just defined the type as opaque data, don't know if that's possible with Nim...

[define-private-public]

PR for what I have is right here: #348

Feel free to edit my main comment since it's a task list. If anyone else replies to this ticket I'll still monitor it. I can provide guidance for CMake if anyone needs it.

[raysan5]

This issue is related with #401.

CMake system has been greatly improved in the last weeks by @a3f.

Just closing this issue for now, it's difficult to track all the points on it... some are already implemented, some could be not valid any more and some should probably better moved to smaller issues.