Merge pull request #7 from skx/2-breakpoint

Added breakpoint support.

Author: skx

README.md

@@ -8,6 +8,7 @@ Table of Contents
    * [Usage](#usage)
    * [My Approach](#my-approach)
    * [Timeline](#timeline)
+      * [Debugging the generated program](#debugging-the-generated-program)
    * [Test Programs](#test-programs)
    * [Future Plans?](#future-plans)
    * [Bug Reports?](#bug-reports)
@@ -96,6 +97,50 @@ In the end it took me about four hours to get something I was happy with, and la
 * After that I slowly made improvements
   * Adding a lexer in [#4](https://github.com/skx/bfcc/pull/4)
   * Allowing the generation of either C or assembly in [#6](https://github.com/skx/bfcc/pull/6)
+  * Allow generating a breakpoint instruction when using the assembly-backend in [#7](https://github.com/skx/bfcc/pull/7).
+
+
+### Debugging the generated program
+
+If you run the compiler with the `-debug` flag a breakpoint will be generated
+immediately at the start of the program.  You can use that breakpoint to easily
+debug the generated binary via `gdb`.
+
+    $ bfcc -debug ./examples/hello-world.bf
+
+Now you can launch that binary under `gdb`, and run it:
+
+    $ gdb ./a.out
+    (gdb) run
+    ..
+    Program received signal SIGTRAP, Trace/breakpoint trap.
+    0x00000000004000bb in _start ()
+
+Disassemble the code via `disassemble`, and step over instructions one at a time via `stepi`.  If your program is long you might see a lot of output from the `disassemble` step.
+
+    (gdb) disassemble
+    Dump of assembler code for function _start:
+       0x00000000004000b0 <+0>:	movabs $0x600290,%r8
+       0x00000000004000ba <+10>:	int3
+    => 0x00000000004000bb <+11>:	addb   $0x8,(%r8)
+       0x00000000004000bf <+15>:	cmpb   $0x0,(%r8)
+       0x00000000004000c3 <+19>:	je     0x40013f <close_loop_1>
+    End of assembler dump.
+
+You can set a breakpoint at a line in the future, and continue running till
+you hit it, with something like this:
+
+     (gdb) break *0x00000000004000c3
+     (gdb) cont
+
+Once there inspect the registers with commands like these two:
+
+     (gdb) print $r8
+     (gdb) print *$r8
+     (gdb) info registers
+
+Further documentation can be found in the `gdb` manual, which is worth reading
+if you've an interest in compilers, debuggers, and decompilers.
 
 
 

generators/generator_asm.go

@@ -35,6 +35,14 @@ _start:
 `
 	buff.WriteString(programStart)
 
+	//
+	// Should we generate a debug-breakpoint?
+	//
+	debug := os.Getenv("DEBUG")
+	if debug == "1" {
+		buff.WriteString("  int3\n")
+	}
+
 	//
 	// Keep track of "[" here.
 	//

main.go

@@ -20,6 +20,7 @@ func main() {
 	//
 	backend := flag.String("backend", "asm", "The backend to use for compilation.")
 	cleanup := flag.Bool("cleanup", true, "Remove the generated files after creation.")
+	debug := flag.Bool("debug", false, "Insert a debugging-breakpoint in the generated file, if possible.")
 	run := flag.Bool("run", false, "Run the program after compiling.")
 	flag.Parse()
 
@@ -71,6 +72,17 @@ func main() {
 		os.Setenv("CLEANUP", "0")
 	}
 
+	//
+	// Will we setup a debug-breakpoint?
+	//
+	// This only makes sense for the ASM-backend.
+	//
+	if *debug {
+		os.Setenv("DEBUG", "1")
+	} else {
+		os.Setenv("DEBUG", "0")
+	}
+
 	//
 	// Generate the compiled version
 	//