Labels and Macros

Labels are variables that can be used by the expression parser. The first item on a line of text is assumed to be a label if it is either in the first column or if it cannot be assembled. The colon on the end of a label is entirely optional.

Brass is a two-pass assembler. In the first pass, each line of the source file is read and parsed. Any label definitions are added to the label list, macros are parsed and each line is translated by the macro preprocessor. No object code is produced until the second pass.

Due to this mode of operation, there are some important things to watch out for:

• Forward references with labels are allowed. For example,

      ld a,(_label)
  ; ...
  _label: .db $FF

  ...is perfectly valid as the address of _label is calculated at the end of the first pass, and the code ld a,(_label) isn't assembled until the second pass.
• Forward references with macros are not allowed. For example,

      add(1,2)
  ; ...
  #define add(arg_a, arg_b) .db arg_a + arg_b

  ...will not work. Remember that macros are just very primitive find-and-replace operations.

The assembler does clear/regenerate all macro definitions on each pass to prevent the following problem:

.org $0000

#ifdef bad_macro
.db $FF
#else
.dw $FFFF
#endif

_label:

#define bad_macro

If the macros weren't cleared and regenerated, in the first pass bad_macro would not have been defined and _label would have had an address of $0002. In the second pass, bad_macro would have been defined, and _label would have had an address of $0001.

The second pass does not perform any macro replacement, just redefinition. See the .define documentation for more in-depth information on macros.