Skip to content

Commit

Permalink
Logging interface (#41)
Browse files Browse the repository at this point in the history 
* Add in a new rcl_logging_interface package.

This has just the header files that the implementations need
to provide, and that the callers can call.  Also port log4cxx,
noop, and spdlog backends to use this new interface.

Signed-off-by: Chris Lalancette <[email protected]>
  • Loading branch information
@clalancette
clalancette authored Jun 9, 2020
1 parent c1bfac6 commit 662fbc7
Show file tree
Hide file tree
Showing 18 changed files with 382 additions and 311 deletions.
38 changes: 38 additions & 0 deletions rcl_logging_interface/CMakeLists.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
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)

add_library(${PROJECT_NAME} INTERFACE)
target_include_directories(${PROJECT_NAME} INTERFACE
"$<INSTALL_INTERFACE:include>")
ament_target_dependencies(${PROJECT_NAME} INTERFACE rcutils)

install(TARGETS ${PROJECT_NAME} EXPORT ${PROJECT_NAME}
ARCHIVE DESTINATION lib
LIBRARY DESTINATION lib
RUNTIME DESTINATION bin)

install(DIRECTORY include/${PROJECT_NAME}/
DESTINATION include/${PROJECT_NAME}
)

ament_export_include_directories(include)
ament_export_targets(${PROJECT_NAME})
ament_export_dependencies(rcutils)
ament_package()
185 changes: 185 additions & 0 deletions rcl_logging_interface/QUALITY_DECLARATION.md
View file
Original file line number Diff line number Diff line change
@@ -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 | ✓ |
80 changes: 46 additions & 34 deletions ...e/rcl_logging_log4cxx/logging_interface.h → ...logging_interface/rcl_logging_interface.h
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// Copyright 2018 Open Source Robotics Foundation, Inc.
// 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.
Expand All @@ -12,53 +12,68 @@
// See the License for the specific language governing permissions and
// limitations under the License.

#ifndef RCL_LOGGING_LOG4CXX__LOGGING_INTERFACE_H_
#define RCL_LOGGING_LOG4CXX__LOGGING_INTERFACE_H_
#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

#include "rcl_logging_log4cxx/visibility_control.h"

typedef int rcl_logging_ret_t;
typedef enum
{
RCL_LOGGING_RET_OK = 0,
RCL_LOGGING_RET_ERROR = 2,
RCL_LOGGING_RET_CONFIG_FILE_DOESNT_EXIST = 21,
RCL_LOGGING_RET_CONFIG_FILE_INVALID = 22,
} rcl_logging_ret_t;

/// Initialize log4cxx logging library.
/*
/// 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.
* \param[in] allocator The allocator to use for memory allocation. This is
* 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, or
* \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_PUBLIC
rcl_logging_ret_t rcl_logging_external_initialize(
const char * config_file,
rcutils_allocator_t allocator);
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 log4cxx external logging system.
/// Free the resources allocated for the external logging system.
/**
* This puts the system into a state equivalent to being uninitialized.
*
* \return always RCL_LOGGING_RET_OK.
* \return RCL_LOGGING_RET_OK if successfully shutdown, or
* \return RCL_LOGGING_RET_ERROR if an unspecified error occurs.
*/
RCL_LOGGING_PUBLIC
rcl_logging_ret_t rcl_logging_external_shutdown();
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.
* 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.
* \param[in] msg The message to be logged. Must be a null terminated C string.
*/
RCL_LOGGING_PUBLIC
void rcl_logging_external_log(int severity, const char * name, const char * msg);
RCL_LOGGING_INTERFACE_PUBLIC
void
rcl_logging_external_log(int severity, const char * name, const char * msg);

/// Set the severity level for a logger.
/**
Expand All @@ -67,20 +82,17 @@ void rcl_logging_external_log(int severity, const char * name, const char * msg)
* 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. Values:
* RCUTILS_LOG_SEVERITY_DEBUG, RCUTILS_LOG_SEVERITY_UNSET, RCUTILS_LOG_SEVERITY_DEBUG,
* RCUTILS_LOG_SEVERITY_INFO, RCUTILS_LOG_SEVERITY_WARN, RCUTILS_LOG_SEVERITY_ERROR,
* RCUTILS_LOG_SEVERITY_FATAL
* \return always RCL_LOGGING_RET_OK.
* 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_PUBLIC
RCL_LOGGING_INTERFACE_PUBLIC
RCUTILS_WARN_UNUSED
rcl_logging_ret_t rcl_logging_external_set_logger_level(const char * name, int level);


#ifdef __cplusplus
} /* extern "C" */
}
#endif

#endif // RCL_LOGGING_LOG4CXX__LOGGING_INTERFACE_H_
#endif // RCL_LOGGING_INTERFACE__RCL_LOGGING_INTERFACE_H_
Loading

0 comments on commit 662fbc7

Please sign in to comment.