1bdep-new(1)                 General Commands Manual                bdep-new(1)
2
3
4

NAME

6       bdep-new - create and initialize new project
7

SYNOPSIS

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

DESCRIPTION

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

NEW OPTIONS

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

COMMON OPTIONS

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

DEFAULT OPTIONS FILES

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

ENVIRONMENT

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

BUGS

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)
Impressum