1Dpkg::Deps(3) libdpkg-perl Dpkg::Deps(3)
2
3
4
6 Dpkg::Deps - parse and manipulate dependencies of Debian packages
7
9 The Dpkg::Deps module provides objects implementing various types of
10 dependencies.
11
12 The most important function is deps_parse(), it turns a dependency line
13 in a set of Dpkg::Deps::{Simple,AND,OR,Union} objects depending on the
14 case.
15
17 All the deps_* functions are exported by default.
18
19 deps_eval_implication($rel_p, $v_p, $rel_q, $v_q)
20 ($rel_p, $v_p) and ($rel_q, $v_q) express two dependencies as
21 (relation, version). The relation variable can have the following
22 values that are exported by Dpkg::Version: REL_EQ, REL_LT, REL_LE,
23 REL_GT, REL_GT.
24
25 This functions returns 1 if the "p" dependency implies the "q"
26 dependency. It returns 0 if the "p" dependency implies that "q" is
27 not satisfied. It returns undef when there's no implication.
28
29 The $v_p and $v_q parameter should be Dpkg::Version objects.
30
31 $dep = deps_concat(@dep_list)
32 This function concatenates multiple dependency lines into a single
33 line, joining them with ", " if appropriate, and always returning a
34 valid string.
35
36 $dep = deps_parse($line, %options)
37 This function parses the dependency line and returns an object,
38 either a Dpkg::Deps::AND or a Dpkg::Deps::Union. Various options
39 can alter the behaviour of that function.
40
41 use_arch (defaults to 1)
42 Take into account the architecture restriction part of the
43 dependencies. Set to 0 to completely ignore that information.
44
45 host_arch (defaults to the current architecture)
46 Define the host architecture. By default it uses
47 Dpkg::Arch::get_host_arch() to identify the proper
48 architecture.
49
50 build_arch (defaults to the current architecture)
51 Define the build architecture. By default it uses
52 Dpkg::Arch::get_build_arch() to identify the proper
53 architecture.
54
55 reduce_arch (defaults to 0)
56 If set to 1, ignore dependencies that do not concern the
57 current host architecture. This implicitly strips off the
58 architecture restriction list so that the resulting
59 dependencies are directly applicable to the current
60 architecture.
61
62 use_profiles (defaults to 1)
63 Take into account the profile restriction part of the
64 dependencies. Set to 0 to completely ignore that information.
65
66 build_profiles (defaults to no profile)
67 Define the active build profiles. By default no profile is
68 defined.
69
70 reduce_profiles (defaults to 0)
71 If set to 1, ignore dependencies that do not concern the
72 current build profile. This implicitly strips off the profile
73 restriction formula so that the resulting dependencies are
74 directly applicable to the current profiles.
75
76 reduce_restrictions (defaults to 0)
77 If set to 1, ignore dependencies that do not concern the
78 current set of restrictions. This implicitly strips off any
79 architecture restriction list or restriction formula so that
80 the resulting dependencies are directly applicable to the
81 current restriction. This currently implies "reduce_arch" and
82 "reduce_profiles", and overrides them if set.
83
84 union (defaults to 0)
85 If set to 1, returns a Dpkg::Deps::Union instead of a
86 Dpkg::Deps::AND. Use this when parsing non-dependency fields
87 like Conflicts.
88
89 build_dep (defaults to 0)
90 If set to 1, allow build-dep only arch qualifiers, that is
91 “:native”. This should be set whenever working with build-
92 deps.
93
94 tests_dep (defaults to 0)
95 If set to 1, allow tests-specific package names in
96 dependencies, that is "@" and "@builddeps@" (since dpkg
97 1.18.7). This should be set whenever working with dependency
98 fields from debian/tests/control.
99
100 $bool = deps_iterate($deps, $callback_func)
101 This function visits all elements of the dependency object, calling
102 the callback function for each element.
103
104 The callback function is expected to return true when everything is
105 fine, or false if something went wrong, in which case the iteration
106 will stop.
107
108 Return the same value as the callback function.
109
110 deps_compare($a, $b)
111 Implements a comparison operator between two dependency objects.
112 This function is mainly used to implement the sort() method.
113
115 There are several kind of dependencies. A Dpkg::Deps::Simple dependency
116 represents a single dependency statement (it relates to one package
117 only). Dpkg::Deps::Multiple dependencies are built on top of this
118 object and combine several dependencies in a different manners.
119 Dpkg::Deps::AND represents the logical "AND" between dependencies while
120 Dpkg::Deps::OR represents the logical "OR". Dpkg::Deps::Multiple
121 objects can contain Dpkg::Deps::Simple object as well as other
122 Dpkg::Deps::Multiple objects.
123
124 In practice, the code is only meant to handle the realistic cases
125 which, given Debian's dependencies structure, imply those restrictions:
126 AND can contain Simple or OR objects, OR can only contain Simple
127 objects.
128
129 Dpkg::Deps::KnownFacts is a special object that is used while
130 evaluating dependencies and while trying to simplify them. It
131 represents a set of installed packages along with the virtual packages
132 that they might provide.
133
134 COMMON METHODS
135 $dep->is_empty()
136 Returns true if the dependency is empty and doesn't contain any
137 useful information. This is true when a Dpkg::Deps::Simple object
138 has not yet been initialized or when a (descendant of)
139 Dpkg::Deps::Multiple contains an empty list of dependencies.
140
141 $dep->get_deps()
142 Returns a list of sub-dependencies. For Dpkg::Deps::Simple it
143 returns itself.
144
145 $dep->output([$fh])
146 "$dep"
147 Returns a string representing the dependency. If $fh is set, it
148 prints the string to the filehandle.
149
150 $dep->implies($other_dep)
151 Returns 1 when $dep implies $other_dep. Returns 0 when $dep implies
152 NOT($other_dep). Returns undef when there's no implication. $dep
153 and $other_dep do not need to be of the same type.
154
155 $dep->sort()
156 Sorts alphabetically the internal list of dependencies. It's a no-
157 op for Dpkg::Deps::Simple objects.
158
159 $dep->arch_is_concerned($arch)
160 Returns true if the dependency applies to the indicated
161 architecture. For multiple dependencies, it returns true if at
162 least one of the sub-dependencies apply to this architecture.
163
164 $dep->reduce_arch($arch)
165 Simplifies the dependency to contain only information relevant to
166 the given architecture. A Dpkg::Deps::Simple object can be left
167 empty after this operation. For Dpkg::Deps::Multiple objects, the
168 non-relevant sub-dependencies are simply removed.
169
170 This trims off the architecture restriction list of
171 Dpkg::Deps::Simple objects.
172
173 $dep->get_evaluation($facts)
174 Evaluates the dependency given a list of installed packages and a
175 list of virtual packages provided. Those lists are part of the
176 Dpkg::Deps::KnownFacts object given as parameters.
177
178 Returns 1 when it's true, 0 when it's false, undef when some
179 information is lacking to conclude.
180
181 $dep->simplify_deps($facts, @assumed_deps)
182 Simplifies the dependency as much as possible given the list of
183 facts (see object Dpkg::Deps::KnownFacts) and a list of other
184 dependencies that are known to be true.
185
186 $dep->has_arch_restriction()
187 For a simple dependency, returns the package name if the dependency
188 applies only to a subset of architectures. For multiple
189 dependencies, it returns the list of package names that have such a
190 restriction.
191
192 $dep->reset()
193 Clears any dependency information stored in $dep so that
194 $dep->is_empty() returns true.
195
196 Dpkg::Deps::Simple
197 Such an object has four interesting properties:
198
199 package
200 The package name (can be undef if the dependency has not been
201 initialized or if the simplification of the dependency lead to its
202 removal).
203
204 relation
205 The relational operator: "=", "<<", "<=", ">=" or ">>". It can be
206 undefined if the dependency had no version restriction. In that
207 case the following field is also undefined.
208
209 version
210 The version.
211
212 arches
213 The list of architectures where this dependency is applicable. It's
214 undefined when there's no restriction, otherwise it's an array ref.
215 It can contain an exclusion list, in that case each architecture is
216 prefixed with an exclamation mark.
217
218 archqual
219 The arch qualifier of the dependency (can be undef if there's
220 none). In the dependency "python:any (>= 2.6)", the arch qualifier
221 is "any".
222
223 METHODS
224
225 $simple_dep->parse_string('dpkg-dev (>= 1.14.8) [!hurd-i386]')
226 Parses the dependency and modifies internal properties to match the
227 parsed dependency.
228
229 $simple_dep->merge_union($other_dep)
230 Returns true if $simple_dep could be modified to represent the
231 union of both dependencies. Otherwise returns false.
232
233 Dpkg::Deps::Multiple
234 This is the base class for Dpkg::Deps::{AND,OR,Union}. It implements
235 the following methods:
236
237 $mul->add($dep)
238 Adds a new dependency object at the end of the list.
239
240 Dpkg::Deps::AND
241 This object represents a list of dependencies who must be met at the
242 same time.
243
244 $and->output([$fh])
245 The output method uses ", " to join the list of sub-dependencies.
246
247 Dpkg::Deps::OR
248 This object represents a list of dependencies of which only one must be
249 met for the dependency to be true.
250
251 $or->output([$fh])
252 The output method uses " | " to join the list of sub-dependencies.
253
254 Dpkg::Deps::Union
255 This object represents a list of relationships.
256
257 $union->output([$fh])
258 The output method uses ", " to join the list of relationships.
259
260 $union->implies($other_dep)
261 $union->get_evaluation($other_dep)
262 Those methods are not meaningful for this object and always return
263 undef.
264
265 $union->simplify_deps($facts)
266 The simplification is done to generate an union of all the
267 relationships. It uses $simple_dep->merge_union($other_dep) to get
268 its job done.
269
270 Dpkg::Deps::KnownFacts
271 This object represents a list of installed packages and a list of
272 virtual packages provided (by the set of installed packages).
273
274 $facts = Dpkg::Deps::KnownFacts->new();
275 Creates a new object.
276
277 $facts->add_installed_package($package, $version, $arch, $multiarch)
278 Records that the given version of the package is installed. If
279 $version/$arch is undefined we know that the package is installed
280 but we don't know which version/architecture it is. $multiarch is
281 the Multi-Arch field of the package. If $multiarch is undef, it
282 will be equivalent to "Multi-Arch: no".
283
284 Note that $multiarch is only used if $arch is provided.
285
286 $facts->add_provided_package($virtual, $relation, $version, $by)
287 Records that the "$by" package provides the $virtual package.
288 $relation and $version correspond to the associated relation given
289 in the Provides field (if present).
290
291 ($check, $param) = $facts->check_package($package)
292 $check is one when the package is found. For a real package, $param
293 contains the version. For a virtual package, $param contains an
294 array reference containing the list of packages that provide it
295 (each package is listed as [ $provider, $relation, $version ]).
296
297 This function is obsolete and should not be used.
298 Dpkg::Deps::KnownFacts is only meant to be filled with data and
299 then passed to Dpkg::Deps methods where appropriate, but it should
300 not be directly queried.
301
303 Version 1.06 (dpkg 1.18.7; module version bumped on dpkg 1.18.24)
304 New option: Add tests_dep option to Dpkg::Deps::deps_parse().
305
306 Version 1.05 (dpkg 1.17.14)
307 New function: Dpkg::Deps::deps_iterate().
308
309 Version 1.04 (dpkg 1.17.10)
310 New options: Add use_profiles, build_profiles, reduce_profiles and
311 reduce_restrictions to Dpkg::Deps::deps_parse().
312
313 New methods: Add $dep->profile_is_concerned() and
314 $dep->reduce_profiles() for all dependency objects.
315
316 Version 1.03 (dpkg 1.17.0)
317 New option: Add build_arch option to Dpkg::Deps::deps_parse().
318
319 Version 1.02 (dpkg 1.17.0)
320 New function: Dpkg::Deps::deps_concat()
321
322 Version 1.01 (dpkg 1.16.1)
323 New method: Add $dep->reset() for all dependency objects.
324
325 New property: Dpkg::Deps::Simple now recognizes the arch qualifier
326 "any" and stores it in the "archqual" property when present.
327
328 New option: Dpkg::Deps::KnownFacts->add_installed_package() now accepts
329 2 supplementary parameters ($arch and $multiarch).
330
331 Deprecated method: Dpkg::Deps::KnownFacts->check_package() is obsolete,
332 it should not have been part of the public API.
333
334 Version 1.00 (dpkg 1.15.6)
335 Mark the module as public.
336
337
338
3391.18.25 2019-07-24 Dpkg::Deps(3)