commit 06d14f43fba0142b757b6d7575e558cd4c6cf5c2
parent 61aa254c6d5d2c464997b46e5da922ca54c817eb
Author: Walther Chen <walther.chen@gmail.com>
Date:   Fri, 11 Nov 2022 09:20:41 -0500

tracing notes in Readme

Diffstat:

MREADME.md | 42++++++++++++++++++++++++++++++++++++++++++


Msrc/opt1.zig | 10----------


2 files changed, 42 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
@@ -22,3 +22,45 @@ There's also a flag to enable tracing of instructions `-Dtrace`, and some fixtur
 ```
 zig build opt1 -Drelease-fast -Dtrace -- fixtures/mandelbrot.bf
 ```
+
+## Notes
+
+### Tracing
+
+Tracing is enabled/disabled at compile time.
+
+In `build.zig`:
+
+```zig
+// Build option for tracing instructions
+const trace_value = b.option(bool, "trace", "enable tracing instructions for interpreter") orelse false;
+const trace_step = b.addOptions();
+trace_step.addOption(bool, "TRACE", trace_value);
+```
+
+creates an option with the flag `-Dtrace`, then assigns it to the variable `TRACE`.
+
+Then, for each executable generated, the option is assigned to a package which can be imported.
+
+`build.zig`:
+```zig
+exe.addOptions("build_with_trace", trace_step);
+```
+
+`main.zig`:
+```zig
+const TRACE = @import("build_with_trace").TRACE;
+
+pub fn main() anyerror!void {
+    if (TRACE) {
+        std.debug.print("Building with TRACE enabled\n", .{});
+    }
+```
+Branches will be automatically eliminated if trace.TRACE is false.
+
+A comment on discord:
+https://discord.com/channels/605571803288698900/605572581046747136/950032936399429662
+
+>there is also aggressive dead-code elimination on comptime-chosen paths. That is to say, if the condition of an if statement/expression is known at comptime (even if the resulting expression is a runtime one), the code of the expression on false will be eliminated, and the contents of the expression of the else clause will be eliminated on true.
+
+There's probably doc for it, will link if found.
diff --git a/src/opt1.zig b/src/opt1.zig
@@ -12,16 +12,6 @@ const TRACE = @import("build_with_trace").TRACE;
 
 pub fn main() anyerror!void {
     if (TRACE) {
-        // this branch be automatically eliminated if trace.TRACE is false.
-        //
-        // A comment on discord:
-        // https://discord.com/channels/605571803288698900/605572581046747136/950032936399429662
-        //
-        //  there is also aggressive dead-code elimination on comptime-chosen paths.
-        //  That is to say, if the condition of an if statement/expression is known at
-        //  comptime (even if the resulting expression is a runtime one), the code of
-        //  the expression on false will be eliminated, and the contents of the
-        //  expression of the else clause will be eliminated on true.
         std.debug.print("Building with TRACE enabled\n", .{});
     }