doc/libsolv-bindings.txt

   1 Libsolv-Bindings(3)
   2 ===================
   3 :man manual: LIBSOLV
   4 :man source: libsolv
   5
   6
   7 Name
   8 ----
   9 libsolv-bindings - access libsolv from perl/python/ruby
  10
  11
  12 Description
  13 -----------
  14 Libsolv's language bindings offer an abstract, object orientated interface
  15 to the library. The supported languages are currently perl, python, and ruby.
  16 All example code (except in the specifics sections, of course) lists first
  17 the ``C-ish'' interface, then the syntax for perl, python, and ruby (in that
  18 order).
  19
  20
  21 Perl Specifics
  22 --------------
  23 Libsolv's perl bindings can be loaded with the following statement:
  24
  25         use solv;
  26
  27 Objects are either created by calling the new() method on a class or they
  28 are returned by calling methods on other objects.
  29
  30         my $pool = solv::Pool->new();
  31         my $repo = $pool->add_repo("my_first_repo");
  32
  33 Swig encapsulates all objects as tied hashes, thus the attributes can be
  34 accessed by treating the object as standard hash reference:
  35
  36         $pool->{appdata} = 42;
  37         printf "appdata is %d\n", $pool->{appdata};
  38
  39 A special exception to this are iterator objects, they are encapsulated as
  40 tied arrays so that it is possible to iterate with a for() statement:
  41
  42         my $iter = $pool->solvables_iter();
  43         for my $solvable (@$iter) { ... };
  44
  45 As a downside of this approach, iterator objects cannot have attributes.
  46
  47 If an array needs to be passed to a method it is usually done by reference,
  48 if a method returns an array it returns it on the perl stack:
  49
  50         my @problems = $solver->solve(\@jobs);
  51
  52 Due to a bug in swig, stringification does not work for libsolv's objects.
  53 Instead, you have to call the object's str() method.
  54
  55         print $dep->str() . "\n";
  56
  57 Swig implements all constants as numeric variables (instead of the more
  58 natural constant subs), so don't forget the leading ``$'' when accessing a
  59 constant. Also do not forget to prepend the namespace of the constant:
  60
  61         $pool->set_flag($solv::Pool::POOL_FLAG_OBSOLETEUSESCOLORS, 1);
  62
  63
  64 Python Specifics
  65 ----------------
  66 The python bindings can be loaded with:
  67
  68         import solv
  69
  70 Objects are either created by calling the constructor method for a class or they
  71 are returned by calling methods on other objects.
  72
  73         pool = solv.Pool()
  74         repo = pool.add_repo("my_first_repo")
  75
  76 Attributes can be accessed as usual:
  77
  78         pool.appdata = 42
  79         print "appdata is %d" % (pool.appdata)
  80
  81 Iterators also work as expected:
  82
  83         for solvable in pool.solvables_iter():
  84
  85 Arrays are passed and returned as list objects:
  86
  87         jobs = []
  88         problems = solver.solve(jobs)
  89
  90 The bindings define stringification for many classes, some also have a
  91 __repr__ method to ease debugging.
  92
  93         print dep
  94         print repr(repo)
  95
  96 Constants are attributes of the corresponding classes:
  97
  98         pool.set_flag(solv.Pool.POOL_FLAG_OBSOLETEUSESCOLORS, 1);
  99
 100
 101 Ruby Specifics
 102 --------------
 103 The ruby bindings can be loaded with:
 104
 105         require 'solv'
 106
 107 Objects are either created by calling the new method on a class or they
 108 are returned by calling methods on other objects. Note that all classes start
 109 with an uppercase letter in ruby, so the class is called ``Solv''.
 110
 111         pool = Solv::Pool.new
 112         repo = pool.add_repo("my_first_repo")
 113
 114 Attributes can be accessed as usual:
 115
 116         pool.appdata = 42
 117         puts "appdata is #{pool.appdata}"
 118
 119 Iterators also work as expected:
 120
 121         for solvable in pool.solvables_iter() do ...
 122
 123 Arrays are passed and returned as array objects:
 124
 125         jobs = []
 126         problems = solver.solve(jobs)
 127
 128 Most classes define a to_s method, so objects can be easily stringified.
 129 Many also define an inspect() method.
 130
 131         puts dep
 132         puts repo.inspect
 133
 134 Constants live in the namespace of the class they belong to:
 135
 136         pool.set_flag(Solv::Pool::POOL_FLAG_OBSOLETEUSESCOLORS, 1);
 137
 138 Note that boolean methods have an added trailing ``?'', to be consistent with
 139 other ruby modules:
 140
 141         puts "empty" if repo.isempty?
 142
 143
 144 Tcl Specifics
 145 -------------
 146 Libsolv's tcl bindings can be loaded with the following statement:
 147
 148         TCL package require solv
 149
 150 Objects are either created by calling class name prefixed with ``new_'',
 151 or they are returned by calling methods on other objects.
 152
 153         TCL set pool [solv::new_Pool]
 154         TCL set repo [$pool add_repo "my_first_repo"]
 155
 156 Swig provides a ``cget'' method to read object attributes, and a
 157 ``configure'' method to write them:
 158
 159         TCL $pool configure -appdata 42
 160         TCL puts "appdata is [$pool cget -appdata]"
 161
 162 The tcl bindings provide a little helper to work with iterators in
 163 a foreach style:
 164
 165         TCL set iter [$pool solvables_iter]
 166         TCL solv::iter s $iter { ... }
 167
 168 libsolv's arrays are mapped to tcl's lists:
 169
 170         TCL set jobs [list $job1 $job2]
 171         TCL set problems [$solver solve $jobs]
 172         TCL puts "We have [llength $problems] problems..."
 173
 174 Stringification is done by calling the object's ``str'' method.
 175
 176         TCL puts [$dep str]
 177
 178 There is one exception: you have to use ``stringify'' for Datamatch
 179 objects, as swig reports a clash with the ``str'' attribute.
 180 Some objects also support a ``=='' method for equality tests, and a
 181 ``!='' method.
 182
 183 Swig implements all constants as numeric variables, constants belonging
 184 to a libsolv class are prefixed with the class name:
 185
 186         TCL $pool set_flag $solv::Pool_POOL_FLAG_OBSOLETEUSESCOLORS 1
 187         TCL puts [$solvable lookup_str $solv::SOLVABLE_SUMMARY]
 188
 189
 190 The Solv Class
 191 --------------
 192 This is the main namespace of the library, you cannot create objects of this
 193 type but it contains some useful constants.
 194
 195 === CONSTANTS ===
 196
 197 Relational flag constants, the first three can be or-ed together
 198
 199 *REL_LT*::
 200 the ``less than'' bit
 201
 202 *REL_EQ*::
 203 the ``equals to'' bit
 204
 205 *REL_GT*::
 206 the ``greater than'' bit
 207
 208 *REL_ARCH*::
 209 used for relations that describe an extra architecture filter, the
 210 version part of the relation is interpreted as architecture.
 211
 212 Special Solvable Ids
 213
 214 *SOLVID_META*::
 215 Access the meta section of a repository or repodata area. This is
 216 like an extra Solvable that has the Id SOLVID_META.
 217
 218 *SOLVID_POS*::
 219 Use the data position stored inside of the pool instead of accessing
 220 some solvable by Id. The bindings have the Datapos objects as an
 221 abstraction mechanism, so you most likely do not need this constant.
 222
 223 Constant string Ids
 224
 225 *ID_NULL*::
 226 Always zero
 227
 228 *ID_EMPTY*::
 229 Always one, describes the empty string
 230
 231 *SOLVABLE_NAME*::
 232 The keyname Id of the name of the solvable.
 233
 234 *...*::
 235 see the libsolv-constantids manpage for a list of fixed Ids.
 236
 237
 238 The Pool Class
 239 --------------
 240 The pool is libsolv's central resource manager. A pool consists of Solvables,
 241 Repositories, Dependencies, each indexed by Ids.
 242
 243 === CLASS METHODS ===
 244
 245         Pool *Pool()
 246         my $pool = solv::Pool->new();
 247         pool = solv.Pool()
 248         pool = Solv::Pool.new()
 249
 250 Create a new pool instance. In most cases you just need one pool.
 251 Note that the returned object "owns" the pool, i.e. if the object is
 252 freed, the pool is also freed. You can use the disown method to
 253 break this ownership relation.
 254
 255 === ATTRIBUTES ===
 256
 257         void *appdata;                  /* read/write */
 258         $pool->{appdata}
 259         pool.appdata
 260         pool.appdata
 261
 262 Application specific data that may be used in any way by the code using the
 263 pool.
 264
 265         Solvable solvables[];           /* read only */
 266         my $solvable = $pool->{solvables}->[$solvid];
 267         solvable = pool.solvables[solvid]
 268         solvable = pool.solvables[solvid]
 269
 270 Look up a Solvable by its id.
 271
 272         Repo repos[];                   /* read only */
 273         my $repo = $pool->{repos}->[$repoid];
 274         repo = pool.repos[repoid]
 275         repo = pool.repos[repoid]
 276
 277 Look up a Repository by its id.
 278
 279         Repo *installed;                /* read/write */
 280         $pool->{installed} = $repo;
 281         pool.installed = repo
 282         pool.installed = repo
 283
 284 Define which repository contains all the installed packages.
 285
 286         const char *errstr;             /* read only */
 287         my $err = $pool->{errstr};
 288         err = pool.errstr
 289         err = pool.errstr
 290
 291 Return the last error string that was stored in the pool.
 292
 293 === CONSTANTS ===
 294
 295 *POOL_FLAG_PROMOTEEPOCH*::
 296 Promote the epoch of the providing dependency to the requesting
 297 dependency if it does not contain an epoch. Used at some time
 298 in old rpm versions, modern systems should never need this.
 299
 300 *POOL_FLAG_FORBIDSELFCONFLICTS*::
 301 Disallow the installation of packages that conflict with themselves.
 302 Debian always allows self-conflicting packages, rpm used to forbid
 303 them but switched to also allowing them since rpm-4.9.0.
 304
 305 *POOL_FLAG_OBSOLETEUSESPROVIDES*::
 306 Make obsolete type dependency match against provides instead of
 307 just the name and version of packages. Very old versions of rpm
 308 used the name/version, then it got switched to provides and later
 309 switched back again to just name/version.
 310
 311 *POOL_FLAG_IMPLICITOBSOLETEUSESPROVIDES*::
 312 An implicit obsoletes is the internal mechanism to remove the
 313 old package on an update. The default is to remove all packages
 314 with the same name, rpm-5 switched to also removing packages
 315 providing the same name.
 316
 317 *POOL_FLAG_OBSOLETEUSESCOLORS*::
 318 Rpm's multilib implementation distinguishes between 32bit and 64bit
 319 packages (the terminology is that they have a different color).
 320 If obsoleteusescolors is set, packages with different colors will
 321 not obsolete each other.
 322
 323 *POOL_FLAG_IMPLICITOBSOLETEUSESCOLORS*::
 324 Same as POOL_FLAG_OBSOLETEUSESCOLORS, but used to find out if
 325 packages of the same name can be installed in parallel. For
 326 current Fedora systems, POOL_FLAG_OBSOLETEUSESCOLORS should be
 327 false and POOL_FLAG_IMPLICITOBSOLETEUSESCOLORS should be true
 328 (this is the default if FEDORA is defined when libsolv is compiled).
 329
 330 *POOL_FLAG_NOINSTALLEDOBSOLETES*::
 331 Since version 4.9.0 rpm considers the obsoletes of installed packages
 332 when checking for dependency conflicts, thus you may not install a
 333 package that is obsoleted by some other installed package unless you
 334 also erase the other package.
 335
 336 *POOL_FLAG_HAVEDISTEPOCH*::
 337 Mandriva added a new field called distepoch that gets checked in
 338 version comparison if the epoch/version/release of two packages
 339 are the same.
 340
 341 *POOL_FLAG_NOOBSOLETESMULTIVERSION*::
 342 If a package is installed in multiversion mode, rpm used to ignore
 343 both the implicit obsoletes and the obsolete dependency of a
 344 package. This was changed to ignoring just the implicit obsoletes,
 345 thus you may install multiple versions of the same name, but
 346 obsoleted packages still get removed.
 347
 348 *POOL_FLAG_ADDFILEPROVIDESFILTERED*::
 349 Make the addfileprovides method only add files from the standard
 350 locations (i.e. the ``bin'' and ``etc'' directories). This is
 351 useful if you have only few packages that use non-standard file
 352 dependencies, but you still want the fast speed that addfileprovides()
 353 generates.
 354
 355 === METHODS ===
 356
 357         void free()
 358         $pool->free();
 359         pool.free()
 360         pool.free()
 361
 362 Force a free of the pool. After this call, you must not access any object
 363 that still references the pool.
 364
 365         void disown()
 366         $pool->disown();
 367         pool.disown()
 368         pool.disown()
 369
 370 Break the ownership relation between the binding object and the pool. After
 371 this call, the pool will not get freed even if the object goes out of
 372 scope. This also means that you must manually call the free method to free
 373 the pool data.
 374
 375         void setdebuglevel(int level)
 376         $pool->setdebuglevel($level);
 377         pool.setdebuglevel(level)
 378         pool.setdebuglevel(level)
 379
 380 Set the debug level. A value of zero means no debug output, the higher the
 381 value, the more output is generated.
 382
 383         int set_flag(int flag, int value)
 384         my $oldvalue = $pool->set_flag($flag, $value);
 385         oldvalue = pool.set_flag(flag, value)
 386         oldvalue = pool.set_flag(flag, value)
 387
 388         int get_flag(int flag)
 389         my $value = $pool->get_flag($flag);
 390         value = pool.get_flag(flag)
 391         value = pool.get_flag(flag)
 392
 393 Set/get a pool specific flag. The flags define how the system works, e.g. how
 394 the package manager treats obsoletes. The default flags should be sane for most
 395 applications, but in some cases you may want to tweak a flag, for example if
 396 you want to solve package dependencies for some other system.
 397
 398         void set_rootdir(const char *rootdir)
 399         $pool->set_rootdir(rootdir);
 400         pool.set_rootdir(rootdir)
 401         pool.set_rootdir(rootdir)
 402
 403         const char *get_rootdir()
 404         my $rootdir = $pool->get_rootdir();
 405         rootdir = pool.get_rootdir()
 406         rootdir = pool.get_rootdir()
 407
 408 Set/get the rootdir to use. This is useful if you want package management
 409 to work only in some directory, for example if you want to setup a chroot
 410 jail. Note that the rootdir will only be prepended to file paths if the
 411 *REPO_USE_ROOTDIR* flag is used.
 412
 413         void setarch(const char *arch = 0)
 414         $pool->setarch();
 415         pool.setarch()
 416         pool.setarch()
 417
 418 Set the architecture for your system. The architecture is used to determine
 419 which packages are installable. It defaults to the result of ``uname -m''.
 420
 421         Repo add_repo(const char *name)
 422         $repo = $pool->add_repo($name);
 423         repo = pool.add_repo(name)
 424         repo = pool.add_repo(name)
 425
 426 Add a Repository with the specified name to the pool. The repository is empty
 427 on creation, use the repository methods to populate it with packages.
 428
 429         Repoiterator repos_iter()
 430         for my $repo (@{$pool->repos_iter()})
 431         for repo in pool.repos_iter():
 432         for repo in pool.repos_iter()
 433
 434 Iterate over the existing repositories.
 435
 436         Solvableiterator solvables_iter()
 437         for my $solvable (@{$pool->solvables_iter()})
 438         for solvable in pool.solvables_iter():
 439         for solvable in pool.solvables_iter()
 440
 441 Iterate over the existing solvables.
 442
 443         Dep Dep(const char *str, bool create = 1)
 444         my $dep = $pool->Dep($string);
 445         dep = pool.Dep(string)
 446         dep = pool.Dep(string)
 447
 448 Create an object describing a string or dependency. If the string is currently
 449 not in the pool and _create_ is false, *undef*/*None*/*nil* is returned.
 450
 451         void addfileprovides()
 452         $pool->addfileprovides();
 453         pool.addfileprovides()
 454         pool.addfileprovides()
 455
 456         Id *addfileprovides_queue()
 457         my @ids = $pool->addfileprovides_queue();
 458         ids = pool.addfileprovides_queue()
 459         ids = pool.addfileprovides_queue()
 460
 461 Some package managers like rpm allow dependencies on files contained in other
 462 packages. To allow libsolv to deal with those dependencies in an efficient way,
 463 you need to call the addfileprovides method after creating and reading all
 464 repositories. This method will scan all dependency for file names and then scan
 465 all packages for matching files. If a filename has been matched, it will be
 466 added to the provides list of the corresponding package. The
 467 addfileprovides_queue variant works the same way but returns an array
 468 containing all file dependencies. This information can be stored in the
 469 meta section of the repositories to speed up the next time the
 470 repository is loaded and addfileprovides is called.
 471
 472         void createwhatprovides()
 473         $pool->createwhatprovides();
 474         pool.createwhatprovides()
 475         pool.createwhatprovides()
 476
 477 Create the internal ``whatprovides'' hash over all of the provides of all
 478 installable packages. This method must be called before doing any lookups on
 479 provides.
 480 It's encouraged to do it right after all repos are set up, usually right after
 481 the call to addfileprovides().
 482
 483         Solvable *whatprovides(DepId dep)
 484         my @solvables = $pool->whatprovides($dep);
 485         solvables = pool.whatprovides(dep)
 486         solvables = pool.whatprovides(dep)
 487
 488 Return all solvables that provide the specified dependency. You can use either
 489 a Dep object or a simple Id as argument.
 490
 491         Solvable *best_solvables(Solvable *solvables, int flags = 0)
 492         my @solvables = $pool->best_solvables($solvables);
 493         solvables = pool.best_solvables(solvables)
 494         solvables = pool.best_solvables(solvables)
 495
 496 Filter list of solvables by repo priority, architecture and version.
 497
 498         Solvable *whatmatchessolvable(Id keyname, Solvable solvable, Id marker = -1)
 499         my @solvables = $pool->whatmatchessolvable($keyname, $solvable)
 500         solvables = pool.whatmatchessolvable(keyname, solvable)
 501         solvables = pool.whatmatchessolvable(keyname, solvable)
 502
 503 Return all solvables that match package dependencies against solvable's
 504 provides.
 505
 506         Id *matchprovidingids(const char *match, int flags)
 507         my @ids = $pool->matchprovidingids($match, $flags);
 508         ids = pool.matchprovidingids(match, flags)
 509         ids = pool.matchprovidingids(match, flags)
 510
 511 Search the names of all provides and return the ones matching the specified
 512 string. See the Dataiterator class for the allowed flags.
 513
 514         Id towhatprovides(Id *ids)
 515         my $offset = $pool->towhatprovides(\@ids);
 516         offset = pool.towhatprovides(ids)
 517         offset = pool.towhatprovides(ids)
 518
 519 ``Internalize'' an array containing Ids. The returned value can be used to
 520 create solver jobs working on a specific set of packages. See the Solver class
 521 for more information.
 522
 523         void set_namespaceproviders(DepId ns, DepId evr, bool value = 1)
 524         $pool->set_namespaceproviders($ns, $evr, 1);
 525         pool.set_namespaceproviders(ns, evr, True)
 526         pool.set_namespaceproviders(ns, evr, true)
 527
 528 Manually set a namespace provides entry in the whatprovides index.
 529
 530         void flush_namespaceproviders(DepId ns, DepId evr)
 531         $pool->flush_namespaceproviders($ns, $evr);
 532         $pool.flush_namespaceproviders(ns, evr)
 533         $pool.flush_namespaceproviders(ns, evr)
 534
 535 Flush the cache of all namespaceprovides matching the specified namespace
 536 dependency. You can use zero as a wildcard argument.
 537
 538         bool isknownarch(DepId id)
 539         my $bool = $pool->isknownarch($id);
 540         bool = pool.isknownarch(id)
 541         bool = pool.isknownarch?(id)
 542
 543 Return true if the specified Id describes a known architecture.
 544
 545         Solver Solver()
 546         my $solver = $pool->Solver();
 547         solver = pool.Solver()
 548         solver = pool.Solver()
 549
 550 Create a new solver object.
 551
 552         Job Job(int how, Id what)
 553         my $job = $pool->Job($how, $what);
 554         job = pool.Job(how, what)
 555         job = pool.Job(how, what)
 556
 557 Create a new Job object. Kind of low level, in most cases you would
 558 instead use a Selection or Dep job constructor.
 559
 560         Selection Selection()
 561         my $sel = $pool->Selection();
 562         sel = pool.Selection()
 563         sel = pool.Selection()
 564
 565 Create an empty selection. Useful as a starting point for merging other
 566 selections.
 567
 568         Selection Selection_all()
 569         my $sel = $pool->Selection_all();
 570         sel = pool.Selection_all()
 571         sel = pool.Selection_all()
 572
 573 Create a selection containing all packages. Useful as starting point for
 574 intersecting other selections or for update/distupgrade jobs.
 575
 576         Selection select(const char *name, int flags)
 577         my $sel = $pool->select($name, $flags);
 578         sel = pool.select(name, flags)
 579         sel = pool.select(name, flags)
 580
 581 Create a selection by matching packages against the specified string. See the
 582 Selection class for a list of flags and how to create solver jobs from a
 583 selection.
 584
 585         Selection matchdeps(const char *name, int flags, Id keyname, Id marker = -1)
 586         my $sel = $pool->matchdeps($name, $flags, $keyname);
 587         sel = pool.matchdeps(name, flags, keyname)
 588         sel = pool.matchdeps(name, flags, keyname)
 589
 590 Create a selection by matching package dependencies against the specified string.
 591 This can be used if you want to match other dependency types than ``provides''.
 592
 593         Selection matchdepid(DepId dep, int flags, Id keyname, Id marker = -1)
 594         my $sel = $pool->matchdepid($dep, $flags, $keyname);
 595         sel = pool.matchdepid(dep, flags, keyname)
 596         sel = pool.matchdepid(dep, flags, keyname)
 597
 598 Create a selection by matching package dependencies against the specified
 599 dependency. This may be faster than matchdeps and also works with complex
 600 dependencies. The downside is that you cannot use globs or case insensitive
 601 matching.
 602
 603         Selection matchsolvable(Solvable solvable, int flags, Id keyname, Id marker = -1)
 604         my $sel = $pool->matchsolvable($solvable, $flags, $keyname);
 605         sel = pool.matchsolvable(solvable, flags, keyname)
 606         sel = pool.matchsolvable(solvable, flags, keyname)
 607
 608 Create a selection by matching package dependencies against the specified
 609 solvable's provides.
 610
 611         void setpooljobs(Jobs *jobs)
 612         $pool->setpooljobs(\@jobs);
 613         pool.setpooljobs(jobs)
 614         pool.setpooljobs(jobs)
 615
 616         Job *getpooljobs()
 617         @jobs = $pool->getpooljobs();
 618         jobs = pool.getpooljobs()
 619         jobs = pool.getpooljobs()
 620
 621 Get/Set fixed jobs stored in the pool. Those jobs are automatically appended to
 622 all solver jobs, they are meant for fixed configurations like which packages
 623 can be multiversion installed, which packages were userinstalled, or which
 624 packages must not be erased.
 625
 626         void set_loadcallback(Callable *callback)
 627         $pool->setloadcallback(\&callbackfunction);
 628         pool.setloadcallback(callbackfunction)
 629         pool.setloadcallback { |repodata| ... }
 630
 631 Set the callback function called when repository metadata needs to be loaded on
 632 demand. To make use of this feature, you need to create repodata stubs that
 633 tell the library which data is available but not loaded. If later on the data
 634 needs to be accessed, the callback function is called with a repodata argument.
 635 You can then load the data (maybe fetching it first from a remote server).
 636 The callback should return true if the data has been made available.
 637
 638         /* bindings only */
 639         $pool->appdata_disown()
 640         pool.appdata_disown()
 641         pool.appdata_disown()
 642
 643 Decrement the reference count of the appdata object. This can be used to break
 644 circular references (e.g. if the pool's appdata value points to some meta data
 645 structure that contains a pool handle). If used incorrectly, this method can
 646 lead to application crashes, so beware. (This method is a no-op for ruby and tcl.)
 647
 648 === DATA RETRIEVAL METHODS ===
 649
 650 In the following functions, the _keyname_ argument describes what to retrieve.
 651 For the standard cases you can use the available Id constants. For example,
 652
 653         $solv::SOLVABLE_SUMMARY
 654         solv.SOLVABLE_SUMMARY
 655         Solv::SOLVABLE_SUMMARY
 656
 657 selects the ``Summary'' entry of a solvable. The _solvid_ argument selects the
 658 desired solvable by Id.
 659
 660         const char *lookup_str(Id solvid, Id keyname)
 661         my $string = $pool->lookup_str($solvid, $keyname);
 662         string = pool.lookup_str(solvid, keyname)
 663         string = pool.lookup_str(solvid, keyname)
 664
 665         Id lookup_id(Id solvid, Id keyname)
 666         my $id = $pool->lookup_id($solvid, $keyname);
 667         id = pool.lookup_id(solvid, keyname)
 668         id = pool.lookup_id(solvid, keyname)
 669
 670         unsigned long long lookup_num(Id solvid, Id keyname, unsigned long long notfound = 0)
 671         my $num = $pool->lookup_num($solvid, $keyname);
 672         num = pool.lookup_num(solvid, keyname)
 673         num = pool.lookup_num(solvid, keyname)
 674
 675         bool lookup_void(Id solvid, Id keyname)
 676         my $bool = $pool->lookup_void($solvid, $keyname);
 677         bool = pool.lookup_void(solvid, keyname)
 678         bool = pool.lookup_void(solvid, keyname)
 679
 680         Id *lookup_idarray(Id solvid, Id keyname)
 681         my @ids = $pool->lookup_idarray($solvid, $keyname);
 682         ids = pool.lookup_idarray(solvid, keyname)
 683         ids = pool.lookup_idarray(solvid, keyname)
 684
 685         Chksum lookup_checksum(Id solvid, Id keyname)
 686         my $chksum = $pool->lookup_checksum($solvid, $keyname);
 687         chksum = pool.lookup_checksum(solvid, keyname)
 688         chksum = pool.lookup_checksum(solvid, keyname)
 689
 690 Lookup functions. Return the data element stored in the specified solvable.
 691 You should probably use the methods of the Solvable class instead.
 692
 693         Dataiterator Dataiterator(Id keyname, const char *match = 0, int flags = 0)
 694         my $di = $pool->Dataiterator($keyname, $match, $flags);
 695         di = pool.Dataiterator(keyname, match, flags)
 696         di = pool.Dataiterator(keyname, match, flags)
 697
 698         Dataiterator Dataiterator_solvid(Id solvid, Id keyname, const char *match = 0, int flags = 0)
 699         my $di = $pool->Dataiterator($solvid, $keyname, $match, $flags);
 700         di = pool.Dataiterator(solvid, keyname, match, flags)
 701         di = pool.Dataiterator(solvid, keyname, match, flags)
 702
 703         for my $d (@$di)
 704         for d in di:
 705         for d in di
 706
 707 Iterate over the matching data elements. See the Dataiterator class for more
 708 information. The Dataiterator method iterates over all solvables in the pool,
 709 whereas the Dataiterator_solvid only iterates over the specified solvable.
 710
 711 === ID METHODS ===
 712
 713 The following methods deal with Ids, i.e. integers representing objects in the
 714 pool. They are considered ``low level'', in most cases you would not use them
 715 but instead the object orientated methods.
 716
 717         Repo id2repo(Id id)
 718         $repo = $pool->id2repo($id);
 719         repo = pool.id2repo(id)
 720         repo = pool.id2repo(id)
 721
 722 Lookup an existing Repository by id. You can also do this by using the *repos*
 723 attribute.
 724
 725         Solvable id2solvable(Id id)
 726         $solvable = $pool->id2solvable($id);
 727         solvable = pool.id2solvable(id)
 728         solvable = pool.id2solvable(id)
 729
 730 Lookup an existing Repository by id. You can also do this by using the
 731 *solvables* attribute.
 732
 733         const char *solvid2str(Id id)
 734         my $str = $pool->solvid2str($id);
 735         str = pool.solvid2str(id)
 736         str = pool.solvid2str(id)
 737
 738 Return a string describing the Solvable with the specified id. The string
 739 consists of the name, version, and architecture of the Solvable.
 740
 741         Id str2id(const char *str, bool create = 1)
 742         my $id = pool->str2id($string);
 743         id = pool.str2id(string)
 744         id = pool.str2id(string)
 745
 746         const char *id2str(Id id)
 747         $string = pool->id2str($id);
 748         string = pool.id2str(id)
 749         string = pool.id2str(id)
 750
 751 Convert a string into an Id and back. If the string is currently not in the
 752 pool and _create_ is false, zero is returned.
 753
 754         Id rel2id(Id name, Id evr, int flags, bool create = 1)
 755         my $id = pool->rel2id($nameid, $evrid, $flags);
 756         id = pool.rel2id(nameid, evrid, flags)
 757         id = pool.rel2id(nameid, evrid, flags)
 758
 759 Create a ``relational'' dependency. Such dependencies consist of a name part,
 760 _flags_ describing the relation, and a version part. The flags are:
 761
 762         $solv::REL_EQ | $solv::REL_GT | $solv::REL_LT
 763         solv.REL_EQ | solv.REL_GT | solv.REL_LT
 764         Solv::REL_EQ | Solv::REL_GT | Solv::REL_LT
 765
 766 Thus, if you want a ``\<='' relation, you would use *REL_LT | REL_EQ*.
 767
 768         Id id2langid(Id id, const char *lang, bool create = 1)
 769         my $id = $pool->id2langid($id, $language);
 770         id = pool.id2langid(id, language)
 771         id = pool.id2langid(id, language)
 772
 773 Create a language specific Id from some other id. This function simply converts
 774 the id into a string, appends a dot and the specified language to the string
 775 and converts the result back into an Id.
 776
 777         const char *dep2str(Id id)
 778         $string = pool->dep2str($id);
 779         string = pool.dep2str(id)
 780         string = pool.dep2str(id)
 781
 782 Convert a dependency id into a string. If the id is just a string, this
 783 function has the same effect as id2str(). For relational dependencies, the
 784 result is the correct ``name relation evr'' string.
 785
 786
 787 The Dependency Class
 788 --------------------
 789 The dependency class is an object orientated way to work with strings and
 790 dependencies. Internally, dependencies are represented as Ids, i.e. simple
 791 numbers. Dependency objects can be constructed by using the Pool's Dep()
 792 method.
 793
 794 === ATTRIBUTES ===
 795
 796         Pool *pool;             /* read only */
 797         $dep->{pool}
 798         dep.pool
 799         dep.pool
 800
 801 Back reference to the pool this dependency belongs to.
 802
 803         Id id;          /* read only */
 804         $dep->{id}
 805         dep.id
 806         dep.id
 807
 808 The id of this dependency.
 809
 810 == Methods ==
 811
 812         Dep Rel(int flags, DepId evrid, bool create = 1)
 813         my $reldep = $dep->Rel($flags, $evrdep);
 814         reldep = dep.Rel(flags, evrdep)
 815         reldep = dep.Rel(flags, evrdep)
 816
 817 Create a relational dependency from the caller dependency, the flags,
 818 and a dependency describing the ``version'' part.
 819 See the pool's rel2id method for a description of the flags.
 820
 821         Selection Selection_name(int setflags = 0)
 822         my $sel = $dep->Selection_name();
 823         sel = dep.Selection_name()
 824         sel = dep.Selection_name()
 825
 826 Create a Selection from a dependency. The selection consists of all packages
 827 that have a name equal to the dependency. If the dependency is of a relational
 828 type, the packages version must also fulfill the dependency.
 829
 830         Selection Selection_provides(int setflags = 0)
 831         my $sel = $dep->Selection_provides();
 832         sel = dep.Selection_provides()
 833         sel = dep.Selection_provides()
 834
 835 Create a Selection from a dependency. The selection consists of all packages
 836 that have at least one provides matching the dependency.
 837
 838         const char *str()
 839         my $str = $dep->str();
 840         str = $dep.str()
 841         str = $dep.str()
 842
 843 Return a string describing the dependency.
 844
 845         <stringification>
 846         my $str = $dep->str;
 847         str = str(dep)
 848         str = dep.to_s
 849
 850 Same as calling the str() method.
 851
 852         <equality>
 853         if ($dep1 == $dep2)
 854         if dep1 == dep2:
 855         if dep1 == dep2
 856
 857 Two dependencies are equal if they are part of the same pool and have the same
 858 ids.
 859
 860
 861 The Repository Class
 862 --------------------
 863 A Repository describes a group of packages, normally coming from the same
 864 source. Repositories are created by the Pool's add_repo() method.
 865
 866 === ATTRIBUTES ===
 867
 868         Pool *pool;                     /* read only */
 869         $repo->{pool}
 870         repo.pool
 871         repo.pool
 872
 873 Back reference to the pool this dependency belongs to.
 874
 875         Id id;                          /* read only */
 876         $repo->{id}
 877         repo.id
 878         repo.id
 879
 880 The id of the repository.
 881
 882         const char *name;               /* read/write */
 883         $repo->{name}
 884         repo.name
 885         repo.name
 886
 887 The repositories name. To libsolv, the name is just a string with no specific
 888 meaning.
 889
 890         int priority;                   /* read/write */
 891         $repo->{priority}
 892         repo.priority
 893         repo.priority
 894
 895 The priority of the repository. A higher number means that packages of this
 896 repository will be chosen over other repositories, even if they have a greater
 897 package version.
 898
 899         int subpriority;                /* read/write */
 900         $repo->{subpriority}
 901         repo.subpriority
 902         repo.subpriority
 903
 904 The sub-priority of the repository. This value is compared when the priorities
 905 of two repositories are the same. It is useful to make the library prefer
 906 on-disk repositories to remote ones.
 907
 908         int nsolvables;                 /* read only */
 909         $repo->{nsolvables}
 910         repo.nsolvables
 911         repo.nsolvables
 912
 913 The number of solvables in this repository.
 914
 915         void *appdata;                  /* read/write */
 916         $repo->{appdata}
 917         repo.appdata
 918         repo.appdata
 919
 920 Application specific data that may be used in any way by the code using the
 921 repository.
 922
 923         Datapos *meta;                  /* read only */
 924         $repo->{meta}
 925         repo.meta
 926         repo.meta
 927
 928 Return a Datapos object of the repodata's metadata. You can use the lookup
 929 methods of the Datapos class to lookup metadata attributes, like the repository
 930 timestamp.
 931
 932 === CONSTANTS ===
 933
 934 *REPO_REUSE_REPODATA*::
 935 Reuse the last repository data area (``repodata'') instead of creating a
 936 new area.
 937
 938 *REPO_NO_INTERNALIZE*::
 939 Do not internalize the added repository data. This is useful if
 940 you plan to add more data because internalization is a costly
 941 operation.
 942
 943 *REPO_LOCALPOOL*::
 944 Use the repodata's pool for Id storage instead of the global pool. Useful
 945 if you don't want to pollute the global pool with many unneeded ids, like
 946 when storing the filelist.
 947
 948 *REPO_USE_LOADING*::
 949 Use the repodata that is currently being loaded instead of creating a new
 950 one. This only makes sense if used in a load callback.
 951
 952 *REPO_EXTEND_SOLVABLES*::
 953 Do not create new solvables for the new data, but match existing solvables
 954 and add the data to them. Repository metadata is often split into multiple
 955 parts, with one primary file describing all packages and other parts
 956 holding information that is normally not needed, like the changelog.
 957
 958 *REPO_USE_ROOTDIR*::
 959 Prepend the pool's rootdir to the path when doing file operations.
 960
 961 *REPO_NO_LOCATION*::
 962 Do not add a location element to the solvables. Useful if the solvables
 963 are not in the final position, so you can add the correct location later
 964 in your code.
 965
 966 *SOLV_ADD_NO_STUBS*::
 967 Do not create stubs for repository parts that can be downloaded on demand.
 968
 969 *SUSETAGS_RECORD_SHARES*::
 970 This is specific to the add_susetags() method. Susetags allows one to refer to
 971 already read packages to save disk space. If this data sharing needs to
 972 work over multiple calls to add_susetags, you need to specify this flag so
 973 that the share information is made available to subsequent calls.
 974
 975 === METHODS ===
 976
 977         void free(bool reuseids = 0)
 978         $repo->free();
 979         repo.free()
 980         repo.free()
 981
 982 Free the repository and all solvables it contains. If _reuseids_ is set to
 983 true, the solvable ids and the repository id may be reused by the library when
 984 added new solvables. Thus you should leave it false if you are not sure that
 985 somebody holds a reference.
 986
 987         void empty(bool reuseids = 0)
 988         $repo->empty();
 989         repo.empty()
 990         repo.empty()
 991
 992 Free all the solvables in a repository. The repository will be empty after this
 993 call. See the free() method for the meaning of _reuseids_.
 994
 995         bool isempty()
 996         $repo->isempty()
 997         repo.empty()
 998         repo.empty?
 999
1000 Return true if there are no solvables in this repository.
1001
1002         void internalize()
1003         $repo->internalize();
1004         repo.internalize()
1005         repo.internalize()
1006
1007 Internalize added data. Data must be internalized before it is available to the
1008 lookup and data iterator functions.
1009
1010         bool write(FILE *fp)
1011         $repo->write($fp)
1012         repo.write(fp)
1013         repo.write(fp)
1014
1015 Write a repo as a ``solv'' file. These files can be read very fast and thus are
1016 a good way to cache repository data. Returns false if there was some error
1017 writing the file.
1018
1019         Solvableiterator solvables_iter()
1020         for my $solvable (@{$repo->solvables_iter()})
1021         for solvable in repo.solvables_iter():
1022         for solvable in repo.solvables_iter()
1023
1024 Iterate over all solvables in a repository.
1025
1026         Repodata add_repodata(int flags = 0)
1027         my $repodata = $repo->add_repodata();
1028         repodata = repo.add_repodata()
1029         repodata = repo.add_repodata()
1030
1031 Add a new repodata area to the repository. This is normally automatically
1032 done by the repo_add methods, so you need this method only in very
1033 rare circumstances.
1034
1035         void create_stubs()
1036         $repo->create_stubs();
1037         repo.create_stubs()
1038         repo.create_stubs()
1039
1040 Calls the create_stubs() repodata method for the last repodata of the
1041 repository.
1042
1043         bool iscontiguous()
1044         $repo->iscontiguous()
1045         repo.iscontiguous()
1046         repo.iscontiguous?
1047
1048 Return true if the solvables of this repository are all in a single block with
1049 no holes, i.e. they have consecutive ids.
1050
1051         Repodata first_repodata()
1052         my $repodata = $repo->first_repodata();
1053         repodata = repo.first_repodata()
1054         repodata = repo.first_repodata()
1055
1056 Checks if all repodatas but the first repodata are extensions, and return the
1057 first repodata if this is the case. Useful if you want to do a store/retrieve
1058 sequence on the repository to reduce the memory using and enable paging, as
1059 this does not work if the repository contains multiple non-extension repodata
1060 areas.
1061
1062         Selection Selection(int setflags = 0)
1063         my $sel = $repo->Selection();
1064         sel = repo.Selection()
1065         sel = repo.Selection()
1066
1067 Create a Selection consisting of all packages in the repository.
1068
1069         Dataiterator Dataiterator(Id key, const char *match = 0, int flags = 0)
1070         my $di = $repo->Dataiterator($keyname, $match, $flags);
1071         di = repo.Dataiterator(keyname, match, flags)
1072         di = repo.Dataiterator(keyname, match, flags)
1073
1074         Dataiterator Dataiterator_meta(Id key, const char *match = 0, int flags = 0)
1075         my $di = $repo->Dataiterator_meta($keyname, $match, $flags);
1076         di = repo.Dataiterator_meta(keyname, match, flags)
1077         di = repo.Dataiterator_meta(keyname, match, flags)
1078
1079         for my $d (@$di)
1080         for d in di:
1081         for d in di
1082
1083 Iterate over the matching data elements in this repository. See the
1084 Dataiterator class for more information. The Dataiterator() method
1085 iterates over all solvables in a repository, whereas the Dataiterator_meta
1086 method only iterates over the repository's meta data.
1087
1088         <stringification>
1089         my $str = $repo->str;
1090         str = str(repo)
1091         str = repo.to_s
1092
1093 Return the name of the repository, or "Repo#<id>" if no name is set.
1094
1095         <equality>
1096         if ($repo1 == $repo2)
1097         if repo1 == repo2:
1098         if repo1 == repo2
1099
1100 Two repositories are equal if they belong to the same pool and have the same id.
1101
1102 === DATA ADD METHODS ===
1103
1104         Solvable add_solvable()
1105         $repo->add_solvable();
1106         repo.add_solvable()
1107         repo.add_solvable()
1108
1109 Add a single empty solvable to the repository. Returns a Solvable object, see
1110 the Solvable class for more information.
1111
1112         bool add_solv(const char *name, int flags = 0)
1113         $repo->add_solv($name);
1114         repo.add_solv(name)
1115         repo.add_solv(name)
1116
1117         bool add_solv(FILE *fp, int flags = 0)
1118         $repo->add_solv($fp);
1119         repo.add_solv(fp)
1120         repo.add_solv(fp)
1121
1122 Read a ``solv'' file and add its contents to the repository. These files can be
1123 written with the write() method and are normally used as fast cache for
1124 repository metadata.
1125
1126         bool add_rpmdb(int flags = 0)
1127         $repo->add_rpmdb();
1128         repo.add_rpmdb()
1129         repo.add_rpmdb()
1130
1131         bool add_rpmdb_reffp(FILE *reffp, int flags = 0)
1132         $repo->add_rpmdb_reffp($reffp);
1133         repo.add_rpmdb_reffp(reffp)
1134         repo.add_rpmdb_reffp(reffp)
1135
1136 Add the contents of the rpm database to the repository. If a solv file
1137 containing an old version of the database is available, it can be passed as
1138 reffp to speed up reading.
1139
1140         Solvable add_rpm(const char *filename, int flags = 0)
1141         my $solvable = $repo->add_rpm($filename);
1142         solvable = repo.add_rpm(filename)
1143         solvable = repo.add_rpm(filename)
1144
1145 Add the metadata of a single rpm package to the repository.
1146
1147         bool add_rpmdb_pubkeys(int flags = 0)
1148         $repo->add_rpmdb_pubkeys();
1149         repo.add_rpmdb_pubkeys()
1150         repo.add_rpmdb_pubkeys()
1151
1152 Add all pubkeys contained in the rpm database to the repository. Note that
1153 newer rpm versions also allow to store the pubkeys in some directory instead
1154 of the rpm database.
1155
1156         Solvable add_pubkey(const char *keyfile, int flags = 0)
1157         my $solvable = $repo->add_pubkey($keyfile);
1158         solvable = repo.add_pubkey(keyfile)
1159         solvable = repo.add_pubkey(keyfile)
1160
1161 Add a pubkey from a file to the repository.
1162
1163         bool add_rpmmd(FILE *fp, const char *language, int flags = 0)
1164         $repo->add_rpmmd($fp, undef);
1165         repo.add_rpmmd(fp, None)
1166         repo.add_rpmmd(fp, nil)
1167
1168 Add metadata stored in the "rpm-md" format (i.e. from files in the ``repodata''
1169 directory) to a repository. Supported files are "primary", "filelists",
1170 "other", "suseinfo". Do not forget to specify the *REPO_EXTEND_SOLVABLES* for
1171 extension files like "filelists" and "other". Use the _language_ parameter if
1172 you have language extension files, otherwise simply use a *undef*/*None*/*nil*
1173 parameter.
1174
1175         bool add_repomdxml(FILE *fp, int flags = 0)
1176         $repo->add_repomdxml($fp);
1177         repo.add_repomdxml(fp)
1178         repo.add_repomdxml(fp)
1179
1180 Add the repomd.xml meta description from the "rpm-md" format to the repository.
1181 This file contains information about the repository like keywords, and also a
1182 list of all database files with checksums. The data is added to the "meta"
1183 section of the repository, i.e. no package gets created.
1184
1185         bool add_updateinfoxml(FILE *fp, int flags = 0)
1186         $repo->add_updateinfoxml($fp);
1187         repo.add_updateinfoxml(fp)
1188         repo.add_updateinfoxml(fp)
1189
1190 Add the updateinfo.xml file containing available maintenance updates to the
1191 repository. All updates are created as special packages that have a "patch:"
1192 prefix in their name.
1193
1194         bool add_deltainfoxml(FILE *fp, int flags = 0)
1195         $repo->add_deltainfoxml($fp);
1196         repo.add_deltainfoxml(fp)
1197         repo.add_deltainfoxml(fp)
1198
1199 Add the deltainfo.xml file (also called prestodelta.xml) containing available
1200 delta-rpms to the repository. The data is added to the "meta" section, i.e. no
1201 package gets created.
1202
1203         bool add_debdb(int flags = 0)
1204         $repo->add_debdb();
1205         repo.add_debdb()
1206         repo.add_debdb()
1207
1208 Add the contents of the debian installed package database to the repository.
1209
1210         bool add_debpackages(FILE *fp, int flags = 0)
1211         $repo->add_debpackages($fp);
1212         repo.add_debpackages($fp)
1213         repo.add_debpackages($fp)
1214
1215 Add the contents of the debian repository metadata (the "packages" file)
1216 to the repository.
1217
1218         Solvable add_deb(const char *filename, int flags = 0)
1219         my $solvable = $repo->add_deb($filename);
1220         solvable = repo.add_deb(filename)
1221         solvable = repo.add_deb(filename)
1222
1223 Add the metadata of a single deb package to the repository.
1224
1225         bool add_mdk(FILE *fp, int flags = 0)
1226         $repo->add_mdk($fp);
1227         repo.add_mdk(fp)
1228         repo.add_mdk(fp)
1229
1230 Add the contents of the mageia/mandriva repository metadata (the
1231 "synthesis.hdlist" file) to the repository.
1232
1233         bool add_mdk_info(FILE *fp, int flags = 0)
1234         $repo->add_mdk_info($fp);
1235         repo.add_mdk_info(fp)
1236         repo.add_mdk_info(fp)
1237
1238 Extend the packages from the synthesis file with the info.xml and files.xml
1239 data. Do not forget to specify *REPO_EXTEND_SOLVABLES*.
1240
1241         bool add_arch_repo(FILE *fp, int flags = 0)
1242         $repo->add_arch_repo($fp);
1243         repo.add_arch_repo(fp)
1244         repo.add_arch_repo(fp)
1245
1246 Add the contents of the archlinux repository metadata (the ".db.tar" file) to
1247 the repository.
1248
1249         bool add_arch_local(const char *dir, int flags = 0)
1250         $repo->add_arch_local($dir);
1251         repo.add_arch_local(dir)
1252         repo.add_arch_local(dir)
1253
1254 Add the contents of the archlinux installed package database to the repository.
1255 The _dir_ parameter is usually set to "/var/lib/pacman/local".
1256
1257         bool add_content(FILE *fp, int flags = 0)
1258         $repo->add_content($fp);
1259         repo.add_content(fp)
1260         repo.add_content(fp)
1261
1262 Add the ``content'' meta description from the susetags format to the repository.
1263 This file contains information about the repository like keywords, and also
1264 a list of all database files with checksums. The data is added to the "meta"
1265 section of the repository, i.e. no package gets created.
1266
1267         bool add_susetags(FILE *fp, Id defvendor, const char *language, int flags = 0)
1268         $repo->add_susetags($fp, $defvendor, $language);
1269         repo.add_susetags(fp, defvendor, language)
1270         repo.add_susetags(fp, defvendor, language)
1271
1272 Add repository metadata in the susetags format to the repository. Like with
1273 add_rpmmd, you can specify a language if you have language extension files. The
1274 _defvendor_ parameter provides a default vendor for packages with missing
1275 vendors, it is usually provided in the content file.
1276
1277         bool add_products(const char *dir, int flags = 0)
1278         $repo->add_products($dir);
1279         repo.add_products(dir)
1280         repo.add_products(dir)
1281
1282 Add the installed SUSE products database to the repository. The _dir_ parameter
1283 is usually "/etc/products.d".
1284
1285
1286 The Solvable Class
1287 ------------------
1288 A solvable describes all the information of one package. Each solvable
1289 belongs to one repository, it can be added and filled manually but in
1290 most cases solvables will get created by the repo_add methods.
1291
1292 === ATTRIBUTES ===
1293
1294         Repo *repo;                     /* read only */
1295         $solvable->{repo}
1296         solvable.repo
1297         solvable.repo
1298
1299 The repository this solvable belongs to.
1300
1301         Pool *pool;                     /* read only */
1302         $solvable->{pool}
1303         solvable.pool
1304         solvable.pool
1305
1306 The pool this solvable belongs to, same as the pool of the repo.
1307
1308         Id id;                          /* read only */
1309         $solvable->{id}
1310         solvable.id
1311         solvable.id
1312
1313 The specific id of the solvable.
1314
1315         char *name;                     /* read/write */
1316         $solvable->{name}
1317         solvable.name
1318         solvable.name
1319
1320         char *evr;                      /* read/write */
1321         $solvable->{evr}
1322         solvable.evr
1323         solvable.evr
1324
1325         char *arch;                     /* read/write */
1326         $solvable->{arch}
1327         solvable.arch
1328         solvable.arch
1329
1330         char *vendor;                   /* read/write */
1331         $solvable->{vendor}
1332         solvable.vendor
1333         solvable.vendor
1334
1335 Easy access to often used attributes of solvables. They are
1336 internally stored as Ids.
1337
1338         Id nameid;                      /* read/write */
1339         $solvable->{nameid}
1340         solvable.nameid
1341         solvable.nameid
1342
1343         Id evrid;                       /* read/write */
1344         $solvable->{evrid}
1345         solvable.evrid
1346         solvable.evrid
1347
1348         Id archid;                      /* read/write */
1349         $solvable->{archid}
1350         solvable.archid
1351         solvable.archid
1352
1353         Id vendorid;                    /* read/write */
1354         $solvable->{vendorid}
1355         solvable.vendorid
1356         solvable.vendorid
1357
1358 Raw interface to the ids. Useful if you want to search for
1359 a specific id and want to avoid the string compare overhead.
1360
1361 === METHODS ===
1362
1363         const char *lookup_str(Id keyname)
1364         my $string = $solvable->lookup_str($keyname);
1365         string = solvable.lookup_str(keyname)
1366         string = solvable.lookup_str(keyname)
1367
1368         Id lookup_id(Id keyname)
1369         my $id = $solvable->lookup_id($keyname);
1370         id = solvable.lookup_id(keyname)
1371         id = solvable.lookup_id(keyname)
1372
1373         unsigned long long lookup_num(Id keyname, unsigned long long notfound = 0)
1374         my $num = $solvable->lookup_num($keyname);
1375         num = solvable.lookup_num(keyname)
1376         num = solvable.lookup_num(keyname)
1377
1378         bool lookup_void(Id keyname)
1379         my $bool = $solvable->lookup_void($keyname);
1380         bool = solvable.lookup_void(keyname)
1381         bool = solvable.lookup_void(keyname)
1382
1383         Chksum lookup_checksum(Id keyname)
1384         my $chksum = $solvable->lookup_checksum($keyname);
1385         chksum = solvable.lookup_checksum(keyname)
1386         chksum = solvable.lookup_checksum(keyname)
1387
1388         Id *lookup_idarray(Id keyname, Id marker = -1)
1389         my @ids = $solvable->lookup_idarray($keyname);
1390         ids = solvable.lookup_idarray(keyname)
1391         ids = solvable.lookup_idarray(keyname)
1392
1393         Dep *lookup_deparray(Id keyname, Id marker = -1)
1394         my @deps = $solvable->lookup_deparray($keyname);
1395         deps = solvable.lookup_deparray(keyname)
1396         deps = solvable.lookup_deparray(keyname)
1397
1398 Generic lookup methods. Retrieve data stored for the specific keyname.
1399 The lookup_idarray() method will return an array of Ids, use
1400 lookup_deparray if you want an array of Dependency objects instead.
1401 Some Id arrays contain two parts of data divided by a specific marker,
1402 for example the provides array uses the SOLVABLE_FILEMARKER id to
1403 store both the ids provided by the package and the ids added by
1404 the addfileprovides method. The default, -1, translates to the
1405 correct marker for the keyname and returns the first part of the
1406 array, use 1 to select the second part or 0 to retrieve all ids
1407 including the marker.
1408
1409         const char *lookup_location(unsigned int *OUTPUT);
1410         my ($location, $mediano) = $solvable->lookup_location();
1411         location, mediano = solvable.lookup_location()
1412         location, mediano = solvable.lookup_location()
1413
1414 Return a tuple containing the on-media location and an optional
1415 media number for multi-part repositories (e.g. repositories
1416 spawning multiple DVDs).
1417
1418         const char *lookup_sourcepkg();
1419         my $sourcepkg = $solvable->lookup_sourcepkg();
1420         sourcepkg = solvable.lookup_sourcepkg()
1421         sourcepkg = solvable.lookup_sourcepkg()
1422
1423 Return a sourcepkg name associated with solvable.
1424
1425         Dataiterator Dataiterator(Id keyname, const char *match = 0, int flags = 0)
1426         my $di = $solvable->Dataiterator($keyname, $match, $flags);
1427         di = solvable.Dataiterator(keyname, match, flags)
1428         di = solvable.Dataiterator(keyname, match, flags)
1429
1430         for my $d (@$di)
1431         for d in di:
1432         for d in di
1433
1434 Iterate over the matching data elements. See the Dataiterator class for more
1435 information.
1436
1437         void add_deparray(Id keyname, DepId dep, Id marker = -1);
1438         $solvable->add_deparray($keyname, $dep);
1439         solvable.add_deparray(keyname, dep)
1440         solvable.add_deparray(keyname, dep)
1441
1442 Add a new dependency to the attributes stored in keyname.
1443
1444         void unset(Id keyname);
1445         $solvable->unset($keyname);
1446         solvable.unset(keyname)
1447         solvable.unset(keyname)
1448
1449 Delete data stored for the specific keyname.
1450
1451         bool installable();
1452         $solvable->installable()
1453         solvable.installable()
1454         solvable.installable?
1455
1456 Return true if the solvable is installable on the system. Solvables
1457 are not installable if the system does not support their architecture.
1458
1459         bool isinstalled();
1460         $solvable->isinstalled()
1461         solvable.isinstalled()
1462         solvable.isinstalled?
1463
1464 Return true if the solvable is installed on the system.
1465
1466         bool identical(Solvable *other)
1467         $solvable->identical($other)
1468         solvable.identical(other)
1469         solvable.identical?(other)
1470
1471 Return true if the two solvables are identical.
1472
1473         int evrcmp(Solvable *other)
1474         $solvable->evrcmp($other)
1475         solvable.evrcmp(other)
1476         solvable.evrcmp(other)
1477
1478 Returns -1 if the epoch/version/release of the solvable is less than the
1479 one from the other solvable, 1 if it is greater, and 0 if they are equal.
1480 Note that "equal" does not mean that the evr is identical.
1481
1482         int matchesdep(Id keyname, DepId id, Id marker = -1)
1483         $solvable->matchesdep($keyname, $dep)
1484         solvable.matchesdep(keyname, dep)
1485         solvable.matchesdep?(keyname, dep)
1486
1487 Return true if the dependencies stored in keyname match the specified dependency.
1488
1489         Selection Selection(int setflags = 0)
1490         my $sel = $solvable->Selection();
1491         sel = solvable.Selection()
1492         sel = solvable.Selection()
1493
1494 Create a Selection containing just the single solvable.
1495
1496         const char *str()
1497         my $str = $solvable->str();
1498         str = $solvable.str()
1499         str = $solvable.str()
1500
1501 Return a string describing the solvable. The string consists of the name,
1502 version, and architecture of the Solvable.
1503
1504         <stringification>
1505         my $str = $solvable->str;
1506         str = str(solvable)
1507         str = solvable.to_s
1508
1509 Same as calling the str() method.
1510
1511         <equality>
1512         if ($solvable1 == $solvable2)
1513         if solvable1 == solvable2:
1514         if solvable1 == solvable2
1515
1516 Two solvables are equal if they are part of the same pool and have the same
1517 ids.
1518
1519
1520 The Dataiterator Class
1521 ----------------------
1522 Dataiterators can be used to do complex string searches or
1523 to iterate over arrays. They can be created via the
1524 constructors in the Pool, Repo, and Solvable classes. The
1525 Repo and Solvable constructors will limit the search to
1526 the repository or the specific package.
1527
1528 === CONSTANTS ===
1529
1530 *SEARCH_STRING*::
1531 Return a match if the search string matches the value.
1532
1533 *SEARCH_STRINGSTART*::
1534 Return a match if the value starts with the search string.
1535
1536 *SEARCH_STRINGEND*::
1537 Return a match if the value ends with the search string.
1538
1539 *SEARCH_SUBSTRING*::
1540 Return a match if the search string can be matched somewhere in the value.
1541
1542 *SEARCH_GLOB*::
1543 Do a glob match of the search string against the value.
1544
1545 *SEARCH_REGEX*::
1546 Do a regular expression match of the search string against the value.
1547
1548 *SEARCH_NOCASE*::
1549 Ignore case when matching strings. Works for all the above match types.
1550
1551 *SEARCH_FILES*::
1552 Match the complete filenames of the file list, not just the base name.
1553
1554 *SEARCH_COMPLETE_FILELIST*::
1555 When matching the file list, check every file of the package not just the
1556 subset from the primary metadata.
1557
1558 *SEARCH_CHECKSUMS*::
1559 Allow the matching of checksum entries.
1560
1561 === METHODS ===
1562
1563         void prepend_keyname(Id keyname);
1564         $di->prepend_keyname($keyname);
1565         di.prepend_keyname(keyname)
1566         di.prepend_keyname(keyname)
1567
1568 Do a sub-search in the array stored in keyname.
1569
1570         void skip_solvable();
1571         $di->skip_solvable();
1572         di.skip_solvable()
1573         di.skip_solvable()
1574
1575 Stop matching the current solvable and advance to the next
1576 one.
1577
1578         <iteration>
1579         for my $d (@$di)
1580         for d in di:
1581         for d in di
1582
1583 Iterate through the matches. If there is a match, the object
1584 in d will be of type Datamatch.
1585
1586 The Datamatch Class
1587 -------------------
1588 Objects of this type will be created for every value matched
1589 by a dataiterator.
1590
1591 === ATTRIBUTES ===
1592
1593         Pool *pool;                             /* read only */
1594         $d->{pool}
1595         d.pool
1596         d.pool
1597
1598 Back pointer to pool.
1599
1600         Repo *repo;                             /* read only */
1601         $d->{repo}
1602         d.repo
1603         d.repo
1604
1605 The repository containing the matched object.
1606
1607         Solvable *solvable;                     /* read only */
1608         $d->{solvable}
1609         d.solvable
1610         d.solvable
1611
1612 The solvable containing the value that was matched.
1613
1614         Id solvid;                              /* read only */
1615         $d->{solvid}
1616         d.solvid
1617         d.solvid
1618
1619 The id of the solvable that matched.
1620
1621         Id key_id;
1622         $d->{key_id}
1623         d.key_id
1624         d.key_id
1625
1626         const char *key_idstr;
1627         $d->{key_idstr}
1628         d.key_idstr
1629         d.key_idstr
1630
1631 The keyname that matched, either as id or string.
1632
1633         Id type_id;
1634         $d->{type_id}
1635         d.type_id
1636         d.type_id
1637
1638         const char *type_idstr;
1639         $d->{type_idstr};
1640         d.type_idstr
1641         d.type_idstr
1642
1643 The key type of the value that was matched, either as id or string.
1644
1645         Id id;
1646         $d->{id}
1647         d.id
1648         d.id
1649
1650         Id idstr;
1651         $d->{idstr}
1652         d.idstr
1653         d.idstr
1654
1655 The Id of the value that was matched (only valid for id types),
1656 either as id or string.
1657
1658         const char *str;
1659         $d->{str}
1660         d.str
1661         d.str
1662
1663 The string value that was matched (only valid for string types).
1664
1665         unsigned long long num;
1666         $d->{num}
1667         d.num
1668         d.num
1669
1670 The numeric value that was matched (only valid for numeric types).
1671
1672         unsigned int num2;
1673         $d->{num2}
1674         d.num2
1675         d.num2
1676
1677 The secondary numeric value that was matched (only valid for types
1678 containing two values).
1679
1680         unsigned int binary;
1681         $d->{binary}
1682         d.binary
1683         d.binary
1684
1685 The value in binary form, useful for checksums and other data
1686 that cannot be represented as a string.
1687
1688 === METHODS ===
1689
1690         Datapos pos();
1691         my $pos = $d->pos();
1692         pos = d.pos()
1693         pos = d.pos()
1694
1695 The position object of the current match. It can be used to do
1696 sub-searches starting at the match (if it is of an array type).
1697 See the Datapos class for more information.
1698
1699         Datapos parentpos();
1700         my $pos = $d->parentpos();
1701         pos = d.parentpos()
1702         pos = d.parentpos()
1703
1704 The position object of the array containing the current match.
1705 It can be used to do sub-searches, see the Datapos class for more
1706 information.
1707
1708         <stringification>
1709         my $str = $d->str;
1710         str = str(d)
1711         str = d.to_s
1712
1713 Return the stringification of the matched value. Stringification
1714 depends on the search flags, for file list entries it will return
1715 just the base name unless SEARCH_FILES is used, for checksums
1716 it will return an empty string unless SEARCH_CHECKSUMS is used.
1717 Numeric values are currently stringified to an empty string.
1718
1719
1720 The Selection Class
1721 -------------------
1722 Selections are a way to easily deal with sets of packages.
1723 There are multiple constructors to create them, the most useful
1724 is probably the select() method in the Pool class.
1725
1726 === CONSTANTS ===
1727
1728 *SELECTION_NAME*::
1729 Create the selection by matching package names.
1730
1731 *SELECTION_PROVIDES*::
1732 Create the selection by matching package provides.
1733
1734 *SELECTION_FILELIST*::
1735 Create the selection by matching package files.
1736
1737 *SELECTION_CANON*::
1738 Create the selection by matching the canonical representation
1739 of the package. This is normally a combination of the name,
1740 the version, and the architecture of a package.
1741
1742 *SELECTION_DOTARCH*::
1743 Allow an ".<architecture>" suffix when matching names or
1744 provides.
1745
1746 *SELECTION_REL*::
1747 Allow the specification of a relation when matching names
1748 or dependencies, e.g. "name >= 1.2".
1749
1750 *SELECTION_GLOB*::
1751 Allow glob matching for package names, package provides, and file names.
1752
1753 *SELECTION_NOCASE*::
1754 Ignore case when matching package names, package provides, and file names.
1755
1756 *SELECTION_FLAT*::
1757 Return only one selection element describing the selected packages.
1758 The default is to create multiple elements for all globbed packages.
1759 Multiple elements are useful if you want to turn the selection into
1760 an install job, in that case you want an install job for every
1761 globbed package.
1762
1763 *SELECTION_SKIP_KIND*::
1764 Remove a "packagekind:" prefix from the package names.
1765
1766 *SELECTION_MATCH_DEPSTR*::
1767 When matching dependencies, do a string match on the result of dep2str
1768 instead of using the normal dependency intersect algorithm.
1769
1770 *SELECTION_INSTALLED_ONLY*::
1771 Limit the package search to installed packages.
1772
1773 *SELECTION_SOURCE_ONLY*::
1774 Limit the package search to source packages only.
1775
1776 *SELECTION_WITH_SOURCE*::
1777 Extend the package search to also match source packages. The default is
1778 only to match binary packages.
1779
1780 *SELECTION_WITH_DISABLED*::
1781 Extend the package search to also include disabled packages.
1782
1783 *SELECTION_WITH_BADARCH*::
1784 Extend the package search to also include packages that are not installable
1785 on the configured architecture.
1786
1787 *SELECTION_WITH_ALL*::
1788 Shortcut for selecting the three modifiers above.
1789
1790 *SELECTION_ADD*::
1791 Add the result of the match to the current selection instead of replacing it.
1792
1793 *SELECTION_SUBTRACT*::
1794 Remove the result of the match to the current selection instead of replacing it.
1795
1796 *SELECTION_FILTER*::
1797 Intersect the result of the match to the current selection instead of replacing it.
1798
1799 === ATTRIBUTES ===
1800
1801         Pool *pool;                             /* read only */
1802         $d->{pool}
1803         d.pool
1804         d.pool
1805
1806 Back pointer to pool.
1807
1808         int flags;                              /* read only */
1809         $sel->{flags}
1810         flags = sel.flags
1811         flags = sel.flags
1812
1813 The result flags of the selection. The flags are a subset
1814 of the ones used when creating the selection, they describe which
1815 method was used to get the result. For example, if you create the
1816 selection with ``SELECTION_NAME | SELECTION_PROVIDES'', the resulting
1817 flags will either be SELECTION_NAME or SELECTION_PROVIDES depending
1818 if there was a package that matched the name or not. If there was
1819 no match at all, the flags will be zero.
1820
1821 === METHODS ===
1822
1823         bool isempty()
1824         $sel->isempty()
1825         sel.isempty()
1826         sel.isempty?
1827
1828 Return true if the selection is empty, i.e. no package could be matched.
1829
1830         Selection clone(int flags = 0)
1831         my $cloned = $sel->clone();
1832         cloned = sel.clone()
1833         cloned = sel.clone()
1834
1835 Return a copy of a selection.
1836
1837         void filter(Selection *other)
1838         $sel->filter($other);
1839         sel.filter(other)
1840         sel.filter(other)
1841
1842 Intersect two selections. Packages will only stay in the selection if there
1843 are also included in the other selecting. Does an in-place modification.
1844
1845         void add(Selection *other)
1846         $sel->add($other);
1847         sel.add(other)
1848         sel.add(other)
1849
1850 Build the union of two selections. All packages of the other selection will
1851 be added to the set of packages of the selection object. Does an in-place
1852 modification. Note that the selection flags are no longer meaningful after the
1853 add operation.
1854
1855         void subtract(Selection *other)
1856         $sel->subtract($other);
1857         sel.subtract(other)
1858         sel.subtract(other)
1859
1860 Remove the packages of the other selection from the packages of the selection
1861 object. Does an in-place modification.
1862
1863         void add_raw(Id how, Id what)
1864         $sel->add_raw($how, $what);
1865         sel.add_raw(how, what)
1866         sel.add_raw(how, what)
1867
1868 Add a raw element to the selection. Check the Job class for information about
1869 the how and what parameters. Note that the selection flags are no longer meaningful
1870 after the add_raw operation.
1871
1872         Job *jobs(int action)
1873         my @jobs = $sel->jobs($action);
1874         jobs = sel.jobs(action)
1875         jobs = sel.jobs(action)
1876
1877 Convert a selection into an array of Job objects. The action parameter is or-ed
1878 to the ``how'' part of the job, it describes the type of job (e.g. install,
1879 erase). See the Job class for the action and action modifier constants.
1880
1881         Solvable *solvables()
1882         my @solvables = $sel->solvables();
1883         solvables = sel.solvables()
1884         solvables = sel.solvables()
1885
1886 Convert a selection into an array of Solvable objects.
1887
1888         void select(const char *name, int flags)
1889         $sel->select($name, $flags);
1890         sel.select(name, flags)
1891         sel.select(name, flags)
1892
1893 Do a select operation and combine the result with the current selection. You
1894 can choose the desired combination method by using either the SELECTION_ADD,
1895 SELECTION_SUBTRACT, or SELECTION_FILTER flag. If none of the flags are
1896 used, SELECTION_FILTER|SELECTION_WITH_ALL is assumed.
1897
1898         void matchdeps(const char *name, int flags, Id keyname, Id marker = -1)
1899         $sel->matchdeps($name, $flags, $keyname);
1900         sel.matchdeps(name, flags, keyname)
1901         sel.matchdeps(name, flags, keyname)
1902
1903 Do a matchdeps operation and combine the result with the current selection.
1904
1905         void matchdepid(DepId dep, int flags, Id keyname, Id marker = -1)
1906         $sel->matchdepid($dep, $flags, $keyname);
1907         sel.matchdepid(dep, flags, keyname)
1908         sel.matchdepid(dep, flags, keyname)
1909
1910 Do a matchdepid operation and combine the result with the current selection.
1911
1912         void matchsolvable(Solvable solvable, int flags, Id keyname, Id marker = -1)
1913         $sel->matchsolvable($solvable, $flags, $keyname);
1914         sel.matchsolvable(solvable, flags, keyname)
1915         sel.matchsolvable(solvable, flags, keyname)
1916
1917 Do a matchsolvable operation and combine the result with the current selection.
1918
1919         <stringification>
1920         my $str = $sel->str;
1921         str = str(sel)
1922         str = sel.to_s
1923
1924 Return a string describing the selection.
1925
1926 The Job Class
1927 -------------
1928 Jobs are the way to specify to the dependency solver what to do.
1929 Most of the times jobs will get created by calling the jobs() method
1930 on a Selection object, but there is also a Job() constructor in the
1931 Pool class.
1932
1933 === CONSTANTS ===
1934
1935 Selection constants:
1936
1937 *SOLVER_SOLVABLE*::
1938 The ``what'' part is the id of a solvable.
1939
1940 *SOLVER_SOLVABLE_NAME*::
1941 The ``what'' part is the id of a package name.
1942
1943 *SOLVER_SOLVABLE_PROVIDES*::
1944 The ``what'' part is the id of a package provides.
1945
1946 *SOLVER_SOLVABLE_ONE_OF*::
1947 The ``what'' part is an offset into the ``whatprovides'' data, created
1948 by calling the towhatprovides() pool method.
1949
1950 *SOLVER_SOLVABLE_REPO*::
1951 The ``what'' part is the id of a repository.
1952
1953 *SOLVER_SOLVABLE_ALL*::
1954 The ``what'' part is ignored, all packages are selected.
1955
1956 *SOLVER_SOLVABLE_SELECTMASK*::
1957 A mask containing all the above selection bits.
1958
1959 Action constants:
1960
1961 *SOLVER_NOOP*::
1962 Do nothing.
1963
1964 *SOLVER_INSTALL*::
1965 Install a package of the specified set of packages. It tries to install
1966 the best matching package (i.e. the highest version of the packages from
1967 the repositories with the highest priority).
1968
1969 *SOLVER_ERASE*::
1970 Erase all of the packages from the specified set. If a package is not
1971 installed, erasing it will keep it from getting installed.
1972
1973 *SOLVER_UPDATE*::
1974 Update the matching installed packages to their best version. If none
1975 of the specified packages are installed, try to update the installed
1976 packages to the specified versions. See the section about targeted
1977 updates about more information.
1978
1979 *SOLVER_WEAKENDEPS*::
1980 Allow to break the dependencies of the matching packages. Handle with care.
1981
1982 *SOLVER_MULTIVERSION*::
1983 Mark the matched packages for multiversion install. If they get to be
1984 installed because of some other job, the installation will keep the old
1985 version of the package installed (for rpm this is done by using ``-i''
1986 instead of ``-U'').
1987
1988 *SOLVER_LOCK*::
1989 Do not change the state of the matched packages, i.e. when they are
1990 installed they stay installed, if not they are not selected for
1991 installation.
1992
1993 *SOLVER_DISTUPGRADE*::
1994 Update the matching installed packages to the best version included in one
1995 of the repositories. After this operation, all come from one of the available
1996 repositories except orphaned packages. Orphaned packages are packages that
1997 have no relation to the packages in the repositories, i.e. no package in the
1998 repositories have the same name or obsolete the orphaned package.
1999 This action brings the installed packages in sync with the ones in the
2000 repository. By default it also turns of arch/vendor/version locking for the
2001 affected packages to simulate a fresh installation. This means that distupgrade can
2002 actually downgrade packages if only lower versions of a package are available
2003 in the repositories. You can tweak this behavior with the SOLVER_FLAG_DUP_
2004 solver flags.
2005
2006 *SOLVER_DROP_ORPHANED*::
2007 Erase all the matching installed packages if they are orphaned. This only makes
2008 sense if there is a ``distupgrade all packages'' job. The default is to erase
2009 orphaned packages only if they block the installation of other packages.
2010
2011 *SOLVER_VERIFY*::
2012 Fix dependency problems of matching installed packages. The default is to ignore
2013 dependency problems for installed packages.
2014
2015 *SOLVER_USERINSTALLED*::
2016 The matching installed packages are considered to be installed by a user,
2017 thus not installed to fulfill some dependency. This is needed input for
2018 the calculation of unneeded packages for jobs that have the
2019 SOLVER_CLEANDEPS flag set.
2020
2021 *SOLVER_ALLOWUNINSTALL*::
2022 Allow the solver to deinstall the matching installed packages if they get
2023 into the way of resolving a dependency. This is like the
2024 SOLVER_FLAG_ALLOW_UNINSTALL flag, but limited to a specific set of packages.
2025
2026 *SOLVER_FAVOR*::
2027 Prefer the specified packages if the solver encounters an alternative. If
2028 a job contains multiple matching favor/disfavor elements, the last one takes
2029 precedence.
2030
2031 *SOLVER_DISFAVOR*::
2032 Avoid the specified packages if the solver encounters an alternative. This
2033 can also be used to block recommended or supplemented packages from being
2034 installed.
2035
2036 *SOLVER_JOBMASK*::
2037 A mask containing all the above action bits.
2038
2039 Action modifier constants:
2040
2041 *SOLVER_WEAK*::
2042 Makes the job a weak job. The solver tries to fulfill weak jobs, but does
2043 not report a problem if it is not possible to do so.
2044
2045 *SOLVER_ESSENTIAL*::
2046 Makes the job an essential job. If there is a problem with the job, the
2047 solver will not propose to remove the job as one solution (unless all
2048 other solutions are also to remove essential jobs).
2049
2050 *SOLVER_CLEANDEPS*::
2051 The solver will try to also erase all packages dragged in through
2052 dependencies when erasing the package. This needs SOLVER_USERINSTALLED
2053 jobs to maximize user satisfaction.
2054
2055 *SOLVER_FORCEBEST*::
2056 Insist on the best package for install, update, and distupgrade jobs. If
2057 this flag is not used, the solver will use the second-best package if the
2058 best package cannot be installed for some reason. When this flag is used,
2059 the solver will generate a problem instead.
2060
2061 *SOLVER_TARGETED*::
2062 Forces targeted operation update and distupgrade jobs. See the section
2063 about targeted updates about more information.
2064
2065 Set constants.
2066
2067 *SOLVER_SETEV*::
2068 The job specified the exact epoch and version of the package set.
2069
2070 *SOLVER_SETEVR*::
2071 The job specified the exact epoch, version, and release of the package set.
2072
2073 *SOLVER_SETARCH*::
2074 The job specified the exact architecture of the packages from the set.
2075
2076 *SOLVER_SETVENDOR*::
2077 The job specified the exact vendor of the packages from the set.
2078
2079 *SOLVER_SETREPO*::
2080 The job specified the exact repository of the packages from the set.
2081
2082 *SOLVER_SETNAME*::
2083 The job specified the exact name of the packages from the set.
2084
2085 *SOLVER_NOAUTOSET*::
2086 Turn of automatic set flag generation for SOLVER_SOLVABLE jobs.
2087
2088 *SOLVER_SETMASK*::
2089 A mask containing all the above set bits.
2090
2091 See the section about set bits for more information.
2092
2093 === ATTRIBUTES ===
2094
2095         Pool *pool;                             /* read only */
2096         $job->{pool}
2097         d.pool
2098         d.pool
2099
2100 Back pointer to pool.
2101
2102         Id how;                                 /* read/write */
2103         $job->{how}
2104         d.how
2105         d.how
2106
2107 Union of the selection, action, action modifier, and set flags.
2108 The selection part describes the semantics of the ``what'' Id.
2109
2110         Id what;                                /* read/write */
2111         $job->{what}
2112         d.what
2113         d.what
2114
2115 Id describing the set of packages, the meaning depends on the
2116 selection part of the ``how'' attribute.
2117
2118 === METHODS ===
2119
2120         Solvable *solvables()
2121         my @solvables = $job->solvables();
2122         solvables = job.solvables()
2123         solvables = job.solvables()
2124
2125 Return the set of solvables of the job as an array of Solvable
2126 objects.
2127
2128         bool isemptyupdate();
2129         $job->isemptyupdate()
2130         job.isemptyupdate()
2131         job.isemptyupdate?
2132
2133 Convenience function to find out if the job describes an update
2134 job with no matching packages, i.e. a job that does nothing.
2135 Some package managers like ``zypper'' like to turn those jobs
2136 into install jobs, i.e. an update of a not-installed package
2137 will result into the installation of the package.
2138
2139         <stringification>
2140         my $str = $job->str;
2141         str = str(job)
2142         str = job.to_s
2143
2144 Return a string describing the job.
2145
2146         <equality>
2147         if ($job1 == $job2)
2148         if job1 == job2:
2149         if job1 == job2
2150
2151 Two jobs are equal if they belong to the same pool and both the
2152 ``how'' and the ``what'' attributes are the same.
2153
2154 === TARGETED UPDATES ===
2155 Libsolv has two modes for upgrades and distupgrade: targeted and
2156 untargeted. Untargeted mode means that the installed packages from
2157 the specified set will be updated to the best version. Targeted means
2158 that packages that can be updated to a package in the specified set
2159 will be updated to the best package of the set.
2160
2161 Here's an example to explain the subtle difference. Suppose that
2162 you have package A installed in version "1.1", "A-1.2" is available
2163 in one of the repositories and there is also package "B" that
2164 obsoletes package A.
2165
2166 An untargeted update of "A" will update the installed "A-1.1" to
2167 package "B", because that is the newest version (B obsoletes A and
2168 is thus newer).
2169
2170 A targeted update of "A" will update "A-1.1" to "A-1.2", as the
2171 set of packages contains both "A-1.1" and "A-1.2", and "A-1.2" is
2172 the newer one.
2173
2174 An untargeted update of "B" will do nothing, as "B" is not installed.
2175
2176 An targeted update of "B" will update "A-1.1" to "B".
2177
2178 Note that the default is to do "auto-targeting", thus if the specified
2179 set of packages does not include an installed package, the solver
2180 will assume targeted operation even if SOLVER_TARGETED is not used.
2181
2182 This mostly matches the intent of the user, with one exception: In
2183 the example above, an update of "A-1.2" will update "A-1.1" to
2184 "A-1.2" (targeted mode), but a second update of "A-1.2" will suddenly
2185 update to "B", as untargeted mode is chosen because "A-1.2" is now
2186 installed.
2187
2188 If you want to have full control over when targeting mode is chosen,
2189 turn off auto-targeting with the SOLVER_FLAG_NO_AUTOTARGET solver option.
2190 In that case, all updates are considered to be untargeted unless they
2191 include the SOLVER_TARGETED flag.
2192
2193 === SET BITS ===
2194 Set bits specify which parts of the specified packages where specified
2195 by the user. It is used by the solver when checking if an operation is
2196 allowed or not. For example, the solver will normally not allow the
2197 downgrade of an installed package. But it will not report a problem if
2198 the SOLVER_SETEVR flag is used, as it then assumes that the user specified
2199 the exact version and thus knows what he is doing.
2200
2201 So if a package "screen-1-1" is installed for the x86_64 architecture and
2202 version "2-1" is only available for the i586 architecture, installing
2203 package "screen-2.1" will ask the user for confirmation because of the
2204 different architecture. When using the Selection class to create jobs
2205 the set bits are automatically added, e.g. selecting ``screen.i586'' will
2206 automatically add SOLVER_SETARCH, and thus no problem will be reported.
2207
2208 The Solver Class
2209 ----------------
2210 Dependency solving is what this library is about. A solver object is needed
2211 for solving to store the result of the solver run. The solver object can be
2212 used multiple times for different jobs, reusing it allows the solver to
2213 re-use the dependency rules it already computed.
2214
2215 === CONSTANTS ===
2216
2217 Flags to modify some of the solver's behavior:
2218
2219 *SOLVER_FLAG_ALLOW_DOWNGRADE*::
2220 Allow the solver to downgrade packages without asking for confirmation
2221 (i.e. reporting a problem).
2222
2223 *SOLVER_FLAG_ALLOW_ARCHCHANGE*::
2224 Allow the solver to change the architecture of an installed package
2225 without asking for confirmation. Note that changes to/from noarch
2226 are always considered to be allowed.
2227
2228 *SOLVER_FLAG_ALLOW_VENDORCHANGE*::
2229 Allow the solver to change the vendor of an installed package
2230 without asking for confirmation. Each vendor is part of one or more
2231 vendor equivalence classes, normally installed packages may only
2232 change their vendor if the new vendor shares at least one equivalence
2233 class.
2234
2235 *SOLVER_FLAG_ALLOW_NAMECHANGE*::
2236 Allow the solver to change the name of an installed package, i.e.
2237 install a package with a different name that obsoletes the installed
2238 package. This option is on by default.
2239
2240 *SOLVER_FLAG_ALLOW_UNINSTALL*::
2241 Allow the solver to erase installed packages to fulfill the jobs.
2242 This flag also includes the above flags. You may want to set this
2243 flag if you only have SOLVER_ERASE jobs, as in that case it's
2244 better for the user to check the transaction overview instead of
2245 approving every single package that needs to be erased.
2246
2247 *SOLVER_FLAG_DUP_ALLOW_DOWNGRADE*::
2248 Like SOLVER_FLAG_ALLOW_DOWNGRADE, but used in distupgrade mode.
2249
2250 *SOLVER_FLAG_DUP_ALLOW_ARCHCHANGE*::
2251 Like SOLVER_FLAG_ALLOW_ARCHCHANGE, but used in distupgrade mode.
2252
2253 *SOLVER_FLAG_DUP_ALLOW_VENDORCHANGE*::
2254 Like SOLVER_FLAG_ALLOW_VENDORCHANGE, but used in distupgrade mode.
2255
2256 *SOLVER_FLAG_DUP_ALLOW_NAMECHANGE*::
2257 Like SOLVER_FLAG_ALLOW_NAMECHANGE, but used in distupgrade mode.
2258
2259 *SOLVER_FLAG_NO_UPDATEPROVIDE*::
2260 If multiple packages obsolete an installed package, the solver checks
2261 the provides of every such package and ignores all packages that
2262 do not provide the installed package name. Thus, you can have an
2263 official update candidate that provides the old name, and other
2264 packages that also obsolete the package but are not considered for
2265 updating. If you cannot use this feature, you can turn it off
2266 by setting this flag.
2267
2268 *SOLVER_FLAG_NEED_UPDATEPROVIDE*::
2269 This is somewhat the opposite of SOLVER_FLAG_NO_UPDATEPROVIDE: Only
2270 packages that provide the installed package names are considered
2271 for updating.
2272
2273 *SOLVER_FLAG_SPLITPROVIDES*::
2274 Make the solver aware of special provides of the form
2275 ``<packagename>:<path>'' used in SUSE systems to support package
2276 splits.
2277
2278 *SOLVER_FLAG_IGNORE_RECOMMENDED*::
2279 Do not process optional (aka weak) dependencies.
2280
2281 *SOLVER_FLAG_ADD_ALREADY_RECOMMENDED*::
2282 Install recommended or supplemented packages even if they have no
2283 connection to the current transaction. You can use this feature
2284 to implement a simple way for the user to install new recommended
2285 packages that were not available in the past.
2286
2287 *SOLVER_FLAG_NO_INFARCHCHECK*::
2288 Turn off the inferior architecture checking that is normally done
2289 by the solver. Normally, the solver allows only the installation
2290 of packages from the "best" architecture if a package is available
2291 for multiple architectures.
2292
2293 *SOLVER_FLAG_BEST_OBEY_POLICY*::
2294 Make the SOLVER_FORCEBEST job option consider only packages that
2295 meet the policies for installed packages, i.e. no downgrades,
2296 no architecture change, no vendor change (see the first flags
2297 of this section). If the flag is not specified, the solver will
2298 enforce the installation of the best package ignoring the
2299 installed packages, which may conflict with the set policy.
2300
2301 *SOLVER_FLAG_NO_AUTOTARGET*::
2302 Do not enable auto-targeting up update and distupgrade jobs. See
2303 the section on targeted updates for more information.
2304
2305 *SOLVER_FLAG_KEEP_ORPHANS*::
2306 Do not allow orphaned packages to be deinstalled if they get
2307 in the way of resolving other packages.
2308
2309 *SOLVER_FLAG_BREAK_ORPHANS*::
2310 Ignore dependencies of orphaned packages that get in the way
2311 of resolving non-orphaned ones. Setting the flag might result
2312 in no longer working packages in case they are orphaned.
2313
2314 *SOLVER_FLAG_FOCUS_INSTALLED*::
2315 Resolve installed packages before resolving the given jobs.
2316 Setting this flag means that the solver will prefer picking
2317 a package version that fits the other installed packages
2318 over updating installed packages.
2319
2320 *SOLVER_FLAG_FOCUS_BEST*::
2321 First resolve the given jobs, then the dependencies of the
2322 resulting packages, then resolve all already installed
2323 packages. This will result in more packages being updated
2324 as when the flag is not used.
2325
2326 *SOLVER_FLAG_INSTALL_ALSO_UPDATES*::
2327 Update the package if a job is already fulfilled by an installed
2328 package.
2329
2330 *SOLVER_FLAG_YUM_OBSOLETES*::
2331 Turn on yum-like package split handling. See the yum documentation
2332 for more details.
2333
2334 *SOLVER_FLAG_URPM_REORDER*::
2335 Turn on urpm like package reordering for kernel packages. See
2336 the urpm documentation for more details.
2337
2338
2339
2340 Basic rule types:
2341
2342 *SOLVER_RULE_UNKNOWN*::
2343 A rule of an unknown class. You should never encounter those.
2344
2345 *SOLVER_RULE_PKG*::
2346 A package dependency rule.
2347
2348 *SOLVER_RULE_UPDATE*::
2349 A rule to implement the update policy of installed packages. Every
2350 installed package has an update rule that consists of the packages
2351 that may replace the installed package.
2352
2353 *SOLVER_RULE_FEATURE*::
2354 Feature rules are fallback rules used when an update rule is disabled. They
2355 include all packages that may replace the installed package ignoring the
2356 update policy, i.e. they contain downgrades, arch changes and so on.
2357 Without them, the solver would simply erase installed packages if their
2358 update rule gets disabled.
2359
2360 *SOLVER_RULE_JOB*::
2361 Job rules implement the job given to the solver.
2362
2363 *SOLVER_RULE_DISTUPGRADE*::
2364 These are simple negative assertions that make sure that only packages
2365 are kept that are also available in one of the repositories.
2366
2367 *SOLVER_RULE_INFARCH*::
2368 Infarch rules are also negative assertions, they disallow the installation
2369 of packages when there are packages of the same name but with a better
2370 architecture.
2371
2372 *SOLVER_RULE_CHOICE*::
2373 Choice rules are used to make sure that the solver prefers updating to
2374 installing different packages when some dependency is provided by
2375 multiple packages with different names. The solver may always break
2376 choice rules, so you will not see them when a problem is found.
2377
2378 *SOLVER_RULE_LEARNT*::
2379 These rules are generated by the solver to keep it from running into
2380 the same problem multiple times when it has to backtrack. They are
2381 the main reason why a sat solver is faster than other dependency solver
2382 implementations.
2383
2384 Special dependency rule types:
2385
2386 *SOLVER_RULE_PKG_NOT_INSTALLABLE*::
2387 This rule was added to prevent the installation of a package of an
2388 architecture that does not work on the system.
2389
2390 *SOLVER_RULE_PKG_NOTHING_PROVIDES_DEP*::
2391 The package contains a required dependency which was not provided by
2392 any package.
2393
2394 *SOLVER_RULE_PKG_REQUIRES*::
2395 Similar to SOLVER_RULE_PKG_NOTHING_PROVIDES_DEP, but in this case
2396 some packages provided the dependency but none of them could be
2397 installed due to other dependency issues.
2398
2399 *SOLVER_RULE_PKG_SELF_CONFLICT*::
2400 The package conflicts with itself. This is not allowed by older rpm
2401 versions.
2402
2403 *SOLVER_RULE_PKG_CONFLICTS*::
2404 To fulfill the dependencies two packages need to be installed, but
2405 one of the packages contains a conflict with the other one.
2406
2407 *SOLVER_RULE_PKG_SAME_NAME*::
2408 The dependencies can only be fulfilled by multiple versions of
2409 a package, but installing multiple versions of the same package
2410 is not allowed.
2411
2412 *SOLVER_RULE_PKG_OBSOLETES*::
2413 To fulfill the dependencies two packages need to be installed, but
2414 one of the packages obsoletes the other one.
2415
2416 *SOLVER_RULE_PKG_IMPLICIT_OBSOLETES*::
2417 To fulfill the dependencies two packages need to be installed, but
2418 one of the packages has provides a dependency that is obsoleted
2419 by the other one. See the POOL_FLAG_IMPLICITOBSOLETEUSESPROVIDES
2420 flag.
2421
2422 *SOLVER_RULE_PKG_INSTALLED_OBSOLETES*::
2423 To fulfill the dependencies a package needs to be installed that is
2424 obsoleted by an installed package. See the POOL_FLAG_NOINSTALLEDOBSOLETES
2425 flag.
2426
2427 *SOLVER_RULE_JOB_NOTHING_PROVIDES_DEP*::
2428 The user asked for installation of a package providing a specific
2429 dependency, but no available package provides it.
2430
2431 *SOLVER_RULE_JOB_UNKNOWN_PACKAGE*::
2432 The user asked for installation of a package with a specific name,
2433 but no available package has that name.
2434
2435 *SOLVER_RULE_JOB_PROVIDED_BY_SYSTEM*::
2436 The user asked for the erasure of a dependency that is provided by the
2437 system (i.e. for special hardware or language dependencies), this
2438 cannot be done with a job.
2439
2440 *SOLVER_RULE_JOB_UNSUPPORTED*::
2441 The user asked for something that is not yet implemented, e.g. the
2442 installation of all packages at once.
2443
2444 Policy error constants
2445
2446 *POLICY_ILLEGAL_DOWNGRADE*::
2447 The solver ask for permission before downgrading packages.
2448
2449 *POLICY_ILLEGAL_ARCHCHANGE*::
2450 The solver ask for permission before changing the architecture of installed
2451 packages.
2452
2453 *POLICY_ILLEGAL_VENDORCHANGE*::
2454 The solver ask for permission before changing the vendor of installed
2455 packages.
2456
2457 *POLICY_ILLEGAL_NAMECHANGE*::
2458 The solver ask for permission before replacing an installed packages with
2459 a package that has a different name.
2460
2461 Solution element type constants
2462
2463 *SOLVER_SOLUTION_JOB*::
2464 The problem can be solved by removing the specified job.
2465
2466 *SOLVER_SOLUTION_POOLJOB*::
2467 The problem can be solved by removing the specified job that is defined
2468 in the pool.
2469
2470 *SOLVER_SOLUTION_INFARCH*::
2471 The problem can be solved by allowing the installation of the specified
2472 package with an inferior architecture.
2473
2474 *SOLVER_SOLUTION_DISTUPGRADE*::
2475 The problem can be solved by allowing to keep the specified package
2476 installed.
2477
2478 *SOLVER_SOLUTION_BEST*::
2479 The problem can be solved by allowing to install the specified package
2480 that is not the best available package.
2481
2482 *SOLVER_SOLUTION_ERASE*::
2483 The problem can be solved by allowing to erase the specified package.
2484
2485 *SOLVER_SOLUTION_REPLACE*::
2486 The problem can be solved by allowing to replace the package with some
2487 other package.
2488
2489 *SOLVER_SOLUTION_REPLACE_DOWNGRADE*::
2490 The problem can be solved by allowing to replace the package with some
2491 other package that has a lower version.
2492
2493 *SOLVER_SOLUTION_REPLACE_ARCHCHANGE*::
2494 The problem can be solved by allowing to replace the package with some
2495 other package that has a different architecture.
2496
2497 *SOLVER_SOLUTION_REPLACE_VENDORCHANGE*::
2498 The problem can be solved by allowing to replace the package with some
2499 other package that has a different vendor.
2500
2501 *SOLVER_SOLUTION_REPLACE_NAMECHANGE*::
2502 The problem can be solved by allowing to replace the package with some
2503 other package that has a different name.
2504
2505
2506 Reason constants
2507
2508 *SOLVER_REASON_UNRELATED*::
2509 The package status did not change as it was not related to any job.
2510
2511 *SOLVER_REASON_UNIT_RULE*::
2512 The package was installed/erased/kept because of a unit rule, i.e. a rule
2513 where all literals but one were false.
2514
2515 *SOLVER_REASON_KEEP_INSTALLED*::
2516 The package was chosen when trying to keep as many packages installed as
2517 possible.
2518
2519 *SOLVER_REASON_RESOLVE_JOB*::
2520 The decision happened to fulfill a job rule.
2521
2522 *SOLVER_REASON_UPDATE_INSTALLED*::
2523 The decision happened to fulfill a package update request.
2524
2525 *SOLVER_REASON_CLEANDEPS_ERASE*::
2526 The package was erased when cleaning up dependencies from other erased
2527 packages.
2528
2529 *SOLVER_REASON_RESOLVE*::
2530 The package was installed to fulfill package dependencies.
2531
2532 *SOLVER_REASON_WEAKDEP*::
2533 The package was installed because of a weak dependency (Recommends or
2534 Supplements).
2535
2536 *SOLVER_REASON_RESOLVE_ORPHAN*::
2537 The decision about the package was made when deciding the fate of orphaned
2538 packages.
2539
2540 *SOLVER_REASON_RECOMMENDED*::
2541 This is a special case of SOLVER_REASON_WEAKDEP.
2542
2543 *SOLVER_REASON_SUPPLEMENTED*::
2544 This is a special case of SOLVER_REASON_WEAKDEP.
2545
2546
2547 === ATTRIBUTES ===
2548
2549         Pool *pool;                             /* read only */
2550         $job->{pool}
2551         d.pool
2552         d.pool
2553
2554 Back pointer to pool.
2555
2556 === METHODS ===
2557
2558         int set_flag(int flag, int value)
2559         my $oldvalue = $solver->set_flag($flag, $value);
2560         oldvalue = solver.set_flag(flag, value)
2561         oldvalue = solver.set_flag(flag, value)
2562
2563         int get_flag(int flag)
2564         my $value = $solver->get_flag($flag);
2565         value = solver.get_flag(flag)
2566         value = solver.get_flag(flag)
2567
2568 Set/get a solver specific flag. The flags define the policies the solver has
2569 to obey. The flags are explained in the CONSTANTS section of this class.
2570
2571         Problem *solve(Job *jobs)
2572         my @problems = $solver->solve(\@jobs);
2573         problems = solver.solve(jobs)
2574         problems = solver.solve(jobs)
2575
2576 Solve a problem specified in the job list (plus the jobs defined in the pool).
2577 Returns an array of problems that need user interaction, or an empty array
2578 if no problems were encountered. See the Problem class on how to deal with
2579 problems.
2580
2581         Transaction transaction()
2582         my $trans = $solver->transaction();
2583         trans = solver.transaction()
2584         trans = solver.transaction()
2585
2586 Return the transaction to implement the calculated package changes. A transaction
2587 is available even if problems were found, this is useful for interactive user
2588 interfaces that show both the job result and the problems.
2589
2590         int reason = describe_decision(Solvable *s, Rule *OUTPUT)
2591         my ($reason, $rule) = $solver->describe_decision($solvable);
2592         (reason, rule) = solver.describe_decision(solvable)
2593         (reason, rule) = solver.describe_decision(solvable)
2594
2595 Return the reason why a specific solvable was installed or erased. For most of
2596 the reasons the rule that triggered the decision is also returned.
2597
2598         Solvable *get_recommended(bool noselected=0);
2599         my @solvables = $solver->get_recommended();
2600         solvables = solver.get_recommended()
2601         solvables = solver.get_recommended()
2602
2603 Return all solvables that are recommended by the solver run result. This includes
2604 solvables included in the result, set noselected if you want to filter those.
2605
2606         Solvable *get_suggested(bool noselected=0);
2607         my @solvables = $solver->get_suggested();
2608         solvables = solver.get_suggested()
2609         solvables = solver.get_suggested()
2610
2611 Return all solvables that are suggested by the solver run result. This includes
2612 solvables included in the result, set noselected if you want to filter those.
2613
2614
2615 The Problem Class
2616 -----------------
2617 Problems are the way of the solver to interact with the user. You can simply list
2618 all problems and terminate your program, but a better way is to present solutions to
2619 the user and let him pick the ones he likes.
2620
2621 === ATTRIBUTES ===
2622
2623         Solver *solv;                           /* read only */
2624         $problem->{solv}
2625         problem.solv
2626         problem.solv
2627
2628 Back pointer to solver object.
2629
2630         Id id;                                  /* read only */
2631         $problem->{id}
2632         problem.id
2633         problem.id
2634
2635 Id of the problem. The first problem has Id 1, they are numbered consecutively.
2636
2637 === METHODS ===
2638
2639         Rule findproblemrule()
2640         my $probrule = $problem->findproblemrule();
2641         probrule = problem.findproblemrule()
2642         probrule = problem.findproblemrule()
2643
2644 Return the rule that caused the problem. Of course in most situations there is no
2645 single responsible rule, but many rules that interconnect with each created the
2646 problem. Nevertheless, the solver uses some heuristic approach to find a rule
2647 that somewhat describes the problem best to the user.
2648
2649         Rule *findallproblemrules(bool unfiltered = 0)
2650         my @probrules = $problem->findallproblemrules();
2651         probrules = problem.findallproblemrules()
2652         probrules = problem.findallproblemrules()
2653
2654 Return all rules responsible for the problem. The returned set of rules contains
2655 all the needed information why there was a problem, but it's hard to present
2656 them to the user in a sensible way. The default is to filter out all update and
2657 job rules (unless the returned rules only consist of those types).
2658
2659         Solution *solutions()
2660         my @solutions = $problem->solutions();
2661         solutions = problem.solutions()
2662         solutions = problem.solutions()
2663
2664 Return an array containing multiple possible solutions to fix the problem. See
2665 the solution class for more information.
2666
2667         int solution_count()
2668         my $cnt = $problem->solution_count();
2669         cnt = problem.solution_count()
2670         cnt = problem.solution_count()
2671
2672 Return the number of solutions without creating solution objects.
2673
2674         <stringification>
2675         my $str = $problem->str;
2676         str = str(problem)
2677         str = problem.to_s
2678
2679 Return a string describing the problem. This is a convenience function, it is
2680 a shorthand for calling findproblemrule(), then ruleinfo() on the problem
2681 rule and problemstr() on the ruleinfo object.
2682
2683 The Rule Class
2684 --------------
2685 Rules are the basic block of sat solving. Each package dependency gets translated
2686 into one or multiple rules.
2687
2688 === ATTRIBUTES ===
2689
2690         Solver *solv;                           /* read only */
2691         $rule->{solv}
2692         rule.solv
2693         rule.solv
2694
2695 Back pointer to solver object.
2696
2697         Id id;                                  /* read only */
2698         $rule->{id}
2699         rule.id
2700         rule.id
2701
2702 The id of the rule.
2703
2704         int type;                               /* read only */
2705         $rule->{type}
2706         rule.type
2707         rule.type
2708
2709 The basic type of the rule. See the constant section of the solver class for the type list.
2710
2711 === METHODS ===
2712
2713         Ruleinfo info()
2714         my $ruleinfo = $rule->info();
2715         ruleinfo = rule.info()
2716         ruleinfo = rule.info()
2717
2718 Return a Ruleinfo object that contains information about why the rule was created. But
2719 see the allinfos() method below.
2720
2721         Ruleinfo *allinfos()
2722         my @ruleinfos = $rule->allinfos();
2723         ruleinfos = rule.allinfos()
2724         ruleinfos = rule.allinfos()
2725
2726 As the same dependency rule can get created because of multiple dependencies, one
2727 Ruleinfo is not enough to describe the reason. Thus the allinfos() method returns
2728 an array of all infos about a rule.
2729
2730         <equality>
2731         if ($rule1 == $rule2)
2732         if rule1 == rule2:
2733         if rule1 == rule2
2734
2735 Two rules are equal if they belong to the same solver and have the same id.
2736
2737 The Ruleinfo Class
2738 ------------------
2739 A Ruleinfo describes one reason why a rule was created.
2740
2741 === ATTRIBUTES ===
2742
2743         Solver *solv;                           /* read only */
2744         $ruleinfo->{solv}
2745         ruleinfo.solv
2746         ruleinfo.solv
2747
2748 Back pointer to solver object.
2749
2750         int type;                               /* read only */
2751         $ruleinfo->{type}
2752         ruleinfo.type
2753         ruleinfo.type
2754
2755 The type of the ruleinfo. See the constant section of the solver class for the
2756 rule type list and the special type list.
2757
2758         Dep *dep;                               /* read only */
2759         $ruleinfo->{dep}
2760         ruleinfo.dep
2761         ruleinfo.dep
2762
2763 The dependency leading to the creation of the rule.
2764
2765         Dep *dep_id;                            /* read only */
2766         $ruleinfo->{'dep_id'}
2767         ruleinfo.dep_id
2768         ruleinfo.dep_id
2769
2770 The Id of the dependency leading to the creation of the rule, or zero.
2771
2772         Solvable *solvable;                     /* read only */
2773         $ruleinfo->{solvable}
2774         ruleinfo.solvable
2775         ruleinfo.solvable
2776
2777 The involved Solvable, e.g. the one containing the dependency.
2778
2779         Solvable *othersolvable;                /* read only */
2780         $ruleinfo->{othersolvable}
2781         ruleinfo.othersolvable
2782         ruleinfo.othersolvable
2783
2784 The other involved Solvable (if any), e.g. the one containing providing
2785 the dependency for conflicts.
2786
2787         const char *problemstr();
2788         my $str = $ruleinfo->problemstr();
2789         str = ruleinfo.problemstr()
2790         str = ruleinfo.problemstr()
2791
2792 A string describing the ruleinfo from a problem perspective. This probably
2793 only makes sense if the rule is part of a problem.
2794
2795 The Solution Class
2796 ------------------
2797 A solution solves one specific problem. It consists of multiple solution elements
2798 that all need to be executed.
2799
2800 === ATTRIBUTES ===
2801
2802         Solver *solv;                           /* read only */
2803         $solution->{solv}
2804         solution.solv
2805         solution.solv
2806
2807 Back pointer to solver object.
2808
2809         Id problemid;                           /* read only */
2810         $solution->{problemid}
2811         solution.problemid
2812         solution.problemid
2813
2814 Id of the problem the solution solves.
2815
2816         Id id;                                  /* read only */
2817         $solution->{id}
2818         solution.id
2819         solution.id
2820
2821 Id of the solution. The first solution has Id 1, they are numbered consecutively.
2822
2823 === METHODS ===
2824
2825         Solutionelement *elements(bool expandreplaces = 0)
2826         my @solutionelements = $solution->elements();
2827         solutionelements = solution.elements()
2828         solutionelements = solution.elements()
2829
2830 Return an array containing the elements describing what needs to be done to
2831 implement the specific solution. If expandreplaces is true, elements of type
2832 SOLVER_SOLUTION_REPLACE will be replaced by one or more elements replace
2833 elements describing the policy mismatches.
2834
2835         int element_count()
2836         my $cnt = $solution->solution_count();
2837         cnt = solution.element_count()
2838         cnt = solution.element_count()
2839
2840 Return the number of solution elements without creating objects. Note that the
2841 count does not match the number of objects returned by the elements() method
2842 of expandreplaces is set to true.
2843
2844
2845 The Solutionelement Class
2846 -------------------------
2847 A solution element describes a single action of a solution. The action is always
2848 either to remove one specific job or to add a new job that installs or erases
2849 a single specific package.
2850
2851 === ATTRIBUTES ===
2852
2853         Solver *solv;                           /* read only */
2854         $solutionelement->{solv}
2855         solutionelement.solv
2856         solutionelement.solv
2857
2858 Back pointer to solver object.
2859
2860         Id problemid;                           /* read only */
2861         $solutionelement->{problemid}
2862         solutionelement.problemid
2863         solutionelement.problemid
2864
2865 Id of the problem the element (partly) solves.
2866
2867         Id solutionid;                          /* read only */
2868         $solutionelement->{solutionid}
2869         solutionelement.solutionid
2870         solutionelement.solutionid
2871
2872 Id of the solution the element is a part of.
2873
2874         Id id;                                  /* read only */
2875         $solutionelement->{id}
2876         solutionelement.id
2877         solutionelement.id
2878
2879 Id of the solution element. The first element has Id 1, they are numbered consecutively.
2880
2881         Id type;                                /* read only */
2882         $solutionelement->{type}
2883         solutionelement.type
2884         solutionelement.type
2885
2886 Type of the solution element. See the constant section of the solver class for the
2887 existing types.
2888
2889         Solvable *solvable;                     /* read only */
2890         $solutionelement->{solvable}
2891         solutionelement.solvable
2892         solutionelement.solvable
2893
2894 The installed solvable that needs to be replaced for replacement elements.
2895
2896         Solvable *replacement;                  /* read only */
2897         $solutionelement->{replacement}
2898         solutionelement.replacement
2899         solutionelement.replacement
2900
2901 The solvable that needs to be installed to fix the problem.
2902
2903         int jobidx;                             /* read only */
2904         $solutionelement->{jobidx}
2905         solutionelement.jobidx
2906         solutionelement.jobidx
2907
2908 The index of the job that needs to be removed to fix the problem, or -1 if the
2909 element is of another type. Note that it's better to change the job to SOLVER_NOOP
2910 type so that the numbering of other elements does not get disturbed. This
2911 method works both for types SOLVER_SOLUTION_JOB and SOLVER_SOLUTION_POOLJOB.
2912
2913 === METHODS ===
2914
2915         Solutionelement *replaceelements()
2916         my @solutionelements = $solutionelement->replaceelements();
2917         solutionelements = solutionelement.replaceelements()
2918         solutionelements = solutionelement.replaceelements()
2919
2920 If the solution element is of type SOLVER_SOLUTION_REPLACE, return an array of
2921 elements describing the policy mismatches, otherwise return a copy of the
2922 element. See also the ``expandreplaces'' option in the solution's elements()
2923 method.
2924
2925         int illegalreplace()
2926         my $illegal = $solutionelement->illegalreplace();
2927         illegal = solutionelement.illegalreplace()
2928         illegal = solutionelement.illegalreplace()
2929
2930 Return an integer that contains the policy mismatch bits or-ed together, or
2931 zero if there was no policy mismatch. See the policy error constants in
2932 the solver class.
2933
2934         Job Job()
2935         my $job = $solutionelement->Job();
2936         illegal = solutionelement.Job()
2937         illegal = solutionelement.Job()
2938
2939 Create a job that implements the solution element. Add this job to the array
2940 of jobs for all elements of type different to SOLVER_SOLUTION_JOB and
2941 SOLVER_SOLUTION_POOLJOB. For the latter two, a SOLVER_NOOB Job is created,
2942 you should replace the old job with the new one.
2943
2944         const char *str()
2945         my $str = $solutionelement->str();
2946         str = solutionelement.str()
2947         str = solutionelement.str()
2948
2949 A string describing the change the solution element consists of.
2950
2951 The Transaction Class
2952 ---------------------
2953 Transactions describe the output of a solver run. A transaction contains
2954 a number of transaction elements, each either the installation of a new
2955 package or the removal of an already installed package. The Transaction
2956 class supports a classify() method that puts the elements into different
2957 groups so that a transaction can be presented to the user in a meaningful
2958 way.
2959
2960 === CONSTANTS ===
2961
2962 Transaction element types, both active and passive
2963
2964 *SOLVER_TRANSACTION_IGNORE*::
2965 This element does nothing. Used to map element types that do not match
2966 the view mode.
2967
2968 *SOLVER_TRANSACTION_INSTALL*::
2969 This element installs a package.
2970
2971 *SOLVER_TRANSACTION_ERASE*::
2972 This element erases a package.
2973
2974 *SOLVER_TRANSACTION_MULTIINSTALL*::
2975 This element installs a package with a different version keeping the other
2976 versions installed.
2977
2978 *SOLVER_TRANSACTION_MULTIREINSTALL*::
2979 This element reinstalls an installed package keeping the other versions
2980 installed.
2981
2982 Transaction element types, active view
2983
2984 *SOLVER_TRANSACTION_REINSTALL*::
2985 This element re-installs a package, i.e. installs the same package again.
2986
2987 *SOLVER_TRANSACTION_CHANGE*::
2988 This element installs a package with same name, version, architecture but
2989 different content.
2990
2991 *SOLVER_TRANSACTION_UPGRADE*::
2992 This element installs a newer version of an installed package.
2993
2994 *SOLVER_TRANSACTION_DOWNGRADE*::
2995 This element installs an older version of an installed package.
2996
2997 *SOLVER_TRANSACTION_OBSOLETES*::
2998 This element installs a package that obsoletes an installed package.
2999
3000 Transaction element types, passive view
3001
3002 *SOLVER_TRANSACTION_REINSTALLED*::
3003 This element re-installs a package, i.e. installs the same package again.
3004
3005 *SOLVER_TRANSACTION_CHANGED*::
3006 This element replaces an installed package with one of the same name,
3007 version, architecture but different content.
3008
3009 *SOLVER_TRANSACTION_UPGRADED*::
3010 This element replaces an installed package with a new version.
3011
3012 *SOLVER_TRANSACTION_DOWNGRADED*::
3013 This element replaces an installed package with an old version.
3014
3015 *SOLVER_TRANSACTION_OBSOLETED*::
3016 This element replaces an installed package with a package that obsoletes
3017 it.
3018
3019 Pseudo element types for showing extra information used by classify()
3020
3021 *SOLVER_TRANSACTION_ARCHCHANGE*::
3022 This element replaces an installed package with a package of a different
3023 architecture.
3024
3025 *SOLVER_TRANSACTION_VENDORCHANGE*::
3026 This element replaces an installed package with a package of a different
3027 vendor.
3028
3029 Transaction mode flags
3030
3031 *SOLVER_TRANSACTION_SHOW_ACTIVE*::
3032 Filter for active view types. The default is to return passive view type,
3033 i.e. to show how the installed packages get changed.
3034
3035 *SOLVER_TRANSACTION_SHOW_OBSOLETES*::
3036 Do not map the obsolete view type into INSTALL/ERASE elements.
3037
3038 *SOLVER_TRANSACTION_SHOW_ALL*::
3039 If multiple packages replace an installed package, only the best of them
3040 is kept as OBSOLETE element, the other ones are mapped to INSTALL/ERASE
3041 elements. This is because most applications want to show just one package
3042 replacing the installed one. The SOLVER_TRANSACTION_SHOW_ALL makes the
3043 library keep all OBSOLETE elements.
3044
3045 *SOLVER_TRANSACTION_SHOW_MULTIINSTALL*::
3046 The library maps MULTIINSTALL elements to simple INSTALL elements. This
3047 flag can be used to disable the mapping.
3048
3049 *SOLVER_TRANSACTION_CHANGE_IS_REINSTALL*::
3050 Use this flag if you want to map CHANGE elements to the REINSTALL type.
3051
3052 *SOLVER_TRANSACTION_OBSOLETE_IS_UPGRADE*::
3053 Use this flag if you want to map OBSOLETE elements to the UPGRADE type.
3054
3055 *SOLVER_TRANSACTION_MERGE_ARCHCHANGES*::
3056 Do not add extra categories for every architecture change, instead cumulate
3057 them in one category.
3058
3059 *SOLVER_TRANSACTION_MERGE_VENDORCHANGES*::
3060 Do not add extra categories for every vendor change, instead cumulate
3061 them in one category.
3062
3063 *SOLVER_TRANSACTION_RPM_ONLY*::
3064 Special view mode that just returns IGNORE, ERASE, INSTALL, MULTIINSTALL
3065 elements. Useful if you want to find out what to feed to the underlying
3066 package manager.
3067
3068 Transaction order flags
3069
3070 *SOLVER_TRANSACTION_KEEP_ORDERDATA*::
3071 Do not throw away the dependency graph used for ordering the transaction.
3072 This flag is needed if you want to do manual ordering.
3073
3074 === ATTRIBUTES ===
3075
3076         Pool *pool;                             /* read only */
3077         $trans->{pool}
3078         trans.pool
3079         trans.pool
3080
3081 Back pointer to pool.
3082
3083 === METHODS ===
3084
3085         bool isempty();
3086         $trans->isempty()
3087         trans.isempty()
3088         trans.isempty?
3089
3090 Returns true if the transaction does not do anything, i.e. has no elements.
3091
3092         Solvable *newsolvables();
3093         my @newsolvables = $trans->newsolvables();
3094         newsolvables = trans.newsolvables()
3095         newsolvables = trans.newsolvables()
3096
3097 Return all packages that are to be installed by the transaction. These are
3098 the packages that need to be downloaded from the repositories.
3099
3100         Solvable *keptsolvables();
3101         my @keptsolvables = $trans->keptsolvables();
3102         keptsolvables = trans.keptsolvables()
3103         keptsolvables = trans.keptsolvables()
3104
3105 Return all installed packages that the transaction will keep installed.
3106
3107         Solvable *steps();
3108         my @steps = $trans->steps();
3109         steps = trans.steps()
3110         steps = trans.steps()
3111
3112 Return all solvables that need to be installed (if the returned solvable
3113 is not already installed) or erased (if the returned solvable is installed).
3114 A step is also called a transaction element.
3115
3116         int steptype(Solvable *solvable, int mode)
3117         my $type = $trans->steptype($solvable, $mode);
3118         type = trans.steptype(solvable, mode)
3119         type = trans.steptype(solvable, mode)
3120
3121 Return the transaction type of the specified solvable. See the CONSTANTS
3122 sections for the mode argument flags and the list of returned types.
3123
3124         TransactionClass *classify(int mode = 0)
3125         my @classes = $trans->classify();
3126         classes = trans.classify()
3127         classes = trans.classify()
3128
3129 Group the transaction elements into classes so that they can be displayed
3130 in a structured way. You can use various mapping mode flags to tweak
3131 the result to match your preferences, see the mode argument flag in
3132 the CONSTANTS section. See the TransactionClass class for how to deal
3133 with the returned objects.
3134
3135         Solvable othersolvable(Solvable *solvable);
3136         my $other = $trans->othersolvable($solvable);
3137         other = trans.othersolvable(solvable)
3138         other = trans.othersolvable(solvable)
3139
3140 Return the ``other'' solvable for a given solvable. For installed packages
3141 the other solvable is the best package with the same name that replaces
3142 the installed package, or the best package of the obsoleting packages if
3143 the package does not get replaced by one with the same name.
3144
3145 For to be installed packages, the ``other'' solvable is the best installed
3146 package with the same name that will be replaced, or the best packages
3147 of all the packages that are obsoleted if the new package does not replace
3148 a package with the same name.
3149
3150 Thus, the ``other'' solvable is normally the package that is also shown
3151 for a given package.
3152
3153         Solvable *allothersolvables(Solvable *solvable);
3154         my @others = $trans->allothersolvables($solvable);
3155         others = trans.allothersolvables(solvable)
3156         others = trans.allothersolvables(solvable)
3157
3158 For installed packages, returns all of the packages that replace us. For to
3159 be installed packages, returns all of the packages that the new package
3160 replaces. The special ``other'' solvable is always the first entry of the
3161 returned array.
3162
3163         long long calc_installsizechange();
3164         my $change = $trans->calc_installsizechange();
3165         change = trans.calc_installsizechange()
3166         change = trans.calc_installsizechange()
3167
3168 Return the size change of the installed system in kilobytes (kibibytes).
3169
3170         void order(int flags = 0);
3171         $trans->order();
3172         trans.order()
3173         trans.order()
3174
3175 Order the steps in the transactions so that dependent packages are updated
3176 before packages that depend on them. For rpm, you can also use rpmlib's
3177 ordering functionality, debian's dpkg does not provide a way to order a
3178 transaction.
3179
3180 === ACTIVE/PASSIVE VIEW ===
3181
3182 Active view lists what new packages get installed, while passive view shows
3183 what happens to the installed packages. Most often there's not much
3184 difference between the two modes, but things get interesting if multiple
3185 packages get replaced by one new package. Say you have installed packages
3186 A-1-1 and B-1-1, and now install A-2-1 which has a new dependency that
3187 obsoletes B. The transaction elements will be
3188
3189   updated   A-1-1 (other: A-2-1)
3190   obsoleted B-1-1 (other: A-2-1)
3191
3192 in passive mode, but
3193
3194   update A-2-1 (other: A-1-1)
3195   erase  B
3196
3197 in active mode. If the mode contains SOLVER_TRANSACTION_SHOW_ALL, the
3198 passive mode list will be unchanged but the active mode list will just
3199 contain A-2-1.
3200
3201 The Transactionclass Class
3202 --------------------------
3203 Objects of this type are returned by the classify() Transaction method.
3204
3205 === ATTRIBUTES ===
3206
3207         Transaction *transaction;               /* read only */
3208         $class->{transaction}
3209         class.transaction
3210         class.transaction
3211
3212 Back pointer to transaction object.
3213
3214         int type;                               /* read only */
3215         $class->{type}
3216         class.type
3217         class.type
3218
3219 The type of the transaction elements in the class.
3220
3221         int count;                              /* read only */
3222         $class->{count}
3223         class.count
3224         class.count
3225
3226 The number of elements in the class.
3227
3228         const char *fromstr;
3229         $class->{fromstr}
3230         class.fromstr
3231         class.fromstr
3232
3233 The old vendor or architecture.
3234
3235         const char *tostr;
3236         $class->{tostr}
3237         class.tostr
3238         class.tostr
3239
3240 The new vendor or architecture.
3241
3242         Id fromid;
3243         $class->{fromid}
3244         class.fromid
3245         class.fromid
3246
3247 The id of the old vendor or architecture.
3248
3249         Id toid;
3250         $class->{toid}
3251         class.toid
3252         class.toid
3253
3254 The id of the new vendor or architecture.
3255
3256 === METHODS ===
3257
3258         void solvables();
3259         my @solvables = $class->solvables();
3260         solvables = class.solvables()
3261         solvables = class.solvables()
3262
3263 Return the solvables for all transaction elements in the class.
3264
3265 Checksums
3266 ---------
3267 Checksums (also called hashes) are used to make sure that downloaded data is
3268 not corrupt and also as a fingerprint mechanism to check if data has changed.
3269
3270 === CLASS METHODS ===
3271
3272         Chksum Chksum(Id type)
3273         my $chksum = solv::Chksum->new($type);
3274         chksum = solv.Chksum(type)
3275         chksum = Solv::Chksum.new(type)
3276
3277 Create a checksum object. Currently the following types are supported:
3278
3279         REPOKEY_TYPE_MD5
3280         REPOKEY_TYPE_SHA1
3281         REPOKEY_TYPE_SHA256
3282
3283 These keys are constants in the *solv* class.
3284
3285         Chksum Chksum(Id type, const char *hex)
3286         my $chksum = solv::Chksum->new($type, $hex);
3287         chksum = solv.Chksum(type, hex)
3288         chksum = Solv::Chksum.new(type, hex)
3289
3290 Create an already finalized checksum object from a hex string.
3291
3292         Chksum Chksum_from_bin(Id type, char *bin)
3293         my $chksum = solv::Chksum->from_bin($type, $bin);
3294         chksum = solv.Chksum.from_bin(type, bin)
3295         chksum = Solv::Chksum.from_bin(type, bin)
3296
3297 Create an already finalized checksum object from a binary checksum.
3298
3299 === ATTRIBUTES ===
3300
3301         Id type;                        /* read only */
3302         $chksum->{type}
3303         chksum.type
3304         chksum.type
3305
3306 Return the type of the checksum object.
3307
3308 === METHODS ===
3309
3310         void add(const char *str)
3311         $chksum->add($str);
3312         chksum.add(str)
3313         chksum.add(str)
3314
3315 Add a (binary) string to the checksum.
3316
3317         void add_fp(FILE *fp)
3318         $chksum->add_fp($file);
3319         chksum.add_fp(file)
3320         chksum.add_fp(file)
3321
3322 Add the contents of a file to the checksum.
3323
3324         void add_stat(const char *filename)
3325         $chksum->add_stat($filename);
3326         chksum.add_stat(filename)
3327         chksum.add_stat(filename)
3328
3329 Stat the file and add the dev/ino/size/mtime member to the checksum. If the
3330 stat fails, the members are zeroed.
3331
3332         void add_fstat(int fd)
3333         $chksum->add_fstat($fd);
3334         chksum.add_fstat(fd)
3335         chksum.add_fstat(fd)
3336
3337 Same as add_stat, but instead of the filename a file descriptor is used.
3338
3339         unsigned char *raw()
3340         my $raw = $chksum->raw();
3341         raw = chksum.raw()
3342         raw = chksum.raw()
3343
3344 Finalize the checksum and return the result as raw bytes. This means that the
3345 result can contain NUL bytes or unprintable characters.
3346
3347         const char *hex()
3348         my $raw = $chksum->hex();
3349         raw = chksum.hex()
3350         raw = chksum.hex()
3351
3352 Finalize the checksum and return the result as hex string.
3353
3354         const char *typestr()
3355         my $typestr = $chksum->typestr();
3356         typestr = chksum.typestr
3357         typestr = chksum.typestr
3358
3359 Return the type of the checksum as a string, e.g. "sha256".
3360
3361         <equality>
3362         if ($chksum1 == $chksum2)
3363         if chksum1 == chksum2:
3364         if chksum1 == chksum2
3365
3366 Checksums are equal if they are of the same type and the finalized results are
3367 the same.
3368
3369         <stringification>
3370         my $str = $chksum->str;
3371         str = str(chksum)
3372         str = chksum.to_s
3373
3374 If the checksum is finished, the checksum is returned as "<type>:<hex>" string.
3375 Otherwise "<type>:unfinished" is returned.
3376
3377
3378 File Management
3379 ---------------
3380 This functions were added because libsolv uses standard *FILE* pointers to
3381 read/write files, but languages like perl have their own implementation of
3382 files. The libsolv functions also support decompression and compression, the
3383 algorithm is selected by looking at the file name extension.
3384
3385         FILE *xfopen(char *fn, char *mode = "r")
3386         my $file = solv::xfopen($path);
3387         file = solv.xfopen(path)
3388         file = Solv::xfopen(path)
3389
3390 Open a file at the specified path. The `mode` argument is passed on to the
3391 stdio library.
3392
3393         FILE *xfopen_fd(char *fn, int fileno)
3394         my $file = solv::xfopen_fd($path, $fileno);
3395         file = solv.xfopen_fd(path, fileno)
3396         file = Solv::xfopen_fd(path, fileno)
3397
3398 Create a file handle from the specified file descriptor. The path argument is
3399 only used to select the correct (de-)compression algorithm, use an empty path
3400 if you want to make sure to read/write raw data. The file descriptor is dup()ed
3401 before the file handle is created.
3402
3403 === METHODS ===
3404
3405         int fileno()
3406         my $fileno = $file->fileno();
3407         fileno = file.fileno()
3408         fileno = file.fileno()
3409
3410 Return file file descriptor of the file. If the file is not open, `-1` is
3411 returned.
3412
3413         void cloexec(bool state)
3414         $file->cloexec($state)
3415         file.cloexec(state)
3416         file.cloexec(state)
3417
3418 Set the close-on-exec flag of the file descriptor. The xfopen function
3419 returns files with close-on-exec turned on, so if you want to pass
3420 a file to some other process you need to call cloexec(0) before calling
3421 exec.
3422
3423         int dup()
3424         my $fileno = $file->dup();
3425         fileno = file.dup()
3426         fileno = file.dup()
3427
3428 Return a copy of the descriptor of the file. If the file is not open, `-1` is
3429 returned.
3430
3431         bool flush()
3432         $file->flush();
3433         file.flush()
3434         file.flush()
3435
3436 Flush the file. Returns false if there was an error. Flushing a closed file
3437 always returns true.
3438
3439         bool close()
3440         $file->close();
3441         file.close()
3442         file.close()
3443
3444 Close the file. This is needed for languages like Ruby that do not destruct
3445 objects right after they are no longer referenced. In that case, it is good
3446 style to close open files so that the file descriptors are freed right away.
3447 Returns false if there was an error.
3448
3449
3450 The Repodata Class
3451 ------------------
3452 The Repodata stores attributes for packages and the repository itself, each
3453 repository can have multiple repodata areas. You normally only need to
3454 directly access them if you implement lazy downloading of repository data.
3455 Repodata areas are created by calling the repository's add_repodata() method
3456 or by using repo_add methods without the REPO_REUSE_REPODATA or REPO_USE_LOADING
3457 flag.
3458
3459 === ATTRIBUTES ===
3460
3461         Repo *repo;                     /* read only */
3462         $data->{repo}
3463         data.repo
3464         data.repo
3465
3466 Back pointer to repository object.
3467
3468         Id id;                                  /* read only */
3469         $data->{id}
3470         data.id
3471         data.id
3472
3473 The id of the repodata area. Repodata ids of different repositories overlap.
3474
3475 === METHODS ===
3476
3477         internalize();
3478         $data->internalize();
3479         data.internalize()
3480         data.internalize()
3481
3482 Internalize newly added data. The lookup functions will only see the new data
3483 after it has been internalized.
3484
3485         bool write(FILE *fp);
3486         $data->write($fp);
3487         data.write(fp)
3488         data.write(fp)
3489
3490 Write the contents of the repodata area as solv file.
3491
3492         Id str2dir(const char *dir, bool create = 1)
3493         my $did = data->str2dir($dir);
3494         did = data.str2dir(dir)
3495         did = data.str2dir(dir)
3496
3497         const char *dir2str(Id did, const char *suffix = 0)
3498         $dir = pool->dir2str($did);
3499         dir = pool.dir2str(did)
3500         dir = pool.dir2str(did)
3501
3502 Convert a string (directory) into an Id and back. If the string is currently not in the
3503 pool and _create_ is false, zero is returned.
3504
3505         void add_dirstr(Id solvid, Id keyname, Id dir, const char *str)
3506         $data->add_dirstr($solvid, $keyname, $dir, $string)
3507         data.add_dirstr(solvid, keyname, dir, string)
3508         data.add_dirstr(solvid, keyname, dir, string)
3509
3510 Add a file path consisting of a dirname Id and a basename string.
3511
3512         bool add_solv(FILE *fp, int flags = 0);
3513         $data->add_solv($fp);
3514         data.add_solv(fp)
3515         data.add_solv(fp)
3516
3517 Replace a stub repodata object with the data from a solv file. This method
3518 automatically adds the REPO_USE_LOADING flag. It should only be used from
3519 a load callback.
3520
3521         void create_stubs();
3522         $data->create_stubs()
3523         data.create_stubs()
3524         data.create_stubs()
3525
3526 Create stub repodatas from the information stored in the repodata meta
3527 area.
3528
3529         void extend_to_repo();
3530         $data->extend_to_repo();
3531         data.extend_to_repo()
3532         data.extend_to_repo()
3533
3534 Extend the repodata so that it has the same size as the repo it belongs to.
3535 This method is needed when setting up a new extension repodata so that it
3536 matches the repository size. It is also needed when switching to a just written
3537 repodata extension to make the repodata match the written extension (which is
3538 always of the size of the repo).
3539
3540         <equality>
3541         if ($data1 == $data2)
3542         if data1 == data2:
3543         if data1 == data2
3544
3545 Two repodata objects are equal if they belong to the same repository and have
3546 the same id.
3547
3548 === DATA RETRIEVAL METHODS ===
3549
3550         const char *lookup_str(Id solvid, Id keyname)
3551         my $string = $data->lookup_str($solvid, $keyname);
3552         string = data.lookup_str(solvid, keyname)
3553         string = data.lookup_str(solvid, keyname)
3554
3555         const char *lookup_id(Id solvid, Id keyname)
3556         my $string = $data->lookup_id($solvid, $keyname);
3557         string = data.lookup_id(solvid, keyname)
3558         string = data.lookup_id(solvid, keyname)
3559
3560         unsigned long long lookup_num(Id solvid, Id keyname, unsigned long long notfound = 0)
3561         my $num = $data->lookup_num($solvid, $keyname);
3562         num = data.lookup_num(solvid, keyname)
3563         num = data.lookup_num(solvid, keyname)
3564
3565         bool lookup_void(Id solvid, Id keyname)
3566         my $bool = $data->lookup_void($solvid, $keyname);
3567         bool = data.lookup_void(solvid, keyname)
3568         bool = data.lookup_void(solvid, keyname)
3569
3570         Id *lookup_idarray(Id solvid, Id keyname)
3571         my @ids = $data->lookup_idarray($solvid, $keyname);
3572         ids = data.lookup_idarray(solvid, keyname)
3573         ids = data.lookup_idarray(solvid, keyname)
3574
3575         Chksum lookup_checksum(Id solvid, Id keyname)
3576         my $chksum = $data->lookup_checksum($solvid, $keyname);
3577         chksum = data.lookup_checksum(solvid, keyname)
3578         chksum = data.lookup_checksum(solvid, keyname)
3579
3580 Lookup functions. Return the data element stored in the specified solvable.
3581 The methods probably only make sense to retrieve data from the special
3582 SOLVID_META solvid that stores repodata meta information.
3583
3584 === DATA STORAGE METHODS ===
3585
3586         void set_str(Id solvid, Id keyname, const char *str);
3587         $data->set_str($solvid, $keyname, $str);
3588         data.set_str(solvid, keyname, str)
3589         data.set_str(solvid, keyname, str)
3590
3591         void set_id(Id solvid, Id keyname, DepId id);
3592         $data->set_id($solvid, $keyname, $id);
3593         data.set_id(solvid, keyname, id)
3594         data.set_id(solvid, keyname, id)
3595
3596         void set_num(Id solvid, Id keyname, unsigned long long num);
3597         $data->set_num($solvid, $keyname, $num);
3598         data.set_num(solvid, keyname, num)
3599         data.set_num(solvid, keyname, num)
3600
3601         void set_void(Id solvid, Id keyname);
3602         $data->set_void($solvid, $keyname);
3603         data.set_void(solvid, keyname)
3604         data.set_void(solvid, keyname)
3605
3606         void set_poolstr(Id solvid, Id keyname, const char *str);
3607         $data->set_poolstr($solvid, $keyname, $str);
3608         data.set_poolstr(solvid, keyname, str)
3609         data.set_poolstr(solvid, keyname, str)
3610
3611         void set_checksum(Id solvid, Id keyname, Chksum *chksum);
3612         $data->set_checksum($solvid, $keyname, $chksum);
3613         data.set_checksum(solvid, keyname, chksum)
3614         data.set_checksum(solvid, keyname, chksum)
3615
3616         void set_sourcepkg(Id solvid, const char *sourcepkg);
3617         $data.set_sourcepkg($solvid, $sourcepkg);
3618         data.set_sourcepkg(solvid, sourcepkg)
3619         data.set_sourcepkg(solvid, sourcepkg)
3620
3621         void set_location(Id solvid, unsigned int mediano, const char *location);
3622         $data.set_location($solvid, $mediano, $location);
3623         data.set_location(solvid, mediano, location)
3624         data.set_location(solvid, mediano, location)
3625
3626         void add_idarray(Id solvid, Id keyname, DepId id);
3627         $data->add_idarray($solvid, $keyname, $id);
3628         data.add_idarray(solvid, keyname, id)
3629         data.add_idarray(solvid, keyname, id)
3630
3631         Id new_handle();
3632         my $handle = $data->new_handle();
3633         handle = data.new_handle()
3634         handle = data.new_handle()
3635
3636         void add_flexarray(Id solvid, Id keyname, Id handle);
3637         $data->add_flexarray($solvid, $keyname, $handle);
3638         data.add_flexarray(solvid, keyname, handle)
3639         data.add_flexarray(solvid, keyname, handle)
3640
3641         void unset(Id solvid, Id keyname);
3642         $data->unset($solvid, $keyname);
3643         data.unset(solvid, keyname)
3644         data.unset(solvid, keyname)
3645
3646 Data storage methods. Probably only useful to store data in the special
3647 SOLVID_META solvid that stores repodata meta information. Note that
3648 repodata areas can have their own Id pool (see the REPO_LOCALPOOL flag),
3649 so be careful if you need to store ids. Arrays are created by calling
3650 the add function for every element. A flexarray is an array of
3651 sub-structures, call new_handle to create a new structure, use the
3652 handle as solvid to fill the structure with data and call add_flexarray
3653 to put the structure in an array.
3654
3655
3656 The Datapos Class
3657 -----------------
3658 Datapos objects describe a specific position in the repository data area.
3659 Thus they are only valid until the repository is modified in some way.
3660 Datapos objects can be created by the pos() and parentpos() methods of
3661 a Datamatch object or by accessing the ``meta'' attribute of a repository.
3662
3663 === ATTRIBUTES ===
3664
3665         Repo *repo;                     /* read only */
3666         $data->{repo}
3667         data.repo
3668         data.repo
3669
3670 Back pointer to repository object.
3671
3672 === METHODS ===
3673
3674         Dataiterator(Id keyname, const char *match, int flags)
3675         my $di = $datapos->Dataiterator($keyname, $match, $flags);
3676         di = datapos.Dataiterator(keyname, match, flags)
3677         di = datapos.Dataiterator(keyname, match, flags)
3678
3679 Create a Dataiterator at the position of the datapos object.
3680
3681         const char *lookup_deltalocation(unsigned int *OUTPUT);
3682         my ($location, $mediano) = $datapos->lookup_deltalocation();
3683         location, mediano = datapos.lookup_deltalocation()
3684         location, mediano = datapos.lookup_deltalocation()
3685
3686 Return a tuple containing the on-media location and an optional media number
3687 for a delta rpm. This obviously only works if the data position points to
3688 structure describing a delta rpm.
3689
3690         const char *lookup_deltaseq();
3691         my $seq = $datapos->lookup_deltaseq();
3692         seq = datapos.lookup_deltaseq();
3693         seq = datapos.lookup_deltaseq();
3694
3695 Return the delta rpm sequence from the structure describing a delta rpm.
3696
3697 === DATA RETRIEVAL METHODS ===
3698
3699         const char *lookup_str(Id keyname)
3700         my $string = $datapos->lookup_str($keyname);
3701         string = datapos.lookup_str(keyname)
3702         string = datapos.lookup_str(keyname)
3703
3704         Id lookup_id(Id solvid, Id keyname)
3705         my $id = $datapos->lookup_id($keyname);
3706         id = datapos.lookup_id(keyname)
3707         id = datapos.lookup_id(keyname)
3708
3709         unsigned long long lookup_num(Id keyname, unsigned long long notfound = 0)
3710         my $num = $datapos->lookup_num($keyname);
3711         num = datapos.lookup_num(keyname)
3712         num = datapos.lookup_num(keyname)
3713
3714         bool lookup_void(Id keyname)
3715         my $bool = $datapos->lookup_void($keyname);
3716         bool = datapos.lookup_void(keyname)
3717         bool = datapos.lookup_void(keyname)
3718
3719         Id *lookup_idarray(Id keyname)
3720         my @ids = $datapos->lookup_idarray($keyname);
3721         ids = datapos.lookup_idarray(keyname)
3722         ids = datapos.lookup_idarray(keyname)
3723
3724         Chksum lookup_checksum(Id keyname)
3725         my $chksum = $datapos->lookup_checksum($keyname);
3726         chksum = datapos.lookup_checksum(keyname)
3727         chksum = datapos.lookup_checksum(keyname)
3728
3729 Lookup functions. Note that the returned Ids are always translated into
3730 the Ids of the global pool even if the repodata area contains its own pool.
3731
3732         Dataiterator Dataiterator(Id keyname, const char *match = 0, int flags = 0)
3733         my $di = $datapos->Dataiterator($keyname, $match, $flags);
3734         di = datapos.Dataiterator(keyname, match, flags)
3735         di = datapos.Dataiterator(keyname, match, flags)
3736
3737         for my $d (@$di)
3738         for d in di:
3739         for d in di
3740
3741 Iterate over the matching data elements. See the Dataiterator class for more
3742 information.
3743
3744 Author
3745 ------
3746 Michael Schroeder <mls@suse.de>
3747
3748 ////
3749 vim: syntax=asciidoc
3750 ////