The Avail Programming Language
Mobile Users: Click here to view our text rendering warning.

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:

https://github.com/AvailLang/Avail.git

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:

$ git clone https://github.com/AvailLang/Avail.git

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:

Branch Name
1.0.0_DEV_2014-04-28

You can obtain a specific release using the following command:

$ git clone https://github.com/AvailLang/Avail.git --branch "$BRANCH_NAME"

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

$ git clone https://github.com/AvailLang/Avail.git --branch "1.0.0_DEV_2014-04-28"

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

$ git pull

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:

Avail/ README.md <-- This one! avail-templates.xml bin build.xml distro eclipse-luna.epf experimental repositories resources src user dictionary

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 1.7, 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 1.7.0_55

    Otherwise, the latest version of the Java SE Development Kit 7 can be obtained at:

    http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html

    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.

    (As of the time of writing, Avail has not yet been tested on Java 1.8. If you try it and it works, then great; otherwise, try running Java 1.7.)

  2. Apache Ant: This is the build software used to compile and install Avail. You will need version 1.8.2 or later. Most modern Unix systems already have some version of Ant installed, but, if you are a Windows user, then you will definitely need to download it yourself if you have not previously done so. You can check to see if Ant is installed and has the correct version like this:

    $ ant -version

    And maybe get back something like this:

    Apache Ant(TM) version 1.8.2 compiled on October 14 2011

    If you want to download a recent binary distribution of Ant, then go here:

    http://ant.apache.org/bindownload.cgi

    Or you can obtain a source distribution here:

    http://ant.apache.org/srcdownload.cgi

    Please follow any installation directions provided by the Apache Ant website or included with the distribution of your choice.

    Please make sure that ant is on your PATH.

Building

You will need to compile Avail using the provided build script, build.xml. To build Avail:

$ cd "$PROJ"/Avail $ ant

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

Buildfile: $PROJ/Avail/build.xml build-sources: [mkdir] Created dir: $PROJ/Avail/bin [javac] Compiling 1022 source files to $PROJ/Avail/bin generate-build-time: generate-primitives-list: avail-vm: [jar] Building jar: $PROJ/Avail/distro/lib/Avail.jar avail-dev: [jar] Building jar: $PROJ/Avail/distro/lib/AvailDev.jar BUILD SUCCESSFUL Total time: 14 seconds

If your transcript includes BUILD SUCCESSFUL near the end, then your build is ready for installation.

Installing

Once you have successfully built the Avail project, you can then install it for either user-specific or system-wide usage. The installation directory (hereinafter, $INSTALL) is specified by an Ant property, "path.install". You can set this property by providing the -Dpath.install=… option to Ant.

You can install Avail into a specific installation directory like this:

$ cd $PROJ/Avail $ ant -Dpath.install=$INSTALL install

If you do not specify -Dpath.install=… explicitly, then $INSTALL defaults to /usr/local/avail on Mac OS X, Linux, and Unix; it defaults to C:\Program Files\Avail on Windows. Note that these are system directories, and in order to install to such a location you may need to escalate your privileges by using a tool like sudo or logging in with an administrative account.

Your transcript should look similar to this:

Buildfile: $PROJ/Avail/build.xml build-sources: generate-build-time: generate-primitives-list: avail-vm: [jar] Building jar: $PROJ/Avail/distro/lib/Avail.jar avail-dev: [jar] Building jar: $PROJ/Avail/distro/lib/AvailDev.jar install: [copy] Copying 229 files to $INSTALL [echo] [echo] ATTENTION ======================================================= [echo] Be sure to set AVAIL_HOME to: [echo] [echo] $INSTALL [echo] [echo] And update your path to include: [echo] [echo] $INSTALL/bin [echo] [echo] For example, a user of bash might include something like the [echo] following in the appropriate shell config file: [echo] [echo] export AVAIL_HOME=$INSTALL [echo] export PATH=$PATH:$INSTALL/bin [echo] [echo] Once your path has been updated, from any directory you can [echo] launch the Avail workbench like this: [echo] [echo] avail-dev [echo] [echo] To develop Avail code, you will also need to set AVAIL_ROOTS to a [echo] valid module root path. If AVAIL_ROOTS is not set, then avail-dev [echo] temporarily sets it to: [echo] [echo] avail=$HOME/.avail/repos/avail.repo,$INSTALL/src/avail;\ [echo] examples=$HOME/.avail/repos/examples.repo,$INSTALL/src/examples [echo] [echo] This is convenient for experimenting with Avail, but must be [echo] extended with custom module roots as you develop your own [echo] modules. [echo] ================================================================= [echo] BUILD SUCCESSFUL Total time: 3 seconds

If your transcript includes BUILD SUCCESSFUL near the end, then the installation has completed. The transcript contains information about how to configure your environment for Avail development. Please be sure to follow these instructions (reiterated in more detail below).

Configuring

In order to develop Avail libraries and programs, you will need to configure your environment appropriately. On Unix, this is best accomplished by updating your shell configuration file. On Windows, you can use the Control Panel to adjust the environment variables.

The following steps should be taken to prepare your environment for Avail development:

  1. Set the AVAIL_HOME environment variable to $INSTALL. (You will need to put $INSTALL in quotation marks " (U+0022) if it contains spaces (U+0020).) The Avail workbench, avail-dev, uses this information to locate Avail, and will not run correctly without AVAIL_HOME being set.
  2. Update your PATH to include $INSTALL/bin. (Again, on Unix systems you will need to put $INSTALL in quotation marks if it contains spaces.) This is where avail-dev is located. This enables your shell to find the command without the user needing to prefix its exact path or change the working directory.
  3. Set the AVAIL_ROOTS environment variable to a valid module roots path so that Avail can find its modules.

A module roots path is a specification of locations that contain Avail code, in either binary or source form. A module roots path comprises several module root specifications separated by semicolons ; (U+003B). (On Unix systems, you will need to put each semicolon in apostrophes ' (U+0027), in order to hide it from the shell's command parser.)

Each module root specification comprises a module root name, which is just a unique logical identifier, and a module root path. A module root name usually denotes a vendor or a project, and does not need to have any relationship to the file system. By convention, the module root name of the Avail standard library is avail, and the official collection of examples supported by The Avail Foundation is called examples. The Avail Foundation advises Avail developers to follow a reverse DNS name convention, like com.acme.super-neato-project, to prevent collision between module root names among several vendors and projects.

A module root path is actually a conjunction of a binary repository path and a source module path, respectively, separated by a comma , (U+002C). A binary repository path locates a binary file that contains the compiled forms of Avail source modules. A source module path locates a directory containing Avail source modules. The same binary repository path may be used for many source paths. If a binary repository path does not refer to an existing file, then "avail-dev" will create and populate this file as needed. A source path must always refer to an existing directory that is readable by the user running avail-dev.

If AVAIL_ROOTS is not defined, then avail-dev will use the following module roots path by default:

avail=$HOME/.avail/repos/avail.repo,$INSTALL/src/avail;examples=$HOME/.avail/repos/examples.repo,$INSTALL/src/examples

This default is suitable for interacting with the Avail system as shipped by The Avail Foundation, but not for developing your own Avail modules. To develop your own Avail modules, your AVAIL_ROOTS environment variable must at least include a module root specification for the Avail standard library, and it must also include module root specifications for your own Avail projects.

For more information on this topic, please read about 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:

$ avail-dev

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.

Back to the top