path: root/bdep/bdep.cli

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

include <bdep/common.cli>;

"\section=1"
"\name=bdep"
"\summary=project dependency manager"

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

    "\h|SYNOPSIS|

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

     \h|DESCRIPTION|

     The \cb{build2} project dependency manager is used to manage the
     dependencies of a project during development.

     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{bdep-} prefix, for example \l{bdep-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{bdep} project is a directory, normally under a version control
     system such as \cb{git(1)}, called \i{project repository}. A project
     contains one or more \i{packages}. If it contain several, then they are
     normally related, for example, the \cb{libhello} library and the
     \cb{hello} program.

     Packages in a project may depend on other packages outside of the
     project. To distinguish between the two we call them \i{project packages}
     and \i{dependency packages}, respectively.  Naturally, our project
     packages may be someone else's dependency packages.

     A simple, single-package project contains the package in the root of the
     project repository. For example (note the location of the package
     \cb{manifest} and \cb{lockfile}):

     \
     hello/
     ├── .git/
     ├── ...
     ├── lockfile
     └── manifest
     \

     See \l{bpkg#manifest-package Package Manifest} for details on the
     \cb{manifest} file.

     If a project contains multiple packages or we wish to place the package
     into a subdirectory, then the root of the project repository must
     contain the \cb{packages.manifest} file that specifies the package
     locations. For example:

     \
     hello/
     ├── .git/
     ├── hello/
     │   ├── ...
     │   ├── lockfile
     │   └── manifest
     ├── libhello/
     │   ├── ...
     │   ├── lockfile
     │   └── manifest
     └── packages.manifest
     \

     For this project, \cb{packages.manifest} would have the following
     contents:

     \
     : 1
     location: hello/
     :
     location: libhello/
     \

     A project repository root would usually also contain the
     \cb{repositories.manifest} file that lists the repositories that provide
     the dependency packages. For example:

     \
     hello/
     ├── ...
     ├── manifest
     └── repositories.manifest
     \

     If our \cb{hello} project wanted to use \cb{libhello} as a dependency
     package, then \cb{repositories.manifest} could look like this:

     \
     : 1
     role: prerequisite
     location: https://example.com/libhello.git
     :
     role: base
     summary: hello project repository
     \

     See \l{bpkg#manifest-repository-list Repository List Manifest} for
     details on the \cb{repositories.manifest} file.

     For development a \cb{bdep} project is associated with one or more
     \l{bpkg(1)} \i{build configurations}. These configuration are used as a
     \i{backing} for building project packages and their dependencies.

     The list of the associated build configuration as well as the list of
     project packages initialized in each configuration are stored in the
     \cb{bdep} \i{project database} under the \cb{.bdep/} subdirectory of the
     project root directory. For example:

     \
     hello-gcc/     # Build configuration for gcc.
     hello-clang/   # Build configuration for clang.
     hello/
     ├── .bdep/
     ├── .git/
     └── ...
     \

     The core of \cb{bdep} functionality is \i{state synchronization} between
     the project and one or more associated build configurations. For example,
     if we list a new dependency in the package's \cb{manifest} file, then
     \cb{bdep} fetches and configures this dependency in a build
     configuration. Similarly, if we upgrade a dependency in a build
     configuration, then \cb{bdep} updates the corresponding entry in the
     package's \cb{lockfile}.

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

     \dl|

     \li|\b{Obtain the Project}\n

         Normally we would use the version control system to obtail the
         project we want to develop:

         \
         $ git clone ssh://example.com/hello.git
         \

         Alternatively, we can use the \l{bdep-new(1)} command to start a new
         project:

         \
         $ bdep new -t exe -l c++ hello
         \

         Similar to version control tools, we normally run \cb{bdep} from the
         project's directory or one of its subdirectories:

         \
         $ cd hello
         \

         See \l{bdep-projects-configs(1)} for alternative ways to specify
         the project location.

         |


     \li|\b{Initialize the Project}\n

         Next we use the \l{bdep-init(1)} command to create new or add
         existing build configurations and initialize our project in these
         configurations:

         \
         $ bdep init -C ../hello-gcc @gcc cc config.cxx=g++
         $ bdep init -A ../hello-clang @clang
         \

         We can now use the \l{bdep-status(1)} command to examine the status
         of our project in its configuration:

         \
         $ bdep status -a
         in configuration @gcc:
         hello configured 0.1.0-a.0.19700101000000

         in configuration @clang:
         hello configured 0.1.0-a.0.19700101000000
         \

         Most \cb{bdep} commands operate on one or more build configurations
         associated with the project. If we don't specify one explicitly, then
         the \i{default configuration} (usually the first added; \cb{gcc} in
         our case) is used. Alternatively, we can specify the configurations
         by name (if assigned), as directories, or with \c{\b{--all}|\b{-a}}
         (see \l{bdep-projects-configs(1)} for details). For example:

         \
         $ bdep status @clang @gcc      # by name
         $ bdep status -c ../hello-gcc  # as a directory
         \

         If a command is operating on multiple configurations (like \cb{status
         -a} in the previous example), then it will print a line identifying
         each configuration before printing the command's result.

         @@ build and run?

         |

     \li|\b{Add, Remove, or Change Dependencies}\n

         Let's say we found \cb{libhello} that we would like to use in our
         project. First we edit our project's \cb{repositories.manifest}
         file and add the \cb{libhello}'s repository as our prerequisite:

         \
         $ cat repositories.manifest
         ...
         role: prerequisite
         location: https://example.com/libhello.git
         ...
         \

         Next we edit our \cb{manifest} file and specify a dependency on
         \cb{libhello}:

         \
         $ cat manifest
         ...
         depends: libhello >= 1.0.0
         ...
         \

         If we now run \l{bdep-status(1)}, we will notice that a new
         \i{iteration} of our project is available for synchronization:

         \
         $ bdep status
         hello configured 0.1.0-a.0.19700101000000
               available  0.1.0-a.0.19700101000000#1
         \

         See \l{bpkg#package-version Package Version} for details on package
         versions and iterations.|

     \li|\b{Synchronize the Project with Configurations}\n

         To synchronize changes in the project's dependency information with
         its build configurations we use the \l{bdep-sync(1)} command.
         Continuing with our example, this will result in \cb{libhello} being
         downloaded and configured since our project now depends on it:

         \
         $ bdep sync

         $ bdep status -i
         hello configured 0.1.0-a.0.19700101000000#1
           libhello >= 1.0.0 configured 1.0.0
         \

         |

     \li|\b{Upgrade or Downgrade Dependencies}\n

         The \l{bdep-sync(1)} command is also used to upgrade or downgrade
         dependencies (and it is also executed as the last step of \cb{init}).
         Let's say we learned a new version of \cb{libhello} was release and
         we would like to try it out.

         To refresh the list of available dependency packages we use the
         \l{bdep-fetch(1)} command (or, as a shortcut, the \cb{-f} flag to
         \cb{status}):

         \
         $ bdep fetch

         $ bdep status libhello
         libhello configured 1.0.0 available [1.1.0]
         \

         Without an explicit version or the \c{\b{--patch}|\b{-p}} option,
         \cb{sync} will upgrade the specified dependency to the latest
         available version:

         \
         $ bdep sync libhello

         $ bdep status -i
         hello configured 0.1.0-a.0.19700101000000#1
           libhello >= 1.0.0 configured 1.1.0
         \

         Let's say we didn't like the new version and would like to go back to
         using the old one. To downgrade a dependency we have to specify its
         version explicitly:

         \
         $ bdep status -o libhello
         libhello configured 1.1.0 available [1.0.0] (1.1.0)

         $ bdep sync libhello/1.0.0
         \

         ||
    "
  }

  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{bdep-help(1)} \- show help for a command or help topic",
      ""
    }

    bool new
    {
      "\l{bdep-new(1)} \- create and initialize new project"
    }

    bool init
    {
      "\l{bdep-init(1)} \- initialize project in build configurations"
    }

    bool sync
    {
      "\l{bdep-sync(1)} \- synchronize project and build configurations"
    }

    bool fetch
    {
      "\l{bdep-fetch(1)} \- fetch list of available project dependencies"
    }

    bool status
    {
      "\l{bdep-status(1)} \- print status of project and/or its dependencies"
    }

    bool config
    {
      "\l{bdep-config(1)} \- manage project's build configurations"
    }
  };

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

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

    bool projects-configs
    {
      "\l{bdep-projects-configs(1)} \- specifying projects and configurations"
    }
  };

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

  "\h|EXIT STATUS|

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