Adding new cli parameters for configuring the logging. (#327)

* Adding new cli parameters for configuring the logging.

cr https://code.amazon.com/reviews/CR-3728503

* Moving the external logger library from rcutils into rcl. Also automatic uncrustify.

* Fixing issue with rebase

* Temporarily switching the default to noop logger ext_lib while system dependency issue is solved for Windows/Mac.

* Fixing the format2/3 xmllint issue.

* style changes, and one actual fix

Signed-off-by: William Woodall <william@osrfoundation.org>

* rename rc_logging* to rcl_logging*

Signed-off-by: William Woodall <william@osrfoundation.org>

* Expand rcl_logging_configure API with allocator

This is to make sure that this API is complete, and we can merge rcl#350 later without breaking the API at a later date.

* update logging.c with new use of allocator in API

* update init.c with new API changes

* Switching back to va_list for output handlers.

* address review comments

Signed-off-by: William Woodall <william@osrfoundation.org>

rcl/CMakeLists.txt

@@ -12,6 +12,9 @@ find_package(rosidl_generator_c REQUIRED)
 
 include_directories(include)
 
+include(cmake/get_default_rcl_logging_implementation.cmake)
+get_default_rcl_logging_implementation(RCL_LOGGING_IMPL)
+
 # Default to C11
 if(NOT CMAKE_C_STANDARD)
  set(CMAKE_C_STANDARD 11)
@@ -38,6 +41,7 @@ set(${PROJECT_NAME}_sources
  src/rcl/init_options.c
  src/rcl/lexer.c
  src/rcl/lexer_lookahead.c
+ src/rcl/logging.c
  src/rcl/node.c
  src/rcl/publisher.c
  src/rcl/remap.c
@@ -58,6 +62,7 @@ ament_target_dependencies(${PROJECT_NAME}
  "rmw"
  "rcutils"
  "rosidl_generator_c"
+ ${RCL_LOGGING_IMPL}
 )
 
 # Causes the visibility macros to use dllexport rather than dllimport,
@@ -86,6 +91,7 @@ ament_export_dependencies(rmw_implementation)
 ament_export_dependencies(rmw)
 ament_export_dependencies(rcutils)
 ament_export_dependencies(rosidl_generator_c)
+ament_export_dependencies(${RCL_LOGGING_IMPL})
 
 if(BUILD_TESTING)
  find_package(ament_lint_auto REQUIRED)

rcl/cmake/get_default_rcl_logging_implementation.cmake

@@ -0,0 +1,46 @@
+# Copyright 2018 Open Source Robotics Foundation, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+#
+# Get the package name of the default logging implementation.
+#
+# Either selecting it using the variable RCL_LOGGING_IMPLEMENTATION or
+# choosing a default from the available implementations.
+#
+# :param var: the output variable name containing the package name
+# :type var: string
+#
+macro(get_default_rcl_logging_implementation var)
+
+ # if logging implementation already specified or RCL_LOGGING_IMPLEMENTATION environment variable
+ # is set then use that, otherwise default to using rcl_logging_noop
+ if(NOT "${RCL_LOGGING_IMPLEMENTATION}" STREQUAL "")
+ set(_logging_implementation "${RCL_LOGGING_IMPLEMENTATION}")
+ elseif(NOT "$ENV{RCL_LOGGING_IMPLEMENTATION}" STREQUAL "")
+ set(_logging_implementation "$ENV{RCL_LOGGING_IMPLEMENTATION}")
+ else()
+ set(_logging_implementation rcl_logging_noop)
+ endif()
+
+ # persist implementation decision in cache
+ # if it was not determined dynamically
+ set(
+ RCL_LOGGING_IMPLEMENTATION "${_logging_implementation}"
+ CACHE STRING "select rcl logging implementation to use" FORCE
+ )
+
+ find_package("${_logging_implementation}" REQUIRED)
+
+ set(${var} ${_logging_implementation})
+endmacro()

rcl/include/rcl/arguments.h

@@ -35,6 +35,10 @@ typedef struct rcl_arguments_t
 } rcl_arguments_t;
 
 #define RCL_LOG_LEVEL_ARG_RULE "__log_level:="
+#define RCL_EXTERNAL_LOG_CONFIG_ARG_RULE "__log_config_file:="
+#define RCL_LOG_DISABLE_STDOUT_ARG_RULE "__log_disable_stdout:="
+#define RCL_LOG_DISABLE_ROSOUT_ARG_RULE "__log_disable_rosout:="
+#define RCL_LOG_DISABLE_EXT_LIB_ARG_RULE "__log_disable_external_lib:="
 #define RCL_PARAM_FILE_ARG_RULE "__params:="
 
 /// Return a rcl_node_t struct with members initialized to `NULL`.

rcl/include/rcl/logging.h

@@ -0,0 +1,77 @@
+// Copyright 2018 Open Source Robotics Foundation, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef RCL__LOGGING_H_
+#define RCL__LOGGING_H_
+
+#include "rcl/allocator.h"
+#include "rcl/arguments.h"
+#include "rcl/macros.h"
+#include "rcl/types.h"
+#include "rcl/visibility_control.h"
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+
+/// Configure the logging system.
+/**
+ * This function should be called during the ROS initialization process.
+ * It will add the enabled log output appenders to the root logger.
+ *
+ * <hr>
+ * Attribute | Adherence
+ * ------------------ | -------------
+ * Allocates Memory | Yes
+ * Thread-Safe | No
+ * Uses Atomics | No
+ * Lock-Free | Yes
+ *
+ * \param global_args The global arguments for the system
+ * \return `RCL_RET_OK` if successful, or
+ * \return `RCL_RET_BAD_ALLOC` if allocating memory failed, or
+ * \return `RCL_RET_ERR` if a general error occurs
+ */
+RCL_PUBLIC
+RCL_WARN_UNUSED
+rcl_ret_t
+rcl_logging_configure(
+ const rcl_arguments_t * global_args,
+ const rcl_allocator_t * allocator);
+
+/**
+ * This function should be called to tear down the logging setup by the configure function.
+ *
+ * <hr>
+ * Attribute | Adherence
+ * ------------------ | -------------
+ * Allocates Memory | No
+ * Thread-Safe | No
+ * Uses Atomics | No
+ * Lock-Free | Yes
+ *
+ * \return `RCL_RET_OK` if successful.
+ * \return `RCL_RET_ERR` if a general error occurs
+ */
+RCL_PUBLIC
+RCL_WARN_UNUSED
+rcl_ret_t rcl_logging_fini();
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // RCL__LOGGING_H_

rcl/include/rcl/logging_external_interface.h

@@ -0,0 +1,75 @@
+// Copyright 2018 Open Source Robotics Foundation, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef RCL__LOGGING_EXTERNAL_INTERFACE_H_
+#define RCL__LOGGING_EXTERNAL_INTERFACE_H_
+
+#include "rcl/macros.h"
+#include "rcl/types.h"
+#include "rcl/visibility_control.h"
+
+/// Initialize the external logging library.
+/**
+ * \param[in] config_file The location of a config file that the external
+ * logging library should use to configure itself.
+ * If no config file is provided this will be set to an empty string.
+ * Must be a NULL terminated c string.
+ * \return RCL_RET_OK if initialized successfully, or
+ * \return RCL_RET_ERROR if an unspecified error occurs.
+ */
+RCL_PUBLIC
+RCL_WARN_UNUSED
+rcl_ret_t
+rcl_logging_external_initialize(const char * config_file);
+
+/// Free the resources allocated for the external logging system.
+/**
+ * This puts the system into a state equivalent to being uninitialized.
+ *
+ * \return RCL_RET_OK if successfully shutdown, or
+ * \return RCL_RET_ERROR if an unspecified error occurs.
+ */
+RCL_PUBLIC
+RCL_WARN_UNUSED
+rcl_ret_t
+rcl_logging_external_shutdown();
+
+/// Log a message.
+/**
+ * \param[in] severity The severity level of the message being logged.
+ * \param[in] name The name of the logger, must either be a null terminated
+ * c string or NULL.
+ * If NULL or empty the root logger will be used.
+ * \param[in] msg The message to be logged. Must be a null terminated c string.
+ */
+RCL_PUBLIC
+void
+rcl_logging_external_log(int severity, const char * name, const char * msg);
+
+/// Set the severity level for a logger.
+/**
+ * This function sets the severity level for the specified logger.
+ * If the name provided is an empty string or NULL it will change the level of
+ * the root logger.
+ *
+ * \param[in] name The name of the logger.
+ * Must be a NULL terminated c string or NULL.
+ * \param[in] level The severity level to be used for the specified logger.
+ * \return RCL_RET_OK if set successfully, or
+ * \return RCL_RET_ERROR if an unspecified error occurs.
+ */
+RCL_PUBLIC
+rcl_ret_t rcl_logging_external_set_logger_level(const char * name, int level);
+
+#endif // RCL__LOGGING_EXTERNAL_INTERFACE_H_

rcl/include/rcl/macros.h

@@ -27,6 +27,8 @@ extern "C"
 # define RCL_WARN_UNUSED _Check_return_
 #endif
 
+#define RCL_UNUSED(x) (void)(x)
+
 #ifdef __cplusplus
 }
 #endif

rcl/package.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0"?>
-<?xml-model href="http://download.ros.org/schema/package_format2.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
-<package format="2">
+<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
+<package format="3">
  <name>rcl</name>
  <version>0.6.0</version>
  <description>The ROS client library common implementation.
@@ -37,6 +37,8 @@
  <test_depend>osrf_testing_tools_cpp</test_depend>
  <test_depend>test_msgs</test_depend>
 
+ <group_depend>rcl_logging_packages</group_depend>
+
  <export>
  <build_type>ament_cmake</build_type>
  </export>