01_getting_started.md (7200B)
1@page docs_getting_started Getting Started 2 3 4Follow the steps in this section to start using GBDK-2020. 5 6# 1. Download a Release and unzip it 7You can get the latest releases from here: https://github.com/gbdk-2020/gbdk-2020/releases 8 9 10# 2. Compile Example projects 11Make sure your GBDK-2020 installation is working correctly by compiling some of the included @ref docs_example_programs "example projects". 12 13If everything works in the steps below and there are no errors reported then each project that was built should have its own .gb ROM file (or suitable extension for the other supported targets). 14 15## Windows (without Make installed): 16Navigate to a project within the example projects folder (`"examples\gb\"` under your GBDK-2020 install folder) and open a command line. Then type: 17 18 compile 19 20or 21 22 compile.bat 23 24This should build the example project. You can also navigate into other example project folders and build in the same way. 25 26 27## Linux / MacOS / Windows with Make installed: 28Navigate to the example projects folder (`"examples/gb/"` under your GBDK-2020 install folder) and open a command line. Then type: 29 30 make 31 32This should build all of the examples sequentially. You can also navigate into an individual example project's folder and build it by typing `make`. 33 34 35# 3. Use a Template 36__To create a new project use a template!__ 37 38There are template projects included in the @ref docs_example_programs "GBDK example projects" to help you get up and running. Their folder names start with `template_`. 39 401. Copy one of the template folders to a new folder name. 41 422. If you moved the folder out of the GBDK examples then you __must__ update the `GBDK` path variable and/or the path to `LCC` in the `Makefile` or `compile.bat` so that it will still build correctly. 43 443. Type `make` on the command line in that folder to verify it still builds. 45 464. Open main.c to start making changes. 47 48 49# 4. If you use GBTD / GBMB, get the fixed version 50If you plan to use GBTD / GBMB for making graphics, make sure to get the version with the `const` fix and other improvements. See @ref const_gbtd_gbmb. 51 52 53# 5. Review Coding Guidelines 54Take a look at the @ref docs_coding_guidelines "coding guidelines", even if you have experience writing software for other platforms. There is important information to help you get good results and performance on the Game Boy. 55 56If you haven't written programs in C before, check the @ref docs_c_tutorials "C tutorials section". 57 58 59# 6. Hardware and Resources 60If you have a specific project in mind, consider what hardware want to target. It isn't something that has to be decided up front, but it can influence design and implementation. 61 62What size will your game or program be? 63 - 32K Cart (no-MBC required) 64 - Larger than 32K (MBC required) 65 - See more details about @ref docs_rombanking_mbcs "ROM Banking and MBCs" 66 67What console platform(s) will it run on? 68 - Game Boy (GB/GBC) 69 - Analogue Pocket (AP) 70 - Sega Master System (SMS) 71 - Game Gear (GG) 72 - Mega Duck (DUCK) 73 - See @ref docs_supported_consoles 74 75If targeting the Game Boy, what hardware will it run on? 76 - Game Boy (& Game Boy Color) 77 - Game Boy Color only 78 - Game Boy & Super Game Boy 79 - See how to @ref faq_gb_type_header_setting "set the compatibility type in the cartridge header". Read more about hardware differences in the @ref Pandocs 80 81 82# 7. Set up C Source debugging 83Tracking down problems in code is easier with a debugger. Emulicious has a @ref Emulicious_debug "debug adapter" that provides C source debugging with GBDK-2020. 84 85 86# 8. Try a GBDK Tutorial 87You might want to start off with a guided GBDK tutorial from the @ref links_gbdk_tutorials "GBDK Tutorials section". 88 89 - __Note:__ Tutorials (or parts of them) may be based on the older GBDK from the 2000's before it was updated to be GBDK-2020. The general principles are all the same, but the setup and parts of the @ref docs_toolchain "toolchain" (compiler/etc) may be somewhat different and some links may be outdated (pointing to the old GBDK or old tools). 90 91 92# 9. Read up! 93- It is strongly encouraged to read more @ref docs_index "GBDK-2020 General Documentation". 94- Learn about the Game Boy hardware by reading through the @ref Pandocs technical reference. 95 96 97# 10. Need help? 98Check out the links for @ref links_help_and_community "online community and support" and read the @ref docs_faq "FAQ". 99 100 101 102# Migrating From Pre-GBDK-2020 Tutorials 103Several popular GBDK Tutorials, Videos and How-to's were made before GBDK-2020 was available, as a result some information they include is outdated or incompatible. The following summarizes changes that should be made for best results. 104 105## Also see: 106- @ref docs_migrating_versions 107- @ref docs_coding_guidelines 108- @ref docs_getting_started (the section above this) 109 110## Use auto-banking 111GBDK-2020 now supports auto-banking (@ref rom_autobanking). In most cases using auto-banking will be easier and less error prone than manually assigning source and assets to banks. 112- There is a source example `banks_autobank` project. 113 114## Non-standard types (UINT8, etc) 115The old GBDK types `UINT8`, `INT8`, `UINT16`, `INT16` are non-standard and less portable. 116 117The following should be used instead: `uint8_t`, `int16_t`, `uint16_t`, `int32_t`, `uint32_t` and `bool`. 118 119These are standard types defined in `stdint.h` (`#include <stdint.h>`) and `stdbool.h` (`#include <stdbool.h>`). 120 121## If using GBTD / GBMB, get the fixed version 122If you plan to use GBTD / GBMB for making graphics, make sure to get the version with the `const` fix and other improvements. See @ref const_gbtd_gbmb. 123 124## LCC and SDCC flags that are not needed 125The following flag is no longer needed with @ref lcc and @ref sdcc, it can be removed without any loss of performance. 126- `-DUSE_SFR` 127 - 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: https://gbdev.gg8.se/forums/viewtopic.php?id=697 128 129## ROM Header Settings (such as Color, SGB, etc) 130Setting 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. 131 132## GBDK Header include changes 133The 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` 134- When including them use `#include <gbdk/...>` instead of `#include <gb/>` 135 136## Include .h headers, not .c source files 137Do not `#include` `.c` source files into other `.c` source files. Instead create `.h` header files for them and include those. 138- https://www.tutorialspoint.com/cprogramming/c_header_files.htm 139 140## Use the Template Projects 141Modern project templates are included with GBDK-2020. Using them (and their Makefile or compile.bat) as a starting point for projects is recommended and can help ensure better default settings and project organization. 142 143## Use hUGEtracker instead of gbt_player 144hUGEtracker and its driver @ref hUGEdriver are smaller, more efficient and more versatile than gbt_player. 145 146