docs_getting_started.html (14656B)
1<!-- HTML header for doxygen 1.8.14--> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4<head> 5<meta http-equiv="cache-control" content="max-age=86400"/> 6<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> 7<meta http-equiv="X-UA-Compatible" content="IE=9"/> 8<meta name="generator" content="Doxygen 1.8.20"/> 9<meta name="viewport" content="width=device-width, initial-scale=1"/> 10<title>GBDK 2020 Docs: Getting Started</title> 11<link href="tabs.css" rel="stylesheet" type="text/css"/> 12<script type="text/javascript" src="jquery.js"></script> 13<script type="text/javascript" src="dynsections.js"></script> 14<link href="navtree.css" rel="stylesheet" type="text/css"/> 15<script type="text/javascript" src="resize.js"></script> 16<script type="text/javascript" src="navtreedata.js"></script> 17<script type="text/javascript" src="navtree.js"></script> 18<link href="search/search.css" rel="stylesheet" type="text/css"/> 19<script type="text/javascript" src="search/searchdata.js"></script> 20<script type="text/javascript" src="search/search.js"></script> 21<link href="doxygen.css" rel="stylesheet" type="text/css" /> 22<link href="doxygen_extra.css" rel="stylesheet" type="text/css"/> 23</head> 24<body> 25<div id="top"><!-- do not remove this div, it is closed by doxygen! --> 26<div id="titlearea"> 27<table cellspacing="0" cellpadding="0"> 28 <tbody> 29 <tr style="height: 56px;"> 30 <td id="projectalign" style="padding-left: 0.5em;"> 31 <div id="projectname">GBDK 2020 Docs 32  <span id="projectnumber">4.0.6</span> 33 </div> 34 <div id="projectbrief">API Documentation for GBDK 2020</div> 35 </td> 36 </tr> 37 </tbody> 38</table> 39</div> 40<!-- end header part --> 41<!-- Generated by Doxygen 1.8.20 --> 42<script type="text/javascript"> 43/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ 44var searchBox = new SearchBox("searchBox", "search",false,'Search'); 45/* @license-end */ 46</script> 47<script type="text/javascript" src="menudata.js"></script> 48<script type="text/javascript" src="menu.js"></script> 49<script type="text/javascript"> 50/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ 51$(function() { 52 initMenu('',true,false,'search.php','Search'); 53 $(document).ready(function() { init_search(); }); 54}); 55/* @license-end */</script> 56<div id="main-nav"></div> 57</div><!-- top --> 58<div id="side-nav" class="ui-resizable side-nav-resizable"> 59 <div id="nav-tree"> 60 <div id="nav-tree-contents"> 61 <div id="nav-sync" class="sync"></div> 62 </div> 63 </div> 64 <div id="splitbar" style="-moz-user-select:none;" 65 class="ui-resizable-handle"> 66 </div> 67</div> 68<script type="text/javascript"> 69/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ 70$(document).ready(function(){initNavTree('docs_getting_started.html',''); initResizable(); }); 71/* @license-end */ 72</script> 73<div id="doc-content"> 74<!-- window showing the filter options --> 75<div id="MSearchSelectWindow" 76 onmouseover="return searchBox.OnSearchSelectShow()" 77 onmouseout="return searchBox.OnSearchSelectHide()" 78 onkeydown="return searchBox.OnSearchSelectKey(event)"> 79</div> 80 81<!-- iframe showing the search results (closed by default) --> 82<div id="MSearchResultsWindow"> 83<iframe src="javascript:void(0)" frameborder="0" 84 name="MSearchResults" id="MSearchResults"> 85</iframe> 86</div> 87 88<div class="PageDoc"><div class="header"> 89 <div class="headertitle"> 90<div class="title">Getting Started </div> </div> 91</div><!--header--> 92<div class="contents"> 93<div class="textblock"><p>Follow the steps in this section to start using GBDK-2020.</p> 94<h1><a class="anchor" id="autotoc_md6"></a> 951. Download a Release and unzip it</h1> 96<p>You can get the latest releases from here: <a href="https://github.com/gbdk-2020/gbdk-2020/releases">https://github.com/gbdk-2020/gbdk-2020/releases</a></p> 97<h1><a class="anchor" id="autotoc_md7"></a> 982. Compile Example projects</h1> 99<p>Make sure your GBDK-2020 installation is working correctly by compiling some of the included <a class="el" href="docs_example_programs.html">example projects</a>.</p> 100<p>If everything in works in the steps below and there are no errors reported then each project that was build should have it's on .gb ROM file (or suitable extension for the other supported targets).</p> 101<h2><a class="anchor" id="autotoc_md8"></a> 102Windows (without Make installed):</h2> 103<p>Navigate to a project within the example projects folder (<code>"examples\gb\"</code> under your GBDK-2020 install folder) and open a command line. Then type: </p><pre class="fragment">compile 104</pre><p>or </p><pre class="fragment">compile.bat 105</pre><p>This should build the example project. You can also navigate into other example project folders and build in the same way.</p> 106<h2><a class="anchor" id="autotoc_md9"></a> 107Linux / MacOS / Windows with Make installed:</h2> 108<p>Navigate to the example projects folder (<code>"examples/gb/"</code> under your GBDK-2020 install folder) and open a command line. Then type: </p><pre class="fragment">make 109</pre><p>This should build all of the examples sequentially. You can also navigate into an individual example project's folder and build it by typing <code>make</code>.</p> 110<h1><a class="anchor" id="autotoc_md10"></a> 1113. Use a Template</h1> 112<p><b>To create a new project use a template!</b></p> 113<p>There are template projects included in the <a class="el" href="docs_example_programs.html">GBDK example projects</a> to help you get up and running. Their folder names start with <code>template_</code>.</p> 114<ol type="1"> 115<li>Copy one of the template folders to a new folder name</li> 116<li>If you moved the folder out of the GBDK examples then you <b>must</b> update the <code>GBDK</code> path variable and/or the path to <code>LCC</code> in the <code>Makefile</code> or <code>compile.bat</code> so that it will still build correctly.</li> 117<li>Type <code>make</code> on the command line in that folder to verify it still builds.</li> 118<li>Open main.c to start making changes.</li> 119</ol> 120<h1><a class="anchor" id="autotoc_md11"></a> 1214. If you use GBTD / GBMB, get the fixed version</h1> 122<p>If you plan to use GBTD / GBMB for making graphics, make sure to get the version with the <code>const</code> fix and other improvements. See <a class="el" href="docs_coding_guidelines.html#const_gbtd_gbmb">const_gbtd_gbmb</a>.</p> 123<h1><a class="anchor" id="autotoc_md12"></a> 1245. Review Coding Guidelines</h1> 125<p>Take a look at the <a class="el" href="docs_coding_guidelines.html">coding guidelines</a>, 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.</p> 126<p>If you haven't written programs in C before, check the <a class="el" href="docs_coding_guidelines.html#docs_c_tutorials">C tutorials section</a>.</p> 127<h1><a class="anchor" id="autotoc_md13"></a> 1286. Hardware and Resources</h1> 129<p>If 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.</p> 130<p>What size will your game or program be?</p><ul> 131<li>32K Cart (no-MBC required)</li> 132<li>Larger than 32K (MBC required)</li> 133<li>See more details about <a class="el" href="docs_rombanking_mbcs.html">ROM Banking and MBCs</a>.</li> 134</ul> 135<p>What console platform(s) will it run on?</p><ul> 136<li>Game Boy (GB/GBC)</li> 137<li>Analogue Pocket (AP)</li> 138<li>Sega Master System (SMS)</li> 139<li>Game Gear (GG)</li> 140<li>Mega Duck (DUCK)</li> 141<li>See <a class="el" href="docs_supported_consoles.html">Supported Consoles & Cross Compiling</a></li> 142</ul> 143<p>If targeting the Game Boy, what hardware will it run on?</p><ul> 144<li>Game Boy (& Game Boy Color)</li> 145<li>Game Boy Color only</li> 146<li>Game Boy & Super Game Boy</li> 147<li>See how to <a class="el" href="docs_faq.html#faq_gb_type_header_setting">set the compatibility type in the cartridge header</a>. Read more about hardware differences in the <a class="el" href="docs_links_and_tools.html#Pandocs">Pandocs</a></li> 148</ul> 149<h1><a class="anchor" id="autotoc_md14"></a> 1507. Set up C Source debugging</h1> 151<p>Tracking down problems in code is easier with a debugger. Emulicious has a <a class="el" href="docs_links_and_tools.html#Emulicious_debug">debug adapter</a> that provides C source debugging with GBDK-2020.</p> 152<h1><a class="anchor" id="autotoc_md15"></a> 1538. Try a GBDK Tutorial</h1> 154<p>You might want to start off with a guided GBDK tutorial from the <a class="el" href="docs_links_and_tools.html#links_gbdk_tutorials">GBDK Tutorials section</a>.</p> 155<ul> 156<li><b>Note:</b> 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 principals are all the same, but the setup and parts of the <a class="el" href="docs_toolchain.html">toolchain</a> (compiler/etc) may be somewhat different and some links may be outdated (pointing to the old GBDK or old tools).</li> 157</ul> 158<h1><a class="anchor" id="autotoc_md16"></a> 1599. Read up!</h1> 160<ul> 161<li>It is strongly encouraged to read more <a class="el" href="index.html#docs_index">GBDK-2020 General Documentation</a>.</li> 162<li>Learn about the Game Boy hardware by reading through the <a class="el" href="docs_links_and_tools.html#Pandocs">Pandocs</a> technical reference.</li> 163</ul> 164<h1><a class="anchor" id="autotoc_md17"></a> 16510. Need help?</h1> 166<p>Check out the links for <a class="el" href="docs_links_and_tools.html#links_help_and_community">online community and support</a> and read the <a class="el" href="docs_faq.html">FAQ</a>.</p> 167<h1><a class="anchor" id="autotoc_md18"></a> 168Migrating From Pre-GBDK-2020 Tutorials</h1> 169<p>Several 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.</p> 170<h2><a class="anchor" id="autotoc_md19"></a> 171Also see:</h2> 172<ul> 173<li><a class="el" href="docs_migrating_versions.html">Migrating to new GBDK Versions</a></li> 174<li><a class="el" href="docs_coding_guidelines.html">Coding Guidelines</a></li> 175<li><a class="el" href="docs_getting_started.html">Getting Started</a> (the section above this)</li> 176</ul> 177<h2><a class="anchor" id="autotoc_md20"></a> 178Use auto-banking</h2> 179<p>GBDK-2020 now supports auto-banking (<a class="el" href="docs_rombanking_mbcs.html#rom_autobanking">rom_autobanking</a>). In most cases using auto-banking will be easier and less error prone than manually assigning source and assets to banks.</p><ul> 180<li>There is a source example <code>banks_autobank</code> project.</li> 181</ul> 182<h2><a class="anchor" id="autotoc_md21"></a> 183Non-standard types (UINT8, etc)</h2> 184<p>The old GBDK types <code>UINT8</code>, <code>INT8</code>, <code>UINT16</code>, <code>INT16</code> are non-standard and less portable.</p> 185<p>The following should be used instead: <code>uint8_t</code>, <code>int16_t</code>, <code>uint16_t</code>, <code>int32_t</code>, <code>uint32_t</code> and <code>bool</code>.</p> 186<p>These are standard types defined in <code>stdint.h</code> (<code>#include <stdint.h></code>) and <code>stdbool.h</code> (<code>#include <stdbool.h></code>).</p> 187<h2><a class="anchor" id="autotoc_md22"></a> 188If using GBTD / GBMB, get the fixed version</h2> 189<p>If you plan to use GBTD / GBMB for making graphics, make sure to get the version with the <code>const</code> fix and other improvements. See <a class="el" href="docs_coding_guidelines.html#const_gbtd_gbmb">const_gbtd_gbmb</a>.</p> 190<h2><a class="anchor" id="autotoc_md23"></a> 191LCC and SDCC flags that are not needed</h2> 192<p>The following flag is no longer needed with <a class="el" href="docs_toolchain.html#lcc">lcc</a> and <a class="el" href="docs_toolchain.html#sdcc">sdcc</a>, it can be removed without any loss of performance.</p><ul> 193<li><code>-DUSE_SFR</code><ul> 194<li>Behavior formerly enabled by USE_SFR_FOR_REG is on by default now (no need to specify it, it isn't a tested <code>#ifdef</code> anymore). check here why: <a href="https://gbdev.gg8.se/forums/viewtopic.php?id=697">https://gbdev.gg8.se/forums/viewtopic.php?id=697</a></li> 195</ul> 196</li> 197</ul> 198<h2><a class="anchor" id="autotoc_md24"></a> 199ROM Header Settings (such as Color, SGB, etc)</h2> 200<p>Setting ROM bytes directly with <code>-Wl-yp0x<address>=0x<value></code> is no longer supported. Instead use <a class="el" href="docs_toolchain.html#makebin">makebin</a> flags. For example, use <code>-Wm-yC</code> instead of <code>-Wl-yp0x143=0xC0</code>. See <a class="el" href="docs_faq.html#faq_gb_type_header_setting">faq_gb_type_header_setting</a>.</p> 201<h2><a class="anchor" id="autotoc_md25"></a> 202GBDK Header include changes</h2> 203<p>The following header files which are now cross platform were moved from <code>gb/</code> to <code>gbdk/</code>: <code>bcd.h</code>, <code>console.h</code>, <code>far_ptr.h</code>, <code>font.h</code>, <code>gbdecompress.h</code>, <code>gbdk-lib.h</code>, <code>incbin.h</code>, <code>metasprites.h</code>, <code>platform.h</code>, <code>version.h</code></p><ul> 204<li>When including them use <code>#include <gbdk/...></code> instead of <code>#include <gb/></code></li> 205</ul> 206<h2><a class="anchor" id="autotoc_md26"></a> 207Include .h headers, not .c source files</h2> 208<p>Do not <code>#include</code> <code>.c</code> source files into other <code>.c</code> source files. Instead create <code>.h</code> header files for them and include those.</p><ul> 209<li><a href="https://www.tutorialspoint.com/cprogramming/c_header_files.htm">https://www.tutorialspoint.com/cprogramming/c_header_files.htm</a></li> 210</ul> 211<h2><a class="anchor" id="autotoc_md27"></a> 212Use the Template Projects</h2> 213<p>Modern 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.</p> 214<h2><a class="anchor" id="autotoc_md28"></a> 215Use hUGEtracker instead of gbt_player</h2> 216<p>hUGEtracker and it's driver <a class="el" href="docs_links_and_tools.html#hUGEdriver">hUGEdriver</a> are smaller, more efficient and more versatile than gbt_player. </p> 217</div></div><!-- contents --> 218</div><!-- PageDoc --> 219</div><!-- doc-content --> 220<!-- HTML footer for doxygen 1.8.14--> 221<!-- start footer part --> 222<div id="nav-path" class="navpath"><!-- id is needed for treeview function! --> 223</div> 224</body> 225</html>