1bdep-new(1) General Commands Manual bdep-new(1)
2
6 bdep-new - create and initialize new project
7
9 bdep new [options] [--no-init] spec [name]
10 bdep new [options] --config-add|-A cfg-dir [@cfg-name] spec [name]
11 bdep new [options] --config-create|-C cfg-dir [@cfg-name] spec [name]
12 [cfg-args]
13 bdep new [options] --package [prj-spec] spec [name]
14 bdep new [options] --subdirectory [prj-spec] spec [name]
15 spec = [type] [lang] [vcs]
17 type = --type|-t (exe|lib|bare|empty)[,type-opt...]
18 lang = --lang|-l (c|c++)[,lang-opt...]
19 vcs = --vcs|-s (git|none)[,vcs-opt...]
20 prj-spec = --directory|-d prj-dir
21 cfg-args = [-- bpkg-options] [--existing|-e | (module | cfg-var)...]
22
24 The new command creates and initializes a new project (the first three
25 forms), a new package in an already existing project (the --package
26 form), or a new source subdirectory in an already existing
27 project/package (the --subdirectory form). All the forms except --sub‐
28 directory first create according to spec a new build2 project/package
29 called name in the name subdirectory of the current working directory
30 (unless overridden with --output-dir|-o).
31 The first form then, unless the --no-init option is specified, initial‐
33 izes an empty project database as if by executing the bdep-init(1) com‐
34 mand with the --empty option. For example:
35 $ bdep new -t exe -l c++ hello
37 Similarly, the second and third forms add an existing or create new
39 build configuration and then initialize the project in that configura‐
40 tion as if by executing the bdep-init(1) command with the --config-add
41 or --config-create option, respectively. For example:
42 $ bdep new -t exe -l c++ -C @gcc hello cc config.cxx=g++
44 The --package form adds the new package to the packages.manifest file
46 creating it if necessary. If no project directory is explicitly speci‐
47 fied with --directory|-d, then the current working directory is
48 assumed. Note that nested packages are not allowed. For example:
49 $ bdep new -t empty hello
51 $ cd hello
52 $ bdep new --package -t lib -l c++ libhello
54 $ bdep new --package -t exe -l c++ hello
55 $ bdep init -C @gcc cc config.cxx=g++
57 After executing these commands the hello project will contain two pack‐
59 ages, libhello and hello.
60 The --subdirectory form operates as-if by first creating according to
62 spec a temporary project called name and then copying its source subdi‐
63 rectory (name/name/) over to the current working directory (unless
64 overridden with --output-dir|-o). If no project/package directory is
65 explicitly specified with --directory|-d, then the current working
66 directory is assumed. For example:
67 $ bdep new -t bare hello
69 $ cd hello
70 $ bdep new --subdirectory -t lib -l c++ libhello
72 $ bdep new --subdirectory -t exe -l c++ hello
73 $ bdep init -C @gcc cc config.cxx=g++
75 After executing these commands the hello project will contain two
77 source subdirectories, libhello/ and hello/.
78 In all the forms, if name is omitted, then the current working direc‐
80 tory name (unless overridden with --output-dir|-o) is used as the
81 project/package/subdirectory name. See Package Name (#package-name) for
82 details on project/package names.
83 The output directory may already contain existing files provided they
85 don't clash with the files to be created. The new command also recog‐
86 nizes certain well-known files and tries to use the extracted informa‐
87 tion in the package manifest file. Specifically, it tries to guess the
88 license from the LICENSE file as well as extract the summary from
89 README.md. This allows for the following workflow:
90 # Create a project with LICENSE and README.md on one of the Git
92 # hosting services (GitHub, GitLab, etc).
93 $ git clone .../libhello.git
95 $ cd libhello
96 $ bdep new -t lib -l c++
98 The project parameters such as type (executable, library, etc), lan‐
100 guage, and version control system can be customized as described next.
101 Some of these parameters also support parameter-specific sub-options
102 (such as the file extensions to use in a C++ project) that can be spec‐
103 ified with a comma after the parameter value.
104 The project type can be specified with the --type|-t option. Valid
106 values for this option and their semantics are described next. If
107 unspecified, an executable project is created by default.
108 exe
110 A project that builds a sample executable. Recognized executable
111 project sub-options:
112 no-tests
114 Don't add support for functional/integration testing.
115 unit-tests
117 Add support for unit testing.
118 no-install
120 Don't add support for installing.
121 license=name
123 no-readme
126 alt-naming
129 See common sub-options below.
130 lib
132 A project that builds a sample library. Recognized library
133 project sub-options:
134 no-tests
136 Don't add support for functional/integration testing.
137 unit-tests
139 Add support for unit testing.
140 no-install
142 Don't add support for installing.
143 no-version
145 Don't add support for generating the version header.
146 license=name
148 no-readme
151 alt-naming
154 See common sub-options below.
155 bare
157 A project without any source code that can be filled later (see
158 --subdirectory). Recognized bare project sub-options:
159 no-tests
161 Don't add support for testing.
162 no-install
164 Don't add support for installing.
165 license=name
167 no-readme
170 alt-naming
173 See common sub-options below.
174 empty
176 An empty project that can be filled with packages (see --pack‐
177 age). Note that the project language is ignored for this project
178 type. Recognized empty project sub-options:
179 no-readme
181 See common sub-options below.
182 common
184 Common project type sub-options:
185 license=name
187 Specify the project's license. Commonly used license names are
188 MIT, ASLv2 (Apache License 2.0), GPLv3, and proprietary. If
189 unspecified, then proprietary is assumed. See the license (#man‐
190 ifest-package-license) package manifest value for details.
191 no-readme
193 Don't add README.md.
194 alt-naming
196 Use the alternative build file/directory naming scheme.
197 The project language can be specified with the --lang|-l option. Valid
199 values for this option and their semantics are described next. If
200 unspecified, a C++ project is created by default.
201 c
203 A C project.
204 c++
206 A C++ project. Recognized language sub-options:
207 binless
209 Create a header-only library.
210 cpp
212 Use the .cpp, .hpp, .ipp, .tpp, and .mpp source file extensions
213 (alias for extension=?pp).
214 extension=pattern
216 Derive source file extensions from pattern by replacing every ?
217 with one of the c (source), h (header), i (inline), t (tem‐
218 plate), or m (module interface) letters. If unspecified and no
219 individual extensions are specified with the below options, then
220 ?xx is used by default.
221 hxx=extension
223 Use the specified extension for header files instead of the
224 default .hxx.
225 cxx=extension
227 Use the specified extension for source files instead of the
228 default .cxx.
229 ixx=extension
231 Use the specified extension for inline files. If unspecified,
232 then assume no inline files are used by the project.
233 txx=extension
235 Use the specified extension for template files. If unspecified,
236 then assume no template files are used by the project.
237 mxx=extension
239 Use the specified extension for module interface files. If
240 unspecified, then assume no modules are used by the project.
241 As an example, the following command creates a header-only C++ library
243 that uses the .h extension for header files and .cpp – for source
244 files:
245 $ bdep new -t lib -l c++,binless,hxx=h,cxx=cpp libhello
247 The project version control system can be specified with the --vcs|-s
249 option. Valid values for this option and their semantics are described
250 next. If unspecified, git is assumed by default.
251 git
253 Initialize a git(1) repository inside the project and generate
254 .gitignore files.
255 none
257 Don't initialize a version control system inside the project.
258 The created project, package, or subdirectory can be further customized
260 using the pre and post-creation hooks specified with the --pre-hook and
261 --post-hook options, respectively. The pre hooks are executed before
262 any new files are created and the post hook – after all the files have
263 been created. The hook commands are executed in the project, package,
264 or source directory as their current working directory. For example:
265 $ bdep new --post-hook "echo .idea/ >>.gitignore" hello
267 The pre hooks are primarily useful for moving/renaming existing files
269 that would otherwise clash with files created by the new command. For
270 example:
271 $ bdep new --pre-hook "mv .gitignore .gitignore.bak" \
273 --post-hook "cat .gitignore.bak >>.gitignore" \
274 --post-hook "rm .gitignore.bak" ...
275 See the --pre-hook and --post-hook options documentation below for
277 details.
278
280 --no-init
281 Don't initialize an empty build configuration set.
282 --package
284 Create a new package inside an already existing project rather
285 than a new project.
286 --subdirectory
288 Create a new source subdirectory inside an already existing
289 project or package rather than a new project.
290 --output-dir|-o dir
292 Create the project, package, or source subdirectory in the spec‐
293 ified directory.
294 --directory|-d dir
296 Assume the project/package is in the specified directory rather
297 than in the current working directory. Only used with --package
298 or --subdirectory.
299 --type|-t type[,opt...]
301 Specify project type and options. Valid values for type are exe
302 (executable project, default), lib (library project), bare (bare
303 project without any source code), and empty (empty project ready
304 to be filled with packages). Valid values for opt are type-spe‐
305 cific.
306 --lang|-l lang[,opt...]
308 Specify project language and options. Valid values for lang are
309 c and c++ (default). Valid values for opt are language-specific.
310 --vcs|-s vcs[,opt...]
312 Specify project version control system and options. Valid values
313 for vcs are git (default) and none. Valid values for opt are
314 system-specific.
315 --pre-hook command
317 --post-hook command
320 Run the specified command before/after creating the project,
321 package, or source directory.
322 The command value is interpreted as a whitespace-separated,
324 potentially quoted command line consisting of a program or a
325 portable builtin (testscript#builtins) optionally followed by
326 arguments and redirects. Specifically, a single level of quotes
327 (either single or double) is removed and whitespaces are not
328 treated as separators inside such quoted fragments. Currently
329 only the stdout redirect to a file is supported. For example:
330 $ bdep new --post-hook "echo '.idea/ # IDE' >>.gitignore" hello
332 The command line elements (program, arguments, etc) may option‐
334 ally contain substitutions – variable names enclosed with the @
335 substitution symbol – which are replaced with the corresponding
336 variable values to produce the actual command. The following
337 variable names are recognized with the double substitution sym‐
338 bol (@@) serving as an escape sequence.
339 @mode@ - one of 'project', 'package', or 'subdirectory'
341 @name@ - project, package, or subdirectory name
342 @base@ - name base (name without extension)
343 @stem@ - name stem (name base without 'lib' prefix)
344 @type@ - type (--type|-t value: 'exe', 'lib', etc)
345 @lang@ - language (--lang|-l value: 'c', 'c++', etc)
346 @vcs@ - version control system (--vcs|-s value: 'git', etc)
347 @root@ - project/package root directory
348 For example:
350 $ bdep new --post-hook "echo bin/ >>@name@/.gitignore" hello
352 These substitution variables are also made available to the hook
354 program as the BDEP_NEW_* environment variables (BDEP_NEW_MODE,
355 BDEP_NEW_NAME, etc).
356 --no-amalgamation
358 Create a project with disabled amalgamation support. This option
359 is normally only used for testing.
360 --no-checks
362 Suppress nested project/package checks. This option is normally
363 only used for testing.
364 --config-add|-A dir
366 Add an existing build configuration dir.
367 --config-create|-C dir
369 Create a new build configuration in dir.
370 --default
372 Make the added or created configuration the default.
373 --no-default
375 Don't make the first added or created configuration the default.
376 --forward
378 Make the added or created configuration forwarded.
379 --no-forward
381 Don't make the added or created configuration forwarded.
382 --auto-sync
384 Make the added or created configuration automatically synchro‐
385 nized.
386 --no-auto-sync
388 Don't make the added or created configuration automatically syn‐
389 chronized.
390 --existing|-e
392 Initialize a bpkg configuration based on an existing build sys‐
393 tem configuration.
394 --wipe Wipe the configuration directory clean before creating the new
396 configuration.
397 --config-name|-n name
399 Specify the build configuration as a name.
400 --config-id num
402 Specify the build configuration as an id.
403
405 The common options are summarized below with a more detailed descrip‐
406 tion available in bdep-common-options(1).
407 -v Print essential underlying commands being executed.
409 -V Print all underlying commands being executed.
411 --quiet|-q
413 Run quietly, only printing error messages.
414 --verbose level
416 Set the diagnostics verbosity to level between 0 and 6.
417 --jobs|-j num
419 Number of jobs to perform in parallel.
420 --no-progress
422 Suppress progress indicators for long-lasting operations, such
423 as network transfers, building, etc.
424 --bpkg path
426 The package manager program to be used for build configuration
427 management.
428 --bpkg-option opt
430 Additional option to be passed to the package manager program.
431 --build path
433 The build program to be used to build packages.
434 --build-option opt
436 Additional option to be passed to the build program.
437 --curl path
439 The curl program to be used for network operations.
440 --curl-option opt
442 Additional option to be passed to the curl program.
443 --pager path
445 The pager program to be used to show long text.
446 --pager-option opt
448 Additional option to be passed to the pager program.
449 --options-file file
451 Read additional options from file.
452 --default-options dir
454 The directory to load additional default options files from.
455 --no-default-options
457 Don't load default options files.
458
460 See bdep-default-options-files(1) for an overview of the default
461 options files. For the new command the search start directory is the
462 project directory in the package and subdirectory modes and the parent
463 directory of the new project in all other modes. The following options
464 files are searched for in each directory and, if found, loaded in the
465 order listed:
466 bdep.options
468 bdep-{config config-add}.options # if --config-add|-A
469 bdep-{config config-add config-create}.options # if --config-create|-C
470 bdep-new.options
471 bdep-new-{project|package|subdirectory}.options # (mode-dependent)
472 The following new command options cannot be specified in the default
474 options files:
475 --output-dir|-o
477 --directory|-d
478 --package
479 --subdirectory
480 --no-checks
481 --config-add|-A
482 --config-create|-C
483 --wipe
484 While the presence of the --pre-hook or --post-hook options in remote
486 default options files will trigger a prompt.
487
489 The BDEP_AUTHOR_EMAIL environment variable can be used to specify the
490 package email address. If not set, the new command will first try to
491 obtain the email from the version control system (if used) and then
492 from the EMAIL environment variable. If all these methods fail, a dummy
493 @example.org email is used.
494
496 Send bug reports to the users@build2.org mailing list.
497
499 Copyright (c) 2014-2019 Code Synthesis Ltd
500 Permission is granted to copy, distribute and/or modify this document
502 under the terms of the MIT License.
503bdep 0.12.0 November 2019 bdep-new(1)