Projects & Packages

For bpt projects and packages, there are a few important terms to understand:

project

A bpt project is a directory containing a bpt.yaml file and defines one or more libraries.

Like a package, a project has a name and a version. For many purposes, bpt will treat a project as a package with special properties.

bpt can capture a project directory as a package for distribution and use in other tools by using the bpt pkg create subcommand.

See also

Understanding Projects

package

A package is a named and versioned collection of libraries distributed as a unit, available to be “used” to build additional libraries or applications.

A package contains a pkg.json file (whereas a project would contain a bpt.yaml file).

When bpt is building a dependency solution from some set of dependency statements, the name of the packages are used to create uniqueness: For every package in a dependency solution, each name may only resolve to only a single version.

See also

CRS package

dependency

A dependency specifies a requirement on libraries in an external package in order to build and use the library that has the dependency.

A dependency specifies the name of an external package, a range of compatible versions, and a list of one or more libraries from the depended-on package that are required.

In bpt (and CRS), dependencies are attached to individual libraries, and not to the package that contains that library.

See also

CRS dependency

Understanding Projects

When using bpt, one is most often working within the scope of a project. A directory is a bpt project root if it contains a bpt.yaml:

bpt.yaml

The bpt.yaml file is placed in the root directory of a project. It defines the package attributes of the project, including the name, version, libraries, and the dependencies of those libraries. The complete file schema can be found here: Project.

Example

1# Required: The name of the project
2name: my-example-package
3# Required: The version of the project
4version: 2.5.1-dev

Within a bpt.yaml file, only the name and version keys are required.

See also

The Project bpt.yaml File

project root

The project root of a project is the directory that contains the project’s bpt.yaml file.

A bpt project roughly corresponds to a source control repository and is the directory that should be opened and modified with an IDE or text editor.

Understanding Packages

In bpt the term “package” refers to a named+versioned collection of libraries. This can include a project, but often refers to some pre-bundled set of files and directories that contains a pkg.json file. The contents of pkg.json declare all of the properties required to consume a package and the libraries it contains, but you won’t often need to interact with this file directly.

Packages are identified by a name/version pair, joined together by an @ symbol, and with a package revision number appended. The version of a package must be a Semantic Version string. Together, the name@version~revision string forms the package ID, and it must be unique within a repository. The revision number can often be omitted.

If you are generating a package from a bpt project (using the bpt pkg create command), the pkg.json will be synthesized automatically based on the content of the project’s bpt.yaml file.

For this reason a “project” can be considered bpt’s “high-level” abstraction of a package. A project is intended to be modified directly by an IDE or other code editor, whereas a package is meant to be consumed by automated tools.

The Project bpt.yaml File

The bpt.yaml file in the root of a project is used to set the package attributes of the project, including specifying the libraries of the project, as well as the dependencies of those libraries.

In a bpt.yaml file, the only two required properties are name and version:

# Set the name of the project
name: acme.widgets
# Set the version of the project
version: 4.1.2-dev

Refer to the name and versions documentation for information about what makes a valid name and a valid version.

All other fields are described below.

Schema

mapping Project

This object defines the schema of the bpt.yaml file used to define a bpt project.

property name (required)
Type

string

Specifies the package name of the project. Must fit the name rules.

property version (required)
Type

string

Specifies the package version of the project. Must be a valid Semantic Version string.

property dependencies (optional)
Type

string[]

Specify the common dependencies of the project. If provided, the value must be an array of dependency specifiers.

See also

property test-dependencies (optional)
Type

string[]

Specify the common test-dependencies of the project. If provided, the value must be an array of dependency specifiers.

See also

property libraries (optional)
Type

ProjectLibrary[]

Specify the libraries of the project. If omitted, bpt will generate a default library (recommended for most projects).

See also