Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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 over-
       ridden  with  --output-dir|-o  or,  in case of --package, with --direc-
       tory|-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, initial-
       izes an empty project database as if by executing the bdep-init(1) com-
       mand 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 configura-
       tion 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	speci-
       fied  with  --directory|-d,  then  it  will be deduced from the current
       working directory (see bdep-projects-configs(1) for details on specify-
       ing 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  di-
       rectory 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	direc-
       tory 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	recog-
       nizes certain well-known	files and tries	to use the extracted  informa-
       tion  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 spec-
       ified 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 un-
       specified, 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	 (tem-
	      plate),  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  de-
	      fault .hxx.

	  cxx=extension
	      Use  the specified extension for source files instead of the de-
	      fault .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  un-
	      specified, 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-op-
       tions for the rest being	language-dependent, as described next. If  un-
       specified, 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  exe-
	      cutable 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  (#mani-
	      fest-package-description)	  package  manifest  value  for	 back-
	      ground).

	  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  li-
	      brary 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 pre-
	      fix.

	  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 mani-
	      fest 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  (#mani-
	      fest-package-description)	  package  manifest  value  for	 back-
	      ground).

	  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 --pack-
	      age).  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 tem-
	      plate 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 (#mani-
	      fest-package-license)  package  manifest value for more informa-
	      tion.

	      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	exist-
	      ing 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  cre-
	      ated 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 ex-
       ecuted  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	direc-
       tory. 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  de-
       tails.

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 spec-
	      ified 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-spe-
	      cific.

       --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,  po-
	      tentially	 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 option-
	      ally 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 sym-
	      bol (@@) 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, config-
	      uration 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 synchro-
	      nized.

       --no-auto-sync
	      Don't make the added or created configuration automatically syn-
	      chronized.

       --existing|-e
	      Initialize a bpkg	configuration based on an existing build  sys-
	      tem 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  descrip-
       tion 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 di-
       rectory and split, where	headers	(typically public  headers  of	a  li-
       brary) and other	source files reside in separate	directories (most com-
       monly 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 differ-
       ences 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 pre-
       fix-source sub-options can be used to customize the respective directo-
       ries 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 ex-
       ample:

       # 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	gener-
       ated 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 lay-
       out):

       # 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 ap-
       proaches	is to create a project with the	split layout  and  the	build-
       files in	the source prefix directories rather than in the source	subdi-
       rectories:

       # 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 di-
       rectory:

       $ 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  op-
       tions  files.  For  the	new  command the search	start directory	is the
       project directory in the	package	and source modes and the parent	direc-
       tory 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)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=bdep-new&sektion=1&manpath=FreeBSD+Ports+15.0>

home | help