06_toolchain.md (11594B)
1@page docs_toolchain GBDK Toolchain 2 3 4@anchor toolchain_overview 5# Overview 6GBDK 2020 uses the SDCC compiler along with some custom tools to build Game Boy ROMs. 7- All tools are located under `bin/` 8- The typical order of tools called is as follows (when using lcc these steps are usually performed automatically). 9 1. Compile and assemble source files (.c, .s, .asm) with @ref sdcc and @ref sdasgb 10 2. Optional: perform auto banking with @ref bankpack on the object files 11 3. Link the object files into .ihx file with @ref sdldgb 12 4. Validate the .ihx file with @ref ihxcheck 13 5. Convert the .ihx file to a ROM file (.gb, .gbc) with @ref makebin 14 15To see individual arguments and options for a tool, run that tool from the command line with either no arguments or with `-h`. 16 17 18# Data Types 19For data types and special C keywords, see @ref file_asm_gbz80_types_h "asm/gbz80/types.h" and @ref file_asm_types_h "asm/types.h". 20 21Also see the SDCC manual (scroll down a little on the linked page): http://sdcc.sourceforge.net/doc/sdccman.pdf#section.1.1 22 23 24@anchor toolchain_changing_important_addresses 25# Changing Important Addresses 26It 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). 27 28@ref lcc will include the following linker defaults for @ref sdldgb if they are not defined by the user. 29 30 - `_shadow_OAM` 31 - Location of sprite ram (requires 0xA0 bytes). 32 - Default `-Wl-g _shadow_OAM=0xC000` 33 34 - `.STACK` 35 - Initial stack address 36 - Default `-Wl-g .STACK=0xE000` 37 38 - `.refresh_OAM` 39 - Address to which the routine for refreshing OAM will be copied (must be in HIRAM). Default 40 - Default `-Wl-g .refresh_OAM=0xFF80` 41 42 - `_DATA` 43 - Start of RAM section (starts after Shadow OAM) 44 - Default `-Wl-b _DATA=0xc0A0` 45 46 - `_CODE` 47 - Start of ROM section 48 - Default `-Wl-b _CODE=0x0200` 49 50 51@anchor toolchain_compiling_programs 52# Compiling programs 53 54The @ref 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: 55 56 - Compile the C source 'source.c', assemble and link it producing the Gameboy image 'image.gb' 57 58 lcc -o image.gb source.c 59 60 - Assemble the file 'source.s' and link it producing the Gameboy image 'image.gb' 61 62 lcc -o image.gb source.s 63 64 - Compile the C program 'source1.c' and assemble it producing the object file 'object1.o' for later linking. 65 66 lcc -c -o object1.o source1.c 67 68 - Assemble the file 'source2.s' producing the object file 'object2.o' for later linking 69 70 lcc -c -o object2.o source2.s 71 72 - Link the two object files 'object1.o' and 'object2.o' and produce the Gameboy image 'image.gb' 73 74 lcc -o image.gb object1.o object2.o 75 76 - Do all sorts of clever stuff by compiling then assembling source1.c, assembling source2.s and then linking them together to produce image.gb. 77 78 lcc -o image.gb source1.c source2.s 79 80Arguments to the assembler, linker, etc can be passed via lcc using -Wp..., -Wf..., -Wa... and -Wl... to pass options to the pre-processor, compiler, assembler and linker respectively. Some common options are: 81 82 - To generate an assembler listing file. 83 84 -Wa-l 85 86 - To generate a linker map file. 87 88 -Wl-m 89 90 - To bind var to address 'addr' at link time. 91 92 -Wl-gvar=addr 93 94For 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. 95 96 lcc -Wa-l -Wl-m -Wl-g_snd_stat=0xff26 -o image.gb hardware.c 97 98 99@subsection Makefiles 100## Using Makefiles 101 102Please see the sample projects included with GBDK-2020 for a couple different examples of how to use Makefiles. 103 104You may also want to read a tutorial on Makefiles. For example: 105https://makefiletutorial.com/ 106https://www.tutorialspoint.com/makefile/index.htm 107 108@anchor build_tools 109# Build Tools 110 111@anchor lcc 112## lcc 113lcc is the compiler driver (front end) for the GBDK/sdcc toolchain. 114 115For detailed settings see @ref lcc-settings 116 117It can be used to invoke all the tools needed for building a rom. 118If preferred, the individual tools can be called directly. 119- the `-v` flag can be used to show the exact steps lcc executes for a build 120- lcc can compile, link and generate a binary in a single pass: `lcc -o somerom.gb somesource.c` 121- @anchor lcc_debug 122 lcc now has a `-debug` flag that will turn on the following recommended flags for debugging 123 - `--debug` for sdcc (lcc equiv: `-Wf-debug`) 124 - `-y` enables .cdb output for @ref sdldgb (lcc equiv: `-Wl-y`) 125 - `-j` enables .noi output for @ref sdldgb (lcc equiv: `-Wl-j`) 126 127 128@anchor sdcc 129## sdcc 130SDCC C Source compiler. 131 132For detailed settings see @ref sdcc-settings 133 134- Arguments can be passed to it through @ref lcc using `-Wf-<argument>` and `-Wp-<argument>` (pre-processor) 135 136@anchor sdasgb 137## sdasgb 138SDCC Assembler for the Game Boy. 139 140For detailed settings see @ref sdasgb-settings 141 142- Arguments can be passed to it through @ref lcc using `-Wa-<argument>` 143 144 145@anchor bankpack 146## bankpack 147Automatic Bank packer. 148 149For detailed settings see @ref bankpack-settings 150 151When enabled, automatically assigns banks for object files where bank has been set to `255`, see @ref rom_autobanking. 152Unless an alternative output is specified the given object files are updated with the new bank numbers. 153- Can be enabled by using the `-autobank` argument with @ref lcc. 154- Must be called after compiling/assembling and before linking. 155- Arguments can be passed to it through @ref lcc using `-Wb-<argument>` 156 157 158@anchor sdldgb 159## sdldgb 160The SDCC linker for the gameboy. 161 162For detailed settings see @ref sdldgb-settings 163 164Links object files (.o) into a .ihx file which can be processed by @ref makebin 165- Arguments can be passed to it through @ref lcc using `-Wl-<argument>` 166 167 168@anchor ihxcheck 169## ihxcheck 170IHX file validator. 171 172For detailed settings see @ref ihxcheck-settings 173 174Checks .ihx files produced by @ref sdldgb for correctness. 175- It will warn if there are multiple writes to the same ROM address. This may indicate mistakes in the code or ROM bank overflows 176- Arguments can be passed to it through @ref lcc using `-Wi-<argument>` 177 178 179@anchor makebin 180## makebin 181IHX to ROM converter. 182 183- For detailed settings see @ref makebin-settings 184- For makebin `-yt` MBC values see @ref setting_mbc_and_rom_ram_banks 185 186Converts .ihx files produced by @ref sdldgb into ROM files (.gb, .gbc). Also used for setting some ROM header data. 187- Arguments can be passed to it through @ref lcc using `-Wm-<argument>` 188 189 190@anchor gbdk_utilities 191# GBDK Utilities 192 193 194@anchor utility_gbcompress 195## GBCompress 196Compresssion utility. 197 198For detailed settings see @ref gbcompress-settings 199 200Compresses (and decompresses) binary file data with the gbcompress algorithm (also used in GBTD/GBMB). Decompression support is available in GBDK, see @ref gb_decompress(). 201 202Can also compress (and decompress) using block style RLE encoding with the `--alg=rle` flag. Decompression support is available in GBDK, see @ref rle_decompress(). 203 204 205@anchor utility_png2asset 206## png2asset 207Tool for converting PNGs into GBDK format MetaSprites and Tile Maps. 208 209- Convert single or multiple frames of graphics into metasprite structured data for use with the ...metasprite...() functions. 210- When `-map` is used, converts images into Tile Maps and matching Tile Sets 211- Supports Game Boy 2bpp, GBC 4bpp, SGB 4bpp, and SMS/GG 4bpp 212 213For detailed settings see @ref png2asset-settings 214For working with sprite properties (including cgb palettes), see @ref metasprite_and_sprite_properties 215For API support see @ref move_metasprite() and related functions in @ref metasprites.h 216 217### Working with png2asset 218 - The origin (pivot) for the metasprite is not required to be in the upper left-hand corner as with regular hardware sprites. See `-px` and `-py`. 219 220 - The conversion process supports using both SPRITES_8x8 (`-spr8x8`) and SPRITES_8x16 mode (`-spr8x16`). If 8x16 mode is used then the height of the metasprite must be a multiple of 16. 221 222#### Terminology 223The following abbreviations are used in this section: 224* Original Game Boy and Game Boy Pocket style hardware: `DMG` 225* Game Boy Color: `CGB` 226 227#### Conversion Process 228png2asset accepts any png as input, although that does not mean any image will be valid. The program will follow the next steps: 229 - The image will be subdivided into tiles of 8x8 or 8x16. 230 - For each tile a palette will be generated. 231 - If there are more than 4 colors in the palette it will throw an error. 232 - The palette will be sorted from darkest to lightest. If there is a transparent color that will be the first one (this will create a palette that will also work with `DMG` devices). 233 - If there are more than 8 palettes the program will throw an error. 234 235With all this, the program will generate a new indexed image (with palette), where each 4 colors define a palette and all colors within a tile can only have colors from one of these palettes 236 237It is also posible to pass a indexed 8-bit png with the palette properly sorted out, using `-keep_palette_order` 238 - Palettes will be extracted from the image palette in groups of 4 colors. 239 - Each tile can only have colors from one of these palettes per tile. 240 - The maximum number of colors is 32. 241 242Using this image a tileset will be created 243 - Duplicated tiles will be removed. 244 - Tiles will be matched without mirror, using vertical mirror, horizontal mirror or both (use `-noflip` to turn off matching mirrored tiles). 245 - The palette won't be taken into account for matching, only the pixel color order, meaning there will be a match between tiles using different palettes but looking identical on grayscale. 246 247 248#### Maps 249Passing `-map` the png can be converted to a map that can be used in both the background and the window. In this case, png2asset will generate: 250 - The palettes 251 - The tileset 252 - The map 253 - The color info 254 - By default, an array of palette index for each tile. This is not the way the hardware works but it takes less space and will create maps compatibles with both `DMG` and `CGB` devices. 255 - Passing `-use_map_attributes` will create an array of map attributes. It will also add mirroring info for each tile and because of that maps created with this won't be compatible with `DMG`. 256 - Use `-noflip` to make background maps which are compatible with `DMG` devices. 257 258#### Meta sprites 259By default the png will be converted to metasprites. The image will be subdivided into meta sprites of `-sw` x `-sh`. In this case png2asset will generate: 260 - The metasprites, containing an array of: 261 - tile index 262 - y offset 263 - x offset 264 - flags, containing the mirror info, the palettes for both DMG and GBC and the sprite priority 265 - The metasprites array 266 267 268#### Super Game Boy Borders (SGB) 269Screen border assets for the Super Game Boy can be generated using png2asset. 270 271The following flags should be used to perform the conversion: 272 - `<input_border_file.png> -map -bpp 4 -max_palettes 4 -pack_mode sgb -use_map_attributes -c <output_border_data.c>` 273 - Where `<input_border_file.png>` is the image of the SGB border (256x224) and `<output_border_data.c>` is the name of the source file to write the assets out to. 274 275 276See the `sgb_border` example project for more details.