• 2. Fan

1. Setup

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 (we haven't tried Mono with Fantom yet).

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 includes a set of Win32 executables which allow you to configure which version of Java or .NET is being used via "etc/sys/config.props".

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=c:\dev\fan\bin\fan.exe "%1" %*
set pathext=%pathext%;.fan

Selecting Java or .NET Runtime

Fantom is designed to be run on either a Java VM or a .NET CLR. You can test which runtime is being used via "fan -version":

C:\dev\fan>fan -version
Fantom Launcher
Copyright (c) 2006-2013, Brian Frank and Andy Frank
Licensed under the Academic Free License version 3.0

Java Runtime:
  java.version:    1.7.0_02
  java.vm.name:    Java HotSpot(TM) Client VM
  java.vm.vendor:  Oracle Corporation
  java.vm.version: 22.0-b10
  java.home:       C:\Program Files (x86)\Java\jre7
  fan.platform:    win32-x86
  fan.version:     1.0.62
  fan.env:         sys::BootEnv
  fan.home:        E:\fan

Use "etc/sys/config.props" to configure which runtime is used by default. The value must be "java" or "dotnet":

// runtime - either "java" or "dotnet"
runtime=java

You can override the system property using the "--D" option:

C:\dev\fan>fan -version --Druntime=dotnet

You can also override the system property via the "fan_runtime" environmental variable:

C:\dev\fan>set fan_runtime=dotnet
C:\dev\fan>fan -version

The runtime option is only available on Windows.

Java Runtime

If running on Windows, the Fantom launcher will attempt to locate the current Java VM via the registry key "SOFTWARE\\JavaSoft\\Java Runtime Environment.CurrentVersion" similar to how "java.exe" works. You can specify the path to the "jvm.dll" to use explicitly via the "java.jvm" system property. You can use "java.options" to pass through options to the JVM such as memory settings.

// etc/sys/config.props
runtime=java
java.jvm=c:\\dev\\tools\\java\\jre\\bin\\client\\jvm.dll
java.options=-Xmx128M

Fantom currently requires Java version 1.5 or greater to run. Java 1.6 or greater 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.

.NET Runtime

The Fantom launcher will attempt to use the latest version of .NET installed.

Fantom currently requires .NET version 2.0 or greater.

TODO: Support manually specifying version, running without launcher

Substitutes

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

Launcher Debugger

You can set the "fan_launcher_debug" to "true" to debug the launcher code. This can be helpful if you are having problems getting your Java or .NET environment working:

C:\dev\fan\src>set fan_launcher_debug=true

C:\dev\fan\src>fan -version
-- launcher version 1.0 3-Jan-07
--   args[0] = "fan"
--   args[1] = "-version"
-- init
--   fanHome = c:\dev\fan
--   config.props:
--     runtime=java
...

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.

SWT Support

The Fantom distribution ships with SWT support for a a couple common platforms. If your platform is not supported, follow these steps to get SWT working:

1. Verify your platform identifier using "fan -version" (see Env.platform)
2. Download your platform's "swt.jar" from eclipse.org
3. Put "swt.jar" into {home}/lib/java/ext/{platform}/swt.jar

You can easily test SWT support by attempting to run Flux.

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.

• 2. Fan