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. An example of a user invoking a clean action is as follows:

.. code-block:: shell

    releng-tool clean

The following outlines available actions:

.. list-table::
    :widths: auto

    * - .. _ACTION_CLEAN:

        ``clean``

      - Clean (removes) a series of folders holding content such as extracted
        archives, built libraries and more. Images and downloaded assets/cache
        are not removed (see |ACTION_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.

    * - .. _ACTION_DISTCLEAN:

        ``distclean``

      - Perform a more extreme pristine clean of the releng-tool project.
        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 |ACTION_CLEAN|_ or |ACTION_MRPROPER|_ actions.

    * - ``extract``

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

    * - ``fetch``

      - All packages will be processed up to the fetch phase (inclusive;
        see also `offline builds`_).

    * - ``init``

      - Initialize an empty root directory with a sample project.

    * - ``licenses``

      - A request to generate all license information for the project.
        Note that license information requires acquiring license
        documents from packages. Therefore, packages will be
        fetched/extracted if not already done.

    * - .. _ACTION_MRPROPER:

        ``mrproper``

      - Perform a pristine clean of the releng-tool project. 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 |ACTION_CLEAN|_
        or |ACTION_DISTCLEAN|_ actions.

    * - ``patch``

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

    * - ``<pkg>-build``

      - Performs the build stage for the package. 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.

    * - .. _ACTION_PKG_CLEAN:

        ``<pkg>-clean``

      - Cleans the build directory for package (if it exists). See also the
        |ACTION_PKG_DISTCLEAN|_ action.

    * - ``<pkg>-configure``

      - Performs the configure stage for the package. 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.

    * - .. _ACTION_PKG_DISTCLEAN:

        ``<pkg>-distclean``

      - Perform a pristine clean of a releng-tool package. This request
        not only removes the build directory but also any cached file or
        directory associated with the package. See also the
        |ACTION_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:

        .. code-block:: shell

            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. 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. 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>-install``

      - Performs the installation stage for the package. 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. 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. 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. 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. 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. 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. 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. 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.

.. |ACTION_CLEAN| replace:: ``clean``
.. |ACTION_DISTCLEAN| replace:: ``distclean``
.. |ACTION_MRPROPER| replace:: ``mrproper``
.. |ACTION_PKG_CLEAN| replace:: ``<pkg>-clean``
.. |ACTION_PKG_DISTCLEAN| replace:: ``<pkg>-distclean``

The following outlines available options:

.. list-table::
    :widths: auto

    * - ``--assets-dir <dir>``

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

        This argument can be ignored if ``--cache-dir`` or ``--dl-dir``
        are set.

    * - ``--cache-dir <dir>``

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

    * - ``--config <file>``

      - Configuration file to load (default: ``<root>/releng``).

    * - ``--debug``

      - Show debug-related messages.

    * - ``-D``, ``--development [<mode>]``

      - Enables `development mode`_.

    * - ``--dl-dir <dir>``

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

    * - ``-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 this help.

    * - ``--images-dir <dir>``

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

    * - ``-j``, ``--jobs <jobs>``

      - Numbers of jobs to handle (default 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 (a value prefixed with a package's name with an at
        sign (``@``)), sources for that package will be looked for inside
        the provided path.

    * - ``--nocolorout``

      - Explicitly disable colorized output.

    * - ``--out-dir <dir>``

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

    * - ``--root-dir <dir>``

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

    * - ``--quirk <quirk-id>``

      - Allows specifying a runtime :ref:`quirk <quirks>` 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.
