Porting command line usage

This document outlines breaking changes made to the command line interface in BuildStream 2.

bst init

  • The global --directory option is no longer observed by bst init, instead the command accepts an optional target directory argument.

  • The --format-version option has been removed in favor of the new --min-version option.

bst build

  • Tracking is no longer supported at build time and must be performed separately, this removes the --track, --track-all, --track-except, --track-cross-junctions and --track-save options from the command.

    To track your elements in BuildStream 2, use the bst source track command instead.

  • The --all option which was used to indicate that all dependencies should be built regardless of whether they are needed for producing the target elements has been removed in favor of adding the --deps option.

    To acheive the same functionality, use bst build --deps all ....

bst show

  • The plan value is no longer supported as a value for the --deps option.

  • Values for the %{state} format have changed

    • junction elements will display junction, as these cannot be built

    • In the case a cached failed build artifact is found, then failed will be displayed

    • Due to changes in the scheduler, we may observe changes as to when waiting, buildable, fetch needed are displayed for a given element.

bst fetch

  • This command has been removed as a top-level command and now exists as bst source fetch

  • Tracking is no longer supported at fetch time and must be performed separately, this removes the --track and --track-cross-junctions options from the command.

    To track your elements in BuildStream 2, use the bst source track command instead.

  • The plan value is no longer supported as a value for the --deps option. The default value for the --deps option is now none.

bst track

  • This command has been removed as a top-level command and now exists as bst source track

bst pull

  • This command has been removed as a top-level command and now exists as bst artifact pull

  • The --remote option has been removed in favor the --artifact-remote option, which can be specified multiple times.

  • The values which can be specified by --artifact-remote options have a new format which is documented here.

bst push

  • This command has been removed as a top-level command and now exists as bst artifact push

  • The --remote option has been removed in favor the --artifact-remote option, which can be specified multiple times.

  • The values which can be specified by --artifact-remote options have a new format which is documented here.

bst checkout

  • This command has been removed as a top-level command and now exists as bst artifact checkout

  • The trailing LOCATION argument has been removed in favor of a --directory option.

    BuildStream 1:

    bst checkout element.bst ~/checkout

    BuildStream 2:

    bst artifact checkout --directory ~/checkout element.bst

bst shell

  • The --sysroot option has been completely removed.

    This is no longer needed for failed builds as the build tree will be cached in a failed build artifact.

  • Sources and artifacts required to produce the shell environment will now be downloaded automatically by default.

bst workspace open

  • The --track option is now removed.

  • The trailing LOCATION argument has been removed in favor of a --directory option.

    BuildStream 1:

    bst workspace open element.bst ~/workspace

    BuildStream 2:

    bst workspace open --directory ~/workspace element.bst

bst workspace reset

  • The --track option is now removed.

bst source-bundle

This command has been completely removed, but similar behavior can be achieved using the bst source checkout command.

BuildStream 1:

bst source-bundle --directory ~/bundle element.bst

BuildStream 2:

bst source checkout \
    --tar ~/sources.tgz \
    --compression gz \
    --include-build-scripts \
    element.bst