Get the Avail Source

A source distribution of Avail is available for users of Windows, Mac OS X, Linux, and other Unix systems. A source distribution is obtained by cloning the official Avail project repository. The following instructions are provided using a Unix terminal. Windows users will need to make the appropriate adjustments to dereference environment variables.

A Git client is required to clone the project repository. If you do not already have one installed, then you can obtain one here. We have noticed that the Git binaries for Mac OS X are sometimes mislinked on older versions of the operating system (< 10.9.x); if you encounter this problem, then uninstall the Git client and install Xcode to obtain a properly linked build of Git.

The Avail project repository is located at:

The master branch tracks main-line development. Assuming that git is available on your PATH, you can obtain the latest-and-greatest from master using the following command:

This will clone the Avail project repository into the shell's working directory as a subdirectory named Avail.

The following branches correspond to supported Avail project releases:

You can obtain a specific release using the following command:

Where $BRANCH_NAME stands for one of the branch names given in the table above. For example, to obtain the 1.4.1 branch, you can issue the following command:

Once you have cloned an Avail project branch, you can stay current with updates to that branch by pulling them from the official repository:

Installation

If you obtained a binary distribution of Avail, then run the installer. Afterward, skip ahead to learn about configuration.

If you obtained a source distribution of Avail, the you have more work to do before you can start experimenting with Avail. The official installation instructions are included in the README.md file of the source distribution:

README.md is a plain text document that contains Unicode code points in the UTF-8 character encoding, so it can be read by most modern editors. As a courtesy to aging developers and system administrators, such as several of the Avail team members, it is manually line-broken to look good on an 80-column display.

If you encounter problems during installation and you discover that there is disagreement between README.md and the following instructions, then please treat README.md as gospel.

Prerequisites

Before installing Avail, you will need to make sure that you have obtained and installed the prerequisite software:

1. Java: You will need version 17, or later, of the Java Development Kit (JDK). Many modern systems already have some version of the JDK, so you should check your JDK version before obtaining and installing it from Oracle (or some other vendor). You can do so like this:

   $ javac -version

   And hopefully you get back something like this:

   javac 17.0.2

   Otherwise, the latest version of the Java SE Development Kit 17 can be obtained from Oracle or other vendors. Links to Oracle's Java versions are notoriously brittle, so it's best to just search for it on their site and find a link that hasn't been broken yet. We've had good experiences with OpenJDK, but other Java 17 JDKs can be used instead.

   Please follow any installation directions provided by the Oracle website or included with the JDK.

   Please make sure that java and javac are on your PATH.

2. Gradle: This is the build software used to compile and install Avail. You do not need to obtain Gradle manually, as the build process will take care of this for you automatically.

Building

You will need to compile Avail using the provided Gradle wrapper. To build Avail on a Unix-based system, such as Linux, Mac OS X, Minimalist GNU for Windows (MinGW), or Windows Subsystem for Linux (WSL):

To build Avail on vanilla Windows:

Where $PROJ is the location of your local copy of the Avail project repository. You should see output similar to this:

If your transcript includes BUILD SUCCESSFUL near the end, then your build is ready for use. Refer to the Avail project's README.md file for additional instructions.

Note that avail-dev.bat makes no effort to configure the environment. You must preconfigure the environment yourself, customize avail-dev.bat to suit your own needs, or use the Avail workbench to establish the module roots. (A lack of Windows expertise on the part of The Avail Foundation is responsible for this minimality; hopefully avail-dev.bat will be richer in a future release.)

For information about Avail's modules, please read module discovery.

After Installation

Grab yourself a refreshing beverage, kick back, fire up the Avail workbench, and experiment with some Avail expressions using the Availuator, because you are done with installation!

If you installed a binary distribution of Avail, then you can launch the Avail workbench by double-clicking on the application's icon.

If you installed a source distribution of Avail, then you can launch the Avail workbench like this:

If you are launching the Avail workbench from a Windows command prompt, then be aware that the name of the batch script is avail-dev.bat, not avail-dev.

Once you've launched the workbench, have a look at the Avail workbench documentation, which includes a tour of the UI and features.