Adding Git Submodules

[MoctezumaDev]

Right now I see a big problem for any new comer which is interested in trying Magnum. They are going only to clone mangnum git repository and as soon as they try to compile the project they will realize that it needs other 3 repositories just to get an example working in Linux.

I have to say that I totally agree in having different repositories for each thing but I also think that magnum should be complete just by cloning it's repository. My experience with Git is not as extensive as with SVN but by using SVN you can have external repositories locked into a specific revisition as directories so that when you check out the repository for the first time its also going to check out the external repositories to a specific revisiton.

I investigated a bit about this and in git you can have submodules (external repositories) locked to a specific commit.

http://git-scm.com/book/en/Git-Tools-Submodules

So we would have a directory structure like

magnum/libs/corrade
magnum/plugins
magnum/examples

A neat thing would be that CMake would also build corrade by default and at least the triangle example.

[mosra]

Great idea! I did similar thing with my previous projects and this is also similar to how Qt5 sources are managed (with great success). However, some people say that submodules are too hard to use and prone to data loss, so I wanted to avoid them for general use case if possible. Magnum (and also all other projects) already uses submodules, there is toolchains submodule which contains stuff for cross-compiling, but it is fully optional and is not needed for common usage.

Instead of adding submodules into magnum repository I would rather have some kind of "superproject" (e.g. magnum-bundle repository) which would contain just the submodules for corrade, magnum, magnum-plugins, magnum-integration, magnum-examples and some tiny bureaucracy (readme/license) stuff on top, but without any actual code (similar to e.g. https://github.com/qtproject/qt5 or https://github.com/harr999y/boost).

I personally hope that CMake would be able to handle this and compile/install everything at once, which will be great. I'll do some research about CMake subprojects/modular projects and will see what can be done.

[svenstaro]

I think you should not go with a super project but merely put all the required repos for magnum into this repo as submodules. examples and plugins and such do not really need to be linked. Other projects also do it pretty much like this rather often.

I think making a super repo is unnecessarily abstract and also hard for you to manage as you need to pull in new deps into the super repo manually after working on one of the specific other repos outside the context of the super repo.

CMake is able to do all of this wonderfully if you switch to using PROJECT_SOURCE_DIR and PROJECT_BINARY_DIR.

So use submodules buy only for making this easier to build but not for putting unrelated things under the same umbrella. Use an organization for that!

Refs:

• http://www.cmake.org/Wiki/CMake_Useful_Variables
• http://stackoverflow.com/questions/8587224/what-is-the-proper-use-of-the-cmake-project-directive

[mosra]

I'd rather not put Magnum dependencies into magnum repository, as for nearly every change in Corrade I would also need to update the submodule in magnum to make it compilable. It would add too much noise and maintenance overhead, the occasional noise with updating Find*.cmake modules in each repo is already annoying enough.

I thought that the super repo would handle just that one use case when you want to do a quick "one-click" install without too much hassle. It would be then just a matter of git clone --recursive or git pull && git submodule update, then you call cmake and cmake --build . --target install and you are done with Corrade, Magnum and all selected plugins/examples/libraries in single step.

This will be best for users who just want to use the project. Any actual development on the library itself is painful with submodules and makes some things unnecessarily complicated (e.g. pulling upstream changes where you want to update just one project, issues when you have uncommited changes in submodule...), so the preferred way for developing the library itself would still be to clone all repos separately.

Thanks for references for the PROJECT_* variables, I'll switch to them.

[mosra]

After two hundred years I was finally able to implement support for CMake subprojects. Sorry it took so long.

What I've done: there is no "superproject" repository anywhere, it's completely up to you as the user how you set it up -- just a matter of putting all the needed repos into your project (Git submodules or whatever) and then adding them in correct order using CMake's add_subdirectory() command. All the magic is then done by find_package(Magnum) and others, which recognize the subprojects and makes them available in your project tree. The same of course works for Corrade, plugin, integration, extras and example repositories too.

The Getting Started Guide was rewritten in 4fdf96d to prefer this approach, as it is much simpler to do (and to explain, too).