1bdep-sync(1) General Commands Manual bdep-sync(1)
2
6 bdep-sync - synchronize project and build configurations
7
9 bdep sync [options] [pkg-spec] [cfg-spec] [pkg-args]
10 bdep sync [options] [pkg-spec] [cfg-spec] --upgrade|-u | --patch|-p
11 bdep sync [options] [pkg-spec] [cfg-spec] [--upgrade|-u | --patch|-p]
12 dep-spec...
13 dep-spec = pkg[/ver]
15 cfg-spec = (@cfg-name | --config|-c cfg-dir)... | --all|-a
16 pkg-spec = (--directory|-d pkg-dir)... | prj-spec
17 prj-spec = --directory|-d prj-dir
18 pkg-args = (?pkg | cfg-var)...
19
21 The sync command synchronizes a project with its build configurations.
22 The first form (no --upgrade or --patch and only pkg-args arguments, if
23 any, are specified) upgrades the project packages to the latest ver‐
24 sion/iteration, adjusts their dependencies according to the latest man‐
25 ifest information, and updates the lockfile.
26 If no project or package directory is specified, then the current work‐
28 ing directory is assumed. If no configuration is specified, then the
29 default configurations are assumed. See bdep-projects-configs(1) for
30 details on specifying projects and configurations. Optional pkg-args
31 are the additional dependency packages and/or configuration variables
32 to pass to the underlying bpkg-pkg-build(1) command.
33 The second form (no arguments but either --upgrade or --patch is speci‐
35 fied), in addition to the first form's functionality, also upgrades or
36 patches immediate (by default or if --immediate|-i is specified) or all
37 (if --recursive|-r is specified) dependencies of the specified project
38 packages. If no project packages are specified explicitly, then this
39 form upgrades or patches dependencies of all the initialized packages
40 in a project.
41 The third form (one or more dep-spec arguments are specified), in addi‐
43 tion to the first form's functionality, also upgrades (by default or if
44 --upgrade is specified) or patches (if --patch is specified) the speci‐
45 fied dependencies. If --immediate|-i or --recursive|-r is specified,
46 then it also upgrades or patches the immediate or all dependencies of
47 the specified dependencies, respectively. Alternative to --upgrade and
48 --patch, the desired upgrade (or downgrade) version can be specified
49 explicitly.
50 Note also that --immediate|-i or --recursive|-r can only be specified
52 with an explicit --upgrade or --patch.
53 Configuration variables can be specified to only apply to specific
55 packages in pkg-args and dep-spec using the argument grouping mechanism
56 (bdep-argument-grouping(1)). Additionally, packages in pkg-args can be
57 placed into specific linked configurations by specifying the configura‐
58 tion with one of the --config* options (or @ notation) using the same
59 grouping mechanism.
60 If during synchronization a build-time dependency is encountered and
62 there is no build configuration of a suitable type associated with the
63 project, then the user is prompted (unless the respective --cre‐
64 ate-*-config option is specified) to automatically create such a con‐
65 figuration and associate it with the project. See bpkg-cfg-create(1)
66 for background on configuration types.
67
69 As an example, consider project prj with two packages, foo and libfoo:
70 prj/
72 |-- foo/
73 `-- libfoo/
74 Assuming foo and libfoo have been initialized in the default build con‐
76 figuration, the following invocations illustrate the common sync use
77 cases (the current working directory is shown before the shell prompt).
78 Synchronize foo and libfoo with the default configuration:
80 prj/$ bdep sync
82 The same (all initialized packages in a project are always synchronized
84 at once):
85 prj/$ cd foo
87 foo/$ bdep sync
88 Add a dependency on libx with sync fetching and configuring a suitable
90 version:
91 foo/$ edit manifest # Add 'depends: libx ^1.0.0'
93 foo/$ bdep sync
94 Upgrade all the immediate dependencies of foo:
96 foo/$ bdep sync -u
98 Upgrade all the dependencies of all the initialized packages in a
100 project recursively:
101 foo/$ cd ../
103 prj/$ bdep sync -u -r
104 Upgrade libx to the latest version:
106 prj/$ bdep sync libx
108 Upgrade libx and its immediate dependencies to the latest version:
110 prj/$ bdep sync -u -i libx
112 Upgrade libx to the latest patch version:
114 prj/$ bdep sync -p libx
116 Upgrade libx and all its dependencies recursively to the latest patch
118 version.
119 prj/$ bdep sync -p -r libx
121 Upgrade libx to version 1.2.3.
123 prj/$ bdep sync libx/1.2.3
125 Upgrade libx to version 1.2.3 and patch all its dependencies, recur‐
127 sively:
128 prj/$ bdep sync -p -r libx/1.2.3
130
132 --upgrade|-u
133 Upgrade dependencies to the latest available version that satis‐
134 fies all the constraints.
135 --patch|-p
137 Upgrade dependencies to the latest available patch version that
138 satisfies all the constraints.
139 --immediate|-i
141 Also upgrade or patch immediate dependencies.
142 --recursive|-r
144 Also upgrade or patch all dependencies, recursively.
145 --yes|-y
147 Don't prompt for confirmation when up/down-grading dependencies.
148 --disfigure
150 Disfigure project packages during synchronization effectively
151 causing their from-scratch reconfiguration.
152 --fetch|-f
154 Perform the fetch command prior to synchronization.
155 --fetch-full|-F
157 Perform the fetch --full command prior to synchronization.
158 --sys-no-query
160 Do not query the system package manager for the installed ver‐
161 sions of packages specified with the sys scheme. See the corre‐
162 sponding bpkg-pkg-build(1) option for details.
163 --sys-install
165 Instruct the system package manager to install available ver‐
166 sions of packages specified with the sys scheme that are not al‐
167 ready installed. See the corresponding bpkg-pkg-build(1) option
168 for details.
169 --sys-no-fetch
171 Do not fetch the system package manager metadata before querying
172 for available versions of packages specified with the sys
173 scheme. See the corresponding bpkg-pkg-build(1) option for de‐
174 tails.
175 --sys-no-stub
177 Do no require a stub for packages specified with the sys scheme.
178 See the corresponding bpkg-pkg-build(1) option for details.
179 --sys-yes
181 Assume the answer to the system package manager prompts is yes.
182 See the corresponding bpkg-pkg-build(1) option for details.
183 --sys-sudo prog
185 The sudo program to use for system package manager interactions
186 that normally require administrative privileges (fetch package
187 metadata, install packages, etc). See the corresponding bpkg-
188 pkg-build(1) option for details.
189 --create-host-config
191 Create a configuration for build-time dependencies without
192 prompt.
193 --create-build2-config
195 Create a configuration for build system module dependencies
196 without prompt.
197 --implicit
199 Perform implicit synchronization. This mode is normally used by
200 other tools (for example, a build system hook) to ensure
201 projects and configurations are synchronized. To improve perfor‐
202 mance, especially for the "everything is already synchronized"
203 case, sync executed in this mode assumes that no configuration
204 flags (see bdep-config(1)) have changed since the last explicit
205 synchronization. It also does not search for a project in the
206 current working directory – if any, its directory should be
207 specified explicitly with --config|-c.
208 --all|-a
210 Use all build configurations.
211 --config|-c dir
213 Specify the build configuration as a directory.
214 --directory|-d dir
216 Assume project/package is in the specified directory rather than
217 in the current working directory.
218 --config-name|-n name
220 Specify the build configuration as a name.
221 --config-id num
223 Specify the build configuration as an id.
224
226 The common options are summarized below with a more detailed descrip‐
227 tion available in bdep-common-options(1).
228 -v Print essential underlying commands being executed.
230 -V Print all underlying commands being executed.
232 --quiet|-q
234 Run quietly, only printing error messages.
235 --verbose level
237 Set the diagnostics verbosity to level between 0 and 6.
238 --stdout-format format
240 Representation format to use for printing to stdout.
241 --jobs|-j num
243 Number of jobs to perform in parallel.
244 --progress
246 Display progress indicators for long-lasting operations, such as
247 network transfers, building, etc.
248 --no-progress
250 Suppress progress indicators for long-lasting operations, such
251 as network transfers, building, etc.
252 --diag-color
254 Use color in diagnostics.
255 --no-diag-color
257 Don't use color in diagnostics.
258 --bpkg path
260 The package manager program to be used for build configuration
261 management.
262 --bpkg-option opt
264 Additional option to be passed to the package manager program.
265 --build path
267 The build program to be used to build packages.
268 --build-option opt
270 Additional option to be passed to the build program.
271 --curl path
273 The curl program to be used for network operations.
274 --curl-option opt
276 Additional option to be passed to the curl program.
277 --pager path
279 The pager program to be used to show long text.
280 --pager-option opt
282 Additional option to be passed to the pager program.
283 --options-file file
285 Read additional options from file.
286 --default-options dir
288 The directory to load additional default options files from.
289 --no-default-options
291 Don't load default options files.
292
294 See bdep-default-options-files(1) for an overview of the default op‐
295 tions files. For the sync command the search start directory is the
296 project directory, except for the implicit mode for which only the pre‐
297 defined directories (system, etc) are searched in. The following op‐
298 tions files are searched for in each directory and, if found, loaded in
299 the order listed:
300 bdep.options
302 bdep-{sync|sync-implicit}.options # (mode-dependent)
303 The following sync command options cannot be specified in the default
305 options files:
306 --directory|-d
308 --implicit
309 --config|-c
310
312 The BDEP_SYNC environment variable can be used to suppress automatic
313 synchronization on build system invocation. If set, auto-synchroniza‐
314 tion will only be performed if the variable's value is true or 1. The
315 ability to suppress auto-synchronization can be useful when you don't
316 have usable bdep and/or bpkg.
317 To avoid recursive re-synchronization, the sync command also maintains
319 the BDEP_SYNCED_CONFIGS environment variable. It contains a space-sepa‐
320 rated, "-quoted list of configuration paths that have been or are being
321 synchronized by the current bdep invocation chain. The sync command ex‐
322 amines this variable and silently ignores synchronization requests that
323 have been or are already being performed.
324
326 Send bug reports to the users@build2.org mailing list.
327
329 Copyright (c) 2014-2023 the build2 authors.
330 Permission is granted to copy, distribute and/or modify this document
332 under the terms of the MIT License.
333bdep 0.16.0 June 2023 bdep-sync(1)