1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
|
// file : bdep/sync.cli
// copyright : Copyright (c) 2014-2018 Code Synthesis Ltd
// license : MIT; see accompanying LICENSE file
include <bdep/project.cli>;
"\section=1"
"\name=bdep-sync"
"\summary=synchronize project and build configurations"
namespace bdep
{
{
"<options>
<prj-spec> <prj-dir>
<pkg-spec> <pkg-dir>
<cfg-spec> <cfg-name> <cfg-dir>
<dep-spec> <pkg> <ver>
<pkg-args> <pkg> <cfg-var>",
"\h|SYNOPSIS|
\c{\b{bdep sync} [<options>] [<pkg-spec>] [<cfg-spec>] [<pkg-args>]\n
\b{bdep sync} [<options>] [<pkg-spec>] [<cfg-spec>] \ \b{--upgrade}|\b{-u} | \b{--patch}|\b{-p}\n
\b{bdep sync} [<options>] [<pkg-spec>] [<cfg-spec>] [\b{--upgrade}|\b{-u} | \b{--patch}|\b{-p}]\n
\ \ \ \ \ \ \ \ \ \ <dep-spec>...
}
\c{<dep-spec> = <pkg>[\b{/}<ver>]\n
<cfg-spec> = (\b{@}<cfg-name> | \b{--config}|\b{-c} <cfg-dir>)... | \b{--all}|\b{-a}\n
<pkg-spec> = (\b{--directory}|\b{-d} <pkg-dir>)... | <prj-spec>\n
<prj-spec> = \b{--directory}|\b{-d} <prj-dir>\n
<pkg-args> = (<pkg> | <cfg-var>)...}
\h|DESCRIPTION|
The \cb{sync} command synchronizes a project with its build
configurations. The first form (no arguments nor \cb{--upgrade} or
\cb{--patch} are specified) upgrades the project packages to the latest
version/iteration, adjusts their dependencies according to the latest
manifest information, and updates the lockfile.
If no project or package directory is specified, then the current working
directory is assumed. If no configuration is specified, then the default
configuration is assumed. See \l{bdep-projects-configs(1)} for details on
specifying projects and configurations. Optional <pkg-args> are the
additional dependency packages and/or configuration variables to pass to
the underlying \l{bpkg-pkg-build(1)} command.
The second form (no arguments but either \cb{--upgrade} or \cb{--patch}
is specified), in addition to the first form's functionality, also
upgrades or patches immediate (by default or if
\c{\b{--immediate}|\b{-i}} is specified) or all (if
\c{\b{--recursive}|\b{-r}} is specified) dependencies of the specified
project packages.
The third form (one or more arguments are specified), in addition to the
first form's functionality, also upgrades (by default or if
\cb{--upgrade} is specified) or patches (if \cb{--patch} is specified)
the specified dependencies. If \c{\b{--immediate}|\b{-i}} or
\c{\b{--recursive}|\b{-r}} is specified, then it also upgrades or patches
the immediate or all dependencies of the specified dependencies,
respectively. Alternative to \cb{--upgrade} and \cb{--patch}, the desired
upgrade (or downgrade) version can be specified explicitly.
Note also that \c{\b{--immediate}|\b{-i}} or \c{\b{--recursive}|\b{-r}}
can only be specified with an explicit \cb{--upgrade} or \cb{--patch}.
\h|EXAMPLES|
As an example, consider project \cb{prj} with two packages, \cb{foo}
and \cb{libfoo}:
\
prj/
├── foo/
└── libfoo/
\
Assuming \cb{foo} and \cb{libfoo} have been initialized in the default
build configuration, the following invocations illustrate the common
\cb{sync} use cases (the current working directory is shown before the
shell prompt).
Synchronize \cb{foo} and \cb{libfoo} with the default configuration:
\
prj/$ bdep sync
\
The same (all initialized packages in a project are always synchronized
at once):
\
prj/$ cd foo
foo/$ bdep sync
\
Add a dependency on \cb{libx} with \cb{sync} fetching and configuring a
suitable version:
\
foo/$ edit manifest # Add 'depends: libx ^1.0.0'
foo/$ bdep sync
\
Upgrade all the immediate dependencies of \cb{foo}:
\
foo/$ bdep sync -u
\
Upgrade all the dependencies of all the initialized packages in a
project recursively:
\
foo/$ cd ../
prj/$ bdep sync -u -r
\
Upgrade \cb{libx} to the latest version:
\
prj/$ bdep sync libx
\
Upgrade \cb{libx} and its immediate dependencies to the latest version:
\
prj/$ bdep sync -i libx
\
Upgrade \cb{libx} to the latest patch version:
\
prj/$ bdep sync -p libx
\
Upgrade \cb{libx} and all its dependencies recursively to the latest patch
version.
\
prj/$ bdep sync -p -r libx
\
Upgrade \cb{libx} to version \cb{1.2.3}.
\
prj/$ bdep sync libx/1.2.3
\
Upgrade \cb{libx} to version \cb{1.2.3} and patch all its dependencies,
recursively:
\
prj/$ bdep sync -p -r libx/1.2.3
\
"
}
// Note that not all project/configuration options are valid for all
// subcommands.
//
class cmd_sync_options: project_options
{
"\h|SYNC OPTIONS|"
bool --upgrade|-u
{
"Upgrade dependencies to the latest available version that satisfies
all the constraints."
}
bool --patch|-p
{
"Upgrade dependencies to the latest available patch version that
satisfies all the constraints."
}
bool --immediate|-i
{
"Also upgrade or patch immediate dependencies."
}
bool --recursive|-r
{
"Also upgrade or patch all dependencies, recursively."
}
bool --fetch|-f
{
"Perform the \cb{fetch} command prior to synchronization."
}
bool --fetch-full|-F
{
"Perform the \cb{fetch --full} command prior to synchronization."
}
bool --yes|-y
{
"Don't prompt for confirmation when up/down-grading dependencies."
}
bool --implicit
{
"Perform implicit synchronization. This mode is normally used by other
tools (for example, a build system hook) to ensure projects and
configurations are synchronized. To improve performance, especially for
the \"everything is already synchronized\" case, \cb{sync} executed in
this mode assumes that no configuration flags (see \l{bdep-config(1)})
have changed since the last explicit synchronization. It also does not
search for a project in the current working directory \- if any, its
directory should be specified explicitly with \c{\b{--config}|\b{-c}}."
}
// The build system hook protocol version. Internal, undocumented, and
// implies --implicit.
//
uint16_t --hook = 0;
};
"\h|ENVIRONMENT|
The \cb{BDEP_SYNC} environment variable can be used to suppress automatic
synchronization on build system invocation. If set, auto-synchronization
will only be performed if the variable's value is \cb{true} or \cb{1}. The
ability to suppress auto-synchronization can be useful when you don't have
usable \cb{bdep} and/or \cb{bpkg}.
To avoid recursive re-synchronization, the \cb{sync} command also maintains
the \cb{BDEP_SYNCED_CONFIGS} environment variable. It contains a
space-separated, \cb{\"}-quoted list of configuration paths that have been
or are being synchronized by the current \cb{bdep} invocation chain. The
\cb{sync} command examines this variable and silently ignores
synchronization requests that have been or are already being performed.
"
}
|