modified Ome logging code and documentation per PR reviews.

* applied LLVM-coding style
* removed of accepting OMEGA_LOG_FILEPATH user macro
* revised ctest for logging to capture PASS/FAIL properly
* updated userGuide and devGuide

components/omega/OmegaBuild.cmake

@@ -26,9 +26,7 @@ macro(setup_common_variables)
     set(OMEGA_CXX_FLAGS "")
   endif()
 
-  if(NOT DEFINED OMEGA_LOG_FILEPATH)
-    set(OMEGA_LOG_FILEPATH "${PROJECT_BINARY_DIR}/omega.log")
-  endif()
+  set(OMEGA_LOG_DEFAULTPATH "${PROJECT_BINARY_DIR}/omega.log")
 
 endmacro()
 
@@ -98,10 +96,12 @@ endmacro()
 ################################
 macro(update_variables)
 
-  add_compile_definitions(OMEGA_LOG_FILEPATH="${OMEGA_LOG_FILEPATH}")
+  add_compile_definitions(OMEGA_LOG_DEFAULTPATH="${OMEGA_LOG_DEFAULTPATH}")
+
 
   if(OMEGA_DEBUG)
     add_compile_definitions(OMEGA_DEBUG)
+    add_compile_definitions(LOG_UNBUFFERED_LOGGING="1")
   endif()
 
   # Set the build type

components/omega/doc/devGuide/Logging.md

@@ -6,19 +6,19 @@ Omega's logging system is built upon the
 [spdlog](https://github.com/gabime/spdlog) logging tool.
 
 Logging macros and custom formatters for YAKL data types have been
-integrated into the Omega logging system via the logging.h header file
+integrated into the Omega logging system via the Logging.h header file
 located in the src/infra directory. Users who wish to utilize Omega's
 logging capabilities must include this header file in their code.
 
-The `src/infra/logging.cpp` file encompasses various functions related
+The `src/infra/Logging.cpp` file encompasses various functions related
 to logging. As of the current version, this file contains the
-`omega_log_init` function, which initialize the logging process.
-It is recommended to invoke the `omega_log_init` function at the beginning
+`OMEGA::initLogging` function, which initialize the logging process.
+It is recommended to invoke the `OMEGA::initLogging` function at the beginning
 of an Omega application to properly initialize the logging system.
 
 ## Initializing Omega Logger
 
-The `omega_log_init` function, located within the `src/infra/logging.cpp`
+The `OMEGA::initLogging` function, located within the `src/infra/Logging.cpp`
 file, serves as a pivotal component for initializing the Omega logging system.
 
 The function establishes the default logger configuration, ensuring that
@@ -29,7 +29,7 @@ allows users to specify the desired file location for logging purposes.
 ## Creating Logging Macros
 
 The Omega logging macros, denoted by the prefix `LOG_`, are defined within
-the `src/infra/logging.h` file. These macros constitute a main part of
+the `src/infra/Logging.h` file. These macros constitute a main part of
 the logging infrastructure, enabling users to seamlessly incorporate
 logging functionality into their Omega applications.
 

components/omega/doc/index.md

@@ -23,6 +23,7 @@ Development is taking place at https://github.com/E3SM-Project/Omega.
 userGuide/QuickStart
 userGuide/OmegaBuild
 userGuide/DataTypes
+userGuide/Logging
 ```
 
 ```{toctree}
@@ -35,6 +36,7 @@ devGuide/CondaEnv
 devGuide/Docs
 devGuide/BuildDocs
 devGuide/CMakeBuild
+devGuide/Logging
 ```
 
 ```{toctree}

components/omega/doc/userGuide/Logging.md

@@ -8,10 +8,10 @@ logging tool. As of this version, It only supports Standalone build mode.
 ## Logging in Standalone Build mode
 
 To use Omega's logging system in Standalone build mode, you need to include
-the logging.h header file in your code.
+the Logging.h header file in your code.
 
 ```c
-#include "logging.h"
+#include "Logging.h"
 ```
 
 You can then use the following macros to write logs of different severity
@@ -56,23 +56,14 @@ Here is a table that summarizes the different log severities and their meanings:
 You can replace the string "World" with any variable whose type is
 a C++ basic data type, such as an int, a float, or a string. You can
 also use a limited set of YAKL variables. For example, the following code
-writes the value of the variable `my_int` as a TRACE level log:
+writes the value of the variable `MyInt` as a TRACE level log:
 
 ```c
-int my_int = 10;
-LOG_TRACE("The value of my_int is: {}", my_int);
+int MyInt = 10;
+LOG_TRACE("The value of MyInt is: {}", MyInt);
 ```
 
-By default, the logfile will be created in the build directory. You can specify
-the log file path using the `OMEGA_LOG_FILEPATH` cmake variable, as follows:
-
-```sh
-cmake \
-  ... \
-  -DOMEGA_LOG_FILEPATH="/path/to/log/file" \
-  ${E3SM_HOME}/components/omega
-  ...
-```
+By default, the logfile will be created in the build directory.
 
 ## E3SM Component Build
 

components/omega/src/CMakeLists.txt

@@ -7,13 +7,21 @@ list(JOIN OMEGA_CXX_FLAGS " " _CXX_FLAGS_EXPANDED)
 
 # Create the library target
 add_library(${OMEGA_LIB_NAME} ${_LIBSRC_FILES})
-set_target_properties(${OMEGA_LIB_NAME} PROPERTIES COMPILE_FLAGS "${_CXX_FLAGS_EXPANDED}")
+set_target_properties(
+		${OMEGA_LIB_NAME}
+		PROPERTIES COMPILE_FLAGS "${_CXX_FLAGS_EXPANDED}"
+)
 
 # add link directories
 target_link_libraries(${OMEGA_LIB_NAME} spdlog "${OMEGA_LDFLAGS}")
 
 # add include directories
-target_include_directories(${OMEGA_LIB_NAME} PRIVATE "${OMEGA_SOURCE_DIR}/src/infra")
+target_include_directories(
+		${OMEGA_LIB_NAME}
+		PRIVATE 
+		"${OMEGA_SOURCE_DIR}/src/base"
+		"${OMEGA_SOURCE_DIR}/src/infra"
+)
 
 # include yakl cmake utility
 include(${E3SM_EXTERNALS_ROOT}/YAKL/yakl_utils.cmake)
@@ -32,12 +40,20 @@ endif()
 # build Omega executable
 if(OMEGA_BUILD_EXECUTABLE)
   set(EXESRC_FILES
-    drivers/drvdummy.cpp
+    drivers/DrvDummy.cpp
   )
   # Create the executable target
   add_executable(${OMEGA_EXE_NAME} ${EXESRC_FILES})
-  set_target_properties(${OMEGA_EXE_NAME} PROPERTIES COMPILE_FLAGS "${_CXX_FLAGS_EXPANDED}")
-  target_include_directories(${OMEGA_EXE_NAME} PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/infra")
+  set_target_properties(
+		${OMEGA_EXE_NAME}
+		PROPERTIES COMPILE_FLAGS "${_CXX_FLAGS_EXPANDED}"
+  )
+  target_include_directories(
+		${OMEGA_EXE_NAME}
+		PRIVATE
+		"${OMEGA_SOURCE_DIR}/src/base"
+		"${CMAKE_CURRENT_SOURCE_DIR}/infra"
+  )
   target_link_libraries(${OMEGA_EXE_NAME} ${OMEGA_LIB_NAME})
 
   # help the executable target to be built with yakl

components/omega/src/drivers/drvdummy.cpp → components/omega/src/drivers/DrvDummy.cpp

@@ -1,19 +1,17 @@
 // OCN dummy driver
 
-#include "logging.h"
+#include "Logging.h"
 #include <iostream>
 
-using namespace std;
-
 void dummy(int argc, char **argv);
 
 int main(int argc, char **argv) {
 
-   cout << endl << "Starting driver..." << endl;
+   std::cout << std::endl << "Starting driver..." << std::endl;
 
    dummy(argc, argv);
 
-   cout << "Stopped driver." << endl;
+   std::cout << "Stopped driver." << std::endl;
 
    return 0;
 }

components/omega/src/infra/LogFormatters.h

@@ -0,0 +1,41 @@
+#ifndef OMEGA_LOG_FORMATTERS_H
+#define OMEGA_LOG_FORMATTERS_H
+//===-- infra/LogFormatters.h - Omega specific log formatters --*- C++ -*-===//
+//
+/// \file
+/// \brief Defines spdlog custom formatters
+///
+/// This header defines custom formatters for Omega logging.
+//
+//===----------------------------------------------------------------------===//
+
+#include "DataTypes.h"
+#include <spdlog/spdlog.h>
+
+template <>
+struct fmt::formatter<OMEGA::ArrayHost1DReal> : fmt::formatter<std::string> {
+   auto format(OMEGA::ArrayHost1DReal my, format_context &ctx)
+       -> decltype(ctx.out()) {
+#ifdef OMEGA_DEBUG
+      return fmt::format_to(
+          ctx.out(), "[data type of '{}' is ArrayHost1DReal.]", my.label());
+#else
+      return fmt::format_to(ctx.out(), "[data type of '' is ArrayHost2DReal.]");
+#endif
+   }
+};
+
+template <>
+struct fmt::formatter<OMEGA::ArrayHost2DReal> : fmt::formatter<std::string> {
+   auto format(OMEGA::ArrayHost2DReal my, format_context &ctx)
+       -> decltype(ctx.out()) {
+#ifdef OMEGA_DEBUG
+      return fmt::format_to(
+          ctx.out(), "[data type of '{}' is ArrayHost2DReal.]", my.label());
+#else
+      return fmt::format_to(ctx.out(), "[data type of '' is ArrayHost2DReal.]");
+#endif
+   }
+};
+
+#endif // OMEGA_LOG_FORMATTERS_H

components/omega/src/infra/Logging.cpp

@@ -0,0 +1,31 @@
+//===-- infra/Logging.cpp - Implements Omega Logging functions --*- C++ -*-===//
+//
+/// \file
+/// \brief implements Omega logging functions
+///
+/// This implements Omega logging initialization.
+//
+//===----------------------------------------------------------------------===//
+
+#include "Logging.h"
+#include <spdlog/sinks/basic_file_sink.h>
+
+namespace OMEGA {
+
+void initLogging(std::shared_ptr<spdlog::logger> Logger) {
+
+   try {
+      Logger->flush_on(spdlog::level::warn);
+      spdlog::set_default_logger(Logger);
+
+   } catch (spdlog::spdlog_ex const &Ex) {
+      std::cout << "Log init failed: " << Ex.what() << std::endl;
+   }
+}
+
+void initLogging(std::string const &LogFilePath) {
+   auto Logger = spdlog::basic_logger_mt("*", LogFilePath);
+   initLogging(Logger);
+}
+
+} // namespace OMEGA

components/omega/src/infra/Logging.h

@@ -0,0 +1,100 @@
+#ifndef OMEGA_LOG_H
+#define OMEGA_LOG_H
+//===-- infra/Logging.h - logging macros and custom formatters --*- C++ -*-===//
+//
+/// \file
+/// \brief Defines logging macros and spdlog custom formatters
+///
+/// This header defines macros for logging. In addition, it includes
+/// Omega-specific log formatters.
+//
+//===----------------------------------------------------------------------===//
+
+#include "LogFormatters.h"
+#include <spdlog/spdlog.h>
+
+namespace OMEGA {
+
+void initLogging(std::shared_ptr<spdlog::logger> Logger);
+void initLogging(std::string const &LogFilePath);
+} // namespace OMEGA
+
+#define LOG_LEVEL_TRACE    SPDLOG_LEVEL_TRACE
+#define LOG_LEVEL_DEBUG    SPDLOG_LEVEL_DEBUG
+#define LOG_LEVEL_INFO     SPDLOG_LEVEL_INFO
+#define LOG_LEVEL_WARN     SPDLOG_LEVEL_WARN
+#define LOG_LEVEL_ERROR    SPDLOG_LEVEL_ERROR
+#define LOG_LEVEL_CRITICAL SPDLOG_LEVEL_CRITICAL
+#define LOG_LEVEL_OFF      SPDLOG_LEVEL_OFF
+
+#if !defined(LOG_ACTIVE_LEVEL)
+#define LOG_ACTIVE_LEVEL LOG_LEVEL_INFO
+#endif
+
+#if defined(LOG_UNBUFFERED_LOGGING)
+#define _LOG_FLUSH(logger) logger->flush()
+#else
+#define _LOG_FLUSH(logger) (void)0
+#endif
+
+#if LOG_ACTIVE_LEVEL <= LOG_LEVEL_TRACE
+#define LOGGER_TRACE(logger, ...)            \
+   SPDLOG_LOGGER_TRACE(logger, __VA_ARGS__); \
+   _LOG_FLUSH(logger)
+#define LOG_TRACE(...) LOGGER_TRACE(spdlog::default_logger(), __VA_ARGS__)
+#else
+#define LOGGER_TRACE(logger, ...) (void)0
+#define LOG_TRACE(...)            (void)0
+#endif
+
+#if LOG_ACTIVE_LEVEL <= LOG_LEVEL_DEBUG
+#define LOGGER_DEBUG(logger, ...)            \
+   SPDLOG_LOGGER_DEBUG(logger, __VA_ARGS__); \
+   _LOG_FLUSH(logger)
+#define LOG_DEBUG(...) LOGGER_DEBUG(spdlog::default_logger(), __VA_ARGS__)
+#else
+#define LOGGER_DEBUG(logger, ...) (void)0
+#define LOG_DEBUG(...)            (void)0
+#endif
+
+#if LOG_ACTIVE_LEVEL <= LOG_LEVEL_INFO
+#define LOGGER_INFO(logger, ...)            \
+   SPDLOG_LOGGER_INFO(logger, __VA_ARGS__); \
+   _LOG_FLUSH(logger)
+#define LOG_INFO(...) LOGGER_INFO(spdlog::default_logger(), __VA_ARGS__)
+#else
+#define LOGGER_INFO(logger, ...) (void)0
+#define LOG_INFO(...)            (void)0
+#endif
+
+#if LOG_ACTIVE_LEVEL <= LOG_LEVEL_WARN
+#define LOGGER_WARN(logger, ...)            \
+   SPDLOG_LOGGER_WARN(logger, __VA_ARGS__); \
+   _LOG_FLUSH(logger)
+#define LOG_WARN(...) LOGGER_WARN(spdlog::default_logger(), __VA_ARGS__)
+#else
+#define LOGGER_WARN(logger, ...) (void)0
+#define LOG_WARN(...)            (void)0
+#endif
+
+#if LOG_ACTIVE_LEVEL <= LOG_LEVEL_ERROR
+#define LOGGER_ERROR(logger, ...)            \
+   SPDLOG_LOGGER_ERROR(logger, __VA_ARGS__); \
+   _LOG_FLUSH(logger)
+#define LOG_ERROR(...) LOGGER_ERROR(spdlog::default_logger(), __VA_ARGS__)
+#else
+#define LOGGER_ERROR(logger, ...) (void)0
+#define LOG_ERROR(...)            (void)0
+#endif
+
+#if LOG_ACTIVE_LEVEL <= LOG_LEVEL_CRITICAL
+#define LOGGER_CRITICAL(logger, ...)            \
+   SPDLOG_LOGGER_CRITICAL(logger, __VA_ARGS__); \
+   _LOG_FLUSH(logger)
+#define LOG_CRITICAL(...) LOGGER_CRITICAL(spdlog::default_logger(), __VA_ARGS__)
+#else
+#define LOGGER_CRITICAL(logger, ...) (void)0
+#define LOG_CRITICAL(...)            (void)0
+#endif
+
+#endif // OMEGA_LOG_H