Add define BOOST_PARSER_DISABLE_TRACE to disable trace mode at compile time.

The trace feature doubles the compile time, even if never used.
This patch introduces the preprocessor define BOOST_PARSER_DISABLE_TRACE
to deactivate this feature at compile time.

Author: Andreas Buhr

.github/workflows/ubuntu.yml

@@ -18,6 +18,13 @@ jobs:
         compiler_version: [g++-10, g++-11]
         cxx_std: [17, 20]
         os: [ubuntu-22.04]
+        disable_trace: [false]
+        include:
+          # Test with trace disabled
+          - compiler_version: g++-11
+            cxx_std: 20
+            os: ubuntu-22.04
+            disable_trace: true
 
     runs-on: ${{ matrix.os }}
 
@@ -30,7 +37,11 @@ jobs:
         run: |
           mkdir build
           cd build
-          cmake .. -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} -DCMAKE_CXX_COMPILER=${{ matrix.compiler_version }} -DCXX_STD=${{ matrix.cxx_std }}
+          if [ "${{ matrix.disable_trace }}" = "true" ]; then
+            cmake .. -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} -DCMAKE_CXX_COMPILER=${{ matrix.compiler_version }} -DCXX_STD=${{ matrix.cxx_std }} -DDISABLE_TRACE=true
+          else
+            cmake .. -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} -DCMAKE_CXX_COMPILER=${{ matrix.compiler_version }} -DCXX_STD=${{ matrix.cxx_std }}
+          fi
 
       - name: Build
         run: cd build ; make -j4

.github/workflows/windows.yml

@@ -17,6 +17,12 @@ jobs:
       matrix:
         cxx_std: [17, 20, 23]
         os: [windows-2022]
+        disable_trace: [false]
+        include:
+          # Test with trace disabled
+          - cxx_std: 20
+            os: windows-2022
+            disable_trace: true
 
     runs-on: ${{ matrix.os }}
 
@@ -26,7 +32,13 @@ jobs:
       - name: Configure CMake
         # Configure CMake in a 'build' subdirectory. Visual Studio is a multi-config generator, so we don't use CMAKE_BUILD_TYPE.
         # See https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html?highlight=cmake_build_type
-        run: cmake -B build -DCXX_STD=${{ matrix.cxx_std }}
+        run: |
+          if ("${{ matrix.disable_trace }}" -eq "true") {
+            cmake -B build -DCXX_STD=${{ matrix.cxx_std }} -DDISABLE_TRACE=true
+          } else {
+            cmake -B build -DCXX_STD=${{ matrix.cxx_std }}
+          }
+        shell: pwsh
 
       - name: Build
         working-directory: build

CMakeLists.txt

@@ -64,6 +64,12 @@ if (BUILD_WITH_HANA)
   add_definitions(-DBOOST_PARSER_USE_HANA_TUPLE)
 endif()
 
+set(DISABLE_TRACE false CACHE BOOL
+    "Disable parser trace functionality (defines BOOST_PARSER_DISABLE_TRACE).")
+if (DISABLE_TRACE)
+  add_definitions(-DBOOST_PARSER_DISABLE_TRACE)
+endif()
+
 
 ##################################################
 # Dependencies

doc/parser.qbk

@@ -148,6 +148,7 @@
 [def _RULES_               [macroref BOOST_PARSER_DEFINE_RULES `BOOST_PARSER_DEFINE_RULES`]]
 [def _AGGR_SIZE_           [macroref BOOST_PARSER_MAX_AGGREGATE_SIZE `BOOST_PARSER_MAX_AGGREGATE_SIZE`]]
 [def _SUBRNG_              [macroref BOOST_PARSER_SUBRANGE `BOOST_PARSER_SUBRANGE`]]
+[def _DISABLE_TRACE_       [macroref BOOST_PARSER_DISABLE_TRACE `BOOST_PARSER_DISABLE_TRACE`]]
 
 [def __p_                  [globalref boost::parser::_p `_p`]]
 

doc/tutorial.qbk

@@ -3766,6 +3766,22 @@ Some things to be aware of when looking at _Parser_ trace output:
   produces that value.  In these cases, you'll see the resolved value of the
   parse argument.
 
+[heading Compile-time trace disabling]
+
+While trace mode is very useful for debugging, it does have some overhead.
+Most parser templates are instantiated twice: Once with tracing enabled,
+once with tracing disabled.
+If you want to completely disable trace functionality at compile time, you can define
+`BOOST_PARSER_DISABLE_TRACE` before including any Boost.Parser headers:
+
+[teletype]``
+#define BOOST_PARSER_DISABLE_TRACE
+#include <boost/parser/parser.hpp>
+``
+
+When this define is set, all trace-related code is compiled out,
+reducing the compile time.
+
 [endsect]
 
 [section Memory Allocation]
@@ -3983,7 +3999,8 @@ This defines a RAII trace object that will produce the verbose trace requested
 by the user if they passed `_trace_::on` to the top-level parse.  It only has
 effect if `detail::enable_trace(flags)` is `true`.  If trace is enabled, it
 will show the state of the parse at the point at which it is defined, and then
-again when it goes out of scope.
+again when it goes out of scope. By defining `BOOST_PARSER_DISABLE_TRACE`,
+the trace feature can be disabled globally at compile time.
 
 [important For the tracing code to work, you must define an overload of
 `detail::print_parser` for your new parser type/template.  See

include/boost/parser/detail/printing.hpp

@@ -598,6 +598,7 @@ namespace boost { namespace parser { namespace detail {
     template<typename Context>
     auto resolve(Context const &, nope n);
 
+    #ifndef BOOST_PARSER_DISABLE_TRACE
     template<
         bool DoTrace,
         typename Iter,
@@ -708,6 +709,7 @@ namespace boost { namespace parser { namespace detail {
         }
         os << "--------------------" << std::endl;
     }
+    #endif // BOOST_PARSER_DISABLE_TRACE
 
 }}}