PLEXIL

This is the top level directory of the PLEXIL distribution.

See https://plexil-group.github.io/plexil_docs/ for information about
this software, including its user manuals. There is more information
in the README files found in the subdirectories.

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 is maintained on recent versions of Linux
and macOS. It should build and run on other Unix-like environments
(e.g. Microsoft Windows Subsystem for Linux, BSD family) without much
effort.

This version of PLEXIL requires a C++14 compliant compiler!

This release depends on the feature set introduced in the C++14
language standard.

Building the PLEXIL tool suite from source requires the following
software:

• POSIX-compliant shell (e.g. GNU bash, dash, zsh, etc.)
• GNU Make and autotools (autoconf, automake, libtool, m4) or
• CMake
• GNU gperf
• gcc/g++, clang/clang++, or other C99 and C++14 compliant compilers
• Java 8 or newer JDK (e.g. openjdk-11-jdk)
• Apache ant, including the antlr module

If you downloaded a tarball, the GNU autotools and gperf are not
needed.

The robosim example program also requires the X11 libraries freeglut,
libxi, libxmu and their header files.

How to build PLEXIL - Simple version

To build the PLEXIL distribution:

1. To build everything, including the robosim and sample-app examples,
   change to this top level directory and type:

make everything

1. If you do not wish to build the examples:

make tools

How to run PLEXIL - Simple version

1. Add the following lines to your shell init file (e.g. ~/.bashrc).
   Set PLEXIL_HOME to the directory containing this README.md file.

export PLEXIL_HOME='/where/i/cloned/plexil'
. "$PLEXIL_HOME/scripts/plexil-setup.sh"

1. Source the init file you just edited:

. ~/.bashrc

1. The plexilc script compiles a PLEXIL plan or a Plexilscript
   simulation script to its XML representation:

plexilc my-plan.ple

produces the Core Plexil file my-plan.plx. Similarly,

plexilc my-script.pst

produces the Plexilscript file my-script.psx

1. The plexiltest script runs the Test Executive on a plan and a
   Plexilscript. This is the easiest way to get started learning the
   PLEXIL language.

plexiltest -p my-plan.plx -s my-script.psx

1. The plexilexec script runs the Universal Executive on a plan and
   requires an interface configuration file. See the Sourceforge
   documentation for more information.

plexilexec -c interface-config.xml -p my-plan.plx`

1. The 'examples' directory contains a number of examples, and is a
   good place to start exploring.

Problem solving

• If you have just updated your git clone from a previous build, you may
  need to precede make all with either:

make clean

or:

make distclean

The latter is sometimes needed when make or autotools files have
changed.

How to build PLEXIL Executive - Custom configuration with autotools

1. Create the script 'src/configure':

cd "$PLEXIL_HOME"
make src/configure

(This will have been done already if you downloaded a release tarball.)

1. Change into the 'src' directory and configure the build:

cd src
./configure --prefix="/where/to/install" ... options ...

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-ipc \
 --enable-sas --enable-test-exec --enable-udp

For a complete list of options, type:

./configure --help

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

1. Change back to the top level directory and build the system:

cd ..
make

Using CMake

The PLEXIL Executive also supports building with CMake, for simpler
integration into CMake-based projects. CMake version 3.6 or newer is
required. The instructions here describe an out-of-tree build, which
is the preferred approach. In-tree builds should also work, but are
not recommended.

1. Create a build directory and change into it.

mkdir plexil-build
cd plexil-build

1. Configure the build using CMake.

cmake "path/to/plexil/src" -DCMAKE_INSTALL_PREFIX="/install/here" ... options ...

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.

cmake path/to/plexil/src -DCMAKE_INSTALL_PREFIX="$PLEXIL_HOME" \
 -DSTANDALONE_SIMULATOR=ON -DTEST_EXEC=ON -DUDP_ADAPTER=ON
 ```

Please see the CAVEATS file in this directory for advice on CMake options.

4. Build and install the system:

make install
```

Cross-compiling the PLEXIL Executive

Cross-compilation of the PLEXIL Executive as a component of other
projects is straightforward, using either the GNU autotools or CMake.

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. This example uses the
GNU autotools.

Similarly, by supplying an appropriate toolchain file with the
-DCMAKE_TOOLCHAIN_FILE option, CMake can build the PLEXIL Executive
for targets other than the host system.