JALv2 Compiler Options
     __________________________________________________________
     __________________________________________________________

   There are many options that can be passed to the compiler to
   tell it, for example, where to find library files, or where to
   put the output files. These options are all described here.

   See the JALv2 documentation for definitions and conventions.
   Any time multiple options are allowed, the default option is
   preceded with a '*'. An {empty} option is interpreted as the
   default option.

   All available compiler options can be seen by passing the
   single options "--help" to the compiler. Use this command to
   also see the defaults for each option.

   Table of Contents
   1. File Options

        1.1. [no-]asm
        1.2. [no-]codfile
        1.3. [no-]hex
        1.4. include
        1.5. include path
        1.6. [no-]log
        1.7. [no]-lst

   2. Misc.

        2.1. clear
        2.2. fastmath
        2.3. quiet
        2.4. task

   3. Bootloader

        3.1. bloader
        3.2. fuse
        3.3. long start
        3.4. rickpic
        3.5. loader18

   4. Warnings

        4.1. all
        4.2. codegen
        4.3. conversion
        4.4. directives
        4.5. misc
        4.6. range
        4.7. stack overflow
        4.8. truncate

   5. Optimizations

        5.1. cexpr reduction
        5.2. const detect
        5.3. expr reduction
        5.4. expr simplify
        5.5. load reduce
        5.6. temp reduce
        5.7. variable frame
        5.8. variable reduce
        5.9. variable reuse

   6. Compiler Debugging

        6.1. codegen
        6.2. debug
        6.3. pcode
        6.4. emu
        6.5. deadcode
     __________________________________________________________

Chapter 1. File Options

1.1. [no-]asm

   Format:
        -asm name
        -no-asm

   Set the name of the generated assembly file to `name'. The
   default is the program name with `.jal' replaced by `.asm', or
   `.asm' appended if the program name doesn't end in `.jal'.

   If '-no-asm' is specified, no '.asm' file will be generated.

   The assembly file can be compiled by the MPASM and hopefully
   generate the same HEX file as JALv2.
     __________________________________________________________

1.2. [no-]codfile

   Format:
        -codfile name
        -no-codfile

   Set the name of the generated COD file to `name'. The default
   is the program name with `.jal' replaced by `.cod', or `.cod'
   appended if the program name doesn't end in `.jal'.

   If '-no-codfile' is specified, no '.cod' file will be
   generated.

   The COD file is a symbol file used by MPASM and probably other
   debugging tools. The format was created and is maintained by
   Byte Craft Limited and its sharing of this format, and general
   support is very much appreciated.
     __________________________________________________________

1.3. [no-]hex

   Format:
        -hex name
        -no-hex

   Set the name of the generated HEX file to `name'. The default
   is the program name with `.jal' replaced by `.hex', or `.hex'
   appended if the program name doesn't end in `.jal'.

   If '-no-hex' is used, no HEX file will be generated.

   The HEX file is used by PIC programmers and bootloaders to load
   the program onto the microcontroller.
     __________________________________________________________

1.4. include

   Format:
        -include filename [ ';' filename2... ]

   include 'filename' before parsing the file. Multiple files can
   be included when separated by ';' or when multiple '-include'
   directives are used.
     __________________________________________________________

1.5. include path

   Format:
        -s path [ ';' path1... ]

   Set the include path, elements separated with ';'. Multiple
   "-s" options append more path elements.
     __________________________________________________________

1.6. [no-]log

   Format:
        -log filename
        -no-log

   Generate a log file which will contain all messages emitted by
   the compiler. If absent, standard output is used.
     __________________________________________________________

1.7. [no]-lst

   Format:
        -lst filename
        -no-lst

   Set the name of the listing file to filename, or prevent the
   generation of a listing file. The default is no listing file.
   The listing file has never been correctly generated, so this
   option is useless.
     __________________________________________________________

Chapter 2. Misc.

2.1. clear

   Format:
        -[no-]clear

   Clear data area on program entry. This does not clear user
   placed or variables, or variables marked VOLATILE.
     __________________________________________________________

2.2. fastmath

   Format:
        -[no-]fastmath

   Use the fastmath versions for multiply.

   Without this flag, only one multiply routine is created which
   can handle the largest types ever multiplied. This creates
   smaller programs, at the expence of runtime speed.

   When this flag is set, a different multiply routine is
   generated for each types multiplied. This results in fast code,
   at the expense of program size. A side effect of this is that
   any multiplication routine that is only used once is inlined.
     __________________________________________________________

2.3. quiet

   Format:
        -[no-]quiet

   Turns off the progress messages
     __________________________________________________________

2.4. task

   Format:
        -task cexpr

   Sets the maximum number of concurrent tasks to cexpr. The
   default is 0. Note this value must be one more than the number
   of concurrent tasks as the main program counts as a task.

   nb: It is better to use `PRAGMA TASK' in your program than
   setting the value here. Doing so guarantees the value is
   correct even if you forget to pass it during compilation.
     __________________________________________________________

Chapter 3. Bootloader

   Booloaders are tiny programs that allow a chip to be
   reprogrammed over the serial or USB ports, eliminating the need
   for extra programming hardware. There are several variants, and
   each has slightly different requirements of the program it
   hosts. These are the ones currently defined.
     __________________________________________________________

3.1. bloader

   Format:
        -bloader

   Using the screamer/bloader PIC loader. See "PRAGMA BOOTLOADER
   BLOADER".
     __________________________________________________________

3.2. fuse

   Format:
        -[no-]fuse

   Put the `__config' line in the assembly or HEX files
     __________________________________________________________

3.3. long start

   Format:
        -long-start

   Force the first generated instruction to be a long jump. See
   "PRAGMA BOOTLOADER LONG_START".
     __________________________________________________________

3.4. rickpic

   Format:
        -rickpic

   Assumes the target PIC is using Rick Farmer's PIC bootloader.
   See "PRAGMA BOOTLOADER RICKPIC".
     __________________________________________________________

3.5. loader18

   Format:
        -loader18 [ cexpr ]

   See "PRAGMA BOOTLOADER LOADER18"
     __________________________________________________________

Chapter 4. Warnings

4.1. all

   Format:
        -W[no-]all

   enable/disable all warnings
     __________________________________________________________

4.2. codegen

   Format:
        -W[no-]codegen

   enable/disable code generation warnings
     __________________________________________________________

4.3. conversion

   Format:
        -W[no-]conversion

   enable/disable signed/unsigned conversion warning
     __________________________________________________________

4.4. directives

   Format:
        -W[no-]directives

   enable/disable warning when a compiler directive is found
     __________________________________________________________

4.5. misc

   Format:
        -W[no-]misc

   enable/disable uncategorized warnings
     __________________________________________________________

4.6. range

   Format:
        -W[no-]range

   enable/disable value out of range warnings
     __________________________________________________________

4.7. stack overflow

   Format:
        -W[no-]stack-overflow

   issue a warning on hardware stack overflow instead of an error
     __________________________________________________________

4.8. truncate

   Format:
        -W[no-]truncate

   enable/disable possible truncation in assignment warning
     __________________________________________________________

Chapter 5. Optimizations

   Optimizations that are enabled by default are considered safe
   -- they have been well tested and shown to not cause any
   problems. Opzimizations that are disabled by default have not
   been as well tested. Using them might be unsafe. Before
   reporting any problems with the compiler, please make sure to
   retest with only the default optimizations and let me know the
   outcome.
     __________________________________________________________

5.1. cexpr reduction

   Format:
        -[no-]cexpr-reduction

   enable/disable constant expression reduction

   Default: enabled

   Purpose: Detect expressions or subexpressions composed
   completely of constants, and reduce these to a single value.
     __________________________________________________________

5.2. const detect

   Format:
        -[no-]const-detect

   enable/disable constant detection

   Default: disabled

   Purpose: Look for variables that are only assigned a single,
   constant value and replace them with that constant value.
     __________________________________________________________

5.3. expr reduction

   Format:
        -[no-]expr-reduction

   enable/disable expression reduction

   Default: enabled

   Purpose: eliminate or refactor many simple operations and
   identities:

     * x +/- 0 --> x
     * x - 0 --> x
     * 0 - x --> -x
     * x - x --> 0
     * x * 0 --> 0
     * x * 1 --> x
     * x * (-1) --> -x
     * x / 1 --> x
     * 0 / x --> 0
     * x / (-1) --> -x
     * x % 0 --> 0
     * x % 1 --> 0
     * x < 0, x unsigned --> 0
     * x <= 0, x unsigned --> x == 0
     * x >=0, x unsigned --> 1
     * x > 0, x unsigned --> x != 0
     * x & 0 --> 0
     * x & x --> x
     * x | 0 --> x
     * x | x --> x
     * x ^ 0 --> x
     * x ^ x --> 0
     * -x, x is single bit --> x
     * 0 << x --> 0
     * x << 0 --> x
     * x << C, where C is >= bit size of x --> x
     __________________________________________________________

5.4. expr simplify

   Format:
        -[no-]expr-simplify

   enable/disable expression simplification

   Default: disabled

   Purpose: Combine common subexpressions.
     __________________________________________________________

5.5. load reduce

   Format:
        -[no-]load-reduce

   enable/disable redundant load of W removal

   Default: disabled

   Purpose: Look for redundant loads into the working register (W)
   and remove them
     __________________________________________________________

5.6. temp reduce

   Format:
        -[no-]temp-reduce

   enable/disable temporary reduction

   Default: disabled

   Purpose: Look for assignments to a temporary which is then
   immediately assigned to another variable and never again used,
   and remove it.
     __________________________________________________________

5.7. variable frame

   Format:
        -[no-]variable-frame

   allocate variables into a full frame

   Default: disabled

   Purpose: Place all variables in a function into a single block
   instead of using the first available space. This can minimize
   the number of bank switching operations, but can also lead to
   less efficient use of the data areas.
     __________________________________________________________

5.8. variable reduce

   Format:
        -[no-]variable-reduce

   enable/disable unused or unassigned variables removal

   Default: enabled

   Purpose: If a variable is assigned a value but never used in an
   expression, it is removed. Likewise if a variable is never
   assigned a value, but is used in an expression it is replaced
   with the constant 0.
     __________________________________________________________

5.9. variable reuse

   Format:
        -[no-]variable-reuse

   enable/disable reusing variable space

   Default: enabled

   Purpose: If two variables, say X and Y, are never, `live,' at
   the same time they can share the same data location. This leads
   to far more efficient use of the data area, but currently can
   lead to extreme compile times (on the order of hours).
     __________________________________________________________

Chapter 6. Compiler Debugging

   These options are most useful for debugging the compiler
   itself.
     __________________________________________________________

6.1. codegen

   Format:
        -[no-]codegen

   do not generate any assembly code
     __________________________________________________________

6.2. debug

   Format:
        -[no-]debug

   show debug information
     __________________________________________________________

6.3. pcode

   Format:
        -[no-]pcode

   show pcode in the asm file
     __________________________________________________________

6.4. emu

   Format:
        -[no-]emu

   Run the emulator after compiling.
     __________________________________________________________

6.5. deadcode

   Format:
        -[no-]deadcode

   enable dead code elimination
