// 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{--source} [<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{--source} form). All the forms except
     \cb{--source} 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}}
     or, in case of \cb{--package}, with \c{\b{--directory}|\b{-d}}).
     If <name> contains a directory component, then the project/package is
     created in this directory, as if it was specified 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

     $ tree hello/
     hello/
     ├── hello/
     │   ├── hello.cxx
     │   └── buildfile
     ├── buildfile
     └── manifest
     \

     Similarly, the second and third forms add an existing or create a 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
     it will be deduced from the current working directory (see
     \l{bdep-projects-configs(1)} for details on specifying projects). 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++

     $ cd ..
     $ tree hello/
     hello/
     ├── hello/
     │   ├── hello/
     │   │   ├── hello.cxx
     │   │   └── buildfile
     │   ├── buildfile
     │   └── manifest
     ├── libhello/
     │   ├── libhello/
     │   │   ├── hello.hxx
     │   │   ├── hello.cxx
     │   │   └── buildfile
     │   ├── buildfile
     │   └── manifest
     └── packages.manifest
     \

     The \cb{--source} 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{/}} by default) 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 -l c++ -t bare hello
     $ cd hello

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

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

     $ cd ..
     $ tree hello/
     hello/
     ├── hello/
     │   ├── hello.cxx
     │   └── buildfile
     ├── libhello/
     │   ├── hello.hxx
     │   ├── hello.cxx
     │   └── buildfile
     ├── buildfile
     └── manifest
     \

     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/source subdirectory name. See
     \l{bpkg#package-name Package Name} for details on project/package names.

     The source subdirectory can be customized with the \cb{subdir} project
     type sub-option (see below for details). For example:

     \
     $ bdep new -l c++ -t lib,subdir=libhello/io libhello-io

     $ tree libhello-io/
     libhello-io/
     └── libhello/
         └── io/
             ├── hello-io.hxx
             └── hello-io.cxx
     \

     By default the source subdirectory is created in the project/package root
     directory and contains both headers (including public headers for
     libraries) as well as sources. This can be customized in a number of ways
     using the \cb{prefix*} and \cb{split} project type sub-options (see below
     for details). For example, to move the source subdirectory inside
     \cb{src/}:

     \
     $ bdep new -l c++ -t exe,prefix=src hello

     $ tree hello/
     hello/
     └── src/
         └── hello/
             └── hello.cxx
     \

     And to split the library source subdirectory into public headers and
     other source files:

     \
     $ bdep new -l c++ -t lib,split libhello

     $ tree libhello/
     libhello/
     ├── include/
     │   └── libhello/
     │       └── hello.hxx
     └── src/
         └── libhello/
             └── hello.cxx
     \

     See the SOURCE LAYOUT section below for details and more examples.

     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. Recognized language sub-options:|

     \li|\n\ \ \ \cb{c++}

         A C project that can also use C++. If specified, then the \cb{hxx},
         \cb{cxx}, \cb{ixx}, \cb{txx}, and \cb{mxx} \cb{c++} language
         sub-options can also be specified.||

     \dl|

     \li|\cb{c++}

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

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

     \li|\n\ \ \ \cb{c}

         A C++ project that can also use C.||

     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++,hxx=h,cxx=cpp -t lib,binless 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-dependent, 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\ \ \ \cb{export-stub}

         Add support for importing this project's targets from other projects.|

     \li|\n\ \ \ \c{\b{prefix=}\i{dir}}

         Optional source prefix relative to project/package root.|

     \li|\n\ \ \ \c{\b{subdir=}\i{dir}}

         Alternative source subdirectory relative to source prefix.|

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

         Omit the source subdirectory.|

     \li|\n\ \ \ \cb{buildfile-in-prefix}

         Create the \cb{buildfile} in the source prefix directory rather than
         in its source subdirectory.|

     \li|\n\ \ \ \cb{third-party}

         Create a package for converting an existing third-party executable to
         \cb{build2}. This sub-option automatically enables the \cb{no-readme}
         sub-option. It also adds a number of values to \cb{manifest} that
         makes sense to specify in a package of a third-party project and,
         unless \cb{no-package-readme} is specified, generates the
         \cb{PACKAGE-README.md} template (see
         \l{bpkg#manifest-package-description \cb{package-description}}
         package manifest value for background).|

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

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

     \li|\ \ \ \cb{no-package-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{binless}

         Create a header-only library.|

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

         Don't add support for DLL symbol exporting.|

     \li|\n\ \ \ \cb{auto-symexport}

         Add support for automatic DLL symbol exporting.|

     \li|\n\ \ \ \c{\b{prefix-include=}\i{dir}}

         Optional public header prefix relative to project/package root.|

     \li|\n\ \ \ \c{\b{prefix-source=}\i{dir}}

         Optional source prefix relative to project/package root.|

     \li|\n\ \ \ \c{\b{prefix=}\i{dir}}

         Shortcut for \c{\b{prefix-include=}\i{dir}\b{,prefix-source=}\i{dir}}.|

     \li|\n\ \ \ \cb{split}

         Shortcut for \cb{prefix-include=include,prefix-source=src}.|

     \li|\n\ \ \ \c{\b{subdir=}\i{dir}}

         Alternative source subdirectory relative to header/source prefix.|

     \li|\n\ \ \ \cb{no-subdir-include}

         Omit the source subdirectory relative to the header prefix.|

     \li|\n\ \ \ \cb{no-subdir-source}

         Omit the source subdirectory relative to the source prefix.|

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

         Shortcut for \cb{no-subdir-include,no-subdir-source}.|

     \li|\n\ \ \ \cb{buildfile-in-prefix}

         Create the \cb{buildfiles} in the header/source prefix directories
         rather than in their source subdirectories.|

     \li|\n\ \ \ \cb{third-party}

         Create a package for converting an existing third-party library to
         \cb{build2}. This sub-option automatically enables the
         \cb{no-version} and \cb{no-readme} sub-options as well as
         \cb{no-symexport} unless \cb{auto-symexport} is specified. It also
         adds a number of values to \cb{manifest} that makes sense to specify
         in a package of a third-party project and, unless
         \cb{no-package-readme} is specified, generates the
         \cb{PACKAGE-README.md} template (see
         \l{bpkg#manifest-package-description \cb{package-description}}
         package manifest value for background).|

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

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

     \li|\ \ \ \cb{no-package-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{--source}). 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{third-party}

         Create a project for converting an existing third-party project to
         \cb{build2}. This sub-option adjusts the generated \cb{README.md}
         template wording to reflect such a conversion.|

     \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. The license name can be an
         \l{https://spdx.org/licenses/ SPDX License Expression}, which, in its
         simplest form, is just the license ID. Or it can be a free form name
         in the \cb{other:} license name scheme. If unspecified, then
         \cb{other: proprietary} is assumed. The following tables lists the
         most commonly used free/open source software license IDs as well as a
         number of pre-defined \cb{other:} names. See the
         \l{bpkg#manifest-package-license \cb{license}} package manifest value
         for more information.

         \
         MIT                MIT License.

         BSD-2-Clause       BSD 2-Clause \"Simplified\" License
         BSD-3-Clause       BSD 3-Clause \"New\" or \"Revised\" License

         GPL-3.0-only       GNU General Public License v3.0 only
         GPL-3.0-or-later   GNU General Public License v3.0 or later

         LGPL-3.0-only      GNU Lesser General Public License v3.0 only
         LGPL-3.0-or-later  GNU Lesser General Public License v3.0 or later

         AGPL-3.0-only      GNU Affero General Public License v3.0 only
         AGPL-3.0-or-later  GNU Affero General Public License v3.0 or later

         Apache-2.0         Apache License 2.0

         MPL-2.0            Mozilla Public License 2.0

         BSL-1.0            Boost Software License 1.0

         Unlicense          The Unlicense (public domain)
         \

         \
         other: public domain     Released into the public domain
         other: available source  Not free/open source with public source code
         other: proprietary       Not free/open source
         other: TODO              License is not yet decided
         \

         |

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

         Don't add new \cb{README.md} (but still check for the existing one).|

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

         Don't add new \cb{PACKAGE-README.md} (but still check for the
         existing one).|

     \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. Recognized version control system sub-options:|

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

         Use the specified name for the initial branch in the newly created
         repository.||

     \dl|

     \li|\cb{none}

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

     The created project, package, or source 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.
     "
  }

  // --lang options
  //
  // The ?xx sub-options can only be specified if the c++ sub-option is
  // specified.
  //
  class cmd_new_c_options
  {
    bool cpp|"c++";
    string hxx;
    string cxx;
    string ixx;
    string txx;
    string mxx;
  };

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

  //--type options
  //
  // Note that we only support combined executable source layouts.
  //
  class cmd_new_exe_options
  {
    bool no-tests;
    bool unit-tests;
    bool no-install;
    bool export-stub;
    dir_path prefix;
    dir_path subdir;
    bool no-subdir;
    bool buildfile-in-prefix;
    bool third-party;
    string license = "other: proprietary";
    bool no-readme;
    bool no-package-readme;
    bool alt-naming;

    // Old name for the subdir sub-option (thus undocumented). @@ TMP drop
    //
    // If specified, we will fail suggesting to use the new sub-option instead.
    //
    dir_path "source";
  };

  class cmd_new_lib_options
  {
    bool binless;
    bool no-tests;
    bool unit-tests;
    bool no-install;
    bool no-version;
    bool no-symexport;
    bool auto-symexport;
    dir_path prefix-include;
    dir_path prefix-source;
    dir_path prefix;
    bool split;
    dir_path subdir;
    bool no-subdir-include;
    bool no-subdir-source;
    bool no-subdir;
    bool buildfile-in-prefix;
    bool third-party;
    string license = "other: proprietary";
    bool no-readme;
    bool no-package-readme;
    bool alt-naming;

    // Old name for the subdir sub-option (thus undocumented). @@ TMP drop.
    //
    // If specified, we will fail suggesting to use the new sub-option instead.
    //
    dir_path "source";
  };

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

  class cmd_new_empty_options
  {
    bool third-party;
    bool no-readme;
  };

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

  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 --source
    {
      "Create a new source subdirectory inside an already existing project or
       package rather than a new project."
    }

    // Old name for the --source option (thus undocumented).
    //
    // If specified, we will fail suggesting to use the new option instead.
    //
    bool --subdirectory;

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

    // Note that --type overrides --type|--config-type from
    // configuration_add_options.
    //
    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 'source'
       @name@ - project, package, or source subdirectory name
       @base@ - name base (name without extension)
       @stem@ - name stem (name base without 'lib' prefix)
       @root@ - project/package root directory
       @pfx@  - combined prefix relative to project/package root
       @inc@  - split header prefix relative to project/package root
       @src@  - split source prefix relative to project/package root
       @sub@  - source subdirectory relative to header/source 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)
       \

       Note that the \cb{@inc@} and \cb{@src@} variables are only set if the
       header/source prefix is split with the combined \cb{@pfx@} variable set
       otherwise.

       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#src-layout|SOURCE LAYOUT|

   C and C++ projects employ a bewildering variety of source code layouts most
   of which fit into two broad classes: \i{combined}, where all the source
   code for a single executable or library resides in the same directory and
   \i{split}, where headers (typically public headers of a library) and other
   source files reside in separate directories (most commonly called
   \cb{include/} and \cb{src/}).

   To support the creation of such varying layouts the \cb{new} command
   divides paths leading to source code inside a package/project into a number
   of customizable components:

   \
   libhello/{include,src}/hello/
       ^         ^          ^
       |         |          |
    project/   source    source
    package    prefix  subdirectory
     root
   \

   Note that while the same physical layout can be achieved with various
   combinations of source prefix and subdirectory, there will be differences
   in semantics since the headers in the project are included with the source
   subdirectory (if any) as a prefix. See \l{intro#proj-struct Canonical
   Project Structure} for rationale and details.

   As we have already seen, the source subdirectory can be customized with the
   \cb{subdir} project type sub-option. For example:

   \
   # libhello/hello/

   $ bdep new -l c++ -t lib,subdir=hello libhello

   $ tree libhello/
   libhello/
   └── hello/
       ├── hello.hxx
       └── hello.cxx
   \

   Note: pass \cb{-l\ c++,cpp} if you prefer the \cb{.hpp}/\cb{.cpp} source
   file naming scheme.

   The source prefix can be combined, in which case it can be customized with
   the single \cb{prefix} project type sub-option. For example:

   \
   # hello/src/hello/

   $ bdep new -l c++ -t exe,prefix=src hello

   $ tree hello/
   hello/
   └── src/
       └── hello/
           └── hello.cxx
   \

   The prefix can also be split, in which case the \cb{prefix-include} and
   \cb{prefix-source} sub-options can be used to customize the respective
   directories independently. If either is omitted, then the corresponding
   prefix is left empty. For example:

   \
   # libhello/{include,.}/libhello/

   $ bdep new -l c++ -t lib,prefix-include=include libhello

   $ tree libhello/
   libhello/
   ├── include/
   │   └── libhello/
   │       └── hello.hxx
   └── libhello/
       └── hello.cxx
   \

   The \cb{split} sub-option is a convenient shortcut for the most common case
   where the header prefix is \cb{include/} and source prefix is \cb{src/}. For
   example:

   \
   # libhello/{include,src}/libhello/

   $ bdep new -l c++ -t lib,split libhello

   $ tree libhello/
   libhello/
   ├── include/
   │   └── libhello/
   │       └── hello.hxx
   └── src/
       └── libhello/
           └── hello.cxx
   \

   The source subdirectory can be omitted by specifying the \cb{no-subdir}
   project type sub-option. For example:

   \
   # hello/src/

   $ bdep new -l c++ -t exe,prefix=src,no-subdir hello

   $ tree hello/
   hello/
   └── src/
       └── hello.cxx
   \

   The same but for the split layout (we also have to disable the generated
   version header that is not supported in this layout):

   \
   # libhello/{include,src}/

   $ bdep new -l c++ -t lib,split,no-subdir,no-version libhello

   $ tree libhello/
   libhello/
   ├── include/
   │   └── hello.hxx
   └── src/
       └── hello.cxx
   \

   To achieve the layout where all the source code resides in the project
   root, we omit both the source prefix and subdirectory (we also have to
   disable a couple of other features that are not supported in this layout):

   \
   # hello/

   $ bdep new -l c++ -t lib,no-subdir,no-version,no-tests libhello

   $ tree libhello/
   libhello/
   ├── hello.cxx
   └── hello.hxx
   \

   We can also omit the source subdirectory but only in the source prefix of
   the split layout by specifying the \cb{no-subdir-source} sub-option. For
   example:

   \
   # libhello/{include/hello,src}/

   $ bdep new -l c++ -t lib,split,subdir=hello,no-subdir-source libhello

   $ tree libhello/
   libhello/
   ├── include/
   │   └── hello/
   │       └── hello.hxx
   └── src/
       └── hello.cxx
   \

   Similarly, we can also omit the source subdirectory but only in the header
   prefix of the split layout by specifying the \cb{no-subdir-include}
   sub-option (we also have to disable the generated version header that is
   not supported in this layout):

   \
   # libhello/{include,src/hello}/

   $ bdep new                                                         \
     -l c++                                                           \
     -t lib,split,subdir=hello,no-subdir-include,no-version           \
     libhello

   $ tree libhello/
   libhello/
   ├── include/
   │   └── hello.hxx
   └── src/
       └── hello/
           └── hello.cxx
   \

   To achieve the split layout where the \cb{include/} directory is inside
   \cb{src/}:

   \
   # libhello/src/{include,.}/hello/

   $ bdep new                                                         \
     -l c++                                                           \
     -t lib,prefix-include=src/include,prefix-source=src,subdir=hello \
     libhello

   $ tree libhello/
   libhello/
   └── src/
       ├── include/
       │   └── hello/
       │       └── hello.hxx
       └── hello/
           └── hello.cxx
   \

   A similar layout but without the source subdirectory in \cb{src/}:

   \
   # libhello/src/{include/hello,.}/

   $ bdep new                                                         \
     -l c++                                                           \
     -t lib,prefix-include=src/include,prefix-source=src,\
   subdir=hello,no-subdir-source                                      \
     libhello

   $ tree libhello/
   libhello/
   └── src/
       ├── include/
       │   └── hello/
       │       └── hello.hxx
       └── hello.cxx
   \

   The layout used by the Boost libraries:

   \
   # libhello/{include/hello,libs/hello/src}/

   $ bdep new                                                         \
     -l c++                                                           \
     -t lib,prefix-include=include,prefix-source=libs/hello/src,\
   subdir=hello,no-subdir-source                                      \
     libhello

   $ tree libhello/
   libhello/
   ├── include/
   │   └── hello/
   │       └── hello.hxx
   └── libs/
       └── hello/
           └── src/
               └── hello.cxx
   \

   A layout where multiple components each have their own \cb{include/src}
   split:

   \
   # hello/libhello1/{include/hello1,src}/
   # hello/libhello2/{include/hello2,src}/

   $ bdep new -l c++ -t bare hello

   $ bdep new -d hello --source                                       \
     -l c++                                                           \
     -t lib,\
   prefix-include=libhello1/include,prefix-source=libhello1/src,\
   subdir=hello1,no-subdir-source                                     \
     libhello1

   $ bdep new -d hello --source                                       \
     -l c++                                                           \
     -t lib,\
   prefix-include=libhello2/include,prefix-source=libhello2/src,\
   subdir=hello2,no-subdir-source                                     \
     libhello2

   $ tree hello/
   hello/
   ├── libhello1/
   │   ├── include/
   │   │   └── hello1/
   │   │       └── hello1.hxx
   │   └── src/
   │       └── hello1.cxx
   └── libhello2/
       ├── include/
       │   └── hello2/
       │       └── hello2.hxx
       └── src/
           └── hello2.cxx
   \

   A layout where libraries and executables have different prefixes:

   \
   # hello/libs/libhello/{include/hello,src}/
   # hello/src/hello/

   $ bdep new -l c++ -t bare hello

   $ bdep new -d hello --source                                       \
     -l c++                                                           \
     -t lib,\
   prefix-include=libs/libhello/include,prefix-source=libs/libhello/src,\
   subdir=hello,no-subdir-source                                      \
     libhello

   $ bdep new -d hello --source -l c++ -t exe,prefix=src hello

   $ tree hello/
   hello/
   ├── libs/
   │   └── libhello/
   │       ├── include/
   │       │   └── hello/
   │       │       └── hello.hxx
   │       └── src/
   │           └── hello.cxx
   └── src/
       └── hello/
           └── hello.cxx
   \

   When packaging a third-party project for \cb{build2}, one of the common
   approaches is to create a project with the split layout and the
   \cb{buildfiles} in the source prefix directories rather than in the source
   subdirectories:

   \
   # hello/libhello/{include,src}/hello/
   # hello/libhello/{include,src}/buildfile

   $ bdep new -l c -t empty hello

   $ bdep new -d hello --package                                      \
     -l c                                                             \
     -t lib,                                                          \
   split,subdir=hello,no-version,no-symexport,buildfile-in-prefix     \
     libhello

   $ tree hello/
   hello/
   └── libhello/
       ├── include/
       │   ├── buildfile
       │   └── hello/
       │       └── hello.h
       └── src/
           ├── buildfile
           └── hello/
               └── hello.c
   \

   After that the upstream project is added as a \cb{git} submodule to the
   project root directory and the source subdirectories are replaced with the
   symbolic links to the directories inside the upstream project directory:

   \
   $ tree hello/
   hello/
   ├── libhello/
   │   ├── include/
   │   │   ├── buildfile
   │   │   └── hello/ -> ../../upstream/include/hello/
   │   └── src/
   │       ├── buildfile
   │       └── hello/ -> ../../upstream/src/
   └── upstream/
       ├── include/
       │   └── hello/
       │       └── hello.h
       └── src/
           └── hello.c
   \

   \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 source 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|source}.options # (mode-dependent)
   \

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

   \
   --output-dir|-o
   --directory|-d
   --package
   --source
   --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{you@example.org} email is used.
  "
}