The Falcon Programming Language

                                0.9 series



BUILD INSTRUCTIONS
==================

  WARNING: Use of SVN is now OBSOLETE.

  Checkout the latest source code from the Git repository from:

  http://git.falconpl.org

  Instructions on how to build the released source packages are contained
in the "BUILDING" document.


FALCON MINIMAL OPERATION
========================

Falcon scripts can be launched through the command

   falcon /path/script_name.fal parameter1 ... parameterN
   falcon script_module parameter1

the option -? will give some interesting help; most useful parameters, to be
placed before the script name, are:
  -L <module_path;module_path> to specify the paths where to search for
                               modules.
  -p module  to pump in extra modules (preload them). Repetitions of -p load
             other modules

On UNIX systems, falcon scripts can be made executable and provide the execute
instruction on the first line, like this:

   #! /usr/bin/falcon
   printl( "Hello world" )


The environment variable FALCON_LOAD_PATH  can provide extra load path
instruction. The priority of load paths are:

- command line -L option
- FALCON_LOAD_PATH
- built-in directory (in config.h created from config.h.in)

So it's always possible to redirect Falcon to load user-provided modules
instead of system ones.


OTHER NOTICES
=============

Under tests/ the testsuite/ and longtests/ contains a series of scripts that
are meant to be used either by faltest program or by pumping in the
testsuite module. Faltest reads the directory provided with -d command line
option and runs all the .fal scripts in there which provide an ID: field
in the comments on top of the file. Valid IDs are numbers optionally followed
by a lowercase letter. Scripts are run in numeric order, and
a list of IDS separated by space can be provided to run one or more tests.
Also, scripts may be categorized, and filtered by category/subcategory using
-c and -C command line switches. The -l switch lists the selected scripts (or
all the scripts found), and the -v switch reports verbose output errors. To
know the path for a script ID, use

  ./faltest -d <dir to scripts> -l -v <ID>

(scripts path are displayed only with -v option).
Finally, -t option gathers execution time info. Other exotic/esoteric options
are -m (NOT compile in memory), -s (compile via assembly), -S (do a
serialization/ deserialization on the compiled module before running it,
instead of using it as soon as it has been compiled).

It's a good idea to launch faltest on the testsuite to verify that your
environment is properly set up.

The longtests/ directory has the same function as the testsuite/ directory,
except for the fact that its tests are meant to run for longer times to check
for stress/repetition features.

The samples/ directory contains some samples and tests for those features that
cannot easily be tested automatically. Those are normal falcon scripts and
can be run with the "falcon" command.

The three directories are a quite complete showdown of falcon language, and
can be used as operating examples.