Fill Routine

[boriel]

I
The asm directive for this is #require "file.asm", which will include the file ONCE at the end of the compilation (include once does it in place).

That's a new one for me. Huh.

Is there a list of these compiler directives somewhere?

Not yet :oops:

Anyway, it's safe to use include once always. But some times you want a library to be "included once later". Let's suppose we have the following files:

file1.asm

Code:

...
call SUB_ASM
ld a, 5
jp _FILE2
; Continue on file2.asm routine
#include once "SUB.asm"

file2.asm

Code:

_FILE2:
rla ; a = a * 2
...
...

Then you realized that if you join both files, the JP _FILE2 can be removed, so remove the JP_FILE2, and replace #include once by #require. The compiler will "include once" the sub.asm file at a later stage, so you can join file1.asm and file2.asm in a row:
file1.asm

Code:

#require "SUB.asm"
..
call SUB_ASM
ld a, 5
; jp _FILE2 ;; removed; goes directly to _FILE2:
; Continue on file2.asm routine

file2.asm

Code:

; Ensures file1.asm goes here
#include once "file1.asm"
_FILE2:
rla ; a = a * 2
...
...

This technique is used with the print routines, and many others. This way, the code gets optimized and in a row, but also allows to discard chunks of code if they are not used (as commented above). So if file1.asm code is not used, it won't be included, (conditional defines, etc...)