User-friendly skip component warning (#165)

Signed-off-by: Michael X. Grey <grey@openrobotics.org>

cmake/IgnConfigureBuild.cmake

@@ -46,11 +46,11 @@ macro(ign_configure_build)
   #============================================================================
   # Print warnings and errors
   if(build_warnings)
-    message(WARNING "-- BUILD WARNINGS")
+    set(all_warnings " CONFIGURATION WARNINGS:")
     foreach (msg ${build_warnings})
-      message(WARNING "-- ${msg}")
+      ign_string_append(all_warnings " -- ${msg}" DELIM "\n")
     endforeach ()
-    message(WARNING "-- END BUILD WARNINGS\n")
+    message(WARNING "${all_warnings}")
   endif (build_warnings)
 
   if(build_errors)
@@ -191,7 +191,7 @@ macro(ign_configure_build)
     # Add the source code directories of each component if they exist
     foreach(component ${ign_configure_build_COMPONENTS})
 
-      if(NOT SKIP_${component})
+      if(NOT SKIP_${component} AND NOT INTERNAL_SKIP_${component})
 
         set(found_${component}_src FALSE)
 
@@ -255,7 +255,9 @@ macro(ign_configure_build)
       else()
 
         set(skip_msg "Skipping the component [${component}]")
-        if(${component}_MISSING_DEPS)
+        if(SKIP_${component})
+          ign_string_append(skip_msg "by user request")
+        elseif(${component}_MISSING_DEPS)
           ign_string_append(skip_msg "because the following packages are missing: ${${component}_MISSING_DEPS}")
         endif()
 

cmake/IgnUtils.cmake

@@ -47,7 +47,8 @@
 #
 # [QUIET]: Optional. If provided, it will be passed forward to cmake's
 #          find_package(~) command. This macro will still print its normal
-#          output.
+#          output, except there will be no warning if the package is missing,
+#          unless REQUIRED or REQUIRED_BY is specified.
 #
 # [BUILD_ONLY]: Optional. Use this to indicate that the project only needs this
 #               package while building, and it does not need to be available to
@@ -197,7 +198,7 @@ macro(ign_find_package PACKAGE_NAME)
 
     #------------------------------------
     # Construct the warning/error message to produce
-    set(${PACKAGE_NAME}_msg "Missing: ${${PACKAGE_NAME}_pretty}")
+    set(${PACKAGE_NAME}_msg "Missing dependency [${${PACKAGE_NAME}_pretty}]")
 
     if(ign_find_package_COMPONENTS)
       ign_list_to_string(comp_str ign_find_package_COMPONENTS DELIM ", ")
@@ -219,19 +220,25 @@ macro(ign_find_package PACKAGE_NAME)
 
       foreach(component ${ign_find_package_REQUIRED_BY})
 
-        # Otherwise, if it was only required by some of the components, create
-        # a warning about which components will not be available.
-        ign_build_warning("Cannot build component [${component}] - ${${PACKAGE_NAME}_msg}")
+        if(NOT SKIP_${component})
+          # Otherwise, if it was only required by some of the components, create
+          # a warning about which components will not be available, unless the
+          # user explicitly requested that it be skipped
+          ign_build_warning("Skipping component [${component}]: ${${PACKAGE_NAME}_msg}.\n    ^~~~~ Set SKIP_${component}=true in cmake to suppress this warning.\n ")
 
-        # Also create a variable to indicate that we should skip the component
-        set(SKIP_${component} true)
+          # Create a variable to indicate that we need to skip the component
+          set(INTERNAL_SKIP_${component} true)
 
-        ign_string_append(${component}_MISSING_DEPS "${${PACKAGE_NAME}_pretty}" DELIM ", ")
+          # Track the missing dependencies
+          ign_string_append(${component}_MISSING_DEPS "${${PACKAGE_NAME}_pretty}" DELIM ", ")
+        endif()
 
       endforeach()
 
     else()
-      ign_build_warning(${${PACKAGE_NAME}_msg})
+      if(NOT ign_find_package_QUIET)
+        ign_build_warning(${${PACKAGE_NAME}_msg})
+      endif()
     endif()
 
   endif()
@@ -771,8 +778,7 @@ endmacro(ign_build_error)
 # ign_build_warning macro
 macro(ign_build_warning)
   foreach(str ${ARGN})
-    set(msg "\t${str}" )
-    list(APPEND build_warnings ${msg})
+    list(APPEND build_warnings "${str}")
   endforeach(str ${ARGN})
 endmacro(ign_build_warning)
 

tutorials/developing_with_ign-cmake.md

@@ -36,6 +36,35 @@ To change the build type, set the CMake flag:
 -DCMAKE_BUILD_TYPE=Debug
 ```
 
+### Disabling or suppressing warnings about optional components
+
+Many ignition packages come with optional component libraries.
+These optional components will typically have additional dependencies that the
+package's core library does not require. If you are missing the dependencies of
+any optional components, you will receive a cmake warning like
+
+```
+-- Skipping component [component_name]: Missing dependency [dependency_name].
+   ^~~~~ Set SKIP_component_name=true in cmake to suppress this warning.
+```
+
+If you do not care about the specified component, you can safely ignore this
+warning. The configuration and build steps will succeed without any problem. The
+only side effect is the optional component will not be built.
+
+If you do want to build the optional component, then you will need to install
+whichever dependencies were said to be missing and then rerun cmake.
+
+If you do *not* want to build the optional component and you want to suppress
+the warning about the missing dependencies, you can set the cmake flag:
+
+```
+-DSKIP_component_name=true
+```
+
+where you should replace `component_name` with the actual name of the component
+as specified inside the angle brackets `[]` of the warning.
+
 ### Creating a compilation database
 
 `CMake` can optionally generate a compilation data base that may be used with a variety of code completion tools.