From 891a907a3005fdb0f154f93d79943e563d8454c6 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Wed, 6 Aug 2025 13:52:13 +1200
Subject: [PATCH] Add and use ENABLE_HELP_SOURCE

Conditionally include help source tracking to preserve ABI.
Docs builds can (and should) use `ENABLE_HELP_SOURCE` so that the generated sphinx docs can perform default grouping and link to source files.
Regular user-builds don't need the source tracking.
---
 .github/workflows/prepare-docs.yml |  1 +
 Makefile                           |  5 +++++
 README.md                          |  6 ++++++
 kernel/register.h                  | 28 ++++++++++++++--------------
 4 files changed, 26 insertions(+), 14 deletions(-)

diff --git a/.github/workflows/prepare-docs.yml b/.github/workflows/prepare-docs.yml
index b47f5f3dd..a02febb3b 100644
--- a/.github/workflows/prepare-docs.yml
+++ b/.github/workflows/prepare-docs.yml
@@ -47,6 +47,7 @@ jobs:
           echo "ENABLE_VERIFIC_LIBERTY := 1" >> Makefile.conf
           echo "ENABLE_VERIFIC_YOSYSHQ_EXTENSIONS := 1" >> Makefile.conf
           echo "ENABLE_CCACHE := 1" >> Makefile.conf
+          echo "ENABLE_HELP_SOURCE := 1" >> Makefile.conf
           make -j$procs ENABLE_LTO=1
 
       - name: Prepare docs
diff --git a/Makefile b/Makefile
index ce438f5db..1463055bd 100644
--- a/Makefile
+++ b/Makefile
@@ -24,6 +24,7 @@ ENABLE_VERIFIC_LIBERTY := 0
 ENABLE_COVER := 1
 ENABLE_LIBYOSYS := 0
 ENABLE_ZLIB := 1
+ENABLE_HELP_SOURCE := 0
 
 # python wrappers
 ENABLE_PYOSYS := 0
@@ -109,6 +110,10 @@ PLUGIN_LINKFLAGS += -L"$(LIBDIR)"
 PLUGIN_LIBS := -lyosys_exe
 endif
 
+ifeq ($(ENABLE_HELP_SOURCE),1)
+CXXFLAGS += -DYOSYS_ENABLE_HELP_SOURCE
+endif
+
 PKG_CONFIG ?= pkg-config
 SED ?= sed
 BISON ?= bison
diff --git a/README.md b/README.md
index 6c576f682..78b8bfc51 100644
--- a/README.md
+++ b/README.md
@@ -276,3 +276,9 @@ From the root of the repository, run `make docs`.  This will build/rebuild yosys
 as necessary before generating the website documentation from the yosys help
 commands.  To build for pdf instead of html, call
 `make docs DOC_TARGET=latexpdf`.
+
+It is recommended to use the `ENABLE_HELP_SOURCE` make option for Yosys builds
+that will be used to build the documentation.  This option enables source
+location tracking for passes and improves the command reference through grouping
+related commands and allowing for the documentation to link to the corresponding
+source files.
diff --git a/kernel/register.h b/kernel/register.h
index e8c017c1d..fba72538f 100644
--- a/kernel/register.h
+++ b/kernel/register.h
@@ -23,22 +23,22 @@
 #include "kernel/yosys_common.h"
 #include "kernel/yosys.h"
 
-#include <version>
-#if __cpp_lib_source_location == 201907L
-  #include <source_location>
-  using std::source_location;
-#elif defined(__has_include)
-#  if __has_include(<experimental/source_location>)
-    #include <experimental/source_location>
-    using std::experimental::source_location;
-#  else
-    #define SOURCE_FALLBACK
-#  endif
-#else
-  #define SOURCE_FALLBACK
+#ifdef YOSYS_ENABLE_HELP_SOURCE
+	#include <version>
+#	if __cpp_lib_source_location == 201907L
+		#include <source_location>
+		using std::source_location;
+		#define HAS_SOURCE_LOCATION
+#	elif defined(__has_include)
+#		if __has_include(<experimental/source_location>)
+			#include <experimental/source_location>
+			using std::experimental::source_location;
+			#define HAS_SOURCE_LOCATION
+#		endif
+#	endif
 #endif
 
-#ifdef SOURCE_FALLBACK
+#ifndef HAS_SOURCE_LOCATION
 struct source_location { // dummy placeholder
 	int line() const { return 0; }
 	int column() const { return 0; }