add ebuild support (goatshriek#355)

Adds an ebuild template that is generated at configuration time and can be used to install the library on Gentoo systems. New build targets and configuration options are also included in this change to improve installation support, not just for Gentoo but in general. These include options to install manpages and examples and a build-test target to compile functionality tests without running them.
AryasCodeTreks · Aug 9, 2023 · 111796d · 111796d
1 parent 86c9296
commit 111796d
Show file tree

Hide file tree

Showing 20 changed files with 952 additions and 508 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
diff --git a/COPYING b/COPYING
@@ -1,3 +1,4 @@
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -198,4 +199,4 @@
    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.
+   limitations under the License.
diff --git a/ChangeLog.md b/ChangeLog.md
@@ -10,7 +10,7 @@ fixes, check out the
 [roadmap](https://github.com/goatshriek/stumpless/blob/master/docs/roadmap.md).
 
 
-## [2.2.0] - 2023-01-16
+## [2.2.0] - 2023-08-08
 ### Fixed
  - Deadlock potential in `stumpless_set_entry_hostname` and
    `stumpless_set_entry_procid` when validation fails.

diff --git a/INSTALL.md b/INSTALL.md
@@ -31,6 +31,30 @@ rpm -i stumpless-2.2.0-x86_64.rpm
 ```
 
 
+## Gentoo ebuild
+A `.ebuild` package is provided with each release version of the library, and
+is also generated during the configuration stage of the build by cmake. The
+generated ebuild is in the `tools/portage` folder of the build directory.
+
+The generated ebuild will be named after the version of stumpless you have.
+If you want the latest commit instead of a release, you'll need to rename this
+to version `stumpless-9999.ebuild` to perform what Gentoo refers to as a
+[live ebuild](https://wiki.gentoo.org/wiki/Ebuild#Live_ebuilds). If you have a
+commit in a release that hasn't been published yet and do not rename the ebuild,
+then the download of the source will fail.
+
+In either case, you could install the ebuild by putting it into a repository and
+running ebuild ultimately as something like:
+
+```sh
+ebuild stumpless-2.2.0.ebuild clean install merge
+```
+
+USE flags and other customizations can be done here as well. Gentoo installs are
+more nuanced than can be discussed here; start with the relevant
+[handbook page](https://wiki.gentoo.org/wiki/Ebuild) if you want to learn more.
+
+
 ## Generic Shell Installer
 CMake generates a shell script that can be used to install the library on
 systems lacking a more traditional package manager, for example Cygwin. Simply

diff --git a/docs/examples/cpp/README.md b/docs/examples/cpp/README.md
@@ -1,8 +1,7 @@
 # C++ Bindings
-
 While stumpless is written in C to keep it as lightweight and simple as
 possible, it has been extended to C++ so that it can be used from the higher
-level language with the same performance benefits.
+level language with nearly the same performance benefits.
 
 These bindings go beyond simply calling C code from C++, however; the entire
 library is exposed via an object-oriented API documented in full
@@ -13,8 +12,8 @@ some useful advantages over the simple functional capabilities of C.
 The C++ bindings are created using
 [Wrapture](https://goatshriek.github.io/wrapture/).
 
-## Stumpless Classes
 
+## Stumpless Classes
 Targets can be created and logged to using the various target classes that match
 target types from the C library. The constructors take the same parameters as
 the matching open target function in the C library. This example shows how to
@@ -33,25 +32,25 @@ depending on how much information you provide:
 
 ```cpp
 // logs the given message to the file
-file_logger.Log( "she just drank ANOTHER bloody mary" );
+file_logger.Log( "she just made ANOTHER u-turn" );
 // the entry will look like this:
-// <14>1 2020-05-15T16:28:56.266031Z Angus - 4484 - - she just drank ANOTHER bloody mary
+// <14>1 2020-05-15T16:28:56.266031Z Angus - 4484 - - she just made ANOTHER u-turn
 // 'Angus' is the name of the system this was logged on
-// the three '-' are the app name, the message id, and the structured data,
+// the three '-' characters are the app name, the message id, and the structured data,
 // which were all empty here
 // '4484' is PID of the process that logged this message
 
 // logs the given message to the file at the given priority
 file_logger.Log( Facility::NEWS, Severity::EMERGENCY,
-                 "Helen's drrunnk agaaaiiiin!!!" );
+                 "Helen's lost again!!!" );
 // the entry will look like this:
-// <56>1 2020-05-15T16:28:56.267113Z Angus - 4484 - - Helen's drrunnk agaaaiiiin!!!
+// <56>1 2020-05-15T16:28:56.267113Z Angus - 4484 - - Helen's lost again!!!
 
 // logs the given message and format strings to the file
 // you can use format strings with the previous forms as well if you want to
-file_logger.Log( "she has had %d drinks in the last %d days", 25, 3 );
+file_logger.Log( "she has gotten lost %d times in the last %d days", 25, 3 );
 // the entry will look like this:
-// <14>1 2020-05-15T16:28:56.267128Z Angus - 4484 - - she has had 25 drinks in the last 3 days
+// <14>1 2020-05-15T16:28:56.267128Z Angus - 4484 - - she has gotten lost 25 times in the last 3 days
 ```
 
 Entries, elements, and parameters are still created much the same way, again
@@ -92,8 +91,8 @@ struct stumpless_target *underlying = file_logger.equivalent;
 std::cout << "using target: " << underlying->name << std::endl;
 ```
 
-## Error Checking
 
+## Error Checking
 Error checking is not as cumbersome as in the C library; an exception is thrown
 whenever an error is detected in the underlying function. This allows code to
 use try/catch blocks rather than check each return value. You can also check the
@@ -110,8 +109,8 @@ try {
 }
 ```
 
-## Constants and Configuration
 
+## Constants and Configuration
 If you need to check information about the configuration of your build of the
 library, you can check the same constants as before for them, though you will
 need to include the C header to do so.
@@ -133,8 +132,8 @@ these constants into a namespace:
 #endif
 ```
 
-## Running this Example
 
+## Running this Example
 If you want to compile and run the example code here, then you'll need to
 compile it with the correct include paths and library load paths. Or you can
 simply compile it with the library specified if the C++ library has already

diff --git a/docs/examples/cpp/cpp_example.cpp b/docs/examples/cpp/cpp_example.cpp
@@ -14,25 +14,25 @@ main( int argc, char **argv ) {
   FileTarget file_logger( "cpp_example.log" );
 
   // logs the given message to the file
-  file_logger.Log( "she just drank ANOTHER bloody mary" );
+  file_logger.Log( "she just made ANOTHER u-turn" );
   // the entry will look like this:
-  // <14>1 2020-05-15T16:28:56.266031Z Angus - 4484 - - she just drank ANOTHER bloody mary
+  // <14>1 2020-05-15T16:28:56.266031Z Angus - 4484 - - she just made ANOTHER u-turn
   // 'Angus' is the name of the system this was logged on
-  // the three '-' are the app name, the message id, and the structured data,
+  // the three '-' characters are the app name, the message id, and the structured data,
   // which were all empty here
   // '4484' is PID of the process that logged this message
 
   // logs the given message to the file at the given priority
   file_logger.Log( Facility::NEWS, Severity::EMERGENCY,
-                   "Helen's drrunnk agaaaiiiin!!!" );
+                   "Helen's lost again!!!" );
   // the entry will look like this:
-  // <56>1 2020-05-15T16:28:56.267113Z Angus - 4484 - - Helen's drrunnk agaaaiiiin!!!
+  // <56>1 2020-05-15T16:28:56.267113Z Angus - 4484 - - Helen's lost again!!!
 
   // logs the given message and format strings to the file
   // you can use format strings with the previous forms as well if you want to
-  file_logger.Log( "she has had %d drinks in the last %d days", 25, 3 );
+  file_logger.Log( "she's gotten lost %d times in the last %d days", 25, 3 );
   // the entry will look like this:
-  // <14>1 2020-05-15T16:28:56.267128Z Angus - 4484 - - she has had 25 drinks in the last 3 days
+  // <14>1 2020-05-15T16:28:56.267128Z Angus - 4484 - - she's gotten lost 25 times in the last 3 days
 
   // creates an Entry for a common event
   Entry up_to_code( Facility::USER,

diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -43,6 +43,9 @@ or want to make a suggestion, please submit an issue on the project's
    pass along a more meaningful return value.
  * [CHANGE] **Entry app name and msgid no longer NULL-terminated.**
    Improve efficiency and memory safety by only using these as byte buffers.
+ * [CHANGE] **Rename `STUMPLESS_DEFAULT_TRANSPORT_PORT`**
+   This symbol will be renamed so that it is clear that it refers to a string
+   literal, likely by adding a `_STR` suffix.
 
 
 ## Unallocated to a release

diff --git a/include/stumpless.h b/include/stumpless.h
@@ -1,7 +1,7 @@
 /* SPDX-License-Identifier: Apache-2.0 */
 
 /*
- * Copyright 2018-2021 Joel E. Anderson
+ * Copyright 2018-2023 Joel E. Anderson
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,67 +16,127 @@
  * limitations under the License.
  */
 
+/** @mainpage Stumpless
+ *
+ * Stumpless is a logging library built for high performance and a rich feature
+ * set.
+ */
+
+/** @example basic_example.c
+ * Demonstrates usage of the basic logging calls (stump(), stump_str(),
+ * stumpless_add_message(), stumplog()).
+ */
+
+/** @example cpp_example.cpp
+ * Demonstrates usage of Stumpless through the C++ bindings.
+ */
+
+/** @example entry_example.c
+ * Demonstrates different ways to work with stumpless_entry and related
+ * structures.
+ */
+
+/** @example file_example.c
+ * Demonstrates how to work with a file target.
+ */
+
+/** @example filter_example.c
+ * Demonstrates how to work with runtime filters on logging targets.
+ */
+
+/** @example function_example.c
+ * Demonstrates how to work with a function target.
+ */
+
+/** @example severity_level_example.c
+ * Demonstrates how to work with the severity levels of logged events.
+ */
+
+/** @example stream_example.c
+ * Demonstrates how to work with a stream target.
+ */
+
 /** @file
- * The main header file for the library. Unless you are specifically trying to
- * reduce your compilation times by including ONLY the necessary headers, it is
- * best to only include this header. It will ensure that all available features
- * are declared, as well as take care of any ordering or conditional includes
- * that may be necessary on the target platform.
+ * The main header file for the stumpless logging library. Unless you are
+ * specifically trying to include ONLY required headers, it is best to simply
+ * include this header to use stumpless. It will ensure that all available
+ * features are declared, as well as take care of any ordering or conditional
+ * includes that may be necessary on the target platform.
  *
- * If you do want to only include specific header files for some reason, you
- * can use this file as a template for doing so. Note that all headers are
- * under a stumpless directory, which should be included in the path.
+ * If you do want to only include specific header files, you can use this file
+ * as a template. Note that all headers are under the stumpless directory,
+ * which must be in the include path.
  */
 
 #ifndef __STUMPLESS_H
-#  define __STUMPLESS_H
-
-#  include <stumpless/config.h>
-#  include <stumpless/element.h>
-#  include <stumpless/entry.h>
-#  include <stumpless/error.h>
-#  include <stumpless/facility.h>
-#  include <stumpless/filter.h>
-#  include <stumpless/generator.h>
-#  include <stumpless/id.h>
-#  include <stumpless/level/alert.h>
-#  include <stumpless/level/crit.h>
-#  include <stumpless/level/debug.h>
-#  include <stumpless/level/emerg.h>
-#  include <stumpless/level/err.h>
-#  include <stumpless/level/info.h>
-#  include <stumpless/level/notice.h>
-#  include <stumpless/level/trace.h>
-#  include <stumpless/level/warning.h>
-#  include <stumpless/log.h>
-#  include <stumpless/memory.h>
-#  include <stumpless/option.h>
-#  include <stumpless/param.h>
-#  include <stumpless/severity.h>
-#  include <stumpless/target.h>
-#  include <stumpless/target/buffer.h>
-#  include <stumpless/target/file.h>
-#  include <stumpless/target/function.h>
-#  include <stumpless/target/stream.h>
-#  include <stumpless/version.h>
-
-#  ifdef STUMPLESS_JOURNALD_TARGETS_SUPPORTED
-#    include <stumpless/config/journald_supported.h>
-#    include <stumpless/target/journald.h>
-#  endif
-
-#  ifdef STUMPLESS_NETWORK_TARGETS_SUPPORTED
-#    include <stumpless/target/network.h>
-#  endif
-
-#  ifdef STUMPLESS_SOCKET_TARGETS_SUPPORTED
-#    include <stumpless/target/socket.h>
-#  endif
-
-#  ifdef STUMPLESS_WINDOWS_EVENT_LOG_TARGETS_SUPPORTED
-#    include <stumpless/config/wel_supported.h>
-#    include <stumpless/target/wel.h>
-#    include <stumpless/windows/default_events.h>
-#  endif
+#define __STUMPLESS_H
+
+#include <stumpless/config.h>
+#include <stumpless/element.h>
+#include <stumpless/entry.h>
+#include <stumpless/error.h>
+#include <stumpless/facility.h>
+#include <stumpless/filter.h>
+#include <stumpless/generator.h>
+#include <stumpless/id.h>
+#include <stumpless/level/alert.h>
+#include <stumpless/level/crit.h>
+#include <stumpless/level/debug.h>
+#include <stumpless/level/emerg.h>
+#include <stumpless/level/err.h>
+#include <stumpless/level/info.h>
+#include <stumpless/level/notice.h>
+#include <stumpless/level/trace.h>
+#include <stumpless/level/warning.h>
+#include <stumpless/log.h>
+#include <stumpless/memory.h>
+#include <stumpless/option.h>
+#include <stumpless/param.h>
+#include <stumpless/severity.h>
+#include <stumpless/target.h>
+#include <stumpless/target/buffer.h>
+#include <stumpless/target/file.h>
+#include <stumpless/target/function.h>
+#include <stumpless/target/stream.h>
+#include <stumpless/version.h>
+
+#ifdef STUMPLESS_JOURNALD_TARGETS_SUPPORTED
+/** @example journald_example.c
+ * Demonstrates how to work with a journald target.
+ */
+
+#  include <stumpless/config/journald_supported.h>
+#  include <stumpless/target/journald.h>
+#endif
+
+#ifdef STUMPLESS_NETWORK_TARGETS_SUPPORTED
+/** @example tcp_example.c
+ * Demonstrates how to work with a network target with a TCP network endpoint.
+ */
+
+/** @example udp_example.c
+ * Demonstrates how to work with a network target with a UDP network endpoint.
+ */
+
+#  include <stumpless/target/network.h>
+#endif
+
+#ifdef STUMPLESS_SOCKET_TARGETS_SUPPORTED
+/** @example socket_example.c
+ * Demonstrates how to work with a socket target.
+ */
+
+#  include <stumpless/target/socket.h>
+#endif
+
+#ifdef STUMPLESS_WINDOWS_EVENT_LOG_TARGETS_SUPPORTED
+/** @example wel_example.c
+ * Demonstrates how to work with a Windows Event Log target.
+ */
+
+#  include <stumpless/config/wel_supported.h>
+#  include <stumpless/target/wel.h>
+#  include <stumpless/windows/default_events.h>
+#endif
 
 #endif /* __STUMPLESS_H */