// file      : bdep/status.cli
// license   : MIT; see accompanying LICENSE file

include <bdep/project.cli>;

"\section=1"
"\name=bdep-status"
"\summary=print status of project and/or its dependencies"

namespace bdep
{
  {
    "<options>
     <prj-spec> <prj-dir>
     <pkg-spec> <pkg-dir>
     <cfg-spec> <cfg-name> <cfg-dir>
     <dep-spec> <pkg> <ver>",

    "\h|SYNOPSIS|

     \c{\b{bdep status} [<options>] [<pkg-spec>] [<cfg-spec>] [<dep-spec>...]}

     \c{<dep-spec> = <pkg>[\b{/}<ver>]\n
        <cfg-spec> = (\b{@}<cfg-name> | \b{--config}|\b{-c} <cfg-dir>)... | \b{--all}|\b{-a}\n
        <pkg-spec> = (\b{--directory}|\b{-d} <pkg-dir>)... | <prj-spec>\n
        <prj-spec> = \b{--directory}|\b{-d} <prj-dir>}

     \h|DESCRIPTION|

     The \cb{status} command prints the status of project packages and/or
     their dependencies in one or more build configurations.

     If no project or package directory is specified, then the current working
     directory is assumed. If no configuration is specified, then the default
     configurations are assumed. See \l{bdep-projects-configs(1)} for details
     on specifying projects and configurations.

     If no <dep-spec> arguments are specified, then \cb{status} prints the
     status of the project's packages. Otherwise, the status of the specified
     dependency packages is printed. Additionally, the status of immediate or
     all dependencies of the above packages can be printed by specifying the
     \c{\b{--immediate}|\b{-i}} or \c{\b{--recursive}|\b{-r}} options,
     respectively.

     In the default output format (see the \cb{--stdout-format} common
     option), the status of each package is printed on a separate line. Note
     that the status is written to \cb{stdout}, not \cb{stderr}. The semantics
     of <dep-spec> and the format of the status line are described in
     \l{bpkg-pkg-status(1)}.

     If the output format is \cb{json}, then the output is a JSON array of
     objects which are the serialized representation of the following C++
     \cb{struct} \cb{configuration_package_status}:

     \
     struct configuration
     {
       uint64_t         id;
       string           path;
       optional<string> name;
     };

     struct configuration_package_status
     {
       configuration          configuration;
       vector<package_status> packages;
     };
     \

     For example:

     \
     [
       {
         \"configuration\": {
           \"id\": 1,
           \"path\": \"/tmp/hello-gcc\",
           \"name\": \"gcc\"
         },
         \"packages\": [
           {
             \"name\": \"hello\",
             \"status\": \"configured\",
             \"version\": \"1.0.0\",
             \"hold_package\": true,
             \"available_versions\": [
               {
                 \"version\": \"1.0.1\"
               },
               {
                 \"version\": \"2.0.0\"
               }
             ],
             \"dependencies\": [
               {
                 \"name\": \"libhello\",
                 \"status\": \"configured\",
                 \"version\": \"1.0.2\"
               }
             ]
           }
         ]
       }
     ]
     \

     See the JSON OUTPUT section in \l{bdep-common-options(1)} for details on
     the overall properties of this format and the semantics of the
     \cb{struct} serialization.

     Refer to the \cb{list} subcommand of \l{bdep-config(1)} for details on
     the \cb{struct} \cb{configuration} members. Refer to
     \l{bpkg-pkg-status(1)} for the definition of \cb{struct}
     \cb{package_status}. Note also that in the \cb{json} output format
     certain conditions (no associated configurations, no initialized
     packages, etc) are not treated as errors but instead result in valid
     output. The uninitialized packages have the special \cb{uninitialized}
     \cb{status} value."
  }

  class cmd_status_options: project_options
  {
    "\h|STATUS OPTIONS|"

    bool --immediate|-i
    {
      "Also print the status of immediate dependencies."
    }

    bool --recursive|-r
    {
      "Also print the status of all dependencies, recursively."
    }

    bool --old-available|-o
    {
      "Print old available versions."
    }

    bool --fetch|-f
    {
      "Perform the \cb{fetch} command prior to printing the status."
    }

    bool --fetch-full|-F
    {
      "Perform the \cb{fetch --full} command prior to printing the status."
    }
  };

  "
   \h|DEFAULT OPTIONS FILES|

   See \l{bdep-default-options-files(1)} for an overview of the default
   options files. For the \cb{status} command the search start directory is
   the project directory. The following options files are searched for in
   each directory and, if found, loaded in the order listed:

   \
   bdep.options
   bdep-status.options
   \

   The following \cb{status} command options cannot be specified in the
   default options files:

   \
   --directory|-d
   \
  "
}