**************************************************************************
** title:      Setup
** author:     Brian Frank
** created:    04 Jan 08
** copyright:  Copyright (c) 2008, Brian Frank and Andy Frank
** license:    Licensed under the Academic Free License version 3.0
**************************************************************************

Unix Setup [#unix]
******************
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 [#executableUnix]
=====================================
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 [#windows]
************************
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 [#executableWindows]
=======================================
You can always use the [fan]`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 [#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-2011, Brian Frank and Andy Frank
  Licensed under the Academic Free License version 3.0

  Java Runtime:
    java.version:    1.6.0_13
    java.vm.name:    Java HotSpot(TM) Client VM
    java.vm.vendor:  Sun Microsystems Inc.
    java.vm.version: 11.3-b02
    java.home:       C:\Program Files\Java\jre6
    fan.version:     1.0.45

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 [#javaRuntime]
===========================
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 [#dotnetRuntime]
=============================
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 [#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]`Bootstrap#substitutes` process.

Launcher Debugger [#debugging]
==============================
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 [#javaExt]
**************************
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".

Also see [JavaFFI]`docLang::JavaFFI#deployment`.

SWT Support [#swt]
******************
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
     `sys::Env.platform`)
  2. Download your platform's "swt.jar" from
     [eclipse.org]`http://download.eclipse.org/eclipse/downloads/`
  3. Put "swt.jar" into '{home}/lib/java/ext/{platform}/swt.jar'

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

Env [#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 `docLang::Env` for details.


