GBDK 2020 Docs
API Documentation for GBDK 2020
|
GBDK 2020 uses the SDCC compiler along with some custom tools to build Game Boy ROMs.
bin/
To see individual arguments and options for a tool, run that tool from the command line with either no arguments or with -h
.
What do these kinds of warnings / errors mean? WARNING: possibly wrote twice at addr 4000 (93->3E)
Warning: Write from one bank spans into the next. 7ff7 -> 8016 (bank 1 -> 2)
You may have a overflow in one of your ROM banks. If there is more data allocated to a bank than it can hold it then will spill over into the next bank. The warnings are generated by ihxcheck during conversion of an .ihx file into a ROM file.
See the section ROM/RAM Banking and MBCs for more details about how banks work and what their size is. You may want to use a tool such as romusage to calculate the amount of free and used space.
It is possible to change some of the important addresses used by the toolchain at link time using the -Wl-g XXX=YYY and =Wl-b XXX=YYY flags (where XXX is the name of the data, and YYY is the new address).
lcc will include the following linker defaults for sdldgb if they are not defined by the user.
_shadow_OAM
-Wl-g _shadow_OAM=0xC000
.STACK
-Wl-g .STACK=0xE000
.refresh_OAM
-Wl-g .refresh_OAM=0xFF80
_DATA
-Wl-b _DATA=0xc0A0
_CODE
-Wl-b _CODE=0x0200
The lcc program is the front end compiler driver for the actual compiler, assembler and linker. It works out what you want to do based on command line options and the extensions of the files you give it, computes the order in which the various programs must be called and then executes them in order. Some examples are:
lcc -o image.gb source.c
lcc -o image.gb source.s
lcc -c -o object1.o source1.c
lcc -c -o object2.o source2.s
lcc -o image.gb object1.o object2.o
lcc -o image.gb source1.c source2.s
Arguments to the assembler etc can be passed via lcc using -Wp..., -Wf..., -Wa... and -Wl... to pass options to the pre-processor, compiler, assembler and linker respectivly. Some common options are:
-Wa-l
-Wl-m
-Wl-gvar=addr
For example, to compile the example in the memory section and to generate a listing and map file you would use the following. Note the leading underscore that C adds to symbol names.
lcc -Wa-l -Wl-m -Wl-g_snd_stat=0xff26 -o image.gb hardware.c
Using Makefiles
Please see the sample projects included with GBDK-2020 for a couple different examples of how to use Makefiles.
You may also want to read a tutorial on Makefiles. For example:
https://makefiletutorial.com/ https://www.tutorialspoint.com/makefile/index.htm
lcc is the compiler driver (front end) for the GBDK/sdcc toolchain. It can be used to invoke all the tools needed for building a rom. If preferred, the individual tools can be called directly.
-v
flag can be used to show the exact steps lcc executes for a buildlcc -o somerom.gb somesource.c
SDCC C Source compiler
-Wf-<argument>
and -Wp-<argument>
(pre-processor)SDCC Assembler for the gameboy
-Wa-<argument>
Automatic Bank packer
When enabled, automatically assigns banks for object files where bank has been set to 255
, see rom_autobanking. Unless an alternative output is specified the given object files are updated with the new bank numbers.
-autobank
argument with lcc.-Wb-<argument>
Limitations
__banked
functions cannot be called from within the same source file they are declared in.__bank_*
symbol).The SDCC linker for the gameboy.
Links object files (.o) into a .ihx file which can be processed by makebin
-Wl-<argument>
IHX file validator
Checks .ihx files produced by sdldgb for correctness.
-Wi-<argument>
IHX to ROM converter
Converts .ihx files produced by sdldgb into ROM files (.gb, .gbc).
-Wm-<argument>
Compresssion utility
Compresses (and decompresses) binary file data with the gbcompress algorithm (also used in GBTD/GBMB). Decompression support is available in GBDK, see gb_decompress().
Tool for converting PNGs into GBDK format MetaSprites