Document debugfile integration

Not how to use debugfiles themselves, that's the scope of another project.

Author: ISSOtm

Makefile.nw

@@ -314,7 +314,7 @@ The \texttt{\$\{@:.mk=.o\}} syntax means “expand to the contents of \texttt{\$
 We also need to inform Make of the dependency files that it should read; but, we don't do so when running \texttt{make clean}, as we don't need dependency info when we're trying to wipe the slate clean!
 <<Assembly rules>>=
 ifeq ($(filter clean,${MAKECMDGOALS}),)
-include $(patsubst src/%.asm,obj/%.mk,${SRCS})
+include ${DEPFILES}
 endif
 @
 Interestingly, Make also treats every such file as a target that needs to be made, and so it will automatically try to generate them if they don't exist yet.
@@ -338,6 +338,40 @@ ${ROM}: $(patsubst src/%.asm,obj/%.o,${SRCS})
 	&& ${RGBFIX} -v ${FIXFLAGS} $@
 @
 
+\pagebreak
+
+\subsubsection{Debugfiles}
+
+Debugfiles are a recent addition to the Game Boy debugging experience.
+They allow instructing the emulator to perform a lot of debug checks, without having to modify the ROM at all!
+A more complete guide to debugfile macros \href{https://github.com/ISSOtm/debugfile.inc/wiki}{can be found on \texttt{debugfile.inc}'s wiki}; but for now, let's focus on how they are hooked up to the build system.
+
+You see, they are implemented in a way you might find a bit strange.
+Unless the symbol \texttt{PRINT\_DEBUGFILE} is defined, the macros from \texttt{debugfile.inc} do \emph{nothing}.
+But if that symbol is defined, they \emph{print} their corresponding debugfile directives.
+That's because this is the only way RGBASM provides of generating such a file; better debugfile integration is planned, but not here yet.
+
+So, first, a debugfile can be generated by assembling the corresponding source file while defining the aforementioned symbol.
+That said, we make the rule depend on the \emph{object file}, so that it's only executed after the whole dependency resolution process.
+
+<<Assembly rules>>=
+obj/%.dbg: obj/%.o
+	${RGBASM} ${ASFLAGS} src/$*.asm -DPRINT_DEBUGFILE
+@
+
+This generates one debugfile per source file, but by default, an emulator will only auto-load a single debugfile (and if it has the appropriate name, hence the use of \texttt{ROMNAME} here).
+Thus, we also generate a “master file”, which includes all of the sub-files.
+
+<<Assembly rules>>=
+bin/${ROMNAME}.dbg: ${SRCS}
+	echo @debugfile 1.0 >$@
+	printf '@include "../%s"\n' ${DEBUGFILES} >>$@
+@
+
+Since the debugfile is made to depend on each source file, creating a new source file re-generates the list of debugfiles.
+However, note that \emph{deleting} a source file will not invalidate the list; this is a limitation that I do not know how to solve with Make.
+Please feel free to send a pull request or to contact me if you know how to solve this.
+
 \subsubsection{Submodules}
 
 A Git “submodule” is, largely, a Git repository inside of a Git repository; this has the benefit of making it easier to update the submodules, but the downside of being a little quirky.
@@ -347,6 +381,8 @@ By default, cloning the repo does not initialise submodules (so they are empty);
 Note that the real paths aren't used!
 Since RGBASM fails to find the files, it outputs the path(s) as passed to \texttt{include}, not where the file would actually be found (e.g. \texttt{src/hardware.inc/hardware.inc}).
 
+\pagebreak % Otherwise the "header line" is on a different page than the code >_<
+
 <<Assembly rules>>=
 hardware.inc/hardware.inc rgbds-structs/structs.asm:
 	@echo '$@ is not present; have you initialized submodules?'
@@ -372,7 +408,7 @@ Since this is a commonly desirable feature, these names are common conventions.
 It is also a little special, as it is the \emph{first} rule in the file (as we will see in \autoref{sec:overall}), it is also the “default” target, i.e. what Make selects as its target if invoked without one (just \texttt{make}).
 
 <<Phony rules>>=
-all: ${ROM}
+all: ${ROM} ${DEBUGFILES} bin/${ROMNAME}.dbg
 .PHONY: all
 
 @
@@ -383,8 +419,6 @@ all: ${ROM}
 
 (As we have seen in \autoref{sec:auto-discovery}, we also made it a little special, its presence suppressing dependency auto-discovery.)
 
-\pagebreak
-
 <<Phony rules>>=
 clean:
 	rm -rf bin obj assets
@@ -413,7 +447,7 @@ This allows the following to work:
 \begin{pygmented}[lang=console]
 $ ls ~/rgbds-0.9.1
 rgbasm  rgbfix  rgbgfx  rgblink
-$ export RGBDS=~/rgbds-0.9.1
+$ export RGBDS=~/rgbds-0.9.1/
 $ make
 ~/rgbds-0.9.1/rgbasm -p 0xFF (etc.)
 \end{pygmented}
@@ -433,7 +467,14 @@ And some file names:
 <<Configuration>>=
 ROM = bin/${ROMNAME}.${ROMEXT}
 SRCS := $(call rwildcard,src,*.asm)
+@
 
+Then some lists of files that will be generated from that list of sources, for convenience:
+
+<<Configuration>>=
+OBJS := $(patsubst src/%.asm,obj/%.o,${SRCS})
+DEPFILES := ${OBJS:.o=.mk}
+DEBUGFILES := ${OBJS:.o=.dbg}
 @
 
 And, last but not least, including the file containing project-specific configuration.