// file      : bpkg/bpkg.cli
// copyright : Copyright (c) 2014-2019 Code Synthesis Ltd
// license   : MIT; see accompanying LICENSE file

include <bpkg/common.cli>;

"\section=1"
"\name=bpkg"
"\summary=package dependency manager"

namespace bpkg
{
  {
    "<command> <topic> <common-options> <command-options> <command-args>",

    "\h|SYNOPSIS|

     \c{\b{bpkg --help}\n
        \b{bpkg --version}\n
        \b{bpkg help} [<command> | <topic>]\n
        \b{bpkg} [<common-options>] <command> [<command-options>] <command-args>}

     \h|DESCRIPTION|

     The \cb{build2} package dependency manager is used to manipulate build
     configurations, packages, and repositories using a set of commands that
     are summarized below.

     For a detailed description of any command or help topic, use the
     \cb{help} command or see the corresponding man page (the man pages have
     the \cb{bpkg-} prefix, for example \l{bpkg-help(1)}). Note also that
     <command-options> and <command-args> can be specified in any order and
     <common-options> can be specified as part of <command-options>."
  }

  // For usage it's nice to see the list of commands on the first page. So
  // let's not put this "extended" description into usage.
  //
  {
    "",
    "",

    "A \cb{bpkg} \i{build configuration} is a directory that contains packages
     built with similar settings. For example, a configuration can be for a
     specific target (\cb{i686}, \cb{x86_64}), compiler (\cb{clang}, \cb{gcc})
     compile options (\cb{-O3}, \cb{-g}), and so on. Configurations are
     relatively cheap and can be created and thrown away as needed.
     Configurations can be moved and copied by simply moving and copying the
     directories. Note, however, that a move or copy may render some packages
     out-of-date. In the \cb{build2} build system terms a \cb{bpkg} build
     configuration is an amalgamation that contains packages as subprojects
     (see \l{bpkg-cfg-create(1)} for details).

     A \i{bpkg package} is an archive or directory (potentially in a version
     control system) that contains a \cb{build2} project plus the package
     \cb{manifest} file. \cb{bpkg} can either use package archives/directories
     directly from the filesystem or it can fetch them from repositories.

     A \i{bpkg repository} is a collection of packages as well as information
     about prerequisite and complement repositories. \i{Archive},
     \i{directory} and \i{version control}-based repositories are supported. A
     repository is identified by its location which can be a local filesystem
     path or a URL. See \l{bpkg-repository-types(1)} for details on the
     repository structures and URL formats.

     If the same version of a package is available from multiple repositories,
     then they are assumed to contain identical package content. In such cases
     \cb{bpkg} prefers local repositories over remote and among local
     repositories it prefers the ones with external packages (see
     \l{bpkg-pkg-unpack(1)} for details on external packages).

     A typical \cb{bpkg} workflow would consist of the following steps.

     \dl|

     \li|\b{Create Configuration}\n

         \
         bpkg create cc                   \
           config.cxx=clang++             \
           config.cc.coptions=-O3         \
           config.install.root=/usr/local \
           config.install.sudo=sudo
         \

         |

     \li|\n\b{Add Source Repositories}\n

         \
         bpkg add https://pkg.cppget.org/1/stable
         bpkg add https://example.org/foo.git
         \

         Repeat this command to add more repositories.
         |

     \li|\n\b{Fetch Available Packages List}\n

         \
         bpkg fetch
         \

         |

     \li|\n\b{Fetch and Build Packages}\n

         \
         bpkg build foo bar
         \

         |

     \li|\n\b{Drop Package}\n

         If some packages are no longer needed, we can remove them from the
         configuration.

         \
         bpkg drop foo
         \

         |

     \li|\n\b{Refresh Available Packages List}\n

         \
         bpkg fetch
         \

         |

     \li|\n\b{Upgrade Packages}\n

         \
         bpkg build bar
         \

         |

     \li|\n\b{Install Packages}\n

         \
         bpkg install bar
         \

         ||
     "
  }

  class commands
  {
    "\h#commands|COMMANDS|"

    //
    // NOTE: Use the same sentence as in the page's \summary and make
    // sure it is short enough to fit in one line in usage.
    //

    bool help
    {
      "[<topic>]",
      "\l{bpkg-help(1)} \- show help for a command or help topic",
      ""
    }

    bool cfg-create|create
    {
      "\l{bpkg-cfg-create(1)} \- create configuration"
    }

    bool rep-info
    {
      "\l{bpkg-rep-info(1)} \- print repository information"
    }

    bool rep-add|add
    {
      "\l{bpkg-rep-add(1)} \- add repository to configuration"
    }

    bool rep-remove|remove
    {
      "\l{bpkg-rep-remove(1)} \- remove repository from configuration"
    }

    bool rep-list|list
    {
      "\l{bpkg-rep-list(1)} \- list repositories in configuration"
    }

    bool rep-fetch|fetch
    {
      "\l{bpkg-rep-fetch(1)} \- fetch list of available packages"
    }

    bool rep-create
    {
      "\l{bpkg-rep-create(1)} \- create repository"
    }

    bool pkg-status|status
    {
      "\l{bpkg-pkg-status(1)} \- print package status"
    }

    bool pkg-build|build
    {
      "\l{bpkg-pkg-build(1)} \- build package"
    }

    bool pkg-drop|drop
    {
      "\l{bpkg-pkg-drop(1)} \- drop package"
    }

    bool pkg-install|install
    {
      "\l{bpkg-pkg-install(1)} \- install package"
    }

    bool pkg-uninstall|uninstall
    {
      "\l{bpkg-pkg-uninstall(1)} \- uninstall package"
    }

    bool pkg-update|update
    {
      "\l{bpkg-pkg-update(1)} \- update package"
    }

    bool pkg-test|test
    {
      "\l{bpkg-pkg-test(1)} \- test package"
    }

    bool pkg-clean|clean
    {
      "\l{bpkg-pkg-clean(1)} \- clean package"
    }

    bool pkg-verify
    {
      "\l{bpkg-pkg-verify(1)} \- verify package archive"
    }

    bool pkg-fetch
    {
      "\l{bpkg-pkg-fetch(1)} \- fetch package archive"
    }

    bool pkg-unpack
    {
      "\l{bpkg-pkg-unpack(1)} \- unpack package archive"
    }

    bool pkg-checkout
    {
      "\l{bpkg-pkg-checkout(1)} \- check out package version"
    }

    bool pkg-configure
    {
      "\l{bpkg-pkg-configure(1)} \- configure package"
    }

    bool pkg-disfigure
    {
      "\l{bpkg-pkg-disfigure(1)} \- disfigure package"
    }

    bool pkg-purge
    {
      "\l{bpkg-pkg-purge(1)} \- purge package"
    }
  };

  // Make sure these don't conflict with command names above.
  //
  class topics
  {
    "\h|HELP TOPICS|"

    bool common-options
    {
      "\l{bpkg-common-options(1)} \- details on common options"
    }

    bool repository-types
    {
      "\l{bpkg-repository-types(1)} \- repository types, structure, and URLs"
    }

    bool repository-signing
    {
      "\l{bpkg-repository-signing(1)} \- how to sign repository"
    }

    bool argument-grouping
    {
      "\l{bpkg-argument-grouping(1)} \- argument grouping facility"
    }
  };

  class options: common_options
  {
    bool --help;
    bool --version;
  };

  "\h|ENVIRONMENT|

  Commands executed by \cb{bpkg} while the build configuration database is
  open will have the \cb{BPKG_OPEN_CONFIG} environment variable set to the
  absolute and normalized configuration directory path. This can be used by
  build system hooks and/or programs that they execute.
  "

  "\h|EXIT STATUS|

  Non-zero exit status is returned in case of an error.
  "
}