1bdep-new(1) General Commands Manual bdep-new(1)
2
3
4
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
16 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
32 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
36 $ bdep new -t exe -l c++ hello
37
38 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
43 $ bdep new -t exe -l c++ -C @gcc hello cc config.cxx=g++
44
45 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
50 $ bdep new -t empty hello
51 $ cd hello
52
53 $ bdep new --package -t lib -l c++ libhello
54 $ bdep new --package -t exe -l c++ hello
55
56 $ bdep init -C @gcc cc config.cxx=g++
57
58 After executing these commands the hello project will contain two pack‐
59 ages, libhello and hello.
60
61 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
68 $ bdep new -t bare hello
69 $ cd hello
70
71 $ bdep new --subdirectory -t lib -l c++ libhello
72 $ bdep new --subdirectory -t exe -l c++ hello
73
74 $ bdep init -C @gcc cc config.cxx=g++
75
76 After executing these commands the hello project will contain two
77 source subdirectories, libhello/ and hello/.
78
79 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
84 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
91 # Create a project with LICENSE and README.md on one of the Git
92 # hosting services (GitHub, GitLab, etc).
93
94 $ git clone .../libhello.git
95 $ cd libhello
96
97 $ bdep new -t lib -l c++
98
99 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
105 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
109 exe
110 A project that builds a sample executable. Recognized executable
111 project sub-options:
112
113 no-tests
114 Don't add support for functional/integration testing.
115
116 unit-tests
117 Add support for unit testing.
118
119 no-install
120 Don't add support for installing.
121
122 license=name
123
124
125 no-readme
126
127
128 alt-naming
129 See common sub-options below.
130
131 lib
132 A project that builds a sample library. Recognized library
133 project sub-options:
134
135 no-tests
136 Don't add support for functional/integration testing.
137
138 unit-tests
139 Add support for unit testing.
140
141 no-install
142 Don't add support for installing.
143
144 no-version
145 Don't add support for generating the version header.
146
147 license=name
148
149
150 no-readme
151
152
153 alt-naming
154 See common sub-options below.
155
156 bare
157 A project without any source code that can be filled later (see
158 --subdirectory). Recognized bare project sub-options:
159
160 no-tests
161 Don't add support for testing.
162
163 no-install
164 Don't add support for installing.
165
166 license=name
167
168
169 no-readme
170
171
172 alt-naming
173 See common sub-options below.
174
175 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
180 no-readme
181 See common sub-options below.
182
183 common
184 Common project type sub-options:
185
186 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
192 no-readme
193 Don't add README.md.
194
195 alt-naming
196 Use the alternative build file/directory naming scheme.
197
198 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
202 c
203 A C project.
204
205 c++
206 A C++ project. Recognized language sub-options:
207
208 binless
209 Create a header-only library.
210
211 cpp
212 Use the .cpp, .hpp, .ipp, .tpp, and .mpp source file extensions
213 (alias for extension=?pp).
214
215 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
222 hxx=extension
223 Use the specified extension for header files instead of the
224 default .hxx.
225
226 cxx=extension
227 Use the specified extension for source files instead of the
228 default .cxx.
229
230 ixx=extension
231 Use the specified extension for inline files. If unspecified,
232 then assume no inline files are used by the project.
233
234 txx=extension
235 Use the specified extension for template files. If unspecified,
236 then assume no template files are used by the project.
237
238 mxx=extension
239 Use the specified extension for module interface files. If
240 unspecified, then assume no modules are used by the project.
241
242 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
246 $ bdep new -t lib -l c++,binless,hxx=h,cxx=cpp libhello
247
248 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
252 git
253 Initialize a git(1) repository inside the project and generate
254 .gitignore files.
255
256 none
257 Don't initialize a version control system inside the project.
258
259 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
266 $ bdep new --post-hook "echo .idea/ >>.gitignore" hello
267
268 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
272 $ bdep new --pre-hook "mv .gitignore .gitignore.bak" \
273 --post-hook "cat .gitignore.bak >>.gitignore" \
274 --post-hook "rm .gitignore.bak" ...
275
276 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
283 --package
284 Create a new package inside an already existing project rather
285 than a new project.
286
287 --subdirectory
288 Create a new source subdirectory inside an already existing
289 project or package rather than a new project.
290
291 --output-dir|-o dir
292 Create the project, package, or source subdirectory in the spec‐
293 ified directory.
294
295 --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
300 --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
307 --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
311 --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
316 --pre-hook command
317
318
319 --post-hook command
320 Run the specified command before/after creating the project,
321 package, or source directory.
322
323 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
331 $ bdep new --post-hook "echo '.idea/ # IDE' >>.gitignore" hello
332
333 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
340 @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
349 For example:
350
351 $ bdep new --post-hook "echo bin/ >>@name@/.gitignore" hello
352
353 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
357 --no-amalgamation
358 Create a project with disabled amalgamation support. This option
359 is normally only used for testing.
360
361 --no-checks
362 Suppress nested project/package checks. This option is normally
363 only used for testing.
364
365 --config-add|-A dir
366 Add an existing build configuration dir.
367
368 --config-create|-C dir
369 Create a new build configuration in dir.
370
371 --default
372 Make the added or created configuration the default.
373
374 --no-default
375 Don't make the first added or created configuration the default.
376
377 --forward
378 Make the added or created configuration forwarded.
379
380 --no-forward
381 Don't make the added or created configuration forwarded.
382
383 --auto-sync
384 Make the added or created configuration automatically synchro‐
385 nized.
386
387 --no-auto-sync
388 Don't make the added or created configuration automatically syn‐
389 chronized.
390
391 --existing|-e
392 Initialize a bpkg configuration based on an existing build sys‐
393 tem configuration.
394
395 --wipe Wipe the configuration directory clean before creating the new
396 configuration.
397
398 --config-name|-n name
399 Specify the build configuration as a name.
400
401 --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
408 -v Print essential underlying commands being executed.
409
410 -V Print all underlying commands being executed.
411
412 --quiet|-q
413 Run quietly, only printing error messages.
414
415 --verbose level
416 Set the diagnostics verbosity to level between 0 and 6.
417
418 --jobs|-j num
419 Number of jobs to perform in parallel.
420
421 --no-progress
422 Suppress progress indicators for long-lasting operations, such
423 as network transfers, building, etc.
424
425 --bpkg path
426 The package manager program to be used for build configuration
427 management.
428
429 --bpkg-option opt
430 Additional option to be passed to the package manager program.
431
432 --build path
433 The build program to be used to build packages.
434
435 --build-option opt
436 Additional option to be passed to the build program.
437
438 --curl path
439 The curl program to be used for network operations.
440
441 --curl-option opt
442 Additional option to be passed to the curl program.
443
444 --pager path
445 The pager program to be used to show long text.
446
447 --pager-option opt
448 Additional option to be passed to the pager program.
449
450 --options-file file
451 Read additional options from file.
452
453 --default-options dir
454 The directory to load additional default options files from.
455
456 --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
467 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
473 The following new command options cannot be specified in the default
474 options files:
475
476 --output-dir|-o
477 --directory|-d
478 --package
479 --subdirectory
480 --no-checks
481 --config-add|-A
482 --config-create|-C
483 --wipe
484
485 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
501 Permission is granted to copy, distribute and/or modify this document
502 under the terms of the MIT License.
503
504
505
506bdep 0.12.0 November 2019 bdep-new(1)