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

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 = (option | module | cfg-var)...

DESCRIPTION

The new command creates and initializes a new project (the first three forms) or a new package in an already existing project (the last form). All four forms 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). See Package Name for details on project/package names.

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

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

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 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 options:

no-tests – Don't add support for functional/integration testing.

unit-tests – Add support for unit testing.

lib
A project that builds a sample library. Recognized library project options:

no-tests – Don't add support for functional/integration testing.

unit-tests – Add support for unit testing.

bare
A project without any source code. Recognized bare project options:

no-tests – Don't add support for testing.

empty
An empty project that can be filled with packages (see --package). Note that the project language is ignored for this project type.

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 options:

cxx – Use the .cxx, .hxx, .ixx, .txx, and .mxx source file extensions (default).

cpp – Use the .cpp, .hpp, .ipp, .tpp, and .mpp source file extensions.

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.

NEW OPTIONS

--no-init
Don't initialize an empty build configuration set.
--package
Create a package inside an already existing project rather than a new project.
--output-dir|-o dir
Create the project in the specified directory.
--directory|-d dir
Assume the project is in the specified directory rather than in the current working directory. Only used with --package.
--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.
--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.
--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.
--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.

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.