path: root/bdep/new.cli

// file      : bdep/new.cli
// 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> <bpkg-options> <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> \ \ \ \ = [<lang>] [<type>] [<vcs>]\n
        <lang> \ \ \ \ = \b{--lang}|\b{-l} (\b{c}|\b{c++})[\b{,}<lang-opt>...]\n
        <type> \ \ \ \ = \b{--type}|\b{-t} (\b{exe}|\b{lib}|\b{bare}|\b{empty})[\b{,}<type-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> = [\b{--} <bpkg-options>] [\b{--existing}|\b{-e} | (<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}}).

     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 -l c++ -t exe 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 -l c++ -t exe -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 -l c++ -t lib  libhello
     $ bdep new --package -l c++ -t exe  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 -l c++ -t lib libhello
     $ bdep new --subdirectory -l c++ -t exe  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/}.

     In all the forms, if <name> is omitted, then the current working
     directory name (unless overridden with \c{\b{--output-dir}|\b{-o}}) is
     used as the project/package/subdirectory name. See \l{bpkg#package-name
     Package Name} for details on project/package names.

     The output directory may already contain existing files provided they
     don't clash with the files to be created. The \cb{new} command also
     recognizes certain well-known files and tries to use the extracted
     information in the package \cb{manifest} file. Specifically, it tries to
     guess the license from the \cb{LICENSE} file as well as extract the
     summary from \cb{README.md}. This allows for the following workflow:

     \
     # Create a project with LICENSE and README.md on one of the Git
     # hosting services (GitHub, GitLab, etc).

     $ git clone .../libhello.git
     $ cd libhello

     $ bdep new -l c++ -t lib
     \

     The project parameters such as language, type (executable, library, etc),
     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 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 -l c++,binless,hxx=h,cxx=cpp -t lib libhello
     \

     The project type can be specified with the \c{\b{--type}|\b{-t}} option.
     The \cb{empty} project type is language-agnostic with the semantics and
     valid sub-options for the rest being language-dependant, as described
     next. If unspecified, an executable project is created by default.

     \dl|

     \li|\cb{exe}

         A project that builds a sample C or C++ 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\ \ \ \cb{no-install}

         Don't add support for installing.|

     \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 C or C++ 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-install}

         Don't add support for installing.|

     \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\ \ \ \cb{no-install}

         Don't add support for installing.|

     \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}). 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 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 created project, package, or subdirectory can be further customized
     using the pre and post-creation hooks specified with the \cb{--pre-hook}
     and \cb{--post-hook} options, respectively. The pre hooks are executed
     before any new files are created and the post hook \- after all the files
     have been created. The hook commands are executed in the project,
     package, or source directory as their current working directory. For
     example:

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

     The pre hooks are primarily useful for moving/renaming existing files
     that would otherwise clash with files created by the \cb{new}
     command. For example:

     \
     $ bdep new --pre-hook  \"mv .gitignore .gitignore.bak\" \\
                --post-hook \"cat .gitignore.bak >>.gitignore\" \\
                --post-hook \"rm .gitignore.bak\" ...
     \

     See the \cb{--pre-hook} and \cb{--post-hook} options documentation below
     for details.
     "
  }

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

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

  class cmd_new_bare_options
  {
    bool no-tests;
    bool no-install;
    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 --pre-hook
    {
      "<command>"
      // Shares documentation with --post-hook.
    }

    strings --post-hook
    {
      "<command>",
      "Run the specified command before/after creating the project, package, or
       source directory.

       The <command> value is interpreted as a whitespace-separated,
       potentially quoted command line consisting of a program or a portable
       \l{testscript#builtins builtin} 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|DEFAULT OPTIONS FILES|

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

   \
   bdep.options
   bdep-{config config-add}.options                # if --config-add|-A
   bdep-{config config-add config-create}.options  # if --config-create|-C
   bdep-new.options
   bdep-new-{project|package|subdirectory}.options # (mode-dependent)
   \

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

   \
   --output-dir|-o
   --directory|-d
   --package
   --subdirectory
   --no-checks
   --config-add|-A
   --config-create|-C
   --wipe
   \

   While the presence of the \cb{--pre-hook} or \cb{--post-hook} options in
   remote default options files will trigger a prompt.


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