Add ROBOTOLOGY_PROJECT_TAGS to specify which tags/branches to use for…

… each CMake package

The problem in switching between branches when the superbuild is already configured are
properly documented in the change-project-tags.md document.

CMakeLists.txt

@@ -83,11 +83,21 @@ if(NOT CMAKE_CONFIGURATION_TYPES)
     set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS ${ROBOTOLOGY_BUILD_TYPES})
 endif()
 
-# Optionally load a file named ProjectsTagsMaster
-# for overwriting the desired branch/tag/commit
-# of the included subprojects of the superbuild
-# Useful for having superbuild "branches"
-include(ProjectsTagsMaster OPTIONAL)
+set(ROBOTOLOGY_PROJECT_TAGS "Stable" CACHE STRING "The tags to be used for the robotology projects: Stable, Unstable or Custom. This can be changed only before the first configuration.")
+mark_as_advanced(ROBOTOLOGY_PROJECT_TAGS)
+set(ROBOTOLOGY_PROJECT_TAGS_CUSTOM_FILE CACHE FILEPATH "If ROBOTOLOGY_PROJECT_TAGS is custom, this file will be loaded to specify the tags of the projects to use.")
+mark_as_advanced(ROBOTOLOGY_PROJECT_TAGS_CUSTOM_FILE)
+set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Stable" "Unstable" "Custom")
+
+if(ROBOTOLOGY_PROJECT_TAGS STREQUAL "Stable")
+    include(ProjectsTagsStable)
+elseif(ROBOTOLOGY_PROJECT_TAGS STREQUAL "Unstable")
+    include(ProjectsTagsUnstable)
+elseif(ROBOTOLOGY_PROJECT_TAGS STREQUAL "Custom")
+    include(${ROBOTOLOGY_PROJECT_TAGS_CUSTOM_FILE})
+else()
+    message(FATAL_ERROR "The ROBOTOLOGY_PROJECT_TAGS variable can be Stable, Unstable or Custom. ${ROBOTOLOGY_PROJECT_TAGS} value is not supported.")
+endif()
 
 #Set CMake policies
 if(NOT CMAKE_VERSION VERSION_LESS 3.0)

README.md

@@ -429,22 +429,8 @@ For this reason, if you are activly developing on a repository managed by the `r
 option to `TRUE`. This option will ensure that the superbuild will not try to automatically update the `<package_name>` repository. See  https://robotology.github.io/ycm/gh-pages/git-master/manual/ycm-superbuild.7.html#developer-mode
 for more details on this options.
 
-Handling the devel branch
-=========================
-[`YARP`](https://github.com/robotology/yarp), [`ICUB`](https://github.com/robotology/icub-main) and several other robotology software uses a `devel` branch for testing experimental features before a full release,
-when this changes are merged in their `master` branch. For more information on this workflow, see [yarp's CONTRIBUTING.md file](https://github.com/robotology/yarp/blob/master/.github/CONTRIBUTING.md).
-
-For ensuring stability to the end-users, the `robotology-superbuild` is always tested against the `master` branches, as this are the recomended branches for users.
-However if you work at [IIT@Genoa](https://www.iit.it/research/lines/icub), it may be possible that you want to interface
-your robot (running the `devel` branch of `yarp` and `icub-main`) with the software  on your PC compiled with the `robotology-superbuild`.
-This is general can be done using the `master` branch of `yarp`, but sometimes there are changes in devel that can introduce incompatibilities
-between yarp `master` and `devel`, see for example https://github.com/robotology/yarp/pull/1010#issuecomment-266453586 ). This incompatibilities are documented in the YARP changelog.
-
-If you want to use a given repository in the `robotology-superbuild` in the `devel` branch, you have to:
-* set the `YCM_EP_DEVEL_MODE_<package_name>` to `TRUE`, such that the superbuild will not try to manage the updates of this repository
-* manually switch the source repository to the devel branch .
-
-To switch back, just manually switch the branches back to `master` and set  `YCM_EP_DEVEL_MODE_<package_name>` variable to `FALSE`.
+By default, the `robotology-superbuild` uses the latest "stable" branches of the robotology repositories, but in some cases it may be necessary to use the "unstable" active development branches, 
+or use some fixed tags. For this advanced functionalities, please refer to the documentation on changing the default project tags, available at [`doc/change-project-tags.md`](doc/change-project-tags.md).
 
 
 Profile-specific documentation

cmake/ProjectsTagsMaster.cmake → cmake/ProjectsTagsStable.cmake

@@ -3,4 +3,5 @@ macro(set_tag tag_name tag_value)
         set(${tag_name} ${tag_value})
     endif()
 endmacro()
+set(YARP_TAG yarp-3.2)
 set(OsqpEigen_TAG v0.4.1) 

cmake/ProjectsTagsDevel.cmake → cmake/ProjectsTagsUnstable.cmake

@@ -16,8 +16,6 @@ set_tag(icub-firmware-shared_TAG devel)
 set_tag(yarp-matlab-bindings_TAG devel)
 set_tag(GazeboYARPPlugins_TAG devel)
 set_tag(robots-configuration_TAG devel)
-set_tag(icub-models_TAG devel)
-set_tag(icub-gazebo_TAG devel)
 set_tag(icub-gazebo-wholebody_TAG devel)
 set_tag(whole-body-controllers_TAG master)
 set_tag(OsqpEigen_TAG v0.4.1) 

doc/change-project-tags.md

@@ -0,0 +1,23 @@
+Change project tags
+===================
+
+For [`YCM`-based superbuilds](http://robotology.github.io/ycm/gh-pages/git-master/manual/ycm-superbuild.7.html), the specific 
+branch, tag or commit used for each specific CMake package can be manually specified  using the [`<package>_TAG`](http://robotology.github.io/ycm/gh-pages/git-master/manual/ycm-superbuild.7.html#overriding-parameters) 
+CMake variables. By default, the `robotology-superbuild` uses the latest "stable" branches of the robotology repositories, but in some cases it may be necessary to use the "unstable" active development branches, 
+or use some fixed tags. These advanced use cases are supported by the `ROBOTOLOGY_PROJECT_TAGS` CMake variable. 
+
+`ROBOTOLOGY_PROJECT_TAGS` is an advanced CMake option, so it is visible from the CMake GUI only after enabling the visualization of advanced variables.
+It can take one of three possible values: 
+* `Stable` :  this is the default value, that will use the tags or branches specified in [`cmake/ProjectTagsStable.cmake`](cmake/ProjectTagsStable.cmake) 
+              that are the stables branches for the robotology projects.
+* `Unstable` : by selecting this option, you will use the tags or branches specified in [`cmake/ProjectTagsUnstable.cmake`](cmake/ProjectTagsUnstable.cmake), 
+               that are the "unstable" active development branches for the robotology projects. This is reccomended just for users that work at the IIT labs in Genoa,
+               as it can break compilation or runtime behaviour without any notice.
+* `Custom` : by selecting this option, you need to manually specify the tags or branches that you want to use by specifying a custom project tags file in the 
+             `ROBOTOLOGY_PROJECT_TAGS_CUSTOM_FILE` CMake option. This is useful when  you want to use a fixed version of the software built by the superbuild.
+
+**Due to limitations on how the CMake's [`ExternalProject`](https://cmake.org/cmake/help/latest/module/ExternalProject.html) modules handles the TAG option, the choice
+of the is option needs to be done before the source code for the CMake packages is downloaded for the first time in the `external` and `robotology` directories. 
+If you want to change the `ROBOTOLOGY_PROJECT_TAGS` or `ROBOTOLOGY_PROJECT_TAGS_CUSTOM_FILE` option in an existing superbuild, you need to manually delete the `external` and `robotology`
+directories, and then configure again the superbuild. Note that this also means that if  you have multiple build directories for the same superbuild, all of them 
+need to use consistent `ROBOTOLOGY_PROJECT_TAGS` values.**