INSTALL

            == Flect: Functional Systems Programming Language ==

                -- Installation --

Flect has to be configured using the included configuration script before it is
built. Note that GNU Make is required for this process. To do this, run:

    $ make config.mak

(Simply running make will invoke the configuration script too, if there is no
configuration file in the project directory.)

You will be asked to configure the following variables:

    * FLECT_OS
    * FLECT_ARCH
    * FLECT_ABI
    * FLECT_FPABI
    * FLECT_ENDIAN
    * FLECT_CROSS
    * FLECT_CC
    * FLECT_CC_TYPE
    * FLECT_CC_ARGS
    * FLECT_LD
    * FLECT_LD_TYPE
    * FLECT_LD_ARGS

See the COMPATIBILITY file for possible values. Some of these variables will
have defaults based on guesstimates about the system you're building on. The
FLECT_CC_ARGS and FLECT_LD_ARGS variables specify extra parameters to pass to
the C99 compiler and the linker, if any. You can generally leave these empty.
The FLECT_CROSS value is a Boolean indicating whether a cross compiler is
being built.

In addition, the following variables configure where Flect should be installed
and where it should look for static/shared libraries:

    * FLECT_PREFIX
    * FLECT_BIN_DIR
    * FLECT_LIB_DIR
    * FLECT_ST_LIB_DIR
    * FLECT_SH_LIB_DIR

In general, a directory hierarchy like this should be set up:

    prefix (FLECT_PREFIX)
    ├───── bin (FLECT_BIN_DIR)
    └───── lib
           └── flect (FLECT_LIB_DIR)
               ├──── static (FLECT_ST_LIB_DIR)
               └──── shared (FLECT_SH_LIB_DIR)

The configuration will be written to config.mak. When you invoke Make from
now on, it will use the values written to this file. You can still override
the values by setting environment variables, should you need to.

Flect can be built, tested, and installed after the configuration is complete.
The build process requires the Mix build tool shipped with Elixir. You should
avoid invoking Mix directly, however.

The makefile has a number of targets for building and testing Flect:

    * all: Runs ebin and escript. This is the default target.
    * ebin: Builds all Flect modules.
    * escript: Builds the escriptized Flect binary. Runs ebin if needed.
    * docs: Builds the documentation. Runs ebin if needed.
    * test: Runs the compiler test suite. Runs ebin if needed.
    * dialyze: Runs Dialyzer on compiled Flect modules. Runs ebin if needed.
    * clean: Cleans up the tree (removes compiled modules, dump files, etc).
    * distclean: Removes any configuration files. Also invokes clean.
    * install: Install Flect to FLECT_PREFIX. Runs escript if needed.
    * uninstall: Remove Flect from FLECT_PREFIX.

A number of variables can be set in the environment to override the tools used
by the makefile:
 
    * RM: The POSIX rm tool.
    * TIME: the POSIX time tool.
    * INSTALL The POSIX install utility.
    * ELIXIR: The Elixir script runner.
    * MIX: The Mix build tool shipped with Elixir.
    * DIALYZER: The Dialyzer tool from the Erlang suite.

You should not normally have to override these if the tools are present in
your environment.

To get an escript:

    $ make escript

This places the escript named flect in the ebin directory. It is completely
self-contained so it can be moved anywhere and will run fine provided the
host system it is run on has Erlang installed. It will make assumptions
about the location of binaries and libraries based on the relevant
configuration variables, however.

It's a good idea to run the test suite before using the compiler:

    $ make test

If this passes, you should be good to go.

Finally, if you're looking to use the Flect library's API, you may want to
build the documentation:

    $ make docs

This places the documentation in the docs directory.