Arguments¶

The command line can be used to specify a single action to perform or provide various options to configure the releng-tool process. Options can be provided before or after an action (if an explicit action is provided). By default, if a user does not specify an action, it is assumed that all steps are to be performed.

releng-tool <options> [action]

Global actions¶

The following outlines available global actions:

`clean`¶

Clean (removes) a series of folders holding content such as extracted archives, built libraries and more.

releng-tool clean

Images and downloaded assets/cache are not removed (see mrproper for a more through all cleaning operation). This clean operation will remove files based off the configured output directory. If an output directory is provided (i.e. --out-dir <dir>) during a clean event, select folders inside this directory will be removed instead of the output directory (if any) found in the root directory.

`distclean`¶

Added in version 0.6.

Perform a more extreme pristine clean of the releng-tool project.

releng-tool distclean

This request removes the cache/, dl/ and output/ directories found in the root directory or overridden by respective arguments, as well as any mode file flags which may be set. See also the clean or mrproper actions.

`extract`¶

All packages will be processed up to the extraction phase (inclusive).

releng-tool extract

`fetch`¶

All packages will be processed up to the fetch phase (inclusive).

releng-tool fetch

Tip

When a fetch is explicitly requested for DVCS sources (e.g. Git), the local cache kept for the repository will be updated against the configured remote. This can be helpful for packages which use a branch for their target revision, or wishing to use a tag which has been moved.

Users may also take advantage of explicit re-fetching of downloaded artifacts when using this action in combination with the -F, --force argument.

See also offline builds and the fetch-full action.

`fetch-full`¶

Added in version 1.3.

All packages will be processed up to the extraction phase, as well as any post-extraction fetch operations for supported package types (e.g. fetching Cargo dependencies).

releng-tool fetch-full

`init`¶

Added in version 0.6.

Initialize an empty root directory with a sample project.

releng-tool init

`licenses`¶

A request to generate all license information for the project.

releng-tool licenses

Note that license information requires acquiring license documents from packages. Therefore, packages will be fetched/extracted if not already done.

`mrproper`¶

Added in version 0.6.

Perform a pristine clean of the releng-tool project.

releng-tool mrproper

This request removes the output/ directory found in the root directory or overridden by the --out-dir argument, as well as any mode file flags which may be set. The cache/ and dl/ directories will remain untouched. See also the clean or distclean actions.

`patch`¶

All packages will be processed up to the patch phase (inclusive).

releng-tool patch

`punch`¶

Added in version 1.2.

A punch request acts in a similar fashion as if no global action was provided. All configured packages will be processed to their completion and any post actions will be run. The difference between a default run and a punch run is when a punch run is requested, any packages that have already been processed will be re-invoked as if a re-configuration request has been made.

This allows a developer to easily attempt to rebuild all packages in their project when multiple packages have been updated.

releng-tool punch

`sbom`¶

Added in version 0.14.

A request to generate a software build of materials (SBOM) for the project.

releng-tool sbom

By default, a releng-tool run will generate an SBOM file at the end of a run. This action can be used to generate an SBOM without requiring a build.

`state`¶

Added in version 0.17.

A request to dump active state information for a project.

releng-tool state

A state request can be used to dump any active configuration and operating modes.

Package actions¶

The following outlines available package-specific actions:

`<pkg>-build`¶

Performs the build stage for the package.

releng-tool <pkg>-build

On success, the specified package will have completed its build. If a package has any package dependencies, these dependencies will be processed before the specified package. If the provided package name does not exist, a notification will be generated.

`<pkg>-clean`¶

Cleans the build directory for package (if it exists).

releng-tool <pkg>-clean

`<pkg>-configure`¶

Performs the configure stage for the package.

releng-tool <pkg>-configure

On success, the specified package will have completed its configuration stage. If a package has any package dependencies, these dependencies will be processed before the specified package. If the provided package name does not exist, a notification will be generated.

`<pkg>-distclean`¶

Added in version 0.8.

Perform a pristine clean of a releng-tool package.

releng-tool <pkg>-distclean

This request not only removes the build directory but also any cached file or directory associated with the package. See also the <pkg>-clean action.

`<pkg>-exec "<cmd>"`¶

Added in version 0.12.

Changed in version 1.4: Support accepting arguments after --.

Invokes a provided command in the package’s build output directory. This package action can be useful for developers attempting to develop/debug a specific package, allowing an easy way to issue commands in a package’s directory without having to manually venture to a package’s output directory. Packages will need to be processed to at least the patch stage before a provided command is issued.

An example is as follows:

releng-tool libfoo-exec "mycmd arg1 arg2"

Alternatively, arguments can be passed using the format:

releng-tool libfoo-exec -- mycmd arg1 arg2

Package environment variables will be available for the invoked command.

`<pkg>-extract`¶

Performs the extraction stage for the package.

releng-tool <pkg>-extract

On success, the specified package will have completed its extraction stage. If the provided package name does not exist, a notification will be generated.

`<pkg>-fetch`¶

Performs the fetch stage for the package.

releng-tool <pkg>-fetch

On success, the specified package stage will have completed its fetch stage. If the provided package name does not exist, a notification will be generated.

`<pkg>-fetch-full`¶

Added in version 1.3.

Performs the fetch and extraction stages for the package, as well as any post-extraction fetch operations for the supported package type (e.g. fetching Cargo dependencies).

releng-tool <pkg>-fetch-full

If the provided package name does not exist, a notification will be generated.

`<pkg>-fresh`¶

Added in version 1.4.

Prepares a package to be ready to invoke its configuration stage. A successful end state results in the specified package will have completed its patch stage. If the package has already been processed before, it will be cleaned ahead of time to start fresh.

releng-tool <pkg>-fresh

If the provided package name does not exist, a notification will be generated.

`<pkg>-install`¶

Performs the installation stage for the package.

releng-tool <pkg>-install

On success, the specified package will have completed its installation stage. If a package has any package dependencies, these dependencies will be processed before the specified package. If the provided package name does not exist, a notification will be generated.

`<pkg>-license`¶

Added in version 0.8.

A request to generate the license information for a specific package in a project.

releng-tool <pkg>-license

Note that license information requires acquiring license documents from the package itself. Therefore, the package will be fetched/extracted if not already done.

`<pkg>-patch`¶

Performs the patch stage for the package.

releng-tool <pkg>-patch

On success, the specified package will have completed its patch stage. If the provided package name does not exist, a notification will be generated.

`<pkg>-rebuild`¶

Force a rebuild of a specific package.

releng-tool <pkg>-rebuild

Once a package has been built, the package will not attempt to be built again. Invoking a rebuild request will tell releng-tool to re-invoke the build step again. This can be useful during times of development where a developer attempts to change a package definition or sources between build attempts. After completing a rebuild, releng-tool will perform the remaining stages of the package (i.e. the installation phase). Users wishing to perform only the rebuild stage are recommended to use <pkg>-rebuild-only instead.