09_migrating_new_versions.md (5070B)
1@page docs_migrating_versions Migrating to new GBDK Versions 2 3This section contains information that may be useful to know or important when upgrading to a newer GBDK release. 4 5# GBDK 2020 versions 6 7## Porting to GBDK 2020 4.0.6 8 - Renamed `bgb_emu.h` to `emu_debug.h` and BGB_* functions to EMU_* 9 - Aliases for the BGB_* ones and a `bgb_emu.h` shim are present for backward compatibility, but updating to the new naming is recommended 10 11 12## Porting to GBDK 2020 4.0.5 13 - GBDK now requires SDCC 12259 or higher with GBDK-2020 patches 14 - @ref utility_png2asset "png2asset" is the new name for the `png2mtspr` utility 15 - @ref lcc : Changed default output format when not specified from `.ihx` to `.gb` (or other active rom extension) 16 - The `_BSS` area is deprecated (use `_DATA` instead) 17 - The `_BASE` area is renamed to `_HOME` 18 - Variables in static storage are now initialized to zero per C standard (but remaining WRAM is not cleared) 19 - @ref itoa(), @ref uitoa(), @ref ltoa(), @ref ultoa() all now require a radix value (base) argument to be passed. On the Game Boy and Analogue Pocket the parameter is required but not utilized. 20 - set_bkg_1bit_data has been renamed to @ref set_bkg_1bpp_data 21 - The following header files which are now cross platform were moved from `gb/` to `gbdk/`: `bcd.h`, `console.h`, `far_ptr.h`, `font.h`, `gbdecompress.h`, `gbdk-lib.h`, `incbin.h`, `metasprites.h`, `platform.h`, `version.h` 22 - When including them use `#include <gbdk/...>` instead of `#include <gb/>` 23 24## Porting to GBDK 2020 4.0.4 25 - GBDK now requires SDCC 12238 or higher 26 - Made sample.h, cgb.h and sgb.h independent from gb.h 27 28 29## Porting to GBDK 2020 4.0.3 30 - No significant changes required 31 32 33## Porting to GBDK 2020 4.0.2 34 - The default font has been reduced from 256 to 96 characters. 35 - Code using special characters may need to be updated. 36 - The off-by-1 character index offset was removed for fonts. Old fonts with the offset need to be re-adjusted. 37 38 39## Porting to GBDK 2020 4.0.1 40 - __Important!__ : The `WRAM` memory region is no longer automatically initialized to zeros during startup. 41 - Any variables which are declared without being initialized may have __indeterminate values instead of 0__ on startup. This might reveal previously hidden bugs in your code. 42 - Check your code for variables that are not initialized before use. 43 - In BGB you can turn on triggering exceptions (options panel) reading from unitialized RAM. This allows for some additional runtime detection of uninitialized vars. 44 - In .ihx files, multiple writes to the same ROM address are now warned about using @ref ihxcheck. 45 - `set_*_tiles()` now wrap maps around horizontal and vertical boundaries correctly. Code relying on it not wrapping correctly may be affected. 46 47 48## Porting to GBDK 2020 4.0 49 - GBDK now requires SDCC 4.0.3 or higher 50 - The old linker `link-gbz80` has been REMOVED, the linker @ref sdldgb from SDCC is used. 51 - Due to the linker change, there are no longer warnings about multiple writes to the same ROM address. 52 - GBDK now generates .ihx files, those are converted to a ROM using @ref makebin (lcc can do this automatically in some use cases) 53 - Setting ROM bytes directly with `-Wl-yp0x<address>=0x<value>` is no longer supported. Instead use @ref makebin flags. For example, use `-Wm-yC` instead of `-Wl-yp0x143=0xC0`. See @ref faq_gb_type_header_setting. 54 - OAM symbol has been renamed to `_shadow_OAM`, that allows accessing shadow OAM directly from C code 55 56 57## Porting to GBDK 2020 3.2 58 - No significant changes required 59 60## Porting to GBDK 2020 3.1.1 61 - No significant changes required 62 63## Porting to GBDK 2020 3.1 64 - Behavior formerly enabled by USE_SFR_FOR_REG is on by default now (no need to specify it, it isn't a tested `#ifdef` anymore). check here why: 65 https://gbdev.gg8.se/forums/viewtopic.php?id=697 66 67## Porting to GBDK 2020 3.0.1 68 - LCC was upgraded to use SDCC v4.0. Makefile changes may be required 69 - The symbol format changed. To get bgb compatible symbols turn on `.noi` output (LCC argument: `-Wl-j` or `-debug`) and use `-Wm-yS` 70 - ?? Suggested: With LCC argument: `-Wa-l` (sdasgb:`-a All user symbols made global`) 71 - In SDCC 3.6.0, the default for char changed from signed to unsigned. 72 - If you want the old behavior use `--fsigned-char`. 73 - lcc includes `--fsigned-char` by default 74 - Explicit declaration of unsigned vars is encouraged (for example, '15U' instead of '15') 75 - `.init` address has been removed 76 77-------------------------------------------------- 78 79# Historical GBDK versions 80 81## GBDK 1.1 to GBDK 2.0 82 - Change your int variables to long if they have to be bigger than 255. If they should only contain values between 0 and 255, use an unsigned int. 83 - If your application uses the delay function, you'll have to adapt your delay values. 84 - Several functions have new names. In particular some of them have been changed to macros (e.g. show_bkg() is now SHOW_BKG). 85 - You will probably have to change the name of the header files that you include. 86