bdep-new(1)

bdep-new(1) 💖 — create and initialize new project

💖 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 🌸

okay so bdep new is your little project-birthday-party planner. It can create and initialize a brand-new project (the first three forms), add a new package inside an already existing project (the --package form), or drop a new source subdirectory into an already existing project/package (the --source form). Every form except --source first makes a new build2 project/package called name according to spec, and it puts it in the name subdirectory of your current working directory — unless you override that with --output-dir|-o, or, for --package, with --directory|-d. And if name has a directory component in it, then the project/package gets created inside that directory, just like you'd passed it with --output-dir|-o.

The first form then — unless you say --no-init — initializes an empty project database, like running the bdep-init(1) command with --empty. For example:

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

$ tree hello/
hello/
|-- hello/
|   |-- hello.cxx
|   `-- buildfile
|-- buildfile
`-- manifest

Same vibe for the second and third forms: they either add an existing build configuration or create a new one, then initialize the project in that configuration, exactly like running bdep-init(1) with --config-add or --config-create, 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, and it creates that file if it's not there yet. If you don't explicitly pass a project directory with --directory|-d, it gets deduced from your current working directory (peep bdep-projects-configs(1) for the deets on specifying projects). Heads up: 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 acts like it first creates a temporary project called name according to spec, then copies its source subdirectory (name/name/ by default) over to your current working directory (unless you override with --output-dir|-o). If no project/package directory is explicitly given with --directory|-d, it assumes the current working directory. 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 every form, if name is omitted, then the current working directory's name (unless overridden with --output-dir|-o) becomes the project/package/source subdirectory name. For the full tea on project/package names, see Package Name (#package-name).

The source subdirectory can be customized with the subdir project type sub-option (more on that below). 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 lives right in the project/package root directory and holds both headers (including public headers for libraries) and sources. You can switch that up in a bunch of ways with the prefix* and split project type sub-options (details below). 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.

---

okay so the sub-options just keep coming, bestie, and they all get comma-glued onto your type:

• no-subdir-source — skip the source subdirectory relative to the source prefix. poof, gone 💨
• no-subdir — shortcut for no-subdir-include,no-subdir-source. two-for-one deal 🎀
• buildfile-in-prefix — buildfiles live in the header/source prefix directories instead of inside their source subdirectories.
• third-party — makes a package for converting an existing third-party library to build2. This one is ✨opinionated✨: it automatically turns on the no-version and no-readme sub-options, plus no-symexport unless auto-symexport is specified. It also adds a bunch of values to manifest that make sense to specify in a package of a third-party project and, unless no-package-readme is specified, it generates the PACKAGE-README.md template (peep the package-description package manifest value for the background tea ☕).
• license=name
• no-readme
• no-package-readme
• alt-naming — see common sub-options below, bestie, it's down there 👇

bare 🫥

A project without any source code that can be filled later (see --source). The recognized bare project sub-options are:

• 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). The recognized empty project sub-options are:

• third-party — create a project for converting an existing third-party project to build2. This sub-option adjusts the wording of the generated README.md template to reflect such a conversion.
• no-readme — see common sub-options below.

common 💫

Common project type sub-options, the ones everybody shares:

• 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 list has the most commonly used free/open source software license IDs plus a bunch of pre-defined other: names. See the license package manifest value for more info.
  • 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 a new README.md (but still check for the existing one 👀).
• no-package-readme — don't add a 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 run before any new files are created and the post hook runs 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 ✨

okay bestie, these are the options that basically every bdep command shares, so once you learn them here you're set for life 💅 they're listed below in their quick-and-dirty form, and if you want the full ✨deluxe✨ treatment you go read bdep-common-options(1), iykyk.

---

• -v — prints the essential underlying commands as they get executed, so you can peek at what's actually happening under the hood 👀
• -V — same vibe but turned ALL the way up: prints all the underlying commands being executed 🔥
• --quiet, -q — run quietly bestie 🤫 only error messages get to speak, everything else stays silent
• --verbose level — sets how chatty the diagnostics get, with level being a number between 0 and 6 🎚️
• --stdout-format format — the representation format used when printing to stdout 🖨️
• --jobs, -j num — how many jobs run in parallel, because multitasking is main character energy 👑
• --progress — shows progress indicators for long-lasting operations like network transfers, building, etc. 🌀
• --no-progress — suppresses those progress indicators for long-lasting operations such as network transfers, building, etc. 🙈
• --diag-color — use color in diagnostics, because plain text is giving beige 🌈
• --no-diag-color — don't use color in diagnostics, monochrome mode activated 💀
• --bpkg path — the package manager program that gets used for build configuration management 📦
• --bpkg-option opt — an extra option to pass along to the package manager program ✨
• --build path — the build program used to build packages 🛠️
• --build-option opt — an extra option to pass along to the build program 💫
• --curl path — the curl program used for network operations 🌐
• --curl-option opt — an extra option to pass along to the curl program 🫶
• --pager path — the pager program used to show long text 📜
• --pager-option opt — an extra option to pass along 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 at all, we're going rogue 😤

---

lowkey the pro move: these live in their own page too, so when you forget one (you will, no shade) just run man bdep-common-options and it's all there for you 💖

🌸 SOURCE LAYOUT 🌸

okay bestie, sit down, grab a boba, because this is where it gets juicy. C and C++ projects are out here living their own lives with a whole chaotic spectrum of source code layouts 💅 — and honestly? most of them fall into two big buckets:

• combined — all the source code for a single executable or library chills in the same directory. one room, everyone together.
• split — headers (usually the public headers of a library) and the other source files live in separate directories. most commonly named include/ and src/. separate rooms, very demure, very mindful.

To support all these varying layouts, the new command splits the paths leading to source code inside a package/project into a bunch of customizable components 🎀:

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

ngl, heads up: the same physical layout can be achieved with various combos of source prefix and subdirectory, but the semantics will differ — because headers in the project get included with the source subdirectory (if any) as a prefix. see Canonical Project Structure (intro#proj-struct) for the rationale and the details, iykyk 📖

As we already saw, the source subdirectory is customizable with the subdir project type sub-option. like, 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, and in that case you customize it 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, and then you get prefix-include and prefix-source sub-options to customize each directory independently 💅 if either one is omitted, the corresponding prefix is just 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 the convenient little shortcut for the most common case, where the header prefix is include/ and the 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

You can omit the source subdirectory entirely 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

Same energy but for the split layout (and we also have to disable the generated version header, which 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 get the layout where all the source code lives in the project root, we omit both the source prefix and the subdirectory (and yep, 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 omit the source subdirectory but only in the header prefix of the split layout, by specifying the no-subdir-include sub-option (and again we have to disable the generated version header, which is not supported here 🙈):

# 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 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 the whole 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

and while we're here — if the --pre-hook or --post-hook options show up in remote default options files, that will trigger a prompt 😳 so, like, be aware.

🌸 ENVIRONMENT 🌸

Okay bestie, this is where you can whisper secrets to bdep new through the environment, and there's literally one (1) variable doing the heavy lifting:

• BDEP_AUTHOR_EMAIL — this is how you tell bdep new what email address to slap on the package. 💌

And here's the little chain of command it follows if you don't set it, because of course there's a whole fallback saga:

1. If BDEP_AUTHOR_EMAIL isn't set, new first tries to snag the email from the version control system (but only if you're actually using one, iykyk).
2. If that doesn't pan out either, it goes for the EMAIL environment variable. 💅
3. And if every single one of those fails? It just shrugs and uses a dummy you@example.org email. Not iconic, but it works. 🫶

---

🐛 BUGS 🐛

Found something cursed? Don't suffer in silence, bestie. Send those bug reports to the users@build2.org mailing list and let the build2 girlies handle it. 💖

---

👑 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. Slay, honestly — free to share, free to remix, just keep the receipts. ✨

---

And that's a wrap on bdep-new(1), fr fr! 🎀 This whole thing is from bdep 0.17.0, dated June 2024 — so if you're reading this from the future, hey, hope the vibes are still immaculate. 💜 Go forth and scaffold some truly stunning packages, bestie. Periodt. 🦋