Commands¶

Lifecycle commands¶

Lifecycle commands can take an optional parameter <part-name>. When a part name is provided, the command applies to the specific part. When no part name is provided, the command applies to all parts.

build¶

Build artefacts defined for a part. If part names are specified only those parts will be built, otherwise all parts will be built.

Usage

rockcraft build [options]

Options

--build-for: Set architecture to build for.
--debug: Shell into the environment if the build fails.
--destructive-mode: Build in the current host.
--ignore: Bypass a restriction to use an unsupported feature.
--platform: Set platform to build for.
--pro: Enable Ubuntu Pro services for this command. Supported values include: ‘esm-apps’, ‘esm-infra’, ‘fips’, ‘fips-preview’, ‘fips-updates’. Multiple values can be passed separated by commas. Note: This feature requires an Ubuntu Pro compatible host and build base.
--shell: Shell into the environment in lieu of the step to run.
--shell-after: Shell into the environment after the step has run.
--use-lxd: Build in a LXD container.

Global options

-h or --help: Show this help message and exit.
-q or --quiet: Only show warnings and errors, not progress.
-v or --verbose: Show debug information and be more verbose.
--verbosity: Set the verbosity level to ‘quiet’, ‘brief’, ‘verbose’, ‘debug’ or ‘trace’.
-V or --version: Show the application version and exit.

clean¶

Clean up artefacts belonging to parts. If no parts are specified, remove the packing environment.

Usage

rockcraft clean [options]

Options

--destructive-mode: Build in the current host.
--platform: Platform to clean.
--use-lxd: Build in a LXD container.

Global options

-h or --help: Show this help message and exit.
-q or --quiet: Only show warnings and errors, not progress.
-v or --verbose: Show debug information and be more verbose.
--verbosity: Set the verbosity level to ‘quiet’, ‘brief’, ‘verbose’, ‘debug’ or ‘trace’.
-V or --version: Show the application version and exit.

pack¶

Process parts and create the final artefact.

Usage

rockcraft pack [options]

Options

--build-for: Set architecture to build for.
--debug: Shell into the environment if the build fails.
--destructive-mode: Build in the current host.
--enable-fetch-service: ==SUPPRESS==.
--ignore: Bypass a restriction to use an unsupported feature.
--output or -o: Output directory for created packages.
--platform: Set platform to build for.
--pro: Enable Ubuntu Pro services for this command. Supported values include: ‘esm-apps’, ‘esm-infra’, ‘fips’, ‘fips-preview’, ‘fips-updates’. Multiple values can be passed separated by commas. Note: This feature requires an Ubuntu Pro compatible host and build base.
--shell: Shell into the environment in lieu of the step to run.
--shell-after: Shell into the environment after the step has run.
--use-lxd: Build in a LXD container.

Global options

-h or --help: Show this help message and exit.
-q or --quiet: Only show warnings and errors, not progress.
-v or --verbose: Show debug information and be more verbose.
--verbosity: Set the verbosity level to ‘quiet’, ‘brief’, ‘verbose’, ‘debug’ or ‘trace’.
-V or --version: Show the application version and exit.

prime¶

Prepare the final payload to be packed, performing additional processing and adding metadata files. If part names are specified only those parts will be primed. The default is to prime all parts.

Usage

rockcraft prime [options]

Options

--build-for: Set architecture to build for.
--debug: Shell into the environment if the build fails.
--destructive-mode: Build in the current host.
--ignore: Bypass a restriction to use an unsupported feature.
--platform: Set platform to build for.
--pro: Enable Ubuntu Pro services for this command. Supported values include: ‘esm-apps’, ‘esm-infra’, ‘fips’, ‘fips-preview’, ‘fips-updates’. Multiple values can be passed separated by commas. Note: This feature requires an Ubuntu Pro compatible host and build base.
--shell: Shell into the environment in lieu of the step to run.
--shell-after: Shell into the environment after the step has run.
--use-lxd: Build in a LXD container.

Global options

-h or --help: Show this help message and exit.
-q or --quiet: Only show warnings and errors, not progress.
-v or --verbose: Show debug information and be more verbose.
--verbosity: Set the verbosity level to ‘quiet’, ‘brief’, ‘verbose’, ‘debug’ or ‘trace’.
-V or --version: Show the application version and exit.

pull¶

Download or retrieve artefacts defined for a part. If part names are specified only those parts will be pulled, otherwise all parts will be pulled.

Usage

rockcraft pull [options]

Options

--build-for: Set architecture to build for.
--debug: Shell into the environment if the build fails.
--destructive-mode: Build in the current host.
--ignore: Bypass a restriction to use an unsupported feature.
--platform: Set platform to build for.
--pro: Enable Ubuntu Pro services for this command. Supported values include: ‘esm-apps’, ‘esm-infra’, ‘fips’, ‘fips-preview’, ‘fips-updates’. Multiple values can be passed separated by commas. Note: This feature requires an Ubuntu Pro compatible host and build base.
--shell: Shell into the environment in lieu of the step to run.
--shell-after: Shell into the environment after the step has run.
--use-lxd: Build in a LXD container.

Global options

-h or --help: Show this help message and exit.
-q or --quiet: Only show warnings and errors, not progress.
-v or --verbose: Show debug information and be more verbose.
--verbosity: Set the verbosity level to ‘quiet’, ‘brief’, ‘verbose’, ‘debug’ or ‘trace’.
-V or --version: Show the application version and exit.

remote-build¶

Command remote-build sends the current project to be built remotely. After the build is complete, packages for each architecture are retrieved and will be available in the local filesystem.

Interrupted remote builds can be resumed using the –recover option.

To set a timeout on the remote-build command, use the option --launchpad-timeout=<seconds>. The timeout is local, so the build on launchpad will continue even if the local instance is interrupted or times out.

Usage

rockcraft remote-build [options]

Options

--launchpad-accept-public-upload: Acknowledge that uploaded code will be publicly available.
--launchpad-timeout: Time in seconds to wait for launchpad to build.
--project: Upload to the specified Launchpad project.
--recover: Recover an interrupted build.

Global options

-h or --help: Show this help message and exit.
-q or --quiet: Only show warnings and errors, not progress.
-v or --verbose: Show debug information and be more verbose.
--verbosity: Set the verbosity level to ‘quiet’, ‘brief’, ‘verbose’, ‘debug’ or ‘trace’.
-V or --version: Show the application version and exit.

stage¶

Stage built artefacts into a common staging area. If part names are specified only those parts will be staged. The default is to stage all parts.

Usage

rockcraft stage [options]

Options

--build-for: Set architecture to build for.
--debug: Shell into the environment if the build fails.
--destructive-mode: Build in the current host.
--ignore: Bypass a restriction to use an unsupported feature.
--platform: Set platform to build for.
--pro: Enable Ubuntu Pro services for this command. Supported values include: ‘esm-apps’, ‘esm-infra’, ‘fips’, ‘fips-preview’, ‘fips-updates’. Multiple values can be passed separated by commas. Note: This feature requires an Ubuntu Pro compatible host and build base.
--shell: Shell into the environment in lieu of the step to run.
--shell-after: Shell into the environment after the step has run.
--use-lxd: Build in a LXD container.

Global options

-h or --help: Show this help message and exit.
-q or --quiet: Only show warnings and errors, not progress.
-v or --verbose: Show debug information and be more verbose.
--verbosity: Set the verbosity level to ‘quiet’, ‘brief’, ‘verbose’, ‘debug’ or ‘trace’.
-V or --version: Show the application version and exit.

test¶

Run spread tests for the project.

Usage

rockcraft test [options]

Options

--debug: Shell into the environment if the build fails.
--ignore: Bypass a restriction to use an unsupported feature.
--platform: Set platform to build for.
--pro: Enable Ubuntu Pro services for this command. Supported values include: ‘esm-apps’, ‘esm-infra’, ‘fips’, ‘fips-preview’, ‘fips-updates’. Multiple values can be passed separated by commas. Note: This feature requires an Ubuntu Pro compatible host and build base.
--shell: Shell into the environment in lieu of the step to run.
--shell-after: Shell into the environment after the step has run.

Global options

-h or --help: Show this help message and exit.
-q or --quiet: Only show warnings and errors, not progress.
-v or --verbose: Show debug information and be more verbose.
--verbosity: Set the verbosity level to ‘quiet’, ‘brief’, ‘verbose’, ‘debug’ or ‘trace’.
-V or --version: Show the application version and exit.

Extension commands¶

expand-extensions¶

Extensions listed rockcraft.yaml will be expanded and shown as output.

Usage

rockcraft expand-extensions [options]

Global options

-h or --help: Show this help message and exit.
-q or --quiet: Only show warnings and errors, not progress.
-v or --verbose: Show debug information and be more verbose.
--verbosity: Set the verbosity level to ‘quiet’, ‘brief’, ‘verbose’, ‘debug’ or ‘trace’.
-V or --version: Show the application version and exit.

extensions¶

List available extensions and their corresponding bases.

Usage

rockcraft extensions [options]

Global options

-h or --help: Show this help message and exit.
-q or --quiet: Only show warnings and errors, not progress.
-v or --verbose: Show debug information and be more verbose.
--verbosity: Set the verbosity level to ‘quiet’, ‘brief’, ‘verbose’, ‘debug’ or ‘trace’.
-V or --version: Show the application version and exit.

list-extensions¶

List available extensions and their corresponding bases.

Usage

rockcraft list-extensions [options]

Global options

-h or --help: Show this help message and exit.
-q or --quiet: Only show warnings and errors, not progress.
-v or --verbose: Show debug information and be more verbose.
--verbosity: Set the verbosity level to ‘quiet’, ‘brief’, ‘verbose’, ‘debug’ or ‘trace’.
-V or --version: Show the application version and exit.

Other commands¶

init¶

Initialise a project.

If ‘<project-dir>’ is provided, initialise in that directory, otherwise initialise in the current working directory.

If ‘–name <name>’ is provided, the project will be named ‘<name>’. Otherwise, the project will be named after the directory it is initialised in.

‘–profile <profile>’ is used to initialise the project for a specific use case.

If ‘–base <base>’ is provided, the project is initialized for that base. Only available for profiles that have base variants.

Init can work in an existing project directory. If there are any files in the directory that would be overwritten, then init command will fail.

Usage

rockcraft init [options]

Options

--base: The base variant of the init profile to use.
--name: The name of project; defaults to the name of <project_dir>.
--profile: Use the specified project profile (default is simple, choices are ‘django-framework’, ‘expressjs-framework’, ‘fastapi-framework’, ‘flask-framework’, ‘go-framework’, ‘simple’, ‘spring-boot-framework’, and ‘test’).
--vcs: Initialise a version control system.

Global options

-h or --help: Show this help message and exit.
-q or --quiet: Only show warnings and errors, not progress.
-v or --verbose: Show debug information and be more verbose.
--verbosity: Set the verbosity level to ‘quiet’, ‘brief’, ‘verbose’, ‘debug’ or ‘trace’.
-V or --version: Show the application version and exit.

version¶

Show the application version and exit

Usage

rockcraft version [options]

Global options

-h or --help: Show this help message and exit.
-q or --quiet: Only show warnings and errors, not progress.
-v or --verbose: Show debug information and be more verbose.
--verbosity: Set the verbosity level to ‘quiet’, ‘brief’, ‘verbose’, ‘debug’ or ‘trace’.
-V or --version: Show the application version and exit.