pkl.Project0.25.3

Overview
Properties
Methods
Classes
Type Aliases

module pkl.Project

A manifest that defines the presence of a project.

Module URI:: pkl:Project
Pkl version:: 0.25.3 or higher
Known subtypes:
Known usages:
All versions:

A project is useful for defining dependencies, and also for defining common evaluator settings.

A project is a directory that contains a project file at its root. The project file is a file named PklProject exactly, that amends or embeds "pkl:Project".

When evaluating from the CLI, the project directory can be specified explicitly using --project-dir flag, or is determined implicitly by walking up the working directory, looking for a directory containing a PklProject file.

When using the API libraries (e.g. pkl-swift, pkl-go or pkl-config-java), the project must be explicitly stated via the evaluator builder.

Embedding `Project`

In a project file, instead of amending pkl:Project, it is possible simply set the output.value property of a module to an instance of Project. This allows defining higher levels of abstraction that encapsulate an underlying Project definition.

When defining an abstraction, it is important to:

Set the module's output.value to the underlying project output.
Set projectFileUri to the enclosing module's URI. This is necessary to determine the correct project directory, as well as for resolving local project dependencies correctly.

The newInstance() helper method exists as a convenient way to set this when embedding project definitions.

Example:

module MyTeamProject

import "pkl:Project"

/// The package name, to be prefixed with `myteam`.
packageName: String

project: Project = (Project.newInstance(module)) {
  package {
    name = "myteam.\(packageName)"
  }
}

output {
  value = project
}

Properties(show inherited)

link

hidden

output: ModuleOutput (pkl.base)Source

The output of this module.

Defaults to all module properties rendered as either Pcf or the format specified on the command line.
link

package: Package?

The details for the package represented by this project.

This section is used if publishing this project as a package.
link
tests: Listing<String>(isDistinct)

The tests of the project.
If set, allows running pkl test without specifying the paths to source modules.

Relative paths are resolved against PklProject's enclosing directory.

Glob imports can be useful for defining this property.

Example:
```
tests = import*("**.test.pkl").keys.toListing()
```
link
dependencies: Mapping<String(!contains("/")), (RemoteDependency|LocalDependency)>

The dependencies of this project.
A dependency is a group of Pkl modules and file resources that can be imported within the project. Within the project, a dependency can be referenced via dependency notation, where the name is prefixed with the @ character.

For example, given the following descriptor:
```
dependencies {
  ["birds"] {
    uri = "package://example.com/birds@1.0.0"
  }
}
```
This enables the following snippet:
```
import "@birds/canary.pkl" // Import a module from the `birds` dependency

birdIndex = read("@birds/index.txt") // Read a file from the `birds` dependency
```
A dependency's coordinates can either be specified in the form of a RemoteDependency descriptor, which gets fetched over the network, or an import of another PklProject file, which represents a package that exists locally.

Remote dependencies are fetched over HTTPS. When fetching a remote dependency, two HTTPS requests are made. Given dependency URI package://example.com/foo@0.5.0, the following requests are made:
1. GET https://example.com/foo@0.5.0 to retreive the metadata JSON file.
2. Given the metadata JSON file, make a GET request to the package URI ZIP archive.
If this project is published as a package, these dependencies are included within the published package metadata.

Local project dependencies

A local project can alternatively be used as a dependency. This is useful when structuring a single repository that publishes multiple packages.

To specify a local project dependency, import the relative PklProject file.

The local project dependency must define its own package.

Example:
```
dependencies {
  ["penguins"] = import("../penguins/PklProject")
}
```
Resolving dependencies

Dependencies must be resolved before they can be used. To resolve dependencies, run the CLI command pkl project resolve. This will generate a PklProject.deps.json file next to the PklProject file.

Minimum version selection

Pkl uses the minimum version selection algorithm 1 to resolve dependencies. A dependency is identfied by its package URI, as well as its major semver number.

To determine the resolved dependencies of a project, the following algorithm is applied:
1. Gather all dependencies, both direct and transitive.
2. For each package's major version, determine the highest declared minor version.
3. Write each resolved depenency to sibling file PklProject.deps.json.
link

evaluatorSettings: EvaluatorSettings

If set, controls the base evaluator settings when running the evaluator.

These settings influence the behavior of the evaluator when running the pkl eval, pkl test, and pkl repl CLI commands. Note that command line flags passed to the CLI will override any settings defined here.

Other integrations can possibly ignore these evaluator settings.

Evaluator settings do not get published as part of a package. It is not possible for a package dependency to influence the evaluator settings of a project.
link

projectFileUri: String

The URI of the PklProject file.

This value is used to resolve relative paths when importing another local project as a dependency.

Methods(show inherited)

link

function

getClass(): Class (pkl.base)Source

Returns the class of this.
link

function

toString(): String (pkl.base)Source

Returns a string representation of this.

This method is used to convert the values of string interpolation expressions to strings.
link

function

ifNonNull<Result>(transform: (NonNull) -> Result): Result? (pkl.base)Source

Returns this |> transform if this is non-null, and null otherwise.

This method is the complement of the ?? operator and the equivalent of an Option type's map and flatMap methods.
link

function

hasProperty(name: String): Boolean (pkl.base)Source

Tells if this object has a property with the given name.
link

function

getProperty(name: String): unknown (pkl.base)Source

Returns the value of the property with the given name.

Throws if a property with this name does not exist.
link

function

getPropertyOrNull(name: String): unknown? (pkl.base)Source

Returns the value of the property with the given name.

Returns null if a property with this name does not exist.
link

function

toDynamic(): Dynamic (pkl.base)Source

Converts this object to a Dynamic object.
link

function

toMap(): Map<String, unknown> (pkl.base)Source

Converts this object to a Map.
link

function
relativePathTo(other: Module): List<String> (pkl.base)Source

Returns the relative, descendent directory path between this module and other.
Throws if no such path exists.

For example, if module mod1 has path /dir1/mod1.pkl, and module mod2 has path /dir1/dir2/dir3/mod2.pkl, then mod1.relativePathTo(mod2) will return List("dir2", "dir3").

A common use case is to compute the directory path between a template located at the root of a hierarchy (say rootModule.pkl) and the currently evaluated module (accessible via the module keyword):
```
import "rootModule.pkl" // self-import
path = rootModule.relativePathTo(module)
```
link

function
newInstance(enclosingModule: Module): Project

Instantiates a project definintion within the enclosing module.
This is a convenience method for setting projectFileUri to the enclosing module's URI.

Example:
```
myProject: Project = (Project.newInstance(module)) {
  dependencies { /* etc */ }
}
```

Classes

Type Aliases

link

typealias

LocalDependency = Project(isLocalPklProject, this != module, this.package != null)

A local dependency is another Project that is local to the file system.

To declare, use import("path/to/PklProject")
link

typealias

PackageUri = Uri(startsWith("package:"), hasVersion)
link

typealias
EmailAddress = String(matches(Regex(#".+@\S+|.+<\S+@\S+>"#)))

An email address, conformant to the RFC5322 mailbox specification.
Can be in the form of an address spec, or a named address.

Examples:
- "johnny.appleseed@example.com"
- "Johnny Appleseed <johnny.appleseed@example.com>"
link

typealias

CommonSpdxLicenseIdentifier = "Apache-2.0"|"MIT"|"BSD-2-Clause"|"BSD-3-Clause"|"ISC"|"GPL-3.0"|"GPL-2.0"|"MPL-2.0"|"MPL-1.1"|"MPL-1.0"|"AGPL-1.0-only"|"AGPL-1.0-or-later"|"AGPL-3.0-only"|"AGPL-3.0-or-later"|"LGPL-2.0-only"|"LGPL-2.0-or-later"|"LGPL-2.1-only"|"LGPL-2.1-or-later"|"LGPL-3.0-only"|"LGPL-3.0-or-later"|"EPL-1.0"|"EPL-2.0"|"UPL-1.0"|"BSL-1.0"|"Unlicense"

Common software licenses in the SPDX License List.

pkl.Project0.25.3

Embedding Project

Properties(show inherited)

Local project dependencies

Resolving dependencies

Minimum version selection

Methods(show inherited)

Classes

Type Aliases

Embedding `Project`