path: root/bdep/new.cli

// file      : bdep/new.cli
// copyright : Copyright (c) 2014-2019 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>\n
        \b{bdep new} [<options>] \b{--subdirectory} [<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), a new package in an already existing project (the
     \cb{--package} form), or a new source subdirectory in an already existing
     project/package (the \cb{--subdirectory} form). All the forms except
     \cb{--subdirectory} 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. For example:

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

     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. For example:

     \
     $ bdep new -t exe -l c++ -C @gcc hello cc config.cxx=g++
     \

     The \cb{--package} 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. For example:

     \
     $ bdep new -t empty hello
     $ cd hello

     $ bdep new --package -t lib -l c++ libhello
     $ bdep new --package -t exe -l c++ hello

     $ bdep init -C @gcc cc config.cxx=g++
     \

     After executing these commands the \cb{hello} project will contain two
     packages, \cb{libhello} and \cb{hello}.

     The \cb{--subdirectory} form operates \i{as-if} by first creating
     according to <spec> a temporary project called <name> and then copying
     its source subdirectory (\c{\i{name}\b{/}\i{name}\b{/}}) over to the
     current working directory (unless overridden with
     \c{\b{--output-dir}|\b{-o}}). If no project/package directory is
     explicitly specified with \c{\b{--directory}|\b{-d}}, then the current
     working directory is assumed. For example:

     \
     $ bdep new -t bare hello
     $ cd hello

     $ bdep new --subdirectory -t lib -l c++ libhello
     $ bdep new --subdirectory -t exe -l c++ hello

     $ bdep init -C @gcc cc config.cxx=g++
     \

     After executing these commands the \cb{hello} project will contain two
     source subdirectories, \cb{libhello/} and \cb{hello/}.

     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 sub-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 sub-options:|

     \li|\n\ \ \ \cb{no-tests}

         Don't add support for functional/integration testing.|

     \li|\n\ \ \ \cb{unit-tests}

         Add support for unit testing.|

     \li|\n\ \ \ \c{\b{license=}\i{name}}|

     \li|\ \ \ \cb{no-readme}|

     \li|\ \ \ \cb{alt-naming}

         See \cb{common} sub-options below.||

     \dl|

     \li|\cb{lib}

         A project that builds a sample library. Recognized library
         project sub-options:|

     \li|\n\ \ \ \cb{no-tests}

         Don't add support for functional/integration testing.|

     \li|\n\ \ \ \cb{unit-tests}

         Add support for unit testing.|

     \li|\n\ \ \ \cb{no-version}

         Don't add support for generating the version header.|

     \li|\n\ \ \ \c{\b{license=}\i{name}}|

     \li|\ \ \ \cb{no-readme}|

     \li|\ \ \ \cb{alt-naming}

         See \cb{common} sub-options below.||

     \dl|

     \li|\cb{bare}

         A project without any source code that can be filled later
         (see \cb{--subdirectory}). Recognized bare project sub-options:|

     \li|\n\ \ \ \cb{no-tests}

         Don't add support for testing.|

     \li|\n\ \ \ \c{\b{license=}\i{name}}|

     \li|\ \ \ \cb{no-readme}|

     \li|\ \ \ \cb{alt-naming}

         See \cb{common} sub-options below.||

     \dl|

     \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. Recognized empty project sub-options:|

     \li|\n\ \ \ \cb{no-readme}

         See \cb{common} sub-options below.||

     \dl|

     \li|\cb{common}

         Common project type sub-options:|

     \li|\n\ \ \ \c{\b{license=}\i{name}}

         Specify the project's license. Commonly used license names are
         \cb{MIT}, \cb{ASLv2} (Apache License 2.0), \cb{GPLv3}, and
         \cb{proprietary}. If unspecified, then \cb{proprietary} is
         assumed. See the \l{bpkg#manifest-package-license \cb{license}}
         package manifest value for details.|

     \li|\n\ \ \ \cb{no-readme}

         Don't add \cb{README.md}.|

     \li|\n\ \ \ \cb{alt-naming}

         Use the alternative build file/directory naming scheme.||

     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.||

     \dl|

     \li|\cb{c++}

         A C++ project. Recognized language sub-options:|

     \li|\n\ \ \ \cb{binless}

         Create a header-only library.|

     \li|\n\ \ \ \cb{cpp}

         Use the \cb{.cpp}, \cb{.hpp}, \cb{.ipp}, \cb{.tpp}, and \cb{.mpp}
         source file extensions (alias for \cb{extension=?pp}).|

     \li|\n\ \ \ \c{\b{extension=}\i{pattern}}

         Derive source file extensions from \ci{pattern} by replacing
         every \cb{?} with one of the \cb{c} (source), \cb{h} (header),
         \cb{i} (inline), \cb{t} (template), or \cb{m} (module interface)
         letters. If unspecified and no individual extensions are specified
         with the below options, then \cb{?xx} is used by default.|

     \li|\n\ \ \ \c{\b{hxx=}\i{extension}}

         Use the specified \ci{extension} for header files instead of
         the default \cb{.hxx}.|

     \li|\n\ \ \ \c{\b{cxx=}\i{extension}}

         Use the specified \ci{extension} for source files instead of
         the default \cb{.cxx}.|

     \li|\n\ \ \ \c{\b{ixx=}\i{extension}}

         Use the specified \ci{extension} for inline files. If
         unspecified, then assume no inline files are used by the
         project.|

     \li|\n\ \ \ \c{\b{txx=}\i{extension}}

         Use the specified \ci{extension} for template files. If
         unspecified, then assume no template files are used by the
         project.|

     \li|\n\ \ \ \c{\b{mxx=}\i{extension}}

         Use the specified \ci{extension} for module interface files. If
         unspecified, then assume no modules are used by the project.||

     As an example, the following command creates a header-only C++ library
     that uses the \cb{.h} extension for header files and \cb{.cpp} \- for
     source files:

     \
     $ bdep new -t lib -l c++,binless,hxx=h,cxx=cpp libhello
     \

     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.||

     \dl|

     \li|\cb{none}

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

     The newly created project, package, or subdirectory can be further
     customized using the post-creation hooks specified with the
     \cb{--post-hook} option. The hook commands are executed in the
     newly created project, package, or source directory as their
     current working directory. For example:

     \
     $ bdep new --post-hook \"echo .idea/ >>.gitignore\" hello
     \

     See the \cb{--post-hook} option documentation below for details.
     "
  }

  //--type options
  //
  class cmd_new_exe_options
  {
    bool no-tests;
    bool unit-tests;
    string license = "proprietary";
    bool no-readme;
    bool alt-naming;
  };

  class cmd_new_lib_options
  {
    bool no-tests;
    bool unit-tests;
    bool no-version;
    string license = "proprietary";
    bool no-readme;
    bool alt-naming;
  };

  class cmd_new_bare_options
  {
    bool no-tests;
    string license = "proprietary";
    bool no-readme;
    bool alt-naming;
  };

  class cmd_new_empty_options
  {
    bool no-readme;
  };

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

  // The cpp flag is the "extension=?pp" alias and is mutually exclusive with
  // extension=.
  //
  class cmd_new_cxx_options
  {
    bool binless;
    bool cpp;
    string extension;
    string hxx;
    string cxx;
    string ixx;
    string txx;
    string mxx;
  };

  // --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 new package inside an already existing project rather than a
       new project."
    }

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

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

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

    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."
    }

    strings --post-hook
    {
      "<command>",
      "Run the specified command in the newly created project, package, or
       source directory.

       The <command> value is interpreted as a whitespace-separated,
       potentially quoted command line consisting of the program optionally
       followed by arguments and redirects. Specifically, a single level of
       quotes (either single or double) is removed and whitespaces are not
       treated as separators inside such quoted fragments. Currently only the
       \cb{stdout} redirect to a file is supported. For example:

       \
       $ bdep new --post-hook \"echo '.idea/ # IDE' >>.gitignore\" hello
       \

       The command line elements (program, arguments, etc) may optionally
       contain substitutions \- variable names enclosed with the \cb{@}
       substitution symbol \- which are replaced with the corresponding
       variable values to produce the actual command. The following variable
       names are recognized with the double substitution symbol (\cb{@@})
       serving as an escape sequence.

       \
       @mode@ - one of 'project', 'package', or 'subdirectory'
       @name@ - project, package, or subdirectory name
       @base@ - name base (name without extension)
       @stem@ - name stem (name base without 'lib' prefix)
       @type@ - type (--type|-t value: 'exe', 'lib', etc)
       @lang@ - language (--lang|-l value: 'c', 'c++', etc)
       @vcs@  - version control system (--vcs|-s value: 'git', etc)
       @root@ - project/package root directory
       \

       For example:

       \
       $ bdep new --post-hook \"echo bin/ >>@name@/.gitignore\" hello
       \

       These substitution variables are also made available to the hook program
       as the \cb{BDEP_NEW_*} environment variables (\cb{BDEP_NEW_MODE},
       \cb{BDEP_NEW_NAME}, etc)."
    }

    // @@ This should be a no-amalgamation type sub-options.
    //
    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.
  "
}