Symbol interpolation

Symbol interpolations can be nested, too!

DEF topic EQUS "life, the universe, and \"everything\""
DEF meaning EQUS "answer"
; Defines answer = 42
DEF {meaning} = 42
; Prints "The answer to life, the universe, and "everything" is $2A"
PRINTLN "The {meaning} to {topic} is {{meaning}}"
PURGE topic, meaning, {meaning}

Symbols can be interpolated even in the contexts that disable automatic expansion of string constants: ‘name’ will be expanded in all of ‘DEF({name})’, ‘DEF {name} EQU/=/EQUS/etc ...’, ‘PURGE {name}’, and ‘MACRO {name}’, but, for example, won't be in ‘DEF(name)’.

It's possible to change the way symbols are printed by specifying a print format like so: ‘{fmt:symbol}’. The ‘fmt’ specifier consists of these parts: ‘<sign><prefix><align><pad><width><frac><type>’. These parts are:

All the format specifier parts are optional except the ‘<type>’. Valid print types are:

Examples:

SECTION "Test", ROM0[2]
X:             ; This works with labels **whose address is known**
Y = 3          ; This also works with variables
SUM equ X + Y  ; And likewise with numeric constants
; Prints "%0010 + $3 == 5"
PRINTLN "{#05b:X} + {#x:Y} == {d:SUM}"

rsset 32
PERCENT rb 1   ; Same with offset constants
VALUE = 20
RESULT = MUL(20.0, 0.32)
; Prints "32% of 20 = 6.40"
PRINTLN "{d:PERCENT}% of {d:VALUE} = {f:RESULT}"

WHO equs STRLWR("WORLD")
; Prints "Hello world!"
PRINTLN "Hello {s:WHO}!"

Although, for these examples, STRFMT would be more approriate; see String expressions further below.

Numeric formats

Underscores are also accepted in numbers, except at the beginning of one. This can be useful for grouping digits, like ‘123_456’ or ‘%1100_1001’.

The "character constant" form yields the value the character maps to in the current charmap. For example, by default (refer to ascii(7)) ‘"A"’ yields 65. See Character maps for information on charmaps.

The last one, Gameboy graphics, is quite interesting and useful. After the backtick, 8 digits between 0 and 3 are expected, corresponding to pixel values. The resulting value is the two bytes of tile data that would produce that row of pixels. For example, ‘`01012323’ is equivalent to ‘$0F55’.

You can also use symbols, which are implicitly replaced with their value.

Operators

~ complements a value by inverting all its bits.

% is used to get the remainder of the corresponding division, so that ‘a / b * b + a % b == a’ is always true. The result has the same sign as the divisor. This makes ‘a % b’. equal to ‘(a + b) % b’ or ‘(a - b) % b’.

Shifting works by shifting all bits in the left operand either left (‘<<’) or right (‘>>’) by the right operand's amount. When shifting left, all newly-inserted bits are reset; when shifting right, they are copies of the original most significant bit instead. This makes ‘a << b’ and ‘a >> b’ equivalent to multiplying and dividing by 2 to the power of b, respectively.

Comparison operators return 0 if the comparison is false, and 1 otherwise.

Unlike in a lot of languages, and for technical reasons, rgbasm still evaluates both operands of ‘&&’ and ‘||’.

! returns 1 if the operand was 0, and 0 otherwise.

Fixed-point expressions

The following functions are designed to operate with fixed-point numbers:

The trigonometry functions ( SIN, COS, TAN, etc) are defined in terms of a circle divided into 65535.0 degrees.

These functions are useful for automatic generation of various tables. For example:

; Generate a 256-byte sine table with values in the range [0, 128]
; (shifted and scaled from the range [-1.0, 1.0])
ANGLE = 0.0
    REPT 256
        db (MUL(64.0, SIN(ANGLE)) + 64.0) >> 16
ANGLE = ANGLE + 256.0 ; 256.0 = 65536 degrees / 256 entries
    ENDR

String expressions

Multi-line strings are contained in triple quotes (‘"""for instance"""’). Escape sequences work the same way in multi-line strings; however, literal newline characters will be included as-is, without needing to escape them with ‘\r’ or ‘\n’.

The following functions operate on string expressions. Most of them return a string, however some of these functions actually return an integer and can be used as part of an integer expression!

Character maps

Character maps allow mapping strings to arbitrary 8-bit values:

CHARMAP "<LF>", 10
CHARMAP "&iacute", 20
CHARMAP "A", 128

Any characters in a string without defined mappings will be copied directly, using the source file's encoding of characters to bytes.

It is possible to create multiple character maps and then switch between them as desired. This can be used to encode debug information in ASCII and use a different encoding for other purposes, for example. Initially, there is one character map called ‘main’ and it is automatically selected as the current character map from the beginning. There is also a character map stack that can be used to save and restore which character map is currently active.

Note: Modifications to a character map take effect immediately from that point onward.

Other functions

Section stack

PUSHS will push the current section context on the section stack. POPS can then later be used to restore it. Useful for defining sections in included files when you don't want to override the section context at the point the file was included.

RAM code

This means the code (or data) will not be stored in the place it gets executed. Luckily, LOAD blocks are the perfect solution to that. Here's an example of how to use them:

SECTION "LOAD example", ROMX
CopyCode:
    ld de, RAMCode
    ld hl, RAMLocation
    ld c, RAMLocation.end - RAMLocation
.loop
    ld a, [de]
    inc de
    ld [hli], a
    dec c
    jr nz, .loop
    ret

RAMCode:
  LOAD "RAM code", WRAM0
RAMLocation:
    ld hl, .string
    ld de, $9864
.copy
    ld a, [hli]
    ld [de], a
    inc de
    and a
    jr nz, .copy
    ret

.string
    db "Hello World!", 0
.end
  ENDL

A LOAD block feels similar to a SECTION declaration because it creates a new one. All data and code generated within such a block is placed in the current section like usual, but all labels are created as if they were placed in this newly-created section.

In the example above, all of the code and data will end up in the "LOAD example" section. You will notice the ‘RAMCode’ and ‘RAMLocation’ labels. The former is situated in ROM, where the code is stored, the latter in RAM, where the code will be loaded.

You cannot nest LOAD blocks, nor can you change the current section within them.

LOAD blocks can use the UNION or FRAGMENT modifiers, as described below.

Unionized sections

• The same unionized section (i.e. having the same name) can be declared several times per rgbasm invocation, and across several invocations. Different declarations are treated and merged identically whether within the same invocation, or different ones.
• If one section has been declared as unionized, all sections with the same name must be declared unionized as well.
• All declarations must have the same type. For example, even if rgblink(1)'s -w flag is used, WRAM0 and WRAMX types are still considered different.
• Different constraints (alignment, bank, etc.) can be specified for each unionized section declaration, but they must all be compatible. For example, alignment must be compatible with any fixed address, all specified banks must be the same, etc.
• Unionized sections cannot have type ROM0 or ROMX.

Different declarations of the same unionized section are not appended, but instead overlaid on top of eachother, just like Unions. Similarly, the size of an unionized section is the largest of all its declarations.

Section fragments

• If one section has been declared as fragment, all sections with the same name must be declared fragments as well.
• All declarations must have the same type. For example, even if rgblink(1)'s -w flag is used, WRAM0 and WRAMX types are still considered different.
• Different constraints (alignment, bank, etc.) can be specified for each unionized section declaration, but they must all be compatible. For example, alignment must be compatible with any fixed address, all specified banks must be the same, etc.
• A section fragment may not be unionized; after all, that wouldn't make much sense.

When RGBASM merges two fragments, the one encountered later is appended to the one encountered earlier.

When RGBLINK merges two fragments, the one whose file was specified last is appended to the one whose file was specified first. For example, assuming ‘bar.o’, ‘baz.o’, and ‘foo.o’ all contain a fragment with the same name, the command

Labels

A label is defined by writing its name at the beginning of a line, followed by one or two colons, without any whitespace between the label name and the colon(s). Declaring a label (global or local) with two colons ‘::’ will define and EXPORT it at the same time. (See Exporting and importing symbols below). When defining a local label, the colon can be omitted, and rgbasm will act as if there was only one.

A label is said to be local if its name contains a dot ‘.’; otherwise, it is said to be global (not to be mistaken with “exported”, explained in Exporting and importing symbols further below). More than one dot in label names is not allowed.

For convenience, local labels can use a shorthand syntax: when a symbol name starting with a dot is found (for example, inside an expression, or when declaring a label), then the current “label scope” is implicitly prepended.

Defining a global label sets it as the current “label scope”, until the next global label definition, or the end of the current section.

Here are some examples of label definitions:

GlobalLabel:
AnotherGlobal:
.locallabel ; This defines "AnotherGlobal.locallabel"
.another_local:
AnotherGlobal.with_another_local:
ThisWillBeExported:: ; Note the two colons
ThisWillBeExported.too::

In a numeric expression, a label evaluates to its address in memory. (To obtain its bank, use the ‘BANK()’ function described in Other functions). For example, given the following, ‘ld de, vPlayerTiles’ would be equivalent to ‘ld de, $80C0’ assuming the section ends up at $80C0:

SECTION "Player tiles", VRAM
PlayerTiles:
    ds 6 * 16

A label's location (and thus value) is usually not determined until the linking stage, so labels usually cannot be used as constants. However, if the section in which the label is defined has a fixed base address, its value is known at assembly time.

Also, while rgbasm obviously can compute the difference between two labels if both are constant, it is also able to compute the difference between two non-constant labels if they both belong to the same section, such as ‘PlayerTiles’ and ‘PlayerTiles.end’ above.

Anonymous labels

Anonymous labels are referenced using a colon ‘:’ followed by pluses ‘+’ or minuses ‘-’. Thus :+ references the next one after the expression, :++ the one after that; :- references the one before the expression; and so on.

    ld hl, :++
:   ld a, [hli] ; referenced by "jr nz"
    ldh [c], a
    dec c
    jr nz, :-
    ret

:   ; referenced by "ld hl"
    dw $7FFF, $1061, $03E0, $58A5

Variables

DEF ARRAY_SIZE EQU 4
DEF COUNT = 2
DEF COUNT = 3
DEF COUNT = ARRAY_SIZE + COUNT
COUNT = COUNT*2
; COUNT now has the value 14

Note that colons ‘:’ following the name are not allowed.

Variables can be conveniently redefined by compound assignment operators like in C:

Examples:

DEF x = 10
DEF x += 1    ; x == 11
DEF y = x - 1 ; y == 10
DEF y *= 2    ; y == 20
DEF y >>= 1   ; y == 10
DEF x ^= y    ; x == 1

Numeric constants

def SCREEN_WIDTH  equ 160 ; In pixels
def SCREEN_HEIGHT equ 144

Note that colons ‘:’ following the name are not allowed.

If you really need to, the REDEF keyword will define or redefine a numeric constant symbol. (It can also be used for variables, although it's not necessary since they are mutable.) This can be used, for example, to update a constant using a macro, without making it mutable in general.

    def NUM_ITEMS equ 0
MACRO add_item
    redef NUM_ITEMS equ NUM_ITEMS + 1
    def ITEM_{02x:NUM_ITEMS} equ \1
ENDM
    add_item 1
    add_item 4
    add_item 9
    add_item 16
    assert NUM_ITEMS == 4
    assert ITEM_04 == 16

Offset constants

               RSRESET
DEF str_pStuff RW   1
DEF str_tData  RB   256
DEF str_bCount RB   1
DEF str_SIZEOF RB   0

The example defines four constants as if by:

DEF str_pStuff EQU 0
DEF str_tData  EQU 2
DEF str_bCount EQU 258
DEF str_SIZEOF EQU 259

There are five commands in the RS group of commands:

If the argument to RB, RW, or RL is omitted, it's assumed to be 1.

Note that colons ‘:’ following the name are not allowed.

String constants

DEF COUNTREG EQUS "[hl+]"
    ld a,COUNTREG

DEF PLAYER_NAME EQUS "\"John\""
    db PLAYER_NAME

This will be interpreted as:

    ld a,[hl+]
    db "John"

String constants can also be used to define small one-line macros:

DEF pusha EQUS "push af\npush bc\npush de\npush hl\n"

Note that colons ‘:’ following the name are not allowed.

String constants can't be exported or imported.

String constants, like numeric constants, cannot be redefined. However, the REDEF keyword will define or redefine a string constant symbol. For example:

DEF s EQUS "Hello, "
REDEF s EQUS "{s}world!"
; prints "Hello, world!"
PRINTLN "{s}0

Important note: When a string constant is expanded, its expansion may contain another string constant, which will be expanded as well. If this creates an infinite loop, rgbasm will error out once a certain depth is reached. See the -r command-line option in rgbasm(1). The same problem can occur if the expansion of a macro invokes another macro, recursively.

The examples above for ‘EQU’, ‘=’, ‘RB’, ‘RW’, ‘RL’, and ‘EQUS’ all start with ‘DEF’. (A variable definition may start with ‘REDEF’ instead, since they are redefinable.) You may use the older syntax without ‘DEF’, but then the name being defined must not have any whitespace before it; otherwise rgbasm will treat it as a macro invocation. Furthermore, without the ‘DEF’ keyword, string constants may be expanded for the name. This can lead to surprising results:

X EQUS "Y"
; this defines Y, not X!
X EQU 42
; prints "Y $2A"
PRINTLN "{X} {Y}"

Macros

MACRO MyMacro
         ld a, 80
         call MyFunc
ENDM

The example above defines ‘MyMacro’ as a new macro. String constants are not expanded within the name of the macro. You may use the older syntax ‘MyMacro: MACRO’ instead of ‘MACRO MyMacro’, with a single colon ‘:’ following the macro's name. With the older syntax, string constants may be expanded for the name.

Macros can't be exported or imported.

Plainly nesting macro definitions is not allowed, but this can be worked around using EQUS. So this won't work:

MACRO outer
    MACRO inner
        PRINTLN "Hello!"
    ENDM
ENDM

But this will:

MACRO outer
DEF definition EQUS "MACRO inner\nPRINTLN \"Hello!\"\nENDM"
    definition
    PURGE definition
ENDM

Macro arguments support all the escape sequences of strings, as well as ‘\,’ to escape commas, as well as ‘\(’ and ‘\)’ to escape parentheses, since those otherwise separate and enclose arguments, respectively.

Exporting and importing symbols

Exporting of symbols has to be done manually, importing is done automatically if rgbasm finds a symbol it does not know about.

The following will cause symbol1, symbol2 and so on to be accessible to other files during the link process:

For example, if you have the following three files:

‘a.asm’:

SECTION "a", WRAM0
LabelA:

‘b.asm’:

SECTION "b", WRAM0
ExportedLabelB1::
ExportedLabelB2:
	EXPORT ExportedLabelB2

‘c.asm’:

SECTION "C", ROM0[0]
	dw LabelA
	dw ExportedLabelB1
	dw ExportedLabelB2

Then ‘c.asm’ can use ‘ExportedLabelB1’ and ‘ExportedLabelB2’, but not ‘LabelA’, so linking them together will fail:

$ rgbasm -o a.o a.asm
$ rgbasm -o b.o b.asm
$ rgbasm -o c.o c.asm
$ rgblink a.o b.o c.o
error: c.asm(2): Unknown symbol "LabelA"
Linking failed with 1 error

Note also that only exported symbols will appear in symbol and map files produced by rgblink(1).

Purging symbols

DEF Kamikaze EQUS  "I don't want to live anymore"
DEF AOLer    EQUS  "Me too"
         PURGE Kamikaze, AOLer

String constants are not expanded within the symbol names.

Predeclared symbols

The current time values will be taken from the SOURCE_DATE_EPOCH environment variable if that is defined as a UNIX timestamp. Refer to the spec at https://reproducible-builds.org/docs/source-date-epoch/.

Statically allocating space in RAM

DS 42 ; Allocates 42 bytes

Empty space in RAM sections will not be initialized. In ROM sections, it will be filled with the value passed to the -p command-line option, except when using overlays with -O.

Defining constant data in ROM

DB 1,2,3,4,"This is a string"

Alternatively, you can use DW to store a list of words (16-bit) or DL to store a list of double-words/longs (32-bit).

Strings are handled a little specially: they first undergo charmap conversion (see Character maps), then each resulting character is output individually. For example, under the default charmap, the following two lines are identical:

DW "Hello!"
DW "H", "e", "l", "l", "o", "!"

If you do not want this special handling, enclose the string in parentheses.

DS can also be used to fill a region of memory with some repeated values. For example:

; outputs 3 bytes: $AA, $AA, $AA
DS 3, $AA
; outputs 7 bytes: $BB, $CC, $BB, $CC, $BB, $CC, $BB
DS 7, $BB, $CC

You can also use DB, DW and DL without arguments. This works exactly like DS 1, DS 2 and DS 4 respectively. Consequently, no-argument DB, DW and DL can be used in a WRAM0 / WRAMX / HRAM / VRAM / SRAM section.

Including binary files

INCBIN "titlepic.bin"
INCBIN "sprites/hero.bin"

You can also include only part of a file with INCBIN. The example below includes 256 bytes from data.bin, starting from byte 78.

INCBIN "data.bin",78,256

The length argument is optional. If only the start position is specified, the bytes from the start position until the end of the file will be included.

Unions

A union starts with a UNION keyword, and ends at the corresponding ENDU keyword. NEXTU separates each block of allocations, and you may use it as many times within a union as necessary.

    ; Let's say PC = $C0DE here
    UNION
    ; Here, PC = $C0DE
Name: ds 8
    ; PC = $C0E6
Nickname: ds 8
    ; PC = $C0EE
    NEXTU
    ; PC is back to $C0DE
Health: dw
    ; PC = $C0E0
Something: ds 6
    ; And so on
Lives: db
    NEXTU
VideoBuffer: ds 19
    ENDU

In the example above, ‘Name, Health, VideoBuffer’ all have the same value, as do ‘Nickname’ and ‘Lives’. Thus, keep in mind that ld [Health], a is identical to ld [Name], a.

The size of this union is 19 bytes, as this is the size of the largest block (the last one, containing ‘VideoBuffer’). Nesting unions is possible, with each inner union's size being considered as described above.

Unions may be used in any section, but inside them may only be DS - like commands (see Statically allocating space in RAM).

Invoking macros

         add a,b
         ld sp,hl
         MyMacro ; This will be expanded
         sub a,87

It's valid to call a macro from a macro (yes, even the same one).

When rgbasm sees MyMacro it will insert the macro definition (the code enclosed in MACRO / ENDM).

Suppose your macro contains a loop.

MACRO LoopyMacro
            xor  a,a
.loop       ld   [hl+],a
            dec  c
            jr   nz,.loop
ENDM

This is fine, but only if you use the macro no more than once per scope. To get around this problem, there is the escape sequence \@ that expands to a unique string.

\@ also works in REPT blocks.

MACRO LoopyMacro
            xor  a,a
.loop\@     ld   [hl+],a
            dec  c
            jr   nz,.loop\@
ENDM

Important note: Since a macro can call itself (or a different macro that calls the first one), there can be circular dependency problems. If this creates an infinite loop, rgbasm will error out once a certain depth is reached. See the -r command-line option in rgbasm(1). Also, a macro can have inside an EQUS which references the same macro, which has the same problem.

It's possible to pass arguments to macros as well! You retrieve the arguments by using the escape sequences \1 through \9, \1 being the first argument specified on the macro invocation.

MACRO LoopyMacro
            ld   hl,\1
            ld   c,\2
            xor  a,a
.loop\@     ld   [hl+],a
            dec  c
            jr   nz,.loop\@
            ENDM

Now you can call the macro specifying two arguments, the first being the address and the second being a byte count. The generated code will then reset all bytes in this range.

LoopyMacro MyVars,54

Arguments are passed as string constants, although there's no need to enclose them in quotes. Thus, an expression will not be evaluated first but kind of copy-pasted. This means that it's probably a very good idea to use brackets around \1 to \9 if you perform further calculations on them. For instance, consider the following:

MACRO print_double
    PRINTLN \1 * 2
ENDM
    print_double 1 + 2

The PRINTLN statement will expand to ‘PRINTLN 1 + 2 * 2’, which will print 5 and not 6 as you might have expected.

Line continuations work as usual inside macros or lists of macro arguments. However, some characters need to be escaped, as in the following example:

MACRO PrintMacro1
    PRINTLN STRCAT(\1)
ENDM
    PrintMacro1 "Hello "\, \
                       "world"
MACRO PrintMacro2
    PRINT \1
ENDM
    PrintMacro2 STRCAT("Hello ", \
                       "world\n")

The comma in ‘PrintMacro1’ needs to be escaped to prevent it from starting another macro argument. The comma in ‘PrintMacro2’ does not need escaping because it is inside parentheses, similar to macro arguments in C. The backslash in ‘\n’ also does not need escaping because string literals work as usual inside macro arguments.

Since there are only nine digits, you can only access the first nine macro arguments like this. To use the rest, you need to put the multi-digit argument number in angle brackets, like ‘\<10>’. This bracketed syntax supports decimal numbers and numeric constant symbols. For example, ‘\<_NARG>’ will get the last argument.

Other macro arguments and symbol interpolations will be expanded inside the angle brackets. For example, if ‘\1’ is ‘13’, then ‘\<\1>’ will expand to ‘\<13>’. Or if ‘v10 = 42’ and ‘x = 10’, then ‘\<v{d:x}>’ will expand to ‘\<42>’.

Another way to access more than nine macro arguments is the SHIFT command, a special command only available in macros. It will shift the arguments by one to the left, and decrease _NARG by 1. \1 will get the value of \2, \2 will get the value of \3, and so forth.

SHIFT can optionally be given an integer parameter, and will apply the above shifting that number of times. A negative parameter will shift the arguments in reverse.

SHIFT is useful in REPT blocks to repeat the same commands with multiple arguments.

Printing things during assembly

PRINT "Hello world!\n"
PRINTLN "Hello world!"
PRINT _NARG, " arguments\n"
PRINTLN "sum: ", 2+3, " product: ", 2*3
PRINTLN "Line #", __LINE__
PRINTLN STRFMT("E = %f", 2.718)

PRINT

prints out each of its comma-separated arguments. Numbers are printed as unsigned uppercase hexadecimal with a leading $. For different formats, use STRFMT.

PRINTLN

prints out each of its comma-separated arguments, if any, followed by a line feed (‘\n’).

Automatically repeating blocks of code

REPT 4
  add  a,c
ENDR

You can also use REPT to generate tables on the fly:

; Generate a 256-byte sine table with values in the range [0, 128]
; (shifted and scaled from the range [-1.0, 1.0])
ANGLE = 0.0
    REPT 256
        db (MUL(64.0, SIN(ANGLE)) + 64.0) >> 16
ANGLE = ANGLE + 256.0 ; 256.0 = 65536 degrees / 256 entries
    ENDR

As in macros, you can also use the escape sequence \@. REPT blocks can be nested.

A common pattern is to repeat a block for each value in some range. FOR is simpler than REPT for that purpose. Everything between FOR and the matching ENDR will be repeated for each value of a given symbol. String constants are not expanded within the symbol name. For example, this code will produce a table of squared values from 0 to 255:

FOR N, 256
      dw N * N
ENDR

It acts just as if you had done:

N = 0
      dw N * N
N = 1
      dw N * N
N = 2
      dw N * N
; ...
N = 255
      dw N * N
N = 256

You can customize the range of FOR values, similarly to Python's ‘range’ function:

The FOR value will be updated by step until it reaches or exceeds stop. For example:

FOR V, 4, 25, 5
      PRINT "{d:V} "
ENDR
      PRINTLN "done {d:V}"

This will print:

4 9 14 19 24 done 29

Just like with REPT blocks, you can use the escape sequence \@ inside of FOR blocks, and they can be nested.

You can stop a repeating block with the BREAK command. A BREAK inside of a REPT or FOR block will interrupt the current iteration and not repeat any more. It will continue running code after the block's ENDR. For example:

FOR V, 1, 100
      PRINT "{d:V}"
      IF V == 5
          PRINT " stop! "
          BREAK
      ENDC
      PRINT ", "
ENDR
      PRINTLN "done {d:V}"

This will print:

1, 2, 3, 4, 5 stop! done 5

Aborting the assembly process

FAIL stops assembling immediately while WARN shows the message but continues afterwards.

If you need to ensure some assumption is correct when compiling, you can use ASSERT and STATIC_ASSERT. Syntax examples are given below:

Function:
      xor a
ASSERT LOW(MyByte) == 0
      ld h, HIGH(MyByte)
      ld l, a
      ld a, [hli]
; You can also indent this!
      ASSERT BANK(OtherFunction) == BANK(Function)
      call OtherFunction
; Lowercase also works
      ld hl, FirstByte
      ld a, [hli]
assert FirstByte + 1 == SecondByte
      ld b, [hl]
      ret
.end
      ; If you specify one, a message will be printed
      STATIC_ASSERT .end - Function < 256, "Function is too large!"

First, the difference between ASSERT and STATIC_ASSERT is that the former is evaluated by RGBASM if it can, otherwise by RGBLINK; but the latter is only ever evaluated by RGBASM. If RGBASM cannot compute the value of the argument to STATIC_ASSERT, it will produce an error.

Second, as shown above, a string can be optionally added at the end, to give insight into what the assertion is checking.

Finally, you can add one of WARN, FAIL or FATAL as the first optional argument to either ASSERT or STATIC_ASSERT. If the assertion fails, WARN will cause a simple warning (controlled by rgbasm(1) flag -Wassert) to be emitted; FAIL (the default) will cause a non-fatal error; and FATAL immediately aborts.

Including other source files

    INCLUDE "irq.inc"

Conditional assembling

IF NUM < 0
  PRINTLN "NUM < 0"
ELIF NUM == 0
  PRINTLN "NUM == 0"
ELSE
  PRINTLN "NUM > 0"
ENDC

The ELIF (standing for "else if") and ELSE blocks are optional. IF / ELIF / ELSE / ENDC blocks can be nested.

Note that if an ELSE block is found before an ELIF block, the ELIF block will be ignored. All ELIF blocks must go before the ELSE block. Also, if there is more than one ELSE block, all of them but the first one are ignored.

Changing options while assembling

OPT takes a comma-separated list of options as its argument:

PUSHO
    OPT g.oOX, Wdiv, L    ; acts like command-line -g.oOX -Wdiv -L
    DW `..ooOOXX          ; uses the graphics constant characters from OPT g
    PRINTLN $80000000/-1  ; prints a warning about division
    LD [$FF88], A         ; encoded as LD, not LDH
POPO
    DW `00112233          ; uses the default graphics constant characters
    PRINTLN $80000000/-1  ; no warning by default
    LD [$FF88], A         ; optimized to use LDH by default

The options that OPT can modify are currently: b, g, p, h, L, and W. The Boolean flag options h and L can be negated as ‘OPT !h’ and ‘OPT !L’ to act like omitting them from the command-line.

POPO and PUSHO provide the interface to the option stack. PUSHO will push the current set of options on the option stack. POPO can then later be used to restore them. Useful if you want to change some options in an include file and you don't want to destroy the options set by the program that included your file. The stack's number of entries is limited only by the amount of memory in your machine.

Requesting alignment

If the constraint cannot be met (for example because the section is fixed at an incompatible address), an error is produced. Note that ALIGN align is a shorthand for ALIGN align, 0.