_______        _______ __   _  ______
     |______ |      |______ | \  | |  ____
     |       |_____ |______ |  \_| |_____|


    Version: 3


I. Introduction

This software is an implementation of "FLENG", a low level concurrent
logic programming language descended from Prolog. A compiler is
provided to translate programs written in FLENG into assembly"
language which can subsequently be compiled and linked into a binary
executable. As FLENG is quite minimal in features, a translator
from "Flat Guarded Horn Clauses" (another concurrent logic language)
into FLENG is also available.

FLENG programs allow for massive parallelism at a very fine grained
level - goals are executed concurrently and communicate solely via
single-assignment logic variables. The use of logic variables for
inter-process communication offers an easy to use and convenient
abstraction to implement many common patterns of synchronization
and message passing in a natural manner. This implementation
additionally can distribute pools of parallel processes over native
OS level threads, thus taking advantage of multicore architectures.
Locking overhead should be small, as data is normally not shared
among processes executing on different threads. Automatic management
of memory is provided using a reference-counting scheme of fixed
size cells, which avoid fragmentation, avoids garbage collection
pauses and keeps the overall memory required to hold live data at
any point of time minimal, while providing relatively good locality.

Interfacing to native code is straightforward and compiled FLENG
code and the run time library support can be linked with other
modules written in C or C++ without problems. The compilation tools
allow cross compilation, provided the architecture is supported.

The compiler generates native code, but does currently not perform
a lot of optimizations, so performance-sensitive code should probably
be written in C or another language. FLENG should be particularly
well suited as a coordination language for providing intercommunication
and synchronization with reasonable overhead while calling out to
C or C++ code for low-level or speed-critical operations.

This is a first release of FLENG, so expect bugs, lack of performance
tuning and missing features. Suggestions for improvement or patches
providing enhancements and corrections are very welcome, see the
user's manual for information on how to contact the author.

The software is open source and released under the 3-clause BSD
license.


II. Build and Installation

* Requirements:

The run-time system for FLENG is written in C99 with GNU extensions
and should be compilable with most C compilers. The FGHC-to-FLENG
translator and the FLENG compiler are written in mostly ISO compliant
Prolog and are known to run under SWI[1] and GNU[2] Prolog. You
will need one of these Prolog systems to be installed, make(1) and
a POSIX compliant sh(1). On x86-64 platforms the "nasm"[3] assembler
is currently required.

The system is known to run on Linux and OpenBSD and should also run
under FreeBSD and NetBSD. Supported target architectures are x86-64
and armv7.

* Configuration:

First run the "configure" shell script, optionally providing
arguments. Enter

    ./configure --help

to see a list of options for specifying the installation location
and possibly selecting the host Prolog implementation to use. By
default, the system will be installed in "/usr/local" and use GNU
Prolog, if found, or, alternatively SWI Prolog. 

* Building:

Once configuration has been done, you can run make(1) to build the
compiler and run-time system:

    make

If no errors occur, you can optionally enter

    make check

to run the test suite. By setting the environment variable
"FLENG_PREFIX" to the current working directory, you can use the
"fleng" driver script in-place to use or test the system without
installation.

* Installation:

To install, enter

    make install

If you have no permissions to access the installation location, use
sudo(1) or doas(1) when invoking "make install".

The following files will be installed:

    $PREFIX
    |-- bin
    |   |-- fghc2fl            <- only if GNU Prolog is used
    |   |-- fl2x64             <-
    |   `-- fleng
    |-- include
    |   |-- fleng-util.h
    |   `-- fleng.h
    |-- share
    |   |-- fleng
    |   |   `-- *.pl           <- only if SWI Prolog is used
    |   `-- man
    |       `-- man1
    |           `-- fleng.1
    `-- lib
        `-- libfleng.a

When using the SWI Prolog system for the FLENG and FGHC compilers,
then additional compiler sources will be installed in 
"$PREFIX/share/fleng".

* Cross-compilation:

To cross compile for a different platform, use the "--target" when
invoking "configure", with the name-prefix of the cross toolchain
you want to use. For example, if you have an Arm/Linux toolchain
in your path, with tools named "arm-bcm2708hardfp-linux-gnueabi-cc",
etc., then the following commands would build the FLENG run time
system using the toolchain's tools and install tools and libraries
in $HOME/armfleng/bin that produces binaries for the target platform:

    ./configure --target=arm-bcm2708hardfp-linux-gnueabi \
        --prefix=$HOME/armfleng
    make
    make install

The target architecture is inferred from the toolchain prefix and
it is assumed to follow the "<arch>-<os>-..." convention.

You can now compile FLENG or FGHC programs directly to Arm binaries
with a command like this:

    PATH=$HOME/armfleng/bin:$PATH
    arm-bcm2708hardfp-linux-gnueabi-fleng hello.ghc


III. References

[1] http://www.swi-prolog.org
[2] http://www.gprolog.org
[3] http://nasm.us