1bdep-config(1) General Commands Manual bdep-config(1)
2
6 bdep-config - manage project build configurations
7
9 bdep config add [options] [prj-spec] [@cfg-name] cfg-dir
10 bdep config create [options] [prj-spec] [@cfg-name] cfg-dir [cfg-args]
11 bdep config link [options] [prj-spec] cfg-spec cfg-spec
12 bdep config unlink [options] [prj-spec] cfg-spec cfg-spec
13 bdep config list [options] [prj-spec] [cfg-spec...]
14 bdep config move [options] [prj-spec] cfg-spec cfg-dir
15 bdep config rename [options] [prj-spec] cfg-spec cfg-name
16 bdep config remove [options] [prj-spec] cfg-spec... | --all|-a
17 bdep config set [options] [prj-spec] cfg-spec... | --all|-a
18 [--[no-]default]
19 [--[no-]forward]
20 [--[no-]auto-sync]
21 cfg-spec = @cfg-name | --config|-c cfg-dir
23 prj-spec = --directory|-d prj-dir
24 cfg-args = [-- [bpkg-options]] [--existing|-e | (module | cfg-var)...]
25
27 The config command provides the following subcommands for managing
28 project's build configurations. If no project directory is specified,
29 then the current working directory is assumed.
30
32 add
33 create
36 The add subcommand adds an existing bpkg(1) build configuration
37 in directory cfg-dir to the project's build configuration set.
38 The create subcommand creates a new configuration in directory
39 cfg-dir by executing the bpkg-cfg-create(1) command and passing
40 to it cfg-args, if any. It then proceeds as add by adding the
41 new configuration to the project's build configuration set.
42 In both subcommands, if cfg-name is specified, then the added
44 configuration is given this name. Several bdep commands can use
45 such names as a more convenient way to specify build configura‐
46 tions (see bdep-projects-configs(1) for details).
47 As a shortcut, if cfg-name is not specified and cfg-dir is a
49 simple path that starts with @, then it is treated as the name
50 and the configuration directory is assumed to be prj-dir-cfg-
51 name. Note that in case of create, cfg-dir must be preceded with
52 -- (double dash) option to disambiguate it from @cfg-name. For
53 example, assuming the project directory is hello:
54 $ bdep config add @clang # ../hello-clang
56 $ bdep config create -- @gcc cc config.cxx=g++ # ../hello-gcc
57 A configuration also has a type that is specified with the
59 --type option (or --config-type from bdep-new(1)). If the type
60 is not specified explicitly, then target is assumed. See bpkg-
61 cfg-create(1) for background on configuration types.
62 Unless the --no-default option is specified, the first added or
64 created build configuration of each type is designated as the
65 default. Several bdep commands use such a configuration by de‐
66 fault if no configuration was specified explicitly (see bdep-
67 projects-configs(1) for details). To make a subsequently added
68 configuration the default use the --default option. Note also
69 that in case of multiple default configurations any given pack‐
70 age within a project can only be initialized in one such config‐
71 uration.
72 The default build configuration of each type is also designated
74 as forwarded unless the --no-forward option is specified or an‐
75 other configuration of this type is already designated as for‐
76 warded. When a project is initialized in a forwarded build con‐
77 figuration, its source directory is configured to forward to
78 this configuration (see b(1) for details on forwarded configura‐
79 tions). To designate a non-default configuration as forwarded
80 use the --forward option. Note also that it is possible to have
81 multiple forwarded configurations, however, any given package
82 within a project can only be initialized in one such configura‐
83 tion.
84 Unless the --no-auto-sync option is specified, an added or cre‐
86 ated build configuration will be automatically synchronized on
87 every build system invocation. Note that this flag affects the
88 entire build configuration and if multiple projects share the
89 same configuration, then they must have a consistent auto-syn‐
90 chronization setting.
91 link
93 The link subcommand links the first specified build configura‐
94 tion with the second by executing the bpkg-cfg-link(1) command.
95 See bpkg-cfg-create(1) for background on linked configurations.
96 unlink
98 The unlink subcommand unlinks the first specified build configu‐
99 ration from the second by executing the bpkg-cfg-unlink(1) com‐
100 mand. See bpkg-cfg-create(1) for background on linked configura‐
101 tions.
102 list
104 The list subcommand prints the list of build configurations as‐
105 sociated with the project. Unless one or more configurations are
106 specified explicitly, list prints all the associate configura‐
107 tions. Note that the output is written to stdout, not stderr.
108 If the output format is json (see the --stdout-format common op‐
110 tion), then the output is a JSON array of objects which are the
111 serialized representation of the following C++ struct configura‐
112 tion:
113 struct package
115 {
116 string name;
117 };
118 struct configuration
120 {
121 uint64_t id;
122 string path;
123 optional<string> name;
124 string type;
125 bool default;
126 bool forward;
127 bool auto_sync;
128 vector<package> packages;
129 };
130 For example:
132 [
134 {
135 "id": 1,
136 "path": "/tmp/hello-gcc",
137 "name": "gcc",
138 "type": "target",
139 "default": true,
140 "forward": true,
141 "auto_sync": true,
142 "packages": [
143 {
144 "name": "hello"
145 }
146 ]
147 }
148 ]
149 See the JSON OUTPUT section in bdep-common-options(1) for de‐
151 tails on the overall properties of this format and the semantics
152 of the struct serialization.
153 The id member is a numeric configuration id that can be used to
155 identify the configuration instead of the name or path (see the
156 --config-id option). The path member is an absolute path to the
157 configuration directory. The packages member contains the array
158 of packages belonging to this project that have been initialized
159 in this configuration. See the create subcommand for the meaning
160 of other members (name, type, default, etc).
161 move
163 The move subcommand assigns the specified build configuration a
164 new directory. It is normally used after moving/renaming the
165 configuration directory. Note that an explicit bdep-sync(1) com‐
166 mand is required for this change to take effect. See bdep-
167 projects-configs(1) for various ways to specify a build configu‐
168 ration.
169 rename
171 The rename subcommand gives the specified build configuration a
172 new name. See bdep-projects-configs(1) for various ways to spec‐
173 ify a build configuration.
174 remove
176 The remove subcommand removes one or more build configurations
177 from the project's build configuration set. Note that only con‐
178 figurations that have no initialized packages can be removed.
179 See bdep-projects-configs(1) for various ways to specify build
180 configurations.
181 set
183 The set subcommand modifies various properties of one or more
184 build configurations associated with the project. See bdep-
185 projects-configs(1) for various ways to specify build configura‐
186 tions.
187 The properties that can be modified include the default
189 (--[no-]default), forward (--[no-]forward), and auto-synchro‐
190 nization (--[no-]auto-sync) flags. Note that changing any of
191 these flags requires an explicit bdep-sync(1) command to take
192 effect.
193
195 --type|--config-type typ
196 The type of the configuration being created. By default, config‐
197 uration of type target is created. See bpkg-cfg-create(1) for
198 background on configuration types.
199 --default
201 Make the added or created configuration the default.
202 --no-default
204 Don't make the first added or created configuration the default.
205 --forward
207 Make the added or created configuration forwarded.
208 --no-forward
210 Don't make the added or created configuration forwarded.
211 --auto-sync
213 Make the added or created configuration automatically synchro‐
214 nized.
215 --no-auto-sync
217 Don't make the added or created configuration automatically syn‐
218 chronized.
219 --existing|-e
221 Initialize a bpkg configuration based on an existing build sys‐
222 tem configuration.
223 --wipe Wipe the configuration directory clean before creating the new
225 configuration.
226 --all|-a
228 Use all build configurations.
229 --config|-c dir
231 Specify the build configuration as a directory.
232 --directory|-d dir
234 Assume project/package is in the specified directory rather than
235 in the current working directory.
236 --config-name|-n name
238 Specify the build configuration as a name.
239 --config-id num
241 Specify the build configuration as an id.
242
244 The common options are summarized below with a more detailed descrip‐
245 tion available in bdep-common-options(1).
246 -v Print essential underlying commands being executed.
248 -V Print all underlying commands being executed.
250 --quiet|-q
252 Run quietly, only printing error messages.
253 --verbose level
255 Set the diagnostics verbosity to level between 0 and 6.
256 --stdout-format format
258 Representation format to use for printing to stdout.
259 --jobs|-j num
261 Number of jobs to perform in parallel.
262 --progress
264 Display progress indicators for long-lasting operations, such as
265 network transfers, building, etc.
266 --no-progress
268 Suppress progress indicators for long-lasting operations, such
269 as network transfers, building, etc.
270 --diag-color
272 Use color in diagnostics.
273 --no-diag-color
275 Don't use color in diagnostics.
276 --bpkg path
278 The package manager program to be used for build configuration
279 management.
280 --bpkg-option opt
282 Additional option to be passed to the package manager program.
283 --build path
285 The build program to be used to build packages.
286 --build-option opt
288 Additional option to be passed to the build program.
289 --curl path
291 The curl program to be used for network operations.
292 --curl-option opt
294 Additional option to be passed to the curl program.
295 --pager path
297 The pager program to be used to show long text.
298 --pager-option opt
300 Additional option to be passed to the pager program.
301 --options-file file
303 Read additional options from file.
304 --default-options dir
306 The directory to load additional default options files from.
307 --no-default-options
309 Don't load default options files.
310
312 See bdep-default-options-files(1) for an overview of the default op‐
313 tions files. For the config command the search start directory is the
314 project directory. The following options files are searched for in each
315 directory and, if found, loaded in the order listed:
316 bdep.options
318 bdep-config.options
319 bdep-config-add.options # if the create subcommand
320 bdep-config-<subcommand>.options # (subcommand-dependent)
321 The following config command options cannot be specified in the default
323 options files:
324 --directory|-d
326 --wipe
327
329 Send bug reports to the users@build2.org mailing list.
330
332 Copyright (c) 2014-2023 the build2 authors.
333 Permission is granted to copy, distribute and/or modify this document
335 under the terms of the MIT License.
336bdep 0.16.0 June 2023 bdep-config(1)