Setup

Unix Setup • Windows Setup • Java Extensions • JLine • Env

Unix Setup

The Fantom distribution is packaged as a zip file. Once unpacked you should add "bin" into your path:

PATH=$PATH:/apps/fantom/bin

The Fantom launchers are implemented as a set of Bash shell scripts which all route to common code sourced in "bin/fanlaunch". The current implementation is pretty simple and requires that you have a "java" command available in your environment.

If the unpacked zip file doesn't have the executable permission set on script files, then the "adm/unixsetup" script will automatically call "chmod +x" on all the shell scripts and Fan build scripts:

bash adm/unixsetup

Executable Scripts

Fantom allows the first line of a source file to start with "#!" to run as a Unix shell script:

#! /usr/bin/env fan
class Script { static Void main() { echo("hi") } }

chmod +x myscript.fan
./myscript.fan

Windows Setup

The Fantom distribution is packaged as a zip file. Once unzipped, you should add the "bin" directory to your path:

PATH=%PATH%;C:\dev\fan\bin

The Fantom launchers are implemented as a set of Windows Batch scripts which all route to common code in "bin\fanlaunch.bat". If your path is configured properly, you should be able to run

fan -version

Executable Scripts

You can always use the fan launcher to run a script by passing it on the command line. But ideally you will want to setup your environment so that you can call fan scripts directly as an executable file:

fan build.fan    // call using fan launcher explicitly
build            // call as executable script

The following series of console commands will make ".fan" files executable assuming we installed to "c:\dev\fan":

assoc .fan=Fan
ftype Fan=cmd.exe /c call "C:\dev\fan\bin\fan.bat" "%1" %*
set pathext=%pathext%;.fan

Java Runtime

The launcher for Windows and Unix determines which java to use in the following order:

  1. If the FAN_JAVA environment variable is set, then we assume it points to the "java.exe" to run.
  2. If the JAVA_HOME environment variable is set, then we use "${JAVA_HOME}/bin/java"
  3. Otherwise, we fallback to the system "java" executable

You can configure the JVM options by editing "etc/sys/config.props" and setting the "java.options" property. This is useful for modifying memory settings for the JVM.

// etc/sys/config.props
java.options=-Xmx128M

Fantom currently requires Java version 1.8 or greater to run. Java 1.8 is required to compile from source.

You can also run Fantom directly without the launcher by adding "sys.jar" to your classpath and ensuring either the "fan_home" environment variable is set or the "fan.home" Java system property is set:

// via env var
C:\>set fan_home=c:\dev\fan
C:\>java -cp %fan_home%\lib\java\sys.jar fanx.tools.Fan -version

// via system property
C:\>java -cp c:\dev\fan\lib\java\sys.jar -Dfan.home=%fan_home% fanx.tools.Fan -version

Each of the tools maps to a different class, for example to run fant then run the Java class fanx.tools.Fant.

Substitutes

Another feature of the launcher scripts is the ability to map specific script files to use an alternate Fantom runtime. This technique is used to manage the bootstrap build process.

Fantom Programs as Windows Services

The Fantom installation includes a binary called fansc.exe in the "bin\" directory of the installation. The "fansc" (Fan Service Control) binary can be used to install and uninstall a Fantom program as a Windows Service. You can run the program without any arguments to see the usage. There are a few requirements for using fansc

  1. Create a windows batch file launcher for your Fantom program. You can use any of the launchers in the "bin\" directory as a template.
  2. You must run the "fansc" program from a command prompt with elevated/administrator privileges.

The following example illustrates installing the default WispService as a windows service:

// Create the bin/wisp.bat file with these contents:
@echo off
call %~dp0\fanlaunch.bat Fan wisp::WispService %*

// Now install it, configuring it to run on port 8080
C:\dev\fantom\fan\bin\> fansc.exe install MyWispService C:\dev\fantom\fan\bin\wisp.bat -port 8080

Java Extensions

You can add Java JARs to the following directories to have them automatically loaded by the Fantom class loader:

  • {home}/lib/java/ext/
  • {home}/lib/java/ext/{platform}

The platform directory is used for JARs which vary by platform. For example the SWT JARs are distributed in platform specific directories. You can verify your platform running "fan -version".

The preferred mechanism to add Java JARs into your Fantom environment is to convert them into a pod.

Also see JavaFFI.

JLine

Running command line applications such as fansh in the Java VM can be unpleasant in Unix and OS X environments because control keys such as the arrow keys are not handled. You can add JLine to your system classpath to fix this. The built-in bash launcher scripts will automatically add "lib/java/jline.jar" into the classpath. Both JLine3 LineReader and JLine2 ConsoleReader are supported. Although more features are supported if using JLine3. If JLine is not found, then java.io.Console is used as a fallback. To integrate command line support into your application use the Console API.

Newer versions of Java do not support adding jars to {java-home}/lib/ext. Instead if you would like jline to be globally available across all installations of Fantom, then set the classpath as environment variable like this:

export CLASSPATH=/work/stuff/jline/jline-3.9.0.jar

Env

The default behavior of Fantom is to manage all its files under the installation directory. But you can boot Fantom using alternative environments to customize how your deployment is structured. See Env for details.

Haxall 3.1.10 ∙ 28-Jun-2024 15:01 EDT