pidl: optionally annotate output for debug purposes

It can sometimes be hard to tell which bit of pidl generated which bit
of C. This commit wants to help.

If the PIDL_DEVELOPER environment variable is set (via waf
--pidl-developer or some other means), pidl will annotate *most* C
indicating which lines were generated by which bits of pidl. It looks
something like this:

_PUBLIC_ enum ndr_err_code ndr_push_auth_session_info(struct ndr_push *ndr, int ndr_flags, const struct auth_session_info *r)
{  //:PIDL: Parse::Pidl::Samba4::NDR::Parser::ParseTypePushFunction  lib/Parse/Pidl/Samba4/NDR/Parser.pm:3079
	NDR_PUSH_CHECK_FLAGS(ndr, ndr_flags);  //:PIDL: Parse::Pidl::Samba4::NDR::Parser::ParseStructPush  lib/Parse/Pidl/Samba4/NDR/Parser.pm:604
	if (ndr_flags & NDR_SCALARS) {
		NDR_CHECK(ndr_push_align(ndr, 5));  //:PIDL: Parse::Pidl::Samba4::NDR::Parser::ParseStructPushPrimitives  lib/Parse/Pidl/Samba4/NDR/Parser.pm:1448
		NDR_CHECK(ndr_push_unique_ptr(ndr, r->security_token));  //:PIDL: Parse::Pidl::Samba4::NDR::Parser::ParsePtrPush  lib/Parse/Pidl/Samba4/NDR/Parser.pm:604
		NDR_CHECK(ndr_push_unique_ptr(ndr, r->unix_token));
		NDR_CHECK(ndr_push_unique_ptr(ndr, r->info));
		NDR_CHECK(ndr_push_unique_ptr(ndr, r->unix_info));
		NDR_CHECK(ndr_push_uint3264(ndr, NDR_SCALARS, 0));
		/* [ignore] 'torture' */  //:PIDL: Parse::Pidl::Samba4::NDR::Parser::ParseElementPushLevel  lib/Parse/Pidl/Samba4/NDR/Parser.pm:729
		NDR_CHECK(ndr_push_DATA_BLOB(ndr, NDR_SCALARS, r->session_key));  //:PIDL: Parse::Pidl::Samba4::NDR::Parser::ParseDataPush  lib/Parse/Pidl/Samba4/NDR/Parser.pm:604
		NDR_CHECK(ndr_push_uint3264(ndr, NDR_SCALARS, 0));  //:PIDL: Parse::Pidl::Samba4::NDR::Parser::ParsePtrPush  lib/Parse/Pidl/Samba4/NDR/Parser.pm:604
		/* [ignore] 'credentials' */  //:PIDL: Parse::Pidl::Samba4::NDR::Parser::ParseElementPushLevel  lib/Parse/Pidl/Samba4/NDR/Parser.pm:729

The comments starting with '//:PIDL:' have the function name, the filename,
and line number. The comment follows the ordinary output, and uses the '//'
style so as not to interfere with multiline /* */ comments if they happen
to exist.

A '//:PIDL:' comment is added whenever the pidl function or indentation
level changes, and very occasionally at other places if pidl runs for a
while without either of these things happening.

This does not affect pidl parsers that do not inherit from Parse::Pidl::Base,
and is careful to have no performance impact on non-debug generation.

This may help with semi-automated flow analysis.

Signed-off-by: Douglas Bagnall <douglas.bagnall@catalyst.net.nz>
Reviewed-by: Andrew Bartlett <abartlet@samba.org>

4 files changed, 64 insertions, 1 deletions

diff --git a/buildtools/wafsamba/samba_autoconf.py b/buildtools/wafsamba/samba_autoconf.py
index 1ccee54bb63..4615e201422 100644
--- a/buildtools/wafsamba/samba_autoconf.py
+++ b/buildtools/wafsamba/samba_autoconf.py
@@ -725,6 +725,9 @@ def SAMBA_CONFIG_H(conf, path=None):
     if Options.options.debug:
         conf.ADD_CFLAGS('-g', testflags=True)
 
+    if Options.options.pidl_developer:
+        conf.env.PIDL_DEVELOPER_MODE = True
+
     if Options.options.developer:
         conf.env.DEVELOPER_MODE = True
 
diff --git a/buildtools/wafsamba/samba_pidl.py b/buildtools/wafsamba/samba_pidl.py
index 3fecfa90eb9..a34c871d183 100644
--- a/buildtools/wafsamba/samba_pidl.py
+++ b/buildtools/wafsamba/samba_pidl.py
@@ -69,6 +69,10 @@ def SAMBA_PIDL(bld, pname, source,
     if cpp == "CPP=xlc_r":
         cpp = ""
 
+    if bld.env['PIDL_DEVELOPER_MODE']:
+        pidl_dev = 'PIDL_DEVELOPER=1 '
+    else:
+        pidl_dev = ''
 
     if bld.CONFIG_SET("CC"):
         if isinstance(bld.CONFIG_GET("CC"), list):
@@ -76,7 +80,7 @@ def SAMBA_PIDL(bld, pname, source,
         else:
             cc = 'CC="%s"' % bld.CONFIG_GET("CC")
 
-    t = bld(rule='cd ${PIDL_LAUNCH_DIR} && %s %s ${PERL} ${PIDL} --quiet ${OPTIONS} --outputdir ${OUTPUTDIR} -- "${IDLSRC}"' % (cpp, cc),
+    t = bld(rule='cd ${PIDL_LAUNCH_DIR} && %s%s %s ${PERL} ${PIDL} --quiet ${OPTIONS} --outputdir ${OUTPUTDIR} -- "${IDLSRC}"' % (pidl_dev, cpp, cc),
             ext_out    = '.c',
             before     = 'c',
             update_outputs = True,
diff --git a/buildtools/wafsamba/wscript b/buildtools/wafsamba/wscript
index 9987c6e4fcc..b9f2f495617 100644
--- a/buildtools/wafsamba/wscript
+++ b/buildtools/wafsamba/wscript
@@ -102,6 +102,9 @@ def options(opt):
     gr.add_option('--enable-developer',
                    help=("Turn on developer warnings and debugging"),
                    action="store_true", dest='developer', default=False)
+    gr.add_option('--pidl-developer',
+                   help=("annotate PIDL-generated code for developers"),
+                   action="store_true", dest='pidl_developer', default=False)
     gr.add_option('--disable-warnings-as-errors',
                    help=("Do not treat all warnings as errors (disable -Werror)"),
                    action="store_true", dest='disable_warnings_as_errors', default=False)
diff --git a/pidl/lib/Parse/Pidl/Base.pm b/pidl/lib/Parse/Pidl/Base.pm
index e89a48d2155..056b7b37d48 100644
--- a/pidl/lib/Parse/Pidl/Base.pm
+++ b/pidl/lib/Parse/Pidl/Base.pm
@@ -44,3 +44,56 @@ sub pidl_both {
 	$self->{res} .= "$txt\n";
 	$self->{res_hdr} .= "$txt\n";
 }
+
+
+# When the PIDL_DEVELOPER env flag is set, we overwrite $self->pidl()
+# and $self->pidl_hdr() to annotate the output with location
+# information.
+
+sub pidl_dev_msg {
+	my $self = shift;
+	my ($pkg, $file, $line, $sub) = caller(2);
+	# minimise the path
+	if ($file =~ m{/pidl/(lib/.+|pidl)$}) {
+		$file = $1;
+	}
+	my $state = $self->{dev_state} // ['uninitialised', 0, ''];
+	my ($ploc, $pline, $ptabs) = @$state;
+	my $loc = "$sub	 $file";
+
+	if ($loc ne $ploc or
+	    abs($line - $pline) > 20 or
+	    $self->{tabs} ne $ptabs) {
+		$self->{dev_state} = [$loc, $line, $self->{tabs}];
+		return "  //<PIDL> $loc:$line";
+	}
+	return '';
+}
+
+
+if ($ENV{PIDL_DEVELOPER}) {
+	undef &pidl;
+	undef &pidl_hdr;
+
+	*Parse::Pidl::Base::pidl = sub {
+		my ($self, $txt) = @_;
+
+		if ($txt) {
+			if ($txt !~ /^#/) {
+				$self->{res} .= $self->{tabs};
+			}
+			$self->{res} .= $txt;
+		}
+		$self->{res} .= $self->pidl_dev_msg;
+		$self->{res} .= "\n";
+	};
+
+	*Parse::Pidl::Base::pidl_hdr = sub {
+		my ($self, $txt) = @_;
+		$txt .= $self->pidl_dev_msg;
+		$self->{res_hdr} .= "$txt\n";
+	}
+}
+
+
+1;