




JALv2 Compiler Options
 

   
Contents
Introduction	4
Chapter 1. File Options	5
1.1. [no-]asm	5
1.2. [no-]codfile	5
1.3. [no-]hex	5
1.4. include	6
1.5. include path	6
1.6. [no-]log	6
1.7. [no]-lst	6
Chapter 2. Misc.	7
2.1. clear	7
2.2. fastmath	7
2.3. quiet	7
2.4. task	7
Chapter 3. Bootloader	8
3.1. bloader	8
3.2. fuse	8
3.3. long start	8
3.4. rickpic	8
3.5. loader18	8
Chapter 4. Warnings	9
4.1. all	9
4.2. codegen	9
4.3. conversion	9
4.4. directives	9
4.5. misc	9
4.6. range	9
4.7. stack overflow	10
4.8. truncate	10
Chapter 5. Optimizations	11
5.1. cexpr reduction	11
5.2. const detect	11
5.3. expr reduction	12
5.4. expr simplify	12
5.5. load reduce	13
5.6. temp reduce	13
5.7. variable frame	13
5.8. variable reduce	13
5.9. variable reuse	14
Chapter 6. Compiler Debugging	15
6.1. codegen	15
6.2. debug	15
6.3. pcode	15
6.4. emu	15
6.5. deadcode	15

 
Introduction

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.
 
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 defaultis 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



