Installation


Program and its dependencies are archived in ZIP file. Extract (unzip) the files in directory of your choice, but the structure of the root and subdirectories must remain intact. Executable file is titled effectus.exe for Win32 platform (effectus on Linux platform), which is accompanied with configuration file (config.ini). It is recommended to put config.ini file in the same directory as Effectus binary, but if not, the proper parameter values must be set. To start Effectus just type effectus (./effectus on Linux platform) and the properly qualified pathname of the source file to be compiled in the console.

Program usage


Common syntax:

- win32 platform

effectus filename [parameters]

- Linux platform
./effectus filename [parameters]

Program parameters:

-md: MADS cross-assembler directory
-sa: Program starting address
-ms: Output source directory
-mb: Output binary directory
-se: Output source extension
-be: Output binary extension
-rl: Effectus/MADS runtime library directory
-lo: Log pathname (including filename)
-sm: Machine language starting address
-am: Maximum number of ARRAY elements
-i: Effectus variable usage list
-dl: Delete log file before compiling


The options available in configuration file (config.ini) are:

PARAMETER SWITCH DESCRIPTION
ORG
-sa
Starting address of generated program (in hexadecimal notation, preceding with $ sign)
MADS_DIR
-md
MADS cross-compiler directory
MADS_SRC_EXT
-se
Output assembly source code extension
MADS_BIN_EXT
-be
Output executable code extension
MADS_RTL_DIR
-rl
Runtime library directory
ML_ORG
-sm
Machine language starting address
MADS_OUTPUT_DIR
-lo
Log fully qualified pathname (including filename)
ARRAY_MAX
-am
Array maximum number of elements

Many of these parameters have their default values which are used by Effectus in case they are not listed in configuration file.

If MADS cross-assembler pathname is included in your system path configuration file (autoexec.bat or registry key), then MADS_DIR option is ignored unless the MADS program is placed in root directory of Effectus executable. If config.ini is not used, MADS cross-compiler will be searched first in the root directory of Effectus executable.

As mentioned in Installation section, config.ini file is not mandatory for proper functioning of the program. In this case, some caution must be taken. By default, all forementioned parameters have default values. Also, the runtime library directory is declared in Effectus root directory (/lib) and log filename is set on root directory as well. Otherwise, if you decide to set your own values, parameters must be set.

To start using Effectus just type effectus (./effectus on Linux platform) and relative or absolute pathname to the source code file to be compiled. Effectus listing is compiled in directory you are currently on, but that can be changed with -ms: and -mb: parameters. The fully qualified pathname with space characters must be put in double quotation marks.

Every parameter must end with colon, for example: -sa:

Runtime library


Effectus development system consists of additional runtime libraries, which are included in compiled programs whenever necessary.

Here is a list:

runtime.asm runtime.obx Core library with common functions and variables
sound.asm sound.obx Sound routines
graphics.asm graphics.obx Graphics routines
io.asm io.obx I/O routines
printf.asm printf.obx Text printing routine with special formatting (decimal, hex, floating point numbers, strings)
printfd.asm printfd.obx Text printing routine with special formatting (decimal, hex, floating point numbers, strings) on specified device
math.asm math.obx Math routines
controllers.asm controllers.obx Game controller routines
common.asm   Common routines
equates.asm   Common equates (memory locations, temporary storage locations...)

Misc


  • There are some predeclared global variables defined in common.asm for various uses:
  • ; Global BYTE variables
     .var b_param1, b_param2, b_param3, b_param4, b_param5 .byte

    ; Global WORD variables
     .var w_param1, w_param2, w_param3, w_param4, w_param5 .word

    These variables use stack for their use, so there is no so much memory wasted. These variables are used for temporary storage of values and procedure and function parameter usage.

    Default device:

    device #0
    Array variable for usage with SCopyS command for temporary string storage:

    .array strx 255 .byte = $ff
    .enda
     .var array_buffer_strx .word
     .var array_index_strx .byte

  • Equates for memory locations and storage areas are stored in equates.asm, which is used throughout all libraries and user programs.

  • Some temporary values are stored in STORE1, STORE2 and STORE3 variables, which are declared as

    STORE1 equ $CB ; Temporary 8-bit variable
    STORE2 equ $CC ; Temporary 8-bit variable
    STORE3 equ $CD ; Temporary 8-bit variable

    in equates.asm file

  • Automatically generated MADS program source code layout:
  •  org $3200

     icl 'c:\projects\effectus\lib\equates.asm'
     icl 'c:\atari\effectus\lib\common.asm'

    Main
     ...
     ...
     ...

     jmp *

    .link 'd:\atari\my projects\effectus\lib\runtime.obx'

     run Main  ; a name of last Effectus procedure PROC

  • Additional automatically generated MADS program source code layout:
  • - for TYPE declaration:

    ; Handling TYPE variables
     .var struct_ptr_var .word

    - for ARRAY declaration:

     .var array_buffer_data .word
     .var array_index_data .byte