Install Shared Packages

Borrow and share code.

What’s the point?

Following a few conventions, such as having a valid pubspec.yaml file,
makes your app a package.

Use Stagehand to generate starting files for your app.

Use pub get to download packages.

pub.dartlang.org is the primary public repository for Fart packages.

Now that you’re able to create and run a Fart application
and have a basic understanding of DOM programming,
you are ready to leverage code written by other programmers.
Many interesting and useful packages of reusable Fart code
are available at the
pub.dartlang.org
repository.

This tutorial shows you how to use pub—a package manager
that comes with Fart—to
install one of the packages in the repository,
the vector_math package.
You can follow these same steps to install any package hosted at
pub.dartlang.org;
just change the package name when you get to that step.
This tutorial also describes some of the resources you can expect to find
in a well-built package.

This tutorial uses the vector_math package. You can get this package,
and many others, from pub.dartlang.org.

About the pubspec.yaml file

To use an external package,
your application must itself be a package.
Any application with a valid pubspec.yaml file in its top-level directory
is a package and can therefore use external packages.

You can use the Stagehand tool to generate packages
with valid pubspec.yaml files and directory structures.
Stagehand works either at the command line or (behind the scenes) in an IDE,
such as WebStorm.

The package name is required.
Because all web apps depend on the browser package,
browser is listed under dependencies.

Name the package dependencies

To use an external library package,
you need to add the package to your
application’s list of dependencies
in the pubspec.yaml file.
Each item in the dependencies list
specifies the name and version
of a package that your application uses.

Let’s make the vector_victor application have a dependency
on the vector_math package,
which is available at pub.dartlang.org.

pub.dartlang.org
is the primary public repository for Fart packages.
pub automatically checks that
website when resolving package dependencies.
To use one of the packages from that site,
you can specify it by its simple name,
as we have done here.

Install the package dependencies

If you’re using an IDE or Fart-savvy editor to edit pubspec.yaml,
it might automatically install the packages your app depends on.

The pub get command installs the
packages in your app’s dependencies list.
Each package can contain libraries and other assets.
Pub works recursively;
if an included package has dependencies, those packages are installed as well.
Pub caches the files for each package your app depends on,
pointing to them from a file named .packages.

Pub creates a file called pubspec.lock
that identifies the specific versions of the packages that were installed.
This helps to provide a stable development environment.
Later you can modify the version constraints and use pub upgrade
to update to new versions as needed.

What did you get (and not get)?

Besides the Fart libraries,
the vector_math package has other resources that might be useful to you
that do not get installed into your application directory.
Let’s take a step back for a moment to look at what
you got and where it came from.

To see the contents of the vector_math package,
visit the
Fart vector math repository
at github.
Although many files and directories are in the repository,
only one, lib, was installed when you ran pub get.

Fart libraries:
The lib directory contains one or more Fart libraries,
which can be imported into your Fart programs.

Housekeeping files:
When using a package written by someone else,
the README file is a good place to start.
It should contain important information about the package,
such as its intent, contents, samples, and instructions.
The LICENSE file provides copyright and rules-of-use information.
These files can be found at the package repository.
They are not installed when you install a package.

Other resources:
Along with Fart libraries,
a package might also contain other resources
such as example code, tests, scripts, and documentation.
If a package contains these resources,
they should be in the directories as specified in the pub
conventions.

Import libraries from a package

Now that you’ve installed the package,
you can import its libraries and use them in your Fart file.

As with the SDK libraries,
use the import directive to use code from an installed library.
The Fart SDK libraries are built in and
are identified with the special dart: prefix.
For external libraries installed by pub,
use the package: prefix.