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

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

小技巧

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

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

See also the fetch action.

init

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

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

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

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

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

See also the <pkg>-distclean action.

<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

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>"

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"

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

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>-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

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.

If using this action, ensure understanding rebuilds has been read to understand this action's effect.

<pkg>-rebuild-only

Force a rebuild of a specific package.

releng-tool <pkg>-rebuild-only

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 stop and perform no other changes. Users wishing to perform a rebuild to the installation phase are recommended to use <pkg>-rebuild instead.

If using this action, ensure understanding rebuilds has been read to understand this action's effect.

<pkg>-reconfigure

Force a re-configuration of a specific package.

releng-tool <pkg>-rebuild-reconfigure

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

If using this action, ensure understanding rebuilds has been read to understand this action's effect.

<pkg>-reconfigure-only

Force a re-configuration of a specific package.

releng-tool <pkg>-reconfigure-only

Once a package has been configured, the package will not attempt to configure it again. Invoking a re-configuration request will tell releng-tool to re-invoke the configuration step again. This can be useful during times of development where a developer attempts to change a package definition or sources between configuration attempts. After completing a re-configuration, releng-tool will stop and perform no other changes. Users wishing to perform a re-configuration to the installation phase are recommended to use <pkg>-reconfigure instead.

If using this action, ensure understanding rebuilds has been read to understand this action's effect.

<pkg>-reinstall

Force a re-installation of a specific package.

releng-tool <pkg>-reinstall

Once a package has been installed, the package will not attempt to install it again. Invoking a re-installation request will tell releng-tool to re-invoke the installation step again. This can be useful during times of development where a developer attempts to change a package definition or sources between installation attempts.

If using this action, ensure understanding rebuilds has been read to understand this action's effect.

Option arguments

The following outlines available options:

--assets-dir <dir>

Directory to hold cache and download folders instead of using a configured root directory.

备注

Configuring an asset directory override is only helpful when attempting to configure a container for all assets. If a user also specifies --cache-dir or --dl-dir overrides, this argument has no effect.

See also RELENG_ASSETS_DIR.

--cache-dir <dir>

Directory for distributed version control cache information (defaults to <root>/cache).

See also RELENG_CACHE_DIR.

--config <file>

Configuration file to load (defaults to <root>/releng).

--debug

Show debug-related messages.

-D, --development [<mode>]

Enables development mode.

--dl-dir <dir>

Directory for download archives (defaults to <root>/dl).

See also RELENG_DL_DIR.

-F, --force

Triggers a forced request for the releng-tool invoke. This entails:

  • Packages will be processed as if a re-configuration request has been made.

  • If an explicit fetch request is made (fetch or <pkg>-fetch), any packages which cache to a file will have their cache files deleted to be re-fetched.

-h, --help

Show a list of all arguments available by releng-tool.

--images-dir <dir>

Directory for image outputs (defaults to <root>/output/images).

-j, --jobs <jobs>

Numbers of jobs to handle (defaults to 0; automatic).

-L, --local-sources [[<pkg>:]<dir>]

Enables local-sources mode.

Without a directory provided, sources of internal packages will be looked for in the parent directory of the configured root directory. Users may use this argument multiple times to override the local-sources configuration. If a package-specific override is provided, sources for that package will be looked for inside the provided path.

--nocolorout

Explicitly disable colorized output.

小技巧

releng-tool respects the NO_COLOR environment variable, if configured in the running environment.

--out-dir <dir>

Directory for output (builds, images, etc.; defaults to <root>/output).

See also RELENG_OUTPUT_DIR.

--relaxed-args

Do not throw an error when releng-tool is provided unknown arguments.

See also RELENG_IGNORE_UNKNOWN_ARGS.

--root-dir <dir>

Directory to process a releng-tool project (defaults to the working directory).

--sbom-format <fmt>

The format to use when generating a software build of materials (SBOM). Multiple formats can be provided (comma-separated).

Type

Value

CSV

csv

HTML

html

JSON

json

JSON (SPDX)

json-spdx

RDP (SPDX)

rdp-spdx

Text

text (default)

XML

xml

See also sbom.

--quirk <quirk-id>

Allows specifying a runtime quirk for the releng-tool process. This option can be used multiple times to apply multiple quirks.

-V, --verbose

Show additional messages.

--version

Show releng-tool's version.

--werror, -Werror

Treat warnings from releng-tool as errors.