This is the top level directory of the PLEXIL distribution.

See http://sourceforge.net/projects/plexil for information about this
software, including its user manuals.  There is more information in
the README files found in each subdirectory of this directory.

The Versions file describes previous releases of Plexil, as well as
the latest features not yet released in a binary distribution.

The CAVEATS file describes known problems and issues in this release.


Software requirements
---------------------

The complete PLEXIL suite should run on most recent versions of Linux
and Mac OS X. It builds on FreeBSD as well, and most of the suite
works out of the box; however, IPC is not yet working, nor is anything
dependent on it (i.e. many of the example apps).

Building the PLEXIL tool suite requires the following software to be
installed:

 GNU Make
 GNU Bash
 gcc/g++ (default), clang/clang++, or other C99 and C++03 compliant compilers
 OpenJDK 8 or Oracle Java SDK 8 (development package, not just runtime)
 Apache ant, including the antlr module

The robosim example program also requires:

 X11 libraries freeglut, libxi, libxmu and their header files

In addition, if you are building from an SVN checkout, the GNU
autotools (autoconf, automake, and libtool) are required.


How to build PLEXIL - Simple version
------------------------------------

To build the PLEXIL distribution on Linux, Mac OS X, or FreeBSD,
simply change to this top level directory and type:

 make all

To build the tool suite without the example applications:

 make tools

To specify a compiler other than gcc/g++, e.g. clang:

 make CC=clang CXX=clang++

On FreeBSD, ensure that GNU make is installed (typically named 'gmake'
on this OS):

 gmake CC=clang CXX=clang++


Advanced builds
---------------

The PLEXIL Executive uses the GNU autotools to allow for easy
customization and cross-compilation when the standard build (above)
is not appropriate for a specific application.

1. Change to the build directory.

  cd plexil-4/src

2. If you are building from a fresh SVN checkout, you will need to
run the GNU autotools first. This step should be unnecessary if you
downloaded a release tarball.

  autoreconf -fi

3. Configure the build using the standard 'configure' script. To get a
listing of the various options, type:

  ./configure --help

The example below includes all the optional PLEXIL components as built
in the previous section, with binaries and libraries installed in the
PLEXIL installation directory.  You can omit or change options as
desired.

  ./configure --prefix=$PLEXIL_HOME --disable-static --enable-gantt --enable-ipc --enable-sas --enable-test-exec --enable-udp

Please see the CAVEATS file in this directory for advice on options to
'configure'.

4. Build and install the system:

  make install


Cross-compiling the PLEXIL Executive
------------------------------------

The use of the GNU autotools enables straightforward cross-compilation
of the PLEXIL Executive for embedded applications.

The file $PLEXIL_HOME/src/build-for-buildroot.sh is an example of
cross-compiling the PLEXIL Executive for use with the 'buildroot'
embedded Linux tool suite on an ARM processor.


Running PLEXIL
--------------

1. Set up your environment. The PLEXIL shell scripts depend on the
setting of PLEXIL_HOME, and for convenience you may wish to add the
PLEXIL scripts and binaries to your shell's path. This example is for
the Bourne/bash shells or similar.

  export PLEXIL_HOME='/location/of/plexil'
  . $PLEXIL_HOME/scripts/plexil-setup.sh

You may wish to add these two lines to your shell init file.

2. The 'plexil' script launches the Plexil Viewer, in which you can
examine, run, and debug plans. You may wish to use the plans in the
'examples' directory as a starting point.

  plexil

3. The 'plexilc' script compiles a PLEXIL plan or Plexilscript
simulation script, depending on the file extension, to the executable
XML representation.

  plexilc my_plan.ple