Glossary of package terms

The following terms are used in the documentation forpackagement management andthe pub tool.

Application package

A package that is not intended to be used as a library. Application packages mayhave dependencies on other packages, but are never depended onthemselves. They are usually meant to be run directly, either on the commandline or in a browser. The opposite of an application package is a librarypackage.

Application packages should check their lockfiles into sourcecontrol, so that everyone working on the application and every location theapplication is deployed has a consistent set of dependencies. Because theirdependencies are constrained by the lockfile, application packages usuallyspecify any for their dependencies’ version constraints.

Dependency

Another package that your package relies on. If your package wants to importcode from some other package, that package must be a dependency. Dependenciesare specified in your package’s pubspec and described inPub Dependencies.

To see the dependencies used by a package, use pub deps.

Entrypoint

In the general context of Dart, an entrypoint isa Dart library that is directly invoked by a Dart implementation. When youreference a Dart library in a <script> tag or pass it as a command-lineargument to the standalone Dart VM, that library is the entrypoint. In otherwords, it’s usually the .dart file that contains main().

In the context of pub, an entrypoint package or root package is the rootof a dependency graph. It will usually be an application. When you run your app,it’s the entrypoint package. Every other package it depends on will not be anentrypoint in that context.

A package can be an entrypoint in some contexts and not in others. Say yourapp uses a library package A. When you run your app, A is not the entrypointpackage. However, if you go over to A and execute its tests, in thatcontext, it is the entrypoint since your app isn’t involved.

Entrypoint directory

A directory inside your package that is allowed to containDart entrypoints.

Pub has a whitelist of these directories: benchmark, bin, example,test, tool, and web. Any subdirectories of those (except bin) may alsocontain entrypoints.

Immediate dependency

A dependency that your package directly uses itself. Thedependencies you list in your pubspec are your package’s immediate dependencies.All other dependencies are transitive dependencies.

Library package

A package that other packages can depend on. Library packages can havedependencies on other packages and can be dependenciesthemselves. They can also include scripts to be run directly. Theopposite of a library package is an application package.

Don’t check the lockfile of a library package into sourcecontrol, since libraries should support a range of dependency versions. Theversion constraints of a library package’simmediate dependencies should be as wide as possible while stillensuring that the dependencies will be compatible with the versions that weretested against.

Since semantic versioning requiresthat libraries increment their major version numbers for any backwardsincompatible changes, library packages will usually require their dependencies’versions to be greater than or equal to the versions that were tested and lessthan the next major version. So if your library depended on the (fictional)transmogrify package and you tested it at version 1.2.1, your versionconstraint would be ^1.2.1.

Lockfile

A file named pubspec.lock that specifies the concrete versions and otheridentifying information for every immediate and transitive dependency a packagerelies on.

Unlike the pubspec, which only lists immediate dependencies and allows versionranges, the lock file comprehensively pins down the entire dependency graph tospecific versions of packages. A lockfile ensures that you can recreate theexact configuration of packages used by an application.

The lockfile is generated automatically for you by pub when you runpub get, pub upgrade,or pub downgrade.If your package is an application package, you will typically check this intosource control. For library packages, you usually won’t.

SDK constraint

The declared versions of the Dart SDK itself that a package declares that itsupports. An SDK constraint is specified using normalversion constraint syntax, but in a special _environment_section in the pubspec.

Source

A kind of place that pub can get packages from. A source isn’t a specific placelike the pub.dev site or some specific Git URL. Each source describes a generalprocedure for accessing a package in some way. For example, git is one source.The git source knows how to download packages given a Git URL. Severaldifferent supported sources are available.

System cache

When pub gets a remote package,it downloads it into a single system cache directory maintained bypub. On Mac and Linux, this directory defaults to ~/.pub-cache.On Windows, the file lives in %APPDATA%\Pub\Cache\bin,though its exact location may vary depending on the Windows version.You can specify a different location using thePUB_CACHE environment variable.

Once packages are in the system cache,pub creates a .packages file that maps each packageused by your application to the corresponding package in the cache.

You only have to download a given version of a package onceand can then reuse it in as many packages as you would like.You can delete and regenerate your .packages file without having to access the network.

Transitive dependency

A dependency that your package indirectly uses because one of its dependenciesrequires it. If your package depends on A, which in turn depends on B whichdepends on C, then A is an immediate dependency and Band C are transitive ones.

Uploader

Someone who has administrative permissions for a package.A package uploader can upload new versions of the package,and they can also add and remove other uploadersfor that package.

If a package has a verified publisher,then all members of the publisher can upload the package.

Verified publisher

One or more users who own a set of packages.Each verified publisher is identified by a verified domain name, such asdart.dev.For general information about verified publishers,see the verified publishers page.For details on creating a verified publisherand transferring packages to it,see the documentation for publishing packages.

Version constraint

A constraint placed on each dependency of a package thatspecifies which versions of that dependency the package is expected to workwith. This can be a single version (0.3.0) or a range of versions (^1.2.1).While any is also allowed, for performance reasons we don’t recommend it.

For more information, seeVersion constraints.

Library packages should always specify version constraintsfor all of their dependencies, but application packagesshould usually allow any version of their dependencies, since they use thelockfile to manage their dependency versions.

For more information, seePub Versioning Philosophy.