--------------------------------
- Effectus brief documentation -
--------------------------------

Effectus - Atari MADS cross-assembler/parser for Action! language

Description
-----------

The goal of Effectus project is to make it compatible with Action! programming
language as close as possible. The name Effectus comes from Latin word for
"execution".

Effectus compiles and produces MADS assembly language source code and binary
files for executing on real 8-bit Atari or software emulator. Current version of
MADS cross-compiler used is 1.9.8. Resulting source code can be further edited
and modified by you depending on your needs. You can configure Effectus to set
MADS and Effectus source code and binary code folder, program starting address,
extensions, etc. by using config.ini file or typing parameters in the console.

examples directory includes some demonstration programs to show what Effectus is
currently able to accomplish. lib directory consists of runtime and several
other supporting libraries. Maintaining the compatibily with Action! will be of
HIGH priority. The implementation of runtime library routines can be changed,
but the number and order of parameters should not be changed. This is one of the
rules you must follow to successfully compile any Effectus program. Also,
additional requirement for proper working of Effectus is having config.ini
configuration file in the same directory as the Effectus executable program.

Features, rules and limitations are listed on the Effectus homepage by visiting:
http://gury.atari8.info/effectus/


Credits:
--------

I have to thank the author of MADS, Tebe, who helped me with many important
suggestions to improve the code. Special thanks also to other people (mainly from
AtariAge and atarionline.pl forums) for the additional help by testing and
finding bugs in Effectus, plus providing new test examples. They are:
greblus, Cosi, w1k, Kaz, ascrnet, dwhyte, devwebcl, twh/f2, TXG/MNX and all
others not listed here.


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 subdirectory must
remain intact. Executable file is titled effectus.exe for Win32 platform, which
is accompanied with config.ini (configuration file). 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 you just have to type effectus
and the properly qualified pathname of the source file to be compiled in the 
console. Read below for further instructions.

Program usage common syntax:

- i386-win32 platform 

  effectus filename [parameters] 

- i386-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 

If config.ini file is in the same directory as Effectus is run, then those
settings are read and used in the program. 

The options available in configuration file 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):  Fully qualified pathname for log file (including filename)

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 Installaction 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 from root where Effectus is run (/lib) and log
filename is set here as well. Otherwise, if you decide to set your own values,
parameters must be set manually. 

To start using Effectus, typically, just type effectus and name of source code
file to be compiled. If the source is somewhere else, use properly qualified
pathname. Your program 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:
