path: root/bdep/new.cli

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

include <bdep/project.cli>;
include <bdep/new-types.hxx>;

"\section=1"
"\name=bdep-new"
"\summary=create and initialize new project"

namespace bdep
{
  {
    "<options> <spec> <name>
     <type> <type-opt>
     <lang> <lang-opt>
     <vcs> <vcs-opt>
     <cfg-name> <cfg-dir>
     <prj-spec> <prj-dir>
     <cfg-args> <option> <module> <cfg-var>",

    "\h|SYNOPSIS|

     \c{\b{bdep new} [<options>] [\b{--no-init}] <spec> <name>\n
        \b{bdep new} [<options>] \b{--config-add|-A} <cfg-dir> [\b{@}<cfg-name>] <spec> <name>\n
        \b{bdep new} [<options>] \b{--config-create|-C} <cfg-dir> [\b{@}<cfg-name>] <spec> <name>\n
        \ \ \ \ \ \ \ \ \ [<cfg-args>]\n
        \b{bdep new} [<options>] \b{--package} [<prj-spec>] <spec> <name>}

     \c{<spec> \ \ \ \ = [<type>] [<lang>] [<vcs>]\n
        <type> \ \ \ \ = \b{--type}|\b{-t} (\b{exe}|\b{lib}|\b{bare}|\b{empty})[\b{,}<type-opt>...]\n
        <lang> \ \ \ \ = \b{--lang}|\b{-l} (\b{c}|\b{c++})[\b{,}<lang-opt>...]\n
        <vcs> \ \ \ \ \ = \b{--vcs}|\b{-s} \ (\b{git}|\b{none})[\b{,}<vcs-opt>...]\n
        <prj-spec> = \b{--directory}|\b{-d} <prj-dir>\n
        <cfg-args> = (<option> | <module> | <cfg-var>)...}

     \h|DESCRIPTION|

     The \cb{new} command creates and initializes a new project (the first
     three forms) or a new package in an already existing project (the last
     form). All four forms first create according to <spec> a new \cb{build2}
     project/package called <name> in the <name> subdirectory of the current
     working directory (unless overridden with \c{\b{--output-dir}|\b{-o}}).
     See \l{bpkg#package-name Package Name} for details on project/package
     names.

     The first form then, unless the \cb{--no-init} option is specified,
     initializes an empty project database as if by executing the
     \l{bdep-init(1)} command with the \cb{--empty} option. Similarly, the
     second and third forms add an existing or create new build configuration
     and then initialize the project in that configuration as if by executing
     the \l{bdep-init(1)} command with the \cb{--config-add} or
     \cb{--config-create} option, respectively.

     The last form adds the new package to the \cb{packages.manifest} file
     creating it if necessary. If no project directory is explicitly specified
     with \c{\b{--directory}|\b{-d}}, then the current working directory is
     assumed. Note that nested packages are not allowed.

     The project parameters such as type (executable, library, etc), language,
     and version control system can be customized as described next. Some of
     these parameters also support parameter-specific options (such as the
     file extensions to use in a C++ project) that can be specified with a
     comma after the parameter value.

     The project type can be specified with the \c{\b{--type}|\b{-t}} option.
     Valid values for this option and their semantics are described next. If
     unspecified, an executable project is created by default.

     \dl|

     \li|\cb{exe}

         A project that builds a sample executable. Recognized executable
         project options:

         \cb{no-tests} \- Don't add support for functional/integration testing.

         \cb{unit-tests} \- Add support for unit testing.
         |

     \li|\cb{lib}

         A project that builds a sample library. Recognized library project
         options:

         \cb{no-tests} \- Don't add support for functional/integration testing.

         \cb{unit-tests} \- Add support for unit testing.
         |

     \li|\cb{bare}

         A project without any source code. Recognized bare project options:

         \cb{no-tests} \- Don't add support for testing.
         |

     \li|\cb{empty}

         An empty project that can be filled with packages (see
         \cb{--package}). Note that the project language is ignored for
         this project type.||

     The project language can be specified with the \c{\b{--lang}|\b{-l}}
     option. Valid values for this option and their semantics are described
     next. If unspecified, a C++ project is created by default.

     \dl|

     \li|\cb{c}

         A C project.|

     \li|\cb{c++}

         A C++ project. Recognized language options:

         \cb{cxx} \- Use the \cb{.cxx}, \cb{.hxx}, \cb{.ixx}, \cb{.txx}, and
         \cb{.mxx} source file extensions (default).

         \cb{cpp} \- Use the \cb{.cpp}, \cb{.hpp}, \cb{.ipp}, \cb{.tpp}, and
         \cb{.mpp} source file extensions.

         \cb{binless} \- Create a header-only library.||

     The project version control system can be specified with the
     \c{\b{--vcs}|\b{-s}} option. Valid values for this option and their
     semantics are described next. If unspecified, \cb{git} is assumed by
     default.

     \dl|

     \li|\cb{git}

         Initialize a \cb{git(1)} repository inside the project and generate
         \cb{.gitignore} files.|

     \li|\cb{none}

         Don't initialize a version control system inside the project.||
     "
  }

  //--type options
  //
  class cmd_new_exe_options
  {
    bool no-tests;
    bool unit-tests;
  };

  class cmd_new_lib_options
  {
    bool no-tests;
    bool unit-tests;
  };

  class cmd_new_bare_options
  {
    bool no-tests;
  };

  class cmd_new_empty_options
  {
  };

  // --lang options
  //
  class cmd_new_c_options
  {
  };

  class cmd_new_cxx_options
  {
    bool cpp;
    bool cxx;
    bool binless;
  };

  // --vcs options
  //
  class cmd_new_git_options
  {
  };

  class cmd_new_none_options
  {
  };

  class cmd_new_options: configuration_add_options, configuration_name_options
  {
    "\h|NEW OPTIONS|"

    bool --no-init
    {
      "Don't initialize an empty build configuration set."
    }

    bool --package
    {
      "Create a package inside an already existing project rather than a
       new project."
    }

    dir_path --output-dir|-o
    {
      "<dir>",
      "Create the project in the specified directory."
    }

    dir_path --directory|-d
    {
      "<dir>",
      "Assume the project is in the specified directory rather than in the
       current working directory. Only used with \cb{--package}."
    }

    cmd_new_type --type|-t
    {
      "<type>[,<opt>...]",
      "Specify project type and options. Valid values for <type> are \cb{exe}
       (executable project, default), \cb{lib} (library project), \cb{bare}
       (bare project without any source code), and \cb{empty} (empty project
       ready to be filled with packages). Valid values for <opt> are
       type-specific."
    }

    cmd_new_lang --lang|-l
    {
      "<lang>[,<opt>...]",
      "Specify project language and options. Valid values for <lang> are \cb{c}
       and \cb{c++} (default). Valid values for <opt> are language-specific."
    }

    cmd_new_vcs --vcs|-s
    {
      "<vcs>[,<opt>...]",
      "Specify project version control system and options. Valid values for
       <vcs> are \cb{git} (default) and \cb{none}. Valid values for <opt> are
       system-specific."
    }

    bool --no-amalgamation
    {
      "Create a project with disabled amalgamation support. This option is
       normally only used for testing."
    }

    bool --no-checks
    {
      "Suppress nested project/package checks. This option is normally only
       used for testing."
    }

    dir_path --config-add|-A
    {
      "<dir>",
      "Add an existing build configuration <dir>."
    }

    dir_path --config-create|-C
    {
      "<dir>",
      "Create a new build configuration in <dir>."
    }
  };

  "\h|ENVIRONMENT|

   The \cb{BDEP_AUTHOR_EMAIL} environment variable can be used to specify the
   package email address. If not set, the \cb{new} command will first try to
   obtain the email from the version control system (if used) and then from
   the \cb{EMAIL} environment variable. If all these methods fail, a dummy
   \cb{@example.org} email is used.
  "
}