Add configuration code that can be reused by components consuming Journal

Journal/JournalConfig.inc.cc

+// Copyright 2020 Autodesk, Inc. All rights reserved.
+//
+// This computer source code and related instructions and comments are the
+// unpublished confidential and proprietary information of Autodesk, Inc.
+// and are protected under applicable copyright and trade secret law. They
+// may not be disclosed to, copied or used by any third party without the
+// prior written consent of Autodesk, Inc.
+
+/*!
+This source file provides the implementation of common configuration options for 
+the journal system  that can be exposed by the component providing journals. The
+component should include this within a namespace, e.g.:
+
+namespace COMPONENT
+{
+namespace Journal
+{
+
+// Also define this as the component name
+#define COMPONENT_NAME_STRING
+
+// Also define this as the component name in UPPER case
+#define COMPONENT_NAME_STRING_UPPER
+
+#include <Base/Journal/JournalConfig.inc.cc>
+
+} // namespace Journal
+} // namespace COMPONENT
+
+*/
+
+#ifndef BASE_JOURNAL_CONFIG_INC_HH_INCLUDED
+#error Please #include the component journal config file
+#endif//BASE_JOURNAL_CONFIG_INC_HH_INCLUDED
+
+#ifndef BASE_JOURNAL_STREAM_HH_INCLUDED
+#error Please #include <Base/Journal/JournalStream.hh>
+#endif//BASE_JOURNAL_STREAM_HH_INCLUDED
+
+#ifndef BASE_ENVIRONMENT_HH_INCLUDED
+#error Please #include <Base/Utils/Environment.hh>
+#endif//BASE_ENVIRONMENT_HH_INCLUDED
+
+#ifndef COMPONENT_NAME_STRING
+#error Please define the component name string when including this
+#endif//COMPONENT_NAME_STRING
+
+#ifndef COMPONENT_NAME_STRING_UPPER
+#error Please define the component name string in upper case when including this
+#endif//COMPONENT_NAME_STRING_UPPER
+
+std::string& base_path_string()
+{// make sure this constructor is called when the base_path_str is accessed
+  static std::string base_path_str = ".";
+  return base_path_str;
+}
+
+void set_base_path(const char* const _base_path) 
+{
+  base_path_string() = _base_path == nullptr ? "." : _base_path;
+}
+
+const char* base_path()
+{
+  return base_path_string().c_str();
+}
+
+#ifdef JOURNAL_ON
+
+struct Setup
+{
+  Setup()
+  {
+    const char* const vrbl_name = COMPONENT_NAME_STRING_UPPER"_JOURNAL_BASE";
+    if (System::Environment::variable(vrbl_name, base_path_string()))
+    {
+      set_on(true); // ... turn on Journal by default
+    }
+  }
+};
+
+static Setup setup__;
+
+void set_on(const bool _on)
+{
+  if (on() == _on)
+    return;
+
+  ::Journal::set_on(_on, "ReForm", base_path());
+
+  if (!on())
+    return;
+
+  output_journal_header(); // define this function to output a journal header
+}
+
+bool on() { return ::Journal::on(); }
+
+const char* output_path() 
+{ 
+  static ::Journal::String otpt_path;
+  otpt_path = ::Journal::output_path();
+  return otpt_path.empty() ? nullptr : otpt_path.c_str(); 
+}
+
+#else
+
+void set_on(const bool) {}
+bool on() { return false; }
+const char* output_path() { return nullptr; }
+
+#endif//JOURNAL_ON

Journal/JournalConfig.inc.hh

+// Copyright 2020 Autodesk, Inc. All rights reserved.
+//
+// This computer source code and related instructions and comments are the
+// unpublished confidential and proprietary information of Autodesk, Inc.
+// and are protected under applicable copyright and trade secret law. They
+// may not be disclosed to, copied or used by any third party without the
+// prior written consent of Autodesk, Inc.
+
+/*!
+This header provides common configuration options for the journal system that
+can be exposed by the component providing journals.The component should
+include this within a namespace, e.g.:
+
+namespace COMPONENT
+{
+namespace Journal
+{
+
+// Also define this either as an empty macro (if the component is a static lib
+// or as an alias to the default export declaration macro.
+#define DECL_JOURNAL_ALIAS DECL_COMPONENT
+
+#include <Base/Journal/JournalConfig.inc.hh>
+
+} // namespace Journal
+} // namespace COMPONENT
+
+The same approach should be used for the corresponding unit file implementing
+the configuration options, see documentation in JournalConfig.inc.cc.
+*/
+
+#ifndef DECL_JOURNAL_ALIAS
+#error Please define the declaration alias for the component, even if left empty
+#endif//DECL_MODULE_CONFIG
+
+#ifndef BASE_JOURNAL_CONFIG_INC_HH_INCLUDED
+#define BASE_JOURNAL_CONFIG_INC_HH_INCLUDED
+
+/*!
+Journal is a system for logging the calls into the SDK, so that the
+operations can be replayed by a component independently of the client
+application that consumes it. It is very useful for reporting bugs.
+
+Journal can be turned on by calling set_on(true), or by defining a path with an
+environment variable [COMPONENT]_JOURNAl_BASE.
+*/
+
+/*!
+Set the base path to use in future journals.
+Pass nullptr (or ".") to use the current app execution folder as base. 
+The current app execution folder (".") is the default base path. 
+
+\note This will not affect any currently running journal. 
+*/
+DECL_JOURNAL_ALIAS void set_base_path(const char* const _base_path = nullptr);
+
+/*!
+Get the base path of any future journal.
+
+\note This is *not* the path of any currently running journal, see \ref
+output_path() to retrive the current journal path.
+*/
+DECL_JOURNAL_ALIAS const char* base_path();
+
+/*!
+Turn on/off the journal: this does nothing if the journal is already in the 
+desired state.
+*/
+DECL_JOURNAL_ALIAS void set_on(const bool _on);
+
+/*!
+Get if the journal is turned on/off.
+*/
+DECL_JOURNAL_ALIAS bool on();
+
+/*!
+Get the journal output path, or a nullptr if the journal is off.
+*/
+DECL_JOURNAL_ALIAS const char* output_path();
+
+#undef DECL_JOURNAL_ALIAS // end of scope for this macro
+
+#endif//BASE_JOURNAL_CONFIG_INC_HH_INCLUDED