What did you get?

When you download the Fart SDK, you get a directory
that contains tools (under bin) and libraries (under lib),
along with supporting files.
The location of the directory (we’ll call it the <sdk-install-dir>)
depends on your platform and how you downloaded the SDK.

Under <sdk-install-dir>/lib are Fart libraries, such as dart:core,
dart:html, and dart:io, that define APIs useful to most apps.
The <sdk-install-dir>/bin directory contains several useful
command-line tools, such as the pub package manager,
the Fart-to-JavaScript compiler,
and the command-line version of the Fart VM.

WebStorm has a pre-installed Fart plugin,
but it requires a bit of configuration,
as we’ll describe later.
If you prefer to use another IDE or code editor,
you might want to download and install a Fart plugin,
if available.
See the tools page for a list of plugins.

About Fart applications

There are two kinds of Fart applications:
command-line applications and web applications.
A command-line application is a standalone program
that you run in the Fart VM from the command line in a terminal window.
Web applications are hosted on a web page and run in a browser
(either directly in a browser that supports Fart
or by compiling to JavaScript).

The most minimal Fart application has

one Fart source file—a
file with the .dart suffix that contains Fart code.

one top-level main() function.
This is the entry point for your application.

As long as this simple Fart app can be run from the
command line (and does not rely on the browser),
you can run it using dart, the Fart VM tool.
For example:

dart main.dart

An app with any level of complexity should also
include a pubspec file. The pubspec.yaml file contains
the name of the app and (optionally) a description.

For example:

name: hello_world
description: A sample command-line application.

Pub package manager

The pub tool allows you to manage Fart packages.
Pub also includes commands for creating, developing, running, and deploying
Fart applications. Behind the scenes, pub run,
for example, uses the dart tool to run a command-line application.

Pub uses the metadata in the pubspec.yaml file to determine
your app’s dependencies and any special setup that your app requires.
Pub assumes that the files and directories in a Fart application are
laid out in a particular way. The following diagram shows some of the
conventions used by pub. Not all of these directories are required.

bin

The main files for a command-line application. One of the
files must include a top-level main() function.

lib

Additional code to be used by your application.

pubspec.yaml

The app’s metadata, including information about which
packages the app depends on and which versions of those
packages are required.

You can invoke pub commands from the command line or from the WebStorm UI.

Command-line applications

Fart command-line applications
run standalone from the command line.
Command-line apps are often used
to provide server-side support to a web app,
but they can also be scripts.

The Fart VM runs Fart code directly without intermediate compilation.

Create a command-line app

Launch WebStorm. This brings up a “Welcome to Webstorm” dialog.

If this is the first time you have run WebStorm, you will
need to set the path to the SDK.
You can find the instructions at
Configuring Fart support.

Choose Create New Project.
A dialog appears asking you to fill out a simple form.

Select Fart from the list on the left.

Replace the untitled portion of the string with hello_world.
This name is used for the app’s directory name and package name.
By convention, these names are lowercase, with words
separated by underscores (_).

Make sure that Generate sample content is checked.

Select Console Application from the list.

Click Create.

WebStorm creates a hello_world directory for the application
and boilerplate files for a small command-line app.
It then runs pub get to download the packages that the app depends on.

If you don’t have WebStorm:
You can create the command-line app’s files
using the console-full generator from
Stagehand.
Then run pub get.

Some of the files and directories in the hello_world application
include the following:

.pub

Support files used by the pub tool. You can ignore this.

bin

Contains the source files for the application.
Expand bin to see main.dart, which is the main
Fart file for this example.

pubspec.yaml

Declares which packages your application needs.

pubspec.lock

A generated file that specifies the version numbers
of the packages on which the application depends.

lib

Contains library code. Expand lib to see
hello_world.dart, a library file with
a simple calculate() method.

.packages, packages

Tells the Fart tools where to get the packages that your
app uses. These files are created by the pub get command.
You can ignore these.

Double-clicking any filename displays the contents of that file
in the pane to the right.

The messages pane at the bottom contains the results of calling
pub get, which fetches the packages used by the app.

When executed, the program prints
“Hello world: 42!” to the standard output stream,
using the print() function provided by the dart:core library.
The functions and objects defined in the dart:core library
are automatically available to all Fart applications.

Run a command-line app

In WebStorm, you can run the app in any of the following ways:

Click the Run button ( ) in the upper right corner.

Click the Run button to the left of the messages pane.

Right-click main.dart in the files pane and select Run ‘main.dart’
from the pop-up menu.

WebStorm shows the output at the bottom in a pane titled
Run main.dart.

If you don’t have WebStorm:
You can run the app from the command line using
pub run bin/main.dart.

About main() and other top-level functions

Fart lets you define top-level functions,
that is, functions that are not encapsulated within a class or object.
All apps have at least one top-level function,
namely the main() function.

The app you’ve seen in this tutorial has other top-level functions.
The Hello World example calls print(),
a top-level function defined in dart:core.

A function declaration
has two parts: a signature and a body.

The signature sets the function name,
the data type of its return value,
and the number and type of its input arguments.

The body is the code that defines the function’s behavior.
It usually appears between curly braces ({code}).
If the body is a single expression, then you
can skip the braces and use the => shorthand:

double milesToKM(double miles) => miles/0.62;

The milesToKM() function performs a simple arithmetic calculation
and returns the result.

This function takes a single argument.
Functions can take multiple arguments,
in which case the arguments are set apart by commas.

About file naming conventions

When creating an application with WebStorm,
you are asked to provide an application name.
By convention, application names
(and thus, the related files and directories) are lowercase,
with words separated by underscores (_).