How To Setup a Fantom Project
Article 3 of Fantom For Beginners
1st March 2014

As a serious programmer you don't want to be a script kiddie forever so lets look at a typical directory structure for a simple Fantom project:

myFantomApp/
 |-- doc/
 |    `-- pod.fandoc
 |-- fan/
 |    |-- Main.fan
 |    `-- *.fan
 |-- test/
 |    `-- *.fan
 `-- build.fan

All your fantom application code goes in the fan/ directory, including the special Main.fan (more later). Put your tests (that is, any class that extends sys::Test) in the test/ directory.

pod.fandoc

When viewing your fantom documentation, (for example, with Explorer or when uploaded to a Pod Repository), then pod.fandoc is what's appended to the bottom of your API index page. Essentially it's your 1 page of documentation / user guide.

See the Fantom Widget Toolkit (FWT) documentation for a live example.

A typical pod.fandoc usually starts with an Overview section:

Overview [#overview]
********************
My AWESOME fantom app!

...

See the Fandoc documentation for more information on the format of .fandoc files.

Note pod.fandoc is optional, a nice to have. Think of it as your readme.txt.

build.fan

build.fan is what binds it all together. It's a fantom build script, akin to Ruby's Rake. Java people can think of it as Ant build file, a Maven pom or a gradle script.

A simple build.fan for our project would look like:

using build

class Build : BuildPod {
    new make() {
        podName    = "myFantomApp"
        summary    = "My AWESOME fantom app"
        depends    = ["sys 1.0"]
        srcDirs    = [`fan/`, `test/`]
        resDirs    = [`doc/`]
    }
}

Your build.fan generally builds a fantom Pod which is similar to a Java .jar file or a Ruby gem. (Note it's the BuildPod superclass that does all the hard work, all we do is configure it!)

depends lists the pods your project depends on; the sys pod always needs to be there. Note that the syntax for dependant pods requires both the pod name and the version, see Depend in the official documentation for full details.

srcDirs and resDirs are Fantom URIs, hence the back quotes. Each directory is relative to build.fan and must end with a forward slash /.

See the Fantom site for official documentation Fantom Build Scripts.

Code Directories

After a while your fan/ dir is going to fill up with classes and you are going to want to organise them in sub-directories. Not a problem.

my-fantom-app/
 ...
 |-- fan/
 |    |-- internal/
 |    |     `-- Hidden.fan
 |    |-- public/
 |    |     `-- Awesome.fan
 |    `-- Main.fan
 ...

Just ensure that each source directory is listed in srcDirs of your build.fan.

srcDirs = [`fan/`, `fan/internal/`, `fan/public/`, `test/`]

Note that srcDirs (and resDirs) are not nested, so including fan/ does NOT automatically include sub-directories. Hence the need to include fan/, fan/internal/ and fan/public/ above.

Also, note that directories are NOT like packages in Java. Regardless of the source directory, the compiled .fcode files are all lumped together in one directory. This means all your source files need different names, even if they are in different directories.

So, now we've created a sample Fantom project, how do we build and run it? Click next.

>>> Next >>>

Edits

• 31 July 2016 - Removed link to Genesis as it is now deprecated.
• 1 Mar 2014 - Added link to Genesis project creator app.
• 6 Nov 2013 - Original article.

---

---

Discuss