bdep-new(1) General Commands Manual bdep-new(1) NAME bdep-new - create and initialize new project SYNOPSIS bdep new [options] [--no-init] spec [name] bdep new [options] --config-add|-A cfg-dir [@cfg-name] spec [name] bdep new [options] --config-create|-C cfg-dir [@cfg-name] spec [name] [cfg-args] bdep new [options] --package [prj-spec] spec [name] bdep new [options] --source [prj-spec] spec [name] spec = [lang] [type] [vcs] lang = --lang|-l (c|c++)[,lang-opt...] type = --type|-t (exe|lib|bare|empty)[,type-opt...] vcs = --vcs|-s (git|none)[,vcs-opt...] prj-spec = --directory|-d prj-dir cfg-args = [-- [bpkg-options]] [--existing|-e | (module | cfg-var)...] DESCRIPTION The new command creates and initializes a new project (the first three forms), a new package in an already existing project (the --package form), or a new source subdirectory in an already existing project/package (the --source form). All the forms except --source first create according to spec a new build2 project/package called name in the name subdirectory of the current working directory (unless overridden with --output-dir|-o or, in case of --package, with --directory|-d). If name contains a directory component, then the project/package is created in this directory, as if it was specified with --output-dir|-o. The first form then, unless the --no-init option is specified, initializes an empty project database as if by executing the bdep- init(1) command with the --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 bdep-init(1) command with the --config-add or --config-create option, respectively. For example: $ bdep new -l c++ -t exe -C @gcc hello cc config.cxx=g++ The --package form adds the new package to the packages.manifest file creating it if necessary. If no project directory is explicitly specified with --directory|-d, then it will be deduced from the current working directory (see 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 --source form operates as-if by first creating according to spec a temporary project called name and then copying its source subdirectory (name/name/ by default) over to the current working directory (unless overridden with --output-dir|-o). If no project/package directory is explicitly specified with --directory|-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 --output-dir|-o) is used as the project/package/source subdirectory name. See Package Name (#package- name) for details on project/package names. The source subdirectory can be customized with the 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 prefix* and split project type sub-options (see below for details). For example, to move the source subdirectory inside 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 new command also recognizes certain well-known files and tries to use the extracted information in the package manifest file. Specifically, it tries to guess the license from the LICENSE file as well as extract the summary from 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 --lang|-l option. Valid values for this option and their semantics are described next. If unspecified, a C++ project is created by default. c A C project. Recognized language sub-options: c++ A C project that can also use C++. If specified, then the hxx, cxx, ixx, txx, and mxx c++ language sub-options can also be specified. c++ A C++ project. Recognized language sub-options: cpp Use the .cpp, .hpp, .ipp, .tpp, and .mpp source file extensions (alias for extension=?pp). extension=pattern Derive source file extensions from pattern by replacing every ? with one of the c (source), h (header), i (inline), t (template), or m (module interface) letters. If unspecified and no individual extensions are specified with the below options, then ?xx is used by default. hxx=extension Use the specified extension for header files instead of the default .hxx. cxx=extension Use the specified extension for source files instead of the default .cxx. ixx=extension Use the specified extension for inline files. If unspecified, then assume no inline files are used by the project. txx=extension Use the specified extension for template files. If unspecified, then assume no template files are used by the project. mxx=extension Use the specified extension for module interface files. If unspecified, then assume no modules are used by the project. c A C++ project that can also use C. As an example, the following command creates a header-only C++ library that uses the .h extension for header files and .cpp - for source files: $ bdep new -l c++,hxx=h,cxx=cpp -t lib,binless libhello The project type can be specified with the --type|-t option. The 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. exe A project that builds a sample C or C++ executable. Recognized executable project sub-options: no-tests Don't add support for functional/integration testing. unit-tests Add support for unit testing. no-install Don't add support for installing. export-stub Add support for importing this project's targets from other projects. prefix=dir Optional source prefix relative to project/package root. subdir=dir Alternative source subdirectory relative to source prefix. no-subdir Omit the source subdirectory. buildfile-in-prefix Create the buildfile in the source prefix directory rather than in its source subdirectory. third-party Create a package for converting an existing third-party executable to build2. This sub-option automatically enables the no-readme sub-option. It also adds a number of values to manifest that makes sense to specify in a package of a third- party project and, unless no-package-readme is specified, generates the PACKAGE-README.md template (see package- description (#manifest-package-description) package manifest value for background). license=name no-readme no-package-readme alt-naming See common sub-options below. lib A project that builds a sample C or C++ library. Recognized library project sub-options: binless Create a header-only library. no-tests Don't add support for functional/integration testing. unit-tests Add support for unit testing. no-install Don't add support for installing. no-version Don't add support for generating the version header. no-symexport Don't add support for DLL symbol exporting. auto-symexport Add support for automatic DLL symbol exporting. prefix-include=dir Optional public header prefix relative to project/package root. prefix-source=dir Optional source prefix relative to project/package root. prefix=dir Shortcut for prefix-include=dir,prefix-source=dir. split Shortcut for prefix-include=include,prefix-source=src. subdir=dir Alternative source subdirectory relative to header/source prefix. no-subdir-include Omit the source subdirectory relative to the header prefix. no-subdir-source Omit the source subdirectory relative to the source prefix. no-subdir Shortcut for no-subdir-include,no-subdir-source. buildfile-in-prefix Create the buildfiles in the header/source prefix directories rather than in their source subdirectories. third-party Create a package for converting an existing third-party library to build2. This sub-option automatically enables the no-version and no-readme sub-options as well as no-symexport unless auto- symexport is specified. It also adds a number of values to manifest that makes sense to specify in a package of a third- party project and, unless no-package-readme is specified, generates the PACKAGE-README.md template (see package- description (#manifest-package-description) package manifest value for background). license=name no-readme no-package-readme alt-naming See common sub-options below. bare A project without any source code that can be filled later (see --source). Recognized bare project sub-options: no-tests Don't add support for testing. no-install Don't add support for installing. license=name no-readme alt-naming See common sub-options below. empty An empty project that can be filled with packages (see --package). Recognized empty project sub-options: third-party Create a project for converting an existing third-party project to build2. This sub-option adjusts the generated README.md template wording to reflect such a conversion. no-readme See common sub-options below. common Common project type sub-options: license=name Specify the project's license. The license name can be an SPDX License Expression (https://spdx.org/licenses/), which, in its simplest form, is just the license ID. Or it can be a free form name in the other: license name scheme. If unspecified, then 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 other: names. See the license (#manifest-package-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 no-readme Don't add new README.md (but still check for the existing one). no-package-readme Don't add new PACKAGE-README.md (but still check for the existing one). alt-naming Use the alternative build file/directory naming scheme. The project version control system can be specified with the --vcs|-s option. Valid values for this option and their semantics are described next. If unspecified, git is assumed by default. git Initialize a git(1) repository inside the project and generate .gitignore files. Recognized version control system sub-options: branch=name Use the specified name for the initial branch in the newly created repository. 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 --pre-hook and --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 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 --pre-hook and --post-hook options documentation below for details. NEW OPTIONS --no-init Don't initialize an empty build configuration set. --package Create a new package inside an already existing project rather than a new project. --source Create a new source subdirectory inside an already existing project or package rather than a new project. --output-dir|-o dir Create the project, package, or source subdirectory in the specified directory. --directory|-d dir Assume the project/package is in the specified directory rather than in the current working directory. Only used with --package or --source. --type|-t type[,opt...] Specify project type and options. Valid values for type are exe (executable project, default), lib (library project), bare (bare project without any source code), and empty (empty project ready to be filled with packages). Valid values for opt are type- specific. --lang|-l lang[,opt...] Specify project language and options. Valid values for lang are c and c++ (default). Valid values for opt are language-specific. --vcs|-s vcs[,opt...] Specify project version control system and options. Valid values for vcs are git (default) and none. Valid values for opt are system-specific. --pre-hook command --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 builtin (testscript#builtins) 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 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 @ 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 (@@) 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 @inc@ and @src@ variables are only set if the header/source prefix is split with the combined @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 BDEP_NEW_* environment variables (BDEP_NEW_MODE, BDEP_NEW_NAME, etc). --no-amalgamation Create a project with disabled amalgamation support. This option is normally only used for testing. --no-checks Suppress nested project/package checks. This option is normally only used for testing. --config-add|-A dir Add an existing build configuration dir. --config-create|-C dir Create a new build configuration in dir. --type|--config-type typ The type of the configuration being created. By default, configuration of type target is created. See bpkg-cfg-create(1) for background on configuration types. --default Make the added or created configuration the default. --no-default Don't make the first added or created configuration the default. --forward Make the added or created configuration forwarded. --no-forward Don't make the added or created configuration forwarded. --auto-sync Make the added or created configuration automatically synchronized. --no-auto-sync Don't make the added or created configuration automatically synchronized. --existing|-e Initialize a bpkg configuration based on an existing build system configuration. --wipe Wipe the configuration directory clean before creating the new configuration. --config-name|-n name Specify the build configuration as a name. --config-id num Specify the build configuration as an id. COMMON OPTIONS The common options are summarized below with a more detailed description available in bdep-common-options(1). -v Print essential underlying commands being executed. -V Print all underlying commands being executed. --quiet|-q Run quietly, only printing error messages. --verbose level Set the diagnostics verbosity to level between 0 and 6. --stdout-format format Representation format to use for printing to stdout. --jobs|-j num Number of jobs to perform in parallel. --progress Display progress indicators for long-lasting operations, such as network transfers, building, etc. --no-progress Suppress progress indicators for long-lasting operations, such as network transfers, building, etc. --diag-color Use color in diagnostics. --no-diag-color Don't use color in diagnostics. --bpkg path The package manager program to be used for build configuration management. --bpkg-option opt Additional option to be passed to the package manager program. --build path The build program to be used to build packages. --build-option opt Additional option to be passed to the build program. --curl path The curl program to be used for network operations. --curl-option opt Additional option to be passed to the curl program. --pager path The pager program to be used to show long text. --pager-option opt Additional option to be passed to the pager program. --options-file file Read additional options from file. --default-options dir The directory to load additional default options files from. --no-default-options Don't load default options files. SOURCE LAYOUT C and C++ projects employ a bewildering variety of source code layouts most of which fit into two broad classes: combined, where all the source code for a single executable or library resides in the same directory and split, where headers (typically public headers of a library) and other source files reside in separate directories (most commonly called include/ and src/). To support the creation of such varying layouts the 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 Canonical Project Structure (intro#proj-struct) for rationale and details. As we have already seen, the source subdirectory can be customized with the 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 -l c++,cpp if you prefer the .hpp/.cpp source file naming scheme. The source prefix can be combined, in which case it can be customized with the single 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 prefix-include and 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 split sub-option is a convenient shortcut for the most common case where the header prefix is include/ and source prefix is 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 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 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 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 include/ directory is inside 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 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 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 build2, one of the common approaches is to create a project with the split layout and the 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 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 DEFAULT OPTIONS FILES See bdep-default-options-files(1) for an overview of the default options files. For the 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 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 --pre-hook or --post-hook options in remote default options files will trigger a prompt. ENVIRONMENT The BDEP_AUTHOR_EMAIL environment variable can be used to specify the package email address. If not set, the new command will first try to obtain the email from the version control system (if used) and then from the EMAIL environment variable. If all these methods fail, a dummy you@example.org email is used. BUGS Send bug reports to the users@build2.org mailing list. COPYRIGHT Copyright (c) 2014-2024 the build2 authors. Permission is granted to copy, distribute and/or modify this document under the terms of the MIT License. bdep 0.17.0 June 2024 bdep-new(1)