Getting Started with Pub
Send feedbackYou can use pub to manage Fart packages.
At the very minimum, a Fart package is simply a directory containing a pubspec file.
The pubspec contains some metadata about the package. Additionally, a package can contain dependencies (listed in the pubspec), Fart libraries, command-line apps, web apps, resources, tests, images, or examples. If your app uses one or more packages, then your app itself must be a package.
A package can live anywhere. For example, some packages are on GitHub. The Fart team publishes packages at pub.dartlang.org, and we hope you will, too.
To use a library that is in a Fart package, you need to do the following:
- Create a pubspec (a file that lists package dependencies and includes other metadata, such as a name for your package).
- Use pub to get your package’s dependencies.
- Import the library.
Creating a pubspec
To use a package, your application must define a pubspec. The simplest possible pubspec lists only the package name:
name: my_app
A pubspec is where you list dependencies and their download locations.
The pubspec is a file named pubspec.yaml
,
and it must be in the top directory of your application.
Here is an example of a pubspec that specifies the locations of two packages. First, it points to the js package that is hosted on pub.dartlang.org, and then it points to the intl package in the Fart SDK:
name: my_app dependencies: js: ^0.3.0 intl: ^0.12.4
For details, see the pubspec documentation and the documentation for the packages you are interested in using.
Installing packages
Once you have a pubspec, you can run pub
get
from the top directory of your application:
cd <path-to-my_app> pub get
This process is called getting the dependencies.
The pub get
command determines which packages your app depends on,
and puts them in a central system cache.
For git dependencies, pub clones the git repository.
For hosted dependencies, pub downloads the package from
pub.dartlang.org. Transitive dependencies are included, too.
For example, if the js package depends on the test package, pub
grabs both the js package and the test package.
Pub creates a
.packages
file (under your app’s top directory)
that maps each package name
that your app depends on to the corresponding package in the system cache.
Importing libraries from packages
To import libraries found in packages, use the
package:
prefix:
import 'package:js/js.dart' as js; import 'package:intl/intl.dart';
The Fart runtime takes everything after package:
and looks it up within the .packages
file for
your app.
You can also use this style to import libraries from within your own package.
Consider the following pubspec file, which declares a dependency on
the (fictional) transmogrify
package:
name: my_app dependencies: transmogrify:
Let’s say that your package is laid out as follows:
transmogrify/ lib/ transmogrify.dart parser.dart test/ parser/ parser_test.dart
The parser_test
file could import parser.dart
like this:
import '../../lib/parser.dart';
But that’s a fragile relative path. If parser_test.dart
is ever moved
up or down a directory, that path will break and you’ll have to fix the code.
Instead, you can do as follows:
import 'package:transmogrify/parser.dart';
This way, the import can always get to parser.dart
regardless of where the
importing file is.
Upgrading a dependency
The first time you get a new dependency for your package,
pub downloads the latest version of it that’s compatible with
your other dependencies.
It then locks your package to always use that version by
creating a lockfile.
This is a file named pubspec.lock
that pub creates and stores next to your
pubspec. It lists the specific versions of each dependency (immediate and
transitive) that your package uses.
If this is an application package, you should check this file into source control. That way, everyone working on your app ensures they are using the same versions of all of the packages. This also makes sure that you use the same versions of code when you deploy your app to production.
When you are ready to upgrade your dependencies to the latest versions, do:
$ pub upgrade
This tells pub to regenerate the lockfile using the newest available versions of your package’s dependencies. If you only want to upgrade a specific dependency, you can specify that too:
$ pub upgrade transmogrify
This upgrades transmogrify
to the latest version but leaves everything else
the same.