bdep-new - Man Page

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] --subdirectory [prj-spec] spec [name]

spec     = [type] [lang] [vcs]
type     = --type|-t (exe|lib|bare|empty)[,type-opt...]
lang     = --lang|-l (c|c++)[,lang-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 --subdirectory form). All the forms except --subdirectory 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).

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 -t exe -l c++ hello

Similarly, the second and third forms add an existing or create new build configuration and then initialize the project in that configuration as if by executing the bdep-init(1) command with the --config-add or --config-create option, respectively. For example:

$ bdep new -t exe -l c++ -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 the current working directory is assumed. Note that nested packages are not allowed. For example:

$ bdep new -t empty hello
$ cd hello

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

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

After executing these commands the hello project will contain two packages, libhello and hello.

The --subdirectory form operates as-if by first creating according to spec a temporary project called name and then copying its source subdirectory (name/name/) 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 -t bare hello
$ cd hello

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

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

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

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/subdirectory name. See Package Name (#package-name) for details on project/package names.

The output directory may already contain existing files provided they don't clash with the files to be created. The 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 -t lib -l c++

The project parameters such as type (executable, library, etc), language, and version control system can be customized as described next. Some of these parameters also support parameter-specific sub-options (such as the file extensions to use in a C++ project) that can be specified with a comma after the parameter value.

The project type can be specified with the --type|-t option. Valid values for this option and their semantics are described next. If unspecified, an executable project is created by default.

exe

A project that builds a sample 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.

   license=name
   no-readme
   alt-naming

See common sub-options below.

lib

A project that builds a sample library. Recognized library 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.

   no-version

Don't add support for generating the version header.

   license=name
   no-readme
   alt-naming

See common sub-options below.

bare

A project without any source code that can be filled later (see --subdirectory). 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). Note that the project language is ignored for this project type. Recognized empty project sub-options:

   no-readme

See common sub-options below.

common

Common project type sub-options:

   license=name

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

   no-readme

Don't add README.md.

   alt-naming

Use the alternative build file/directory naming scheme.

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.

c++

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

   binless

Create a header-only library.

   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.

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 -t lib -l c++,binless,hxx=h,cxx=cpp libhello

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.

none

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

The created project, package, or subdirectory can be further customized using the pre and post-creation hooks specified with the --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.

--subdirectory

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

--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 'subdirectory'
@name@ - project, package, or subdirectory name
@base@ - name base (name without extension)
@stem@ - name stem (name base without 'lib' prefix)
@type@ - type (--type|-t value: 'exe', 'lib', etc)
@lang@ - language (--lang|-l value: 'c', 'c++', etc)
@vcs@  - version control system (--vcs|-s value: 'git', etc)
@root@ - project/package root directory

For example:

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

These substitution variables are also made available to the hook program as the 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.

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

--jobs|-j num

Number of jobs to perform in parallel.

--no-progress

Suppress progress indicators for long-lasting operations, such as network transfers, building, etc.

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

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 subdirectory modes and the parent directory of the new project in all other modes. The following options files are searched for in each directory and, if found, loaded in the order listed:

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

The following new command options cannot be specified in the default options files:

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

While the presence of the --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 @example.org email is used.

Bugs

Send bug reports to the users@build2.org mailing list.

Referenced By

bdep(1).

November 2019 bdep 0.12.0