home | help
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 cre-
     ating 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 tem-
     porary project  called  name  and	then  copying  its  source  subdirectory
     (name/name/ by default) over to the current working directory (unless over-
     ridden with --output-dir|-o). If no project/package directory is explicitly
     specified	with  --directory|-d,  then the current working directory is as-
     sumed. 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/pack-
     age/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  li-
     braries) as well as sources. This can be customized in a number of ways us-
     ing 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 val-
     ues  for  this  option and their semantics are described next.  If unspeci-
     fied, 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 ex-
	    tensions 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	unspeci-
	    fied, 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  exe-
	    cutable 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  tem-
	    plate (see package-description (#manifest-package-description) pack-
	    age 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 tem-
	    plate (see package-description (#manifest-package-description) pack-
	    age 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  Li-
	    cense  Expression  (https://spdx.org/licenses/),  which, in its sim-
	    plest form, is just the license ID. Or it can be a free form name in
	    the other: license name scheme. If unspecified, then other:  propri-
	    etary  is assumed. The following tables lists the most commonly used
	    free/open source software license IDs as well as a number of pre-de-
	    fined 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  op-
     tion.  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 .git-
	    ignore 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 cus-
     tomized 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 (ex-
	    ecutable  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-spe-
	    cific.

     --pre-hook command

     --post-hook command
	    Run  the  specified command before/after creating the project, pack-
	    age, or source directory.

	    The command value is interpreted as a  whitespace-separated,  poten-
	    tially  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 in-
	    side 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 @ substitu-
	    tion 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,  configura-
	    tion  of  type  target  is created. See bpkg-cfg-create(1) for back-
	    ground 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 synchro-
	    nized.

     --existing|-e
	    Initialize a bpkg configuration based on an  existing  build  system
	    configuration.

     --wipe Wipe  the configuration directory clean before creating the new con-
	    figuration.

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

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

     --offline
	    Do not attempt to download resources (packages, repository metadata,
	    etc), instead taking them from the local fetch  cache  if  available
	    and failing otherwise.

     --no-fetch-cache
	    Disable  local  caching  of download resources (packages, repository
	    metadata, etc).

     --fetch-cache mode
	    Comma-separated list of local fetch cache modes.

     --fetch-cache-session id
	    The local fetch cache session.

     --sqlite-synchronous mode
	    Filesystem synchronization mode for the project SQLite database.

     --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 cus-
     tomizable components:

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

     Note that while the same physical layout can be achieved with various  com-
     binations	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 (in-
     tro#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 in-
     dependently. 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  exam-
     ple:

     # 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 dis-
     able 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 exam-
     ple:

     # 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  ap-
     proaches 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 direc-
     tory  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  op-
     tions 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 de-
     fault options files will trigger a prompt.

ENVIRONMENT
     The BDEP_AUTHOR_EMAIL environment variable can be used to specify the pack-
     age 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 en-
     vironment 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-2026 the build2 authors.

     Permission is granted to copy, distribute and/or modify this document under
     the terms of the MIT License.

bdep 0.18.0			   April 2026			     bdep-new(1)

home | help