[buildstream] 06/07: doc/source/porting_command_line.rst: Documenting breaking changes

[tv...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

tvb pushed a commit to branch tristan/porting-guide
in repository https://gitbox.apache.org/repos/asf/buildstream.git

commit 47d83f066036dba0fa7830c9caf157629dd8e6e9
Author: Tristan van Berkom <tr...@codethink.co.uk>
AuthorDate: Sat Jan 1 15:54:49 2022 +0900

    doc/source/porting_command_line.rst: Documenting breaking changes
---
 doc/source/porting_command_line.rst | 167 ++++++++++++++++++++++++++++++++++++
 1 file changed, 167 insertions(+)

diff --git a/doc/source/porting_command_line.rst b/doc/source/porting_command_line.rst
index b0cd905..4520c07 100644
--- a/doc/source/porting_command_line.rst
+++ b/doc/source/porting_command_line.rst
@@ -4,3 +4,170 @@
 
 Porting command line usage
 ==========================
+This document outlines breaking changes made to the :ref:`command line interface <commands>`
+in BuildStream 2.
+
+
+:ref:`bst init <invoking_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.
+
+
+:ref:`bst build <invoking_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 :ref:`bst source track <invoking_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 ...``.
+
+
+:ref:`bst show <invoking_show>`
+-------------------------------
+
+* The ``plan`` value is no longer supported as a value for the ``--deps`` option.
+
+* Values for the ``%{state}`` format have changed
+
+  * :mod:`junction <elements.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.
+
+
+:ref:`bst fetch <invoking_source_fetch>`
+----------------------------------------
+
+* This command has been removed as a top-level command and now exists as :ref:`bst source fetch <invoking_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 :ref:`bst source track <invoking_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``.
+
+
+:ref:`bst track <invoking_source_track>`
+----------------------------------------
+
+* This command has been removed as a top-level command and now exists as :ref:`bst source track <invoking_source_track>`
+
+
+:ref:`bst pull <invoking_artifact_pull>`
+----------------------------------------
+
+* This command has been removed as a top-level command and now exists as :ref:`bst artifact pull <invoking_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 :ref:`documented here <invoking_specify_remotes>`.
+
+
+:ref:`bst push <invoking_artifact_push>`
+----------------------------------------
+
+* This command has been removed as a top-level command and now exists as :ref:`bst artifact push <invoking_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 :ref:`documented here <invoking_specify_remotes>`.
+
+
+
+:ref:`bst checkout <invoking_artifact_checkout>`
+------------------------------------------------
+
+* This command has been removed as a top-level command and now exists as :ref:`bst artifact checkout <invoking_artifact_checkout>`
+
+* The trailing ``LOCATION`` argument has been removed in favor of a ``--directory`` option.
+
+  **BuildStream 1:**
+
+  .. code:: shell
+
+     bst checkout element.bst ~/checkout
+
+  **BuildStream 2:**
+
+  .. code:: shell
+
+     bst artifact checkout --directory ~/checkout element.bst
+
+
+:ref:`bst shell <invoking_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.
+
+
+:ref:`bst workspace open <invoking_workspace_open>`
+---------------------------------------------------
+
+* The ``--track`` option is now removed.
+
+* The trailing ``LOCATION`` argument has been removed in favor of a ``--directory`` option.
+
+  **BuildStream 1:**
+
+  .. code:: shell
+
+     bst workspace open element.bst ~/workspace
+
+  **BuildStream 2:**
+
+  .. code:: shell
+
+     bst workspace open --directory ~/workspace element.bst
+
+
+:ref:`bst workspace reset <invoking_workspace_reset>`
+-----------------------------------------------------
+
+* The ``--track`` option is now removed.
+
+
+:ref:`bst source-bundle <invoking_source_checkout>`
+---------------------------------------------------
+This command has been completely removed, but similar behavior can be achieved
+using the :ref:`bst source checkout <invoking_source_checkout>` command.
+
+
+**BuildStream 1:**
+
+.. code:: shell
+
+   bst source-bundle --directory ~/bundle element.bst
+
+**BuildStream 2:**
+
+.. code:: shell
+
+   bst source checkout \
+       --tar ~/sources.tgz \
+       --compression gz \
+       --include-build-scripts \
+       element.bst