[Foxy] Allow configuring logging directory through environment variables

rcl_logging_interface/CMakeLists.txt

@@ -0,0 +1,58 @@
+cmake_minimum_required(VERSION 3.5)
+
+project(rcl_logging_interface)
+
+# Default to C11
+if(NOT CMAKE_C_STANDARD)
+  set(CMAKE_C_STANDARD 11)
+endif()
+# Default to C++14
+if(NOT CMAKE_CXX_STANDARD)
+  set(CMAKE_CXX_STANDARD 14)
+endif()
+
+if(NOT WIN32)
+  add_compile_options(-Wall -Wextra -Wpedantic)
+endif()
+
+find_package(ament_cmake_ros REQUIRED)
+find_package(rcutils REQUIRED)
+
+set(${PROJECT_NAME}_sources
+  "src/logging_dir.c"
+)
+add_library(${PROJECT_NAME} ${${PROJECT_NAME}_sources})
+target_include_directories(${PROJECT_NAME} PUBLIC
+  "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>"
+  "$<INSTALL_INTERFACE:include>")
+ament_target_dependencies(${PROJECT_NAME} rcutils)
+target_compile_definitions(${PROJECT_NAME} PRIVATE "RCL_LOGGING_INTERFACE_BUILDING_DLL")
+
+install(
+  DIRECTORY include/
+  DESTINATION include
+)
+install(TARGETS ${PROJECT_NAME} EXPORT ${PROJECT_NAME}
+  ARCHIVE DESTINATION lib
+  LIBRARY DESTINATION lib
+  RUNTIME DESTINATION bin)
+
+ament_export_include_directories(include)
+ament_export_targets(${PROJECT_NAME})
+ament_export_dependencies(rcutils)
+
+if(BUILD_TESTING)
+  find_package(ament_lint_auto REQUIRED)
+  ament_lint_auto_find_test_dependencies()
+
+  find_package(ament_cmake_gtest REQUIRED)
+  find_package(rcpputils REQUIRED)
+  ament_add_gtest(test_get_logging_directory test/test_get_logging_directory.cpp)
+  if(TARGET test_get_logging_directory)
+    target_link_libraries(test_get_logging_directory ${PROJECT_NAME})
+    target_include_directories(test_get_logging_directory PRIVATE include)
+    ament_target_dependencies(test_get_logging_directory rcutils rcpputils)
+  endif()
+endif()
+
+ament_package()

rcl_logging_interface/QUALITY_DECLARATION.md

@@ -0,0 +1,185 @@
+This document is a declaration of software quality for the `rcl_logging_interface` package, based on the guidelines in [REP-2004](https://github.com/ros-infrastructure/rep/blob/rep-2004/rep-2004.rst).
+
+# `rcl_logging_interface` Quality Declaration
+
+The package `rcl_logging_interface` claims to be in the **Quality Level 4** category.
+
+Below are the rationales, notes, and caveats for this claim, organized by each requirement listed in the [Package Quality Categories in REP-2004](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#package-quality-categories) of the ROS2 developer guide.
+
+## Version Policy [1]
+
+### Version Scheme [1.i]
+
+`rcl_logging_interface` uses `semver` according to the recommendation for ROS Core packages in the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#versioning).
+
+### Version Stability [1.ii]
+
+Currently this package is at or above a stable version, i.e. `>= 1.0.0`.
+
+### Public API Declaration [1.iii]
+
+All symbols in the installed headers are considered part of the public API.
+
+All installed headers are in the [include](./include/rcl_logging_interface) directory of the package.
+
+### API Stability Policy [1.iv]
+
+`rcl_logging_interface` will not break public API within a released ROS distribution, i.e. no major releases once the ROS distribution is released.
+
+### ABI Stability Policy [1.v]
+
+`rcl_logging_interface` contains only header files, and thus ABI Stability does not apply to it.
+
+### ABI and ABI Stability Within a Released ROS Distribution [1.vi]
+
+`rcl_logging_interface` will not break API nor ABI within a released ROS distribution, i.e. no major releases once the ROS distribution is released.
+
+## Change Control Process [2]
+
+`rcl_logging_interface` follows the recommended guidelines for ROS Core packages in the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#change-control-process).
+
+### Change Requests [2.i]
+
+All changes will occur through a pull request, check [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#change-control-process) for additional information.
+
+### Contributor Origin [2.ii]
+
+This package uses DCO as its confirmation of contributor origin policy. More information can be found in [CONTRIBUTING](../CONTRIBUTING.md)
+
+### Peer Review Policy [2.iii]
+
+Following the recommended guidelines in the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#change-control-process) all pull requests must have at least 1 peer review.
+
+### Continuous Integration [2.iv]
+
+All pull requests must pass CI on all [tier 1 platforms](https://www.ros.org/reps/rep-2000.html#support-tiers)
+
+Currently nightly results can be seen here:
+* [linux-aarch64_release](https://ci.ros2.org/view/nightly/job/nightly_linux-aarch64_release/lastBuild/testReport/rcl_logging_interface/)
+* [linux_release](https://ci.ros2.org/view/nightly/job/nightly_linux_release/lastBuild/testReport/rcl_logging_interface`/)
+* [mac_osx_release](https://ci.ros2.org/view/nightly/job/nightly_osx_release/lastBuild/testReport/rcl_logging_interface/)
+* [windows_release](https://ci.ros2.org/view/nightly/job/nightly_win_rel/lastBuild/testReport/rcl_logging_interface/)
+
+###  Documentation Policy [2.v]
+
+All pull requests must resolve related documentation changes before merging.
+
+## Documentation [3]
+
+### Feature Documentation [3.i]
+
+`rcl_logging_interface` does not have feature documentation.
+
+### Public API Documentation [3.ii]
+
+`rcl_logging_interface` does not have public API documentation.
+
+### License [3.iii]
+
+The license for `rcl_logging_interface` is Apache 2.0, and a summary is in each source file, the type is declared in the [`package.xml`](./package.xml) manifest file, and a full copy of the license is in the [`LICENSE`](../LICENSE) file.
+
+There is an automated test which runs a linter that ensures each file has a license statement. [Here](https://ci.ros2.org/view/nightly/job/nightly_linux_release/lastBuild/testReport/rcl_logging_interface/) can be found a list with the latest results of the various linters being run on the package.
+
+### Copyright Statements [3.iv]
+
+The copyright holders each provide a statement of copyright in each source code file in `rcl_logging_interface`.
+
+There is an automated test which runs a linter that ensures each file has at least one copyright statement. Latest linter result report can be seen [here](https://ci.ros2.org/view/nightly/job/nightly_linux_release/lastBuild/testReport/rcl_logging_interface/copyright/).
+
+## Testing [4]
+
+### Feature Testing [4.i]
+
+`rcl_logging_interface` does not include feature testing.
+
+### Public API Testing [4.ii]
+
+`rcl_logging_interface` does not include Public API testing.
+
+### Coverage [4.iii]
+
+`rcl_logging_interface` does not include tests, so coverage is not provided.
+
+### Performance [4.iv]
+
+`rcl_logging_interface` does not conduct performance tests.
+
+### Linters and Static Analysis [4.v]
+
+`rcl_logging_interface` uses and passes all the standard linters and static analysis tools for a C package as described in the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#linters-and-static-analysis). Passing implies there are no linter/static errors when testing against CI of supported platforms.
+
+Currently nightly results can be seen here:
+* [linux-aarch64_release](https://ci.ros2.org/view/nightly/job/nightly_linux-aarch64_release/lastBuild/testReport/rcl_logging_interface/)
+* [linux_release](https://ci.ros2.org/view/nightly/job/nightly_linux_release/lastBuild/testReport/rcl_logging_interface/)
+* [mac_osx_release](https://ci.ros2.org/view/nightly/job/nightly_osx_release/lastBuild/testReport/rcl_logging_interface/)
+* [windows_release](https://ci.ros2.org/view/nightly/job/nightly_win_rel/lastBuild/testReport/rcl_logging_interface/)
+
+## Dependencies [5]
+
+Below are evaluations of each of `rcl_logging_interface`'s run-time and build-time dependencies that have been determined to influence the quality.
+
+`rcl_logging_interface` depends on the ROS package `rcutils`.
+
+`rcutils` was declared to be Quality Level 4 [here](https://github.com/ros2/rcutils/blob/master/QUALITY_DECLARATION.md).
+
+### Optional Direct Runtime ROS Dependencies [5.ii]
+
+`rcl_logging_interface` has no optional Direct Runtime ROS dependencies that need to be considered for this declaration.
+
+### Direct Runtime non-ROS Dependency [5.iii]
+
+`rcl_logging_spdlog` has no Direct Runtime non-ROS dependencies that need to be considered for this declaration.
+
+## Platform Support [6]
+
+`rcl_logging_interface` supports all of the tier 1 platforms as described in [REP-2000](https://www.ros.org/reps/rep-2000.html#support-tiers), and tests each change against all of them.
+
+## Security [7]
+
+### Vulnerability Disclosure Policy [7.i]
+
+This package conforms to the Vulnerability Disclosure Policy in [REP-2006](https://www.ros.org/reps/rep-2006.html).
+
+# Current status Summary
+
+The chart below compares the requirements in the REP-2004 with the current state of the `rcl` package.
+
+|Number|  Requirement| Current state |
+|--|--|--|
+|1| **Version policy** |---|
+|1.i|Version Policy available | ✓ |
+|1.ii|Stable version | ☓ |
+|1.iii|Declared public API | ✓ |
+|1.iv|API stability policy | ✓ |
+|1.v|ABI stability policy | ✓ |
+|1.vi_|API/ABI stable within ros distribution | ✓ |
+|2| **Change control process** |---|
+|2.i| All changes occur on change request | ✓ |
+|2.ii| Contributor origin (DCO, CLA, etc) | ✓ |
+|2.iii| Peer review policy | ✓ |
+|2.iv| CI policy for change requests | ✓ |
+|2.v| Documentation policy for change requests | ✓ |
+|3| **Documentation** | --- |
+|3.i| Per feature documentation | ☓ |
+|3.ii| Per public API item documentation | ☓ |
+|3.iii| Declared License(s) | ✓ |
+|3.iv| Copyright in source files| ✓ |
+|3.v.a| Quality declaration linked to README | ✓ |
+|3.v.b| Centralized declaration available for peer review | ✓ |
+|4| Testing | --- |
+|4.i| Feature items tests | ☓ |
+|4.ii| Public API tests | ☓ |
+|4.iii.a| Using coverage | ☓ |
+|4.iii.a| Coverage policy | ☓ |
+|4.iv.a| Performance tests (if applicable) | ☓ |
+|4.iv.b| Performance tests policy| ✓ |
+|4.v.a| Code style enforcement (linters)| ✓ |
+|4.v.b| Use of static analysis tools | ✓ |
+|5| Dependencies | --- |
+|5.i| Must not have ROS lower level dependencies | ✓ |
+|5.ii| Optional ROS lower level dependencies | ✓ |
+|5.iii| Justifies quality use of non-ROS dependencies | ✓ |
+|6| Platform support | --- |
+|6.i| Support targets Tier1 ROS platforms | ✓ |
+|7| Security | --- |
+|7.i| Vulnerability Disclosure Policy | ✓ |

rcl_logging_interface/include/rcl_logging_interface/rcl_logging_interface.h

@@ -0,0 +1,123 @@
+// Copyright 2020 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_INTERFACE__RCL_LOGGING_INTERFACE_H_
+#define RCL_LOGGING_INTERFACE__RCL_LOGGING_INTERFACE_H_
+
+#include "rcl_logging_interface/visibility_control.h"
+#include "rcutils/allocator.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum
+{
+  RCL_LOGGING_RET_OK = 0,
+  RCL_LOGGING_RET_ERROR = 2,
+  RCL_LOGGING_RET_INVALID_ARGUMENT = 11,
+  RCL_LOGGING_RET_CONFIG_FILE_DOESNT_EXIST = 21,
+  RCL_LOGGING_RET_CONFIG_FILE_INVALID = 22,
+} rcl_logging_ret_t;
+
+/// 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 provided, it must be a null terminated C string.
+ *   If set to NULL or the empty string, the logging library will use defaults.
+ * \param[in] allocator The allocator to use for memory allocation.  This is
+ *   an rcutils_allocator_t rather than an rcl_allocator_t to ensure that the
+ *   rcl_logging_* packages don't have a circular dependency back to rcl.
+ * \return RCL_LOGGING_RET_OK if initialized successfully.
+ * \return RCL_LOGGING_RET_ERROR if an unspecified error occurs.
+ * \return RCL_LOGGING_RET_CONFIG_FILE_DOESNT_EXIST if a config_file is provided
+ *   but the file doesn't exist.
+ * \return RCL_LOGGING_RET_CONFIG_FILE_INVALID if a config_file is provided but
+ *   the logging backend doesn't understand it.
+ */
+RCL_LOGGING_INTERFACE_PUBLIC
+RCUTILS_WARN_UNUSED
+rcl_logging_ret_t
+rcl_logging_external_initialize(const char * config_file, rcutils_allocator_t allocator);
+
+/// Free the resources allocated for the external logging system.
+/**
+ * This puts the system into a state equivalent to being uninitialized.
+ *
+ * \return RCL_LOGGING_RET_OK if successfully shutdown, or
+ * \return RCL_LOGGING_RET_ERROR if an unspecified error occurs.
+ */
+RCL_LOGGING_INTERFACE_PUBLIC
+RCUTILS_WARN_UNUSED
+rcl_logging_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_LOGGING_INTERFACE_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_LOGGING_RET_OK if set successfully, or
+ * \return RCL_LOGGING_RET_ERROR if an unspecified error occurs.
+ */
+RCL_LOGGING_INTERFACE_PUBLIC
+RCUTILS_WARN_UNUSED
+rcl_logging_ret_t rcl_logging_external_set_logger_level(const char * name, int level);
+
+/// Get the logging directory.
+/**
+ * Uses various environment variables to construct a logging directory path.
+ *
+ * Use $ROS_LOG_DIR if ROS_LOG_DIR is set and not empty.
+ * Otherwise, use $ROS_HOME/log, using ~/.ros for ROS_HOME if not set or if empty.
+ *
+ * It also expands an initial '~' to the current user's home directory,
+ * and converts the path separator if necessary.
+ *
+ * If successful, the directory C string should be deallocated using the given allocator when it is
+ * no longer needed.
+ *
+ * \param[in] allocator The allocator to use for memory allocation.
+ * \param[out] directory The C string pointer at which to write the directory path.
+ *   Only meaningful if the call is successful. Must not be nullptr and must point to nullptr.
+ * \return RCL_LOGGING_RET_OK if successful, or
+ * \return RCL_LOGGING_RET_INVALID_ARGUMENT if any arguments are invalid, or
+ * \return RCL_LOGGING_RET_ERROR if an unspecified error occurs.
+ */
+RCL_LOGGING_INTERFACE_PUBLIC
+rcl_logging_ret_t
+rcl_logging_get_logging_directory(rcutils_allocator_t allocator, char ** directory);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  // RCL_LOGGING_INTERFACE__RCL_LOGGING_INTERFACE_H_