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

include <bpkg/common.cli>;

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

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

    "\h|SYNOPSIS|

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

     \h|DESCRIPTION|

     The \cb{build2} package manager is used to manipulate 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 \i{bpkg configuration} is a directory that will contain 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} configuration is an
     amalgamation that contains packages as subprojects.

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

     A \i{bpkg repository} is a collection of packages as well as prerequisite
     and complement repositories. A repository is identified by its location,
     which can be a local filesystem path or a remote HTTP or HTTPS URL.

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

     \dl|

     \li|\b{Create Configuration}\n

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

         |

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

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

         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 libfoo bar
         \

         |

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

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

         \
         bpkg drop libfoo
         \

         |

     \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|"

    //
    // 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 cfg-add|add
    {
      "<rep>",
      "\l{bpkg-cfg-add(1)} \- add repository to configuration",
      ""
    }

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

    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
    {
      "<archive>",
      "\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-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"
    }

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

    bool rep-create
    {
      "[<dir>]",
      "\l{bpkg-rep-create(1)} \- create repository",
      ""
    }
  };

  // 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"
    }
  };

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

  "\h|EXIT STATUS|

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