                  GameBoy Library Guidelines V1.3
                  -------------------------------

  These are meant to be modular, coherent libraries that
 will work together towards a programming project. They
 are specifically geared towards the RGBDS assembler
 package for GameBoy written by Carsten Sorensen.


 file extensions
 ---------------

  *.asm - Files containing assembly code.

          (So far the alternatives to this extension are:

           .z80 - But the GameBoy doesn't really contain a z80.
           .gba - Stands for Game Boy Assembly.
           .gal - Stands for Gameboy Assembly Langauge.

           I'm using .asm because no one has really voiced an
           opinion on this. These other extensions would be more
           clear I'm sure. Possibly no one really has an opinion
           or preference on this from the feedback so far.)

  *.bin - Raw binary include files.
  *.gb  - Final GB rom image code.
  *.inc - Defines or Macros include files.
  *.lnk - Link instructions for linker.
  *.obj - Compiled code before linking.


 subroutine prefixes
 -------------------

   In an attempt to be as modular as possible, the following subroutine
  prefixes are suggested as a means of organizing code and data into
  seperate categories.

  add - addition routines
  bug - debug related code (i.e. bug_DisplayRegisters)
  div - divide routines (i.e. div_HLDE_BC_DE_rBC)
  dly - delay for X seconds or milliseconds
  chr - character set or font (i.e. chr_IBMPC)
  grf - simple graphics (char set or char mem) manipulation (i.e. grf_LineDraw)
  lcd - screen (but not sprite or graphics) related (i.e. lcd_WaitVRAM)
  pad - keypad routines
  pan - map panning routines
  rev - revision macros  (i.e. rev_Check_hardware_inc)
  sio - serial related (short for Serial Input/Output)
  snd - sound related
  spr - sprite related code
  sub - subtraction routines
  tab - data tables
  mem - memory copy, memory set, or bank jump/calls
  mul - multiply routines (i.e. mul_HL_DE_HLDE)
  zip - compression/decompression code


 Math assembly files
 -------------------

   The following file notation & function names were chosen to
  make math file & function names predictable. If you don't
  want to use a 16 char function name as in the first example
  then one of the first lines in your code could be:

    divide equs "DivHLDE_BC_DE_rBCu"

  +--------- Signed or Unsigned
  | +-+-+--- Smallest values to the left
  | | | |+-- Revision (a,b,c,d,etc.)
  | | | ||
  V V V VV
  u161632a.asm  - Unsigned math:

                   MulDE_HL_BCDEu::      <---- function name

                         BCDE = DE * HL

  s080816a.asm  - Signed math:

                   MulB_C_DEs::

                         B * C = DE

  u161632a.asm  - Unsigned math:

                   DivHLDE_DE_BC_rDEu::

                         HLDE / DE = BC, DE = remainder

  u081632a.asm  - Unsigned math:

                   DivHLDE_B_DEu::

                         HLDE / B = DE


 Code Programming & Structure
 ----------------------------

 Compiler commands are usually entered in all upper
case to easily distinguish them from code to be
compiled.

 Defines are usually entered in all upper case to
easily distinguish them from ram variables.

 Code libraries are written, whenever possible, to be
compileable as stand-alone .obj files OR to be included
into existing code. Careful library design usually makes
this possible. It is assumed a code library can be used
either way unless commented otherwise.

 The current code libraries make the following assumptions:

1. All code resides in the section HOME. Code in banks
  is not currently an option with these libraries.

2. The code libraries must be included (if included instead
  of compiled standalone) between sections. The reasoning
  here is that currently code libs have free control over
  changing the section without regard to restoring the
  last section state active before the include operation.


Include defines file structure
------------------------------

 Include define files that are designed to be used with
standalone code or include code will tend to be included
twice or more because of the compile process causing a
compile error. This is why a compile check test is helpful.

  For example, Let's say we have a code file that can be
 compiled and linked with other code. Let's say this file
 accesses hardware as well. We would need to include
 "hardware.inc" somewhere in this standalone code file
 in order for it to compile.

  Let's say we decided to use this standalone code file
 as an include code file for a larger project. If this
 larger project accesses hardware then it's main file
 will include "hardware.inc". It will have to do this
 because it does not and should not assume that an
 include file has already included "hardware.inc".
 If this project includes the standalone code as well
 then due to nesting "hardware.inc" will be included again.
 This will cause a compile error.

  The solution? Add a compiler IF statement to see if
 an include define file has already been included once
 somewhere in the compile process. If so, the IF statement
 will prevent it from occuring any more times. This
 technique is often used in C programming libraries.

  Next it is helpful to warn the user if the define
 include file present is outdated for the software
 currently being compiled. This can be done with a
 "CheckRev" macro. See any include define file for
 an example.
