Fantom

 

Env

Overview

The sys::Env class is used to access and customize the Fantom environment. Key aspects of the runtime delegate to the currently installed environment including:

  • standard I/O
  • home, working, and temporary directories
  • pod resolution
  • config property resolution
  • locale property resolution
  • Java classloading resolution (when using JVM)

Directory Structure

The standard directory structure for Fantom installations is:

lib/
  fan/
    podA.pod
    podB.pod
    .. other pods
  java/
    .. jar files
  dotnet/
    .. .NET DLLs
etc/
  sys/
    config.props
    ... other sys config/runtime files
  build/
    config.props
    ... other build config/runtime files
  podA/
    config.props
    ... other config/runtime files
  podB/
    config.props
    ... other config/runtime files

The top level "lib" directory is used to store library files which contain code. The directories under "lib" are organized by platform: fan, java, dotnet. The ".pod" files themselves are stored under "lib/fan/".

The top level "etc" directory is used to store system wide configuration files and other files that a pod might need at runtime. The directories under "etc" are organized by pod - each subdirectory under "etc" should match a pod name.

BootEnv

The default envirnoment used to boots up a Fantom environment is called the BootEnv. The homeDir of the BootEnv is always relative to the location used to launch Fantom (fan.exe or fan bash script).

Core libraries like sys must be loaded out of the BootEnv.

Setting Env

You can override the default environment using the FAN_ENV environmental variable. This variable should map to a qualified type name of the Env subclass to use. The class must have a default no-argument constructor.

The BootEnv is used to load the environment class specified. This requires that the pod defining your environment is located under "{homeDir}/lib/fan/".

PathEnv

The util::PathEnv is a simple env implementation that uses a search path instead of requiring all your files be located under the "fan.home". The search path is specified with the FAN_ENV_PATH envirnomenal variable. For example:

C:\dev\fan>set FAN_ENV=util::PathEnv
C:\dev\fan>set FAN_ENV_PATH=/dev/work/

The directory specified should be structured using the standard conventions. In the example above we would look for pods in "/dev/work/lib/fan/". You can specify more than one directory using your operating system's path separator. Note that the path always implicitly includes "fan.home" as the last directory in search path.

The list of paths is specified in priority order. The first directory in the path is used for workDir. Priority order is used to resolve pods and configuration files. Typically you will use this mechanism to keep a pristine boot directory, and do pod development and configuration overrides in a separate working directory.

For example let's consider this directory structure:

boot/
  lib/
    fan/
      podA.pod
      podB.pod
work/
  lib/
    fan/
      podB.pod
      podC.pod

In this configuration, things would be resolved as follows:

podA  =>  boot/lib/fan/podA.pod
podB  =>  work/lib/fan/podB.pod
podC  =>  work/lib/fan/podC.pod

Note how work directory trumps boot for resolution of podB even though it exists in both directories.

JarDistEnv

The JarDistEnv is a JVM only environment which is used to deploy a set of Fantom pods as a single Java JAR file. A JarDistEnv differs from other environments in that it has no access to the standard directory structure on the file system. Rather everything the environment might need is self contained as resources inside the JAR file.

The following features are not supported in the JarDistEnv:

  • type database
  • file system overrides for config and locale
  • homeDir, workDir, tempDir all default to current working directory

See the build::JarDist task and example script for how to build a JAR for deployment.