__        ___     _ _
 \ \      / / |__ (_) | ___ _   _    ___  _ __ __ _
  \ \ /\ / /| '_ \| | |/ _ \ | | |  / _ \| '__/ _` |
   \ V  V / | | | | | |  __/ |_| |_| (_) | | | (_| |
    \_/\_/  |_| |_|_|_|\___|\__, (_)\___/|_|  \__, |
                            |___/             |___/

======================================================================
Contents
======================================================================

1. Introduction

2. Installation

3. Building from Source

4. Making a Contribution

======================================================================
1. Introduction
======================================================================

Whiley is a programming language particularly suited to
safety-critical systems. It is a hybrid object-oriented and functional
programming language which employs extended static checking to
eliminate errors at compile time, including divide-by-zero, array
out-of-bounds and null dereference errors.

Whiley compiles to the Java Virtual Machine and is fully
inter-operable with existing Java applications.  Whiley will operate
on any system that can run Java including Windows, Mac OS and Linux.
Whiley is released under the New BSD License --- see the LICENSE file
for more on this.

To find out more, visit http://whiley.org

======================================================================
2. Installation
======================================================================

There are several ways to get started with Whiley:

1) You can run it directly in your web browser.

2) Or, you can download and run the executable Jar.

3) Or, you can download and setup the Whiley Development Kit.

4) You can install the Eclipse Plugin.

The Eclipse plugin is the easiest way to get started with Whiley (see
instructions below).  If you don't use Eclipse, another simple option
is to download and run the executable Jar.  Finally, developers may
like to download the Whiley Development Kit (WDK), which includes the
source code for the compiler/runtime and various scripts to simplify
compiling and running Whiley programs from the command-line.

2.1 Whiley Play
----------------------------------------------------------------------

To run Whiley in your web-browser, goto http://whiley.org/play/

2.2 Whiley Executable Jar
----------------------------------------------------------------------
If you're running on a Windows system without cygwin, or you're having
trouble getting the wycc scripts to work, then a useful alternative is
to run the executable jar file directly.  First, download the
wycc-all-vX.Y.Z.jar file from http://whiley.org/downloads.  Then, you
can compile Whiley files as follows:

% cd examples
% java -jar wycc-all-vX.Y.Z.jar compile hello-world.whiley

(here, vX.Y.Z is the version number of the distribution)

Then, to run the program you would do this:

% java -jar wycc-all-vX.Y.Z.jar run hello-world
Hello World

(note: under Mac OS and UNIX you will want to replace the ';' with a ':')

2.3 Whiley Development Kit (WDK)
----------------------------------------------------------------------
To install the Whiley Development Kit, first download it from
http://whiley.org/downloads.  Then, unpack the tarball into an
appropriate directory (as you've probably already done).  You then
need to make sure that PATH environment variable points to the bin/
directory, where several scripts are provided for running Whiley.
(don't worry if you don't know what the PATH is, as you can instead
run the jar directly --- see below).

With the PATH setup correctly, you should be able to run the wyjc
command to compile Whiley programs as follows:

% cd examples
% wy compile hello-world.whiley

At this point, you can run the program using the whiley command:

% wy run hello-world
Hello World

============================================================================
3. Building from Source
============================================================================

The compiler for Whiley shipped with the "Whiley Development Kit" is
really a compiler framework called the "Whiley Compiler Collection".
This is made up of a number of plugins, of which the "WhileyCompiler"
is perhaps the most important.  This is responsible for compiling
Whiley files into the Whiley Intermediate Language (WyIL).  Additional
plugins (e.g. the "Whiley2JavaCompiler") are responsible for compiling
WyIL files for various targets (e.g. JVM bytecode).

As an example, you can build the WhileyCompiler plugin from scratch by
cloning this repository.  You can build the compiler by running 'ant'
at the top level (you need to have Apache Ant installed to do this).
At this point, you need to install the new plugin into your
distribution of the Whiley Development Kit (see above) in order for it
to be recognised by the "wy" command (you can do this by simply
copying wyc-vX.Y.Z.jar into the lib/ directory).

Setting up the WhileyCompiler under an IDE should be straightforward,
provided it supports Maven.  This is because the necessary
dependencies for the WhileyCompiler (e.g. other components of the
Whiley Compiler Collection) are hosted on Maven central.

============================================================================
4. Making a Contribution
============================================================================

When making a contribution to the Whiley project, you will need to
first sign-off the developers certificate of origin.  Please see the
CONTRIBUTORS file for more details.