From: Michael Schroeder Date: Thu, 16 May 2013 13:44:02 +0000 (+0200) Subject: start with the bindings documentation X-Git-Tag: upstream/0.4.0~133 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=234a84c6f0d725e483ff5577b4f3f84d3f4e63c5;p=platform%2Fupstream%2Flibsolv.git start with the bindings documentation --- diff --git a/doc/filters/xcode.conf b/doc/filters/xcode.conf new file mode 100644 index 0000000..294f908 --- /dev/null +++ b/doc/filters/xcode.conf @@ -0,0 +1,12 @@ +[blockdef-listing] +xcode-style=template="verseblock",presubs=(),postsubs=("callouts",),filter="filters/xcode.pl {basebackend}" + +[paradef-xcode] +delimiter=(?s)^(?P\s+.*) +template=verseblock +subs=verbatim +filter=filters/xcode.pl {basebackend} + +[paradef-literal] +delimiter=(?s)^(?P\s{1,7}\S.*) + diff --git a/doc/filters/xcode.pl b/doc/filters/xcode.pl new file mode 100755 index 0000000..ab17c7f --- /dev/null +++ b/doc/filters/xcode.pl @@ -0,0 +1,62 @@ +#!/usr/bin/perl + +die("I only understand docbook\n") unless @ARGV && $ARGV[0] eq 'docbook'; + +#my $ii = '//'; +#my $io = '//'; + +#my $si = '**'; +#my $so = '**'; + +my $ii = ''; +my $io = ''; + +my $si = ''; +my $so = ''; + +while() { + chomp; + my $in = ''; + my $out = ''; + s/^\s+//; + s/\s+$//; + if (/^(.*)(\s*\/\*.*?\*\/\s*?)$/) { + $out = $2; + $_ = $1; + } + if (/^(my\s+)(.*?)$/) { + $in = $1; + $_ = $2; + } + if (/(?$1<-I>/g; + # small fixup for callbackfunctions + s/\\(&[a-zA-Z_]+)/\\<-S>$1<-I>/; + # small fixup for stringification + s/\$<-S>/<-S>\$/g; + # iterators + s/^ //; + s/ $//; + s/^(for (?:my )?)(\S+) /$1<-S>$2<-I> /; + } + $_ = "$_<-S>"; + s/(\s*)<-S>/$1/g; + s/<-S>(\s*)/$1/g; + s/(\s*)<-I>/$1/g; + s/<-I>(\s*)/$1/g; + s/(\s+)/$1/g; + s/(\s+)<-S>/<-S>$1/g; + s/(\s+)/$1/g; + s/(\s+)<-I>/<-I>$1/g; + s//$si/g; + s/<-S>/$so/g; + s//$ii/g; + s/<-I>/$io/g; + print "$in$_$out\n"; +} diff --git a/doc/libsolv-bindings.3 b/doc/libsolv-bindings.3 new file mode 100644 index 0000000..8617f36 --- /dev/null +++ b/doc/libsolv-bindings.3 @@ -0,0 +1,1924 @@ +'\" t +.\" Title: libsolv-bindings +.\" Author: [see the "Author" section] +.\" Generator: DocBook XSL Stylesheets v1.76.1 +.\" Date: 05/16/2013 +.\" Manual: LIBSOLV +.\" Source: libsolv +.\" Language: English +.\" +.TH "LIBSOLV\-BINDINGS" "3" "05/16/2013" "libsolv" "LIBSOLV" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +libsolv-bindings \- access libsolv from perl/python/ruby +.SH "DESCRIPTION" +.sp +bla bla bla +.SH "THE POOL" +.sp +The pool is libsolv\(cqs central resource manager\&. A pool consists of Solvables, Repositories, Dependencies, each indexed by Ids\&. +.SS "CLASS METHODS" +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBPool *Pool()\fR +my \fI$pool\fR \fB= solv::Pool\->new()\fR; +\fIpool\fR \fB= solv\&.Pool()\fR +\fIpool\fR \fB= Solv::Pool\&.new()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Create a new pool instance\&. In most cases you just need one pool\&. +.SS "ATTRIBUTES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid *appdata;\fR /* read/write */ +\fI$pool\fR\fB\->{\*(Aqappdata\*(Aq}\fR +\fIpool\fR\fB\&.appdata\fR +\fIpool\fR\fB\&.appdata\fR +.fi +.if n \{\ +.RE +.\} +.sp +Application specific data that may be used in any way by the code using the pool\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBSolvable solvables[];\fR /* read only */ +my \fI$solvable\fR \fB=\fR \fI$pool\fR\fB\->{\*(Aqsolvables\*(Aq}\->[\fR\fI$solvid\fR\fB]\fR; +\fIsolvable\fR \fB=\fR \fIpool\fR\fB\&.solvables[\fR\fIsolvid\fR\fB]\fR +\fIsolvable\fR \fB=\fR \fIpool\fR\fB\&.solvables[\fR\fIsolvid\fR\fB]\fR +.fi +.if n \{\ +.RE +.\} +.sp +Look up a Solvable by its id\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBRepo repos[];\fR /* read only */ +my \fI$repo\fR \fB=\fR \fI$pool\fR\fB\->{\*(Aqrepos\*(Aq}\->[\fR\fI$repoid\fR\fB]\fR; +\fIrepo\fR \fB=\fR \fIpool\fR\fB\&.repos[\fR\fIrepoid\fR\fB]\fR +\fIrepo\fR \fB=\fR \fIpool\fR\fB\&.repos[\fR\fIrepoid\fR\fB]\fR +.fi +.if n \{\ +.RE +.\} +.sp +Look up a Repository by its id\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBRepo *installed;\fR /* read/write */ +\fI$pool\fR\fB\->{\*(Aqinstalled\*(Aq} =\fR \fI$repo\fR; +\fIpool\fR\fB\&.installed =\fR \fIrepo\fR +\fIpool\fR\fB\&.installed =\fR \fIrepo\fR +.fi +.if n \{\ +.RE +.\} +.sp +Define which repository contains all the installed packages\&. +.SS "METHODS" +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid free()\fR +\fI$pool\fR\fB\->free()\fR; +\fIpool\fR\fB\&.free()\fR +\fIpool\fR\fB\&.free()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Free a pool\&. This is currently done with a method instead of relying on reference counting or garbage collection because it\(cqs hard to track every reference to a pool\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid setdebuglevel(int\fR \fIlevel\fR\fB)\fR +\fI$pool\fR\fB\->setdebuglevel(\fR\fI$level\fR\fB)\fR; +\fIpool\fR\fB\&.setdebuglevel(\fR\fIlevel\fR\fB)\fR +\fIpool\fR\fB\&.setdebuglevel(\fR\fIlevel\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Set the debug level\&. A value of zero means no debug output, the higher the value, the more output is generated\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBint set_flag(int\fR \fIflag\fR\fB, int\fR \fIvalue\fR\fB)\fR +my \fI$oldvalue\fR \fB=\fR \fI$pool\fR\fB\->set_flag(\fR\fI$flag\fR\fB,\fR \fI$value\fR\fB)\fR; +\fIoldvalue\fR \fB=\fR \fIpool\fR\fB\&.set_flag(\fR\fIflag\fR\fB,\fR \fIvalue\fR\fB)\fR +\fIoldvalue\fR \fB=\fR \fIpool\fR\fB\&.set_flag(\fR\fIflag\fR\fB,\fR \fIvalue\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBint get_flag(int\fR \fIflag\fR\fB)\fR +my \fI$value\fR \fB=\fR \fI$pool\fR\fB\->get_flag(\fR\fI$flag\fR\fB)\fR; +\fIvalue\fR \fB=\fR \fIpool\fR\fB\&.get_flag(\fR\fIflag\fR\fB)\fR +\fIvalue\fR \fB=\fR \fIpool\fR\fB\&.get_flag(\fR\fIflag\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Set/get a pool specific flag\&. The flags define how the system works, e\&.g\&. how the package manager treats obsoletes\&. The default flags should be sane for most applications, but in some cases you may want to tweak a flag, for example if you want to solv package dependencies for some other system than yours\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid set_rootdir(const char *\fR\fIrootdir\fR\fB)\fR +\fI$pool\fR\fB\->set_rootdir(\fR\fIrootdir\fR\fB)\fR; +\fIpool\fR\fB\&.set_rootdir(\fR\fIrootdir\fR\fB)\fR +\fIpool\fR\fB\&.set_rootdir(\fR\fIrootdir\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBconst char *get_rootdir()\fR +my \fI$rootdir\fR \fB=\fR \fI$pool\fR\fB\->get_rootdir()\fR; +\fIrootdir\fR \fB=\fR \fIpool\fR\fB\&.get_rootdir()\fR +\fIrootdir\fR \fB=\fR \fIpool\fR\fB\&.get_rootdir()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Set/get the rootdir to use\&. This is useful if you want package management to work only in some directory, for example if you want to setup a chroot jail\&. Note that the rootdir will only be prepended to file paths if the \fBREPO_USE_ROOTDIR\fR flag is used\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid setarch(const char *\fR\fIarch\fR \fB= 0)\fR +\fI$pool\fR\fB\->setarch()\fR; +\fIpool\fR\fB\&.setarch()\fR +\fIpool\fR\fB\&.setarch()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Set the architecture for your system\&. The architecture is used to determine which packages are installable\&. It defaults to the result of \(lquname \-m\(rq\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBRepo *add_repo(const char *\fR\fIname\fR\fB)\fR +\fI$repo\fR \fB=\fR \fI$pool\fR\fB\->add_repo(\fR\fI$name\fR\fB)\fR; +\fIrepo\fR \fB=\fR \fIpool\fR\fB\&.add_repo(\fR\fIname\fR\fB)\fR +\fIrepo\fR \fB=\fR \fIpool\fR\fB\&.add_repo(\fR\fIname\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add a Repository with the specified name to the pool\&. The reposiory is empty on creation, use the repository methods to populate it with packages\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBRepoiterator *repos_iter()\fR +\fBfor my\fR \fI$repo\fR \fB(\fR\fI@\fR\fB{\fR\fI$pool\fR\fB\->repos_iter()})\fR +\fBfor\fR \fIrepo\fR \fBin\fR \fIpool\fR\fB\&.repos_iter():\fR +\fBfor\fR \fIrepo\fR \fBin\fR \fIpool\fR\fB\&.repos_iter()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Iterate over the existing repositories\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBSolvableiterator *solvables_iter()\fR +\fBfor my\fR \fI$solvable\fR \fB(\fR\fI@\fR\fB{\fR\fI$pool\fR\fB\->solvables_iter()})\fR +\fBfor\fR \fIsolvable\fR \fBin\fR \fIpool\fR\fB\&.solvables_iter():\fR +\fBfor\fR \fIsolvable\fR \fBin\fR \fIpool\fR\fB\&.solvables_iter()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Iterate over the existing solvables\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBDep *Dep(const char *\fR\fIstr\fR\fB, bool\fR \fIcreate\fR\fB=1)\fR +my \fI$dep\fR \fB=\fR \fI$pool\fR\fB\->Dep(\fR\fI$string\fR\fB)\fR; +\fIdep\fR \fB=\fR \fIpool\fR\fB\&.Dep(\fR\fIstring\fR\fB)\fR +\fIdep\fR \fB=\fR \fIpool\fR\fB\&.Dep(\fR\fIstring\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Create an object describing a string or dependency\&. If the string is currently not in the pool and \fIcreate\fR is false, \fBundef\fR/\fBNone\fR/\fBnil\fR is returned\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid addfileprovides()\fR +\fI$pool\fR\fB\->addfileprovides()\fR; +\fIpool\fR\fB\&.addfileprovides()\fR +\fIpool\fR\fB\&.addfileprovides()\fR +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBQueue addfileprovides_queue()\fR +my \fI@ids\fR \fB=\fR \fI$pool\fR\fB\->addfileprovides_queue()\fR; +\fIids\fR \fB=\fR \fIpool\fR\fB\&.addfileprovides_queue()\fR +\fIids\fR \fB=\fR \fIpool\fR\fB\&.addfileprovides_queue()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Some package managers like rpm allow dependencies on files contained in other packages\&. To allow libsolv to deal with those dependencies in an efficient way, you need to call the addfileprovides method after creating and reading all repositories\&. This method will scan all dependency for file names and than scan all packages for matching files\&. If a filename has been matched, it will be added to the provides list of the corresponding package\&. The addfileprovides_queue variant works the same way but returns an array containing all file dependencies\&. This information can be stored with the repository to speed up the next usage of the repository\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid createwhatprovides()\fR +\fI$pool\fR\fB\->createwhatprovides()\fR; +\fIpool\fR\fB\&.createwhatprovides()\fR +\fIpool\fR\fB\&.createwhatprovides()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Create the internal \(lqwhatprovides\(rq hash over all of the provides of all packages\&. This method must be called before doing any lookups on provides\&. It\(cqs encuraged to do it right after all repos are set up, usually right after the call to addfileprovides()\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBQueue whatprovides(DepId\fR \fIdep\fR\fB)\fR +my \fI@solvables\fR \fB=\fR \fI$pool\fR\fB\->whatprovides(\fR\fI$dep\fR\fB)\fR; +\fIsolvables\fR \fB=\fR \fIpool\fR\fB\&.whatprovides(\fR\fIdep\fR\fB)\fR +\fIsolvables\fR \fB=\fR \fIpool\fR\fB\&.whatprovides(\fR\fIdep\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Return all solvables that provide the specified dependency\&. You can use either a Dep object or an simple Id as argument\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBQueue matchprovidingids(const char *\fR\fImatch\fR\fB, int\fR \fIflags\fR\fB)\fR +my \fI@ids\fR \fB=\fR \fI$pool\fR\fB\->matchprovidingids(\fR\fI$match\fR\fB,\fR \fI$flags\fR\fB)\fR; +\fIids\fR \fB=\fR \fIpool\fR\fB\&.matchprovidingids(\fR\fImatch\fR\fB,\fR \fIflags\fR\fB)\fR +\fIids\fR \fB=\fR \fIpool\fR\fB\&.matchprovidingids(\fR\fImatch\fR\fB,\fR \fIflags\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Search the names of all provides and return the ones matching the specified string\&. See the Dataiterator class for the allowed flags\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBId towhatprovides(Queue\fR \fIids\fR\fB)\fR +my \fI$offset\fR \fB=\fR \fI$pool\fR\fB\->towhatprovides(\e\fR\fI@ids\fR\fB)\fR; +\fIoffset\fR \fB=\fR \fIpool\fR\fB\&.towhatprovides(\fR\fIids\fR\fB)\fR +\fIoffset\fR \fB=\fR \fIpool\fR\fB\&.towhatprovides(\fR\fIids\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +\(lqInternalize\(rq an array containing Ids\&. The returned value can be used to create solver jobs working on a specific set of packages\&. See the Solver class for more information\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool isknownarch(DepId\fR \fIid\fR\fB)\fR +my \fI$bool\fR \fB=\fR \fI$pool\fR\fB\->isknownarch(\fR\fI$id\fR\fB)\fR; +\fIbool\fR \fB=\fR \fIpool\fR\fB\&.isknownarch(\fR\fIid\fR\fB)\fR +\fIbool\fR \fB=\fR \fIpool\fR\fB\&.isknownarch?(\fR\fIid\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Return true if the specified Id describs a known architecture\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBSolver *Solver()\fR +my \fI$solver\fR \fB=\fR \fI$pool\fR\fB\->Solver()\fR; +\fIsolver\fR \fB=\fR \fIpool\fR\fB\&.Solver()\fR +\fIsolver\fR \fB=\fR \fIpool\fR\fB\&.Solver()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Create a new solver object\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBSolver *Job(int\fR \fIhow\fR\fB, Id\fR \fIwhat\fR\fB)\fR +my \fI$job\fR \fB=\fR \fI$pool\fR\fB\->Job(\fR\fI$how\fR\fB,\fR \fI$what\fR\fB)\fR; +\fIjob\fR \fB=\fR \fIpool\fR\fB\&.Job(\fR\fIhow\fR\fB,\fR \fIwhat\fR\fB)\fR +\fIjob\fR \fB=\fR \fIpool\fR\fB\&.Job(\fR\fIhow\fR\fB,\fR \fIwhat\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Create a new Job object\&. Kind of low level, in most cases you would use a Selection or Dep job constructor instead\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBSelection *Selection()\fR +my \fI$sel\fR \fB=\fR \fI$pool\fR\fB\->Selection()\fR; +\fIsel\fR \fB=\fR \fIpool\fR\fB\&.Selection()\fR +\fIsel\fR \fB=\fR \fIpool\fR\fB\&.Selection()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Create an empty selection\&. Useful as a starting point for merging other selections\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBSelection *Selection_all()\fR +my \fI$sel\fR \fB=\fR \fI$pool\fR\fB\->Selection_all()\fR; +\fIsel\fR \fB=\fR \fIpool\fR\fB\&.Selection_all()\fR +\fIsel\fR \fB=\fR \fIpool\fR\fB\&.Selection_all()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Create a selection containing all packages\&. Useful as starting point for intersecting other selections or for update/distupgrade jobs\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBSelection *select(const char *\fR\fIname\fR\fB, int\fR \fIflags\fR\fB)\fR +my \fI$sel\fR \fB=\fR \fI$pool\fR\fB\->select(\fR\fI$name\fR\fB,\fR \fI$flags\fR\fB)\fR; +\fIsel\fR \fB=\fR \fIpool\fR\fB\&.select(\fR\fIname\fR\fB,\fR \fIflags\fR\fB)\fR +\fIsel\fR \fB=\fR \fIpool\fR\fB\&.select(\fR\fIname\fR\fB,\fR \fIflags\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Create a selection by matching packages against the specified string\&. See the Selection class for a list of flags and how to create solver jobs from a selection\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid setpooljobs(Jobs *\fR\fIjobs\fR\fB)\fR +\fI$pool\fR\fB\->setpooljobs(\e\fR\fI@jobs\fR\fB)\fR; +\fIpool\fR\fB\&.setpooljobs(\fR\fIjobs\fR\fB)\fR +\fIpool\fR\fB\&.setpooljobs(\fR\fIjobs\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBJobs *getpooljobs()\fR +\fI@jobs\fR \fB=\fR \fI$pool\fR\fB\->getpooljobs()\fR; +\fIjobs\fR \fB=\fR \fIpool\fR\fB\&.getpooljobs()\fR +\fIjobs\fR \fB=\fR \fIpool\fR\fB\&.getpooljobs()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Get/Set fixed jobs stored in the pool\&. Those jobs are automatically appended to all solver jobs, they are meant for fixed configurations like which packages can be multiversion installed, which packages were userinstalled or must not be erased\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid set_loadcallback(Callable *\fR\fIcallback\fR\fB)\fR +\fI$pool\fR\fB\->setloadcallback(\e\fR\fI&callbackfunction\fR\fB)\fR; +\fIpool\fR\fB\&.setloadcallback(\fR\fIcallbackfunction\fR\fB)\fR +\fIpool\fR\fB\&.setloadcallback { |\fR\fIrepodata\fR\fB| \&.\&.\&. }\fR +.fi +.if n \{\ +.RE +.\} +.sp +Set the callback function called when repository metadata needs to be loaded on demand\&. To make use of this feature, you need to create repodata stubs that tell the library which data is available but not loaded\&. If later on the data needs to be accessed, the callback function is called with a repodata argument\&. You can then load the data (maybe fetching it first from an remote server)\&. The callback should return true if the data has been made available\&. +.SS "DATA RETRIEVAL METHODS" +.sp +In the following functions, the \fIkeyname\fR argument describes what to retrive\&. For the standard cases you can use the available Id constants\&. For example, +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fB$solv::SOLVABLE_SUMMARY\fR +\fBsolv\&.SOLVABLE_SUMMARY\fR +\fBSolv::SOLVABLE_SUMMARY\fR +.fi +.if n \{\ +.RE +.\} +.sp +selects the \(lqSummary\(rq entry of a solvable\&. The \fIsolvid\fR argument selects the desired solvable by Id\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBconst char *lookup_str(Id\fR \fIsolvid\fR\fB, Id\fR \fIkeyname\fR\fB)\fR +my \fI$string\fR \fB=\fR \fI$pool\fR\fB\->lookup_str(\fR\fI$solvid\fR\fB,\fR \fI$keyname\fR\fB)\fR; +\fIstring\fR \fB=\fR \fIpool\fR\fB\&.lookup_str(\fR\fIsolvid\fR\fB,\fR \fIkeyname\fR\fB)\fR +\fIstring\fR \fB=\fR \fIpool\fR\fB\&.lookup_str(\fR\fIsolvid\fR\fB,\fR \fIkeyname\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBId lookup_id(Id\fR \fIsolvid\fR\fB, Id\fR \fIkeyname\fR\fB)\fR +my \fI$id\fR \fB=\fR \fI$pool\fR\fB\->lookup_id(\fR\fI$solvid\fR\fB,\fR \fI$keyname\fR\fB)\fR; +\fIid\fR \fB=\fR \fIpool\fR\fB\&.lookup_id(\fR\fIsolvid\fR\fB,\fR \fIkeyname\fR\fB)\fR +\fIid\fR \fB=\fR \fIpool\fR\fB\&.lookup_id(\fR\fIsolvid\fR\fB,\fR \fIkeyname\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBunsigned int lookup_num(Id\fR \fIsolvid\fR\fB, Id\fR \fIkeyname\fR\fB, unsigned int\fR \fInotfound\fR \fB= 0)\fR +my \fI$num\fR \fB=\fR \fI$pool\fR\fB\->lookup_num(\fR\fI$solvid\fR\fB,\fR \fI$keyname\fR\fB)\fR; +\fInum\fR \fB=\fR \fIpool\fR\fB\&.lookup_num(\fR\fIsolvid\fR\fB,\fR \fIkeyname\fR\fB)\fR +\fInum\fR \fB=\fR \fIpool\fR\fB\&.lookup_num(\fR\fIsolvid\fR\fB,\fR \fIkeyname\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool lookup_void(Id\fR \fIsolvid\fR\fB, Id\fR \fIkeyname\fR\fB)\fR +my \fI$bool\fR \fB=\fR \fI$pool\fR\fB\->lookup_void(\fR\fI$solvid\fR\fB,\fR \fI$keyname\fR\fB)\fR; +\fIbool\fR \fB=\fR \fIpool\fR\fB\&.lookup_void(\fR\fIsolvid\fR\fB,\fR \fIkeyname\fR\fB)\fR +\fIbool\fR \fB=\fR \fIpool\fR\fB\&.lookup_void(\fR\fIsolvid\fR\fB,\fR \fIkeyname\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBChksum *lookup_checksum(Id\fR \fIsolvid\fR\fB, Id\fR \fIkeyname\fR\fB)\fR +my \fI$chksum\fR \fB=\fR \fI$pool\fR\fB\->lookup_checksum(\fR\fI$solvid\fR\fB,\fR \fI$keyname\fR\fB)\fR; +\fIchksum\fR \fB=\fR \fIpool\fR\fB\&.lookup_checksum(\fR\fIsolvid\fR\fB,\fR \fIkeyname\fR\fB)\fR +\fIchksum\fR \fB=\fR \fIpool\fR\fB\&.lookup_checksum(\fR\fIsolvid\fR\fB,\fR \fIkeyname\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Lookup functions\&. Return the data element stored in the specified solvable\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBDataiterator *Dataiterator(Id\fR \fIsolvid\fR\fB, Id\fR \fIkeyname\fR\fB, const char *\fR\fImatch\fR\fB, int\fR \fIflags\fR\fB)\fR +my \fI$di\fR \fB=\fR \fI$pool\fR\fB\->Dataiterator(\fR\fI$solvid\fR\fB,\fR \fI$keyname\fR\fB,\fR \fI$match\fR\fB,\fR \fI$flags\fR\fB)\fR; +\fIdi\fR \fB=\fR \fIpool\fR\fB\&.Dataiterator(\fR\fIsolvid\fR\fB,\fR \fIkeyname\fR\fB,\fR \fImatch\fR\fB,\fR \fIflags\fR\fB)\fR +\fIdi\fR \fB=\fR \fIpool\fR\fB\&.Dataiterator(\fR\fIsolvid\fR\fB,\fR \fIkeyname\fR\fB,\fR \fImatch\fR\fB,\fR \fIflags\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBfor my\fR \fI$d\fR \fB(\fR\fI@$di\fR\fB)\fR +\fBfor\fR \fId\fR \fBin\fR \fIdi\fR\fB:\fR +\fBfor\fR \fId\fR \fBin\fR \fIdi\fR +.fi +.if n \{\ +.RE +.\} +.sp +Iterate over the matching data elements\&. See the Dataiterator class for more information\&. +.SS "ID METHODS" +.sp +The following methods deal with Ids, i\&.e\&. integers representing objects in the pool\&. They are considered \(lqlow level\(rq, in most cases you would not use them but instead the object orientated methods\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBRepo *id2repo(Id\fR \fIid\fR\fB)\fR +\fI$repo\fR \fB=\fR \fI$pool\fR\fB\->id2repo(\fR\fI$id\fR\fB)\fR; +\fIrepo\fR \fB=\fR \fIpool\fR\fB\&.id2repo(\fR\fIid\fR\fB)\fR +\fIrepo\fR \fB=\fR \fIpool\fR\fB\&.id2repo(\fR\fIid\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Lookup an existing Repository by id\&. You can also do this by using the \fBrepos\fR attribute\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBSolvable *id2solvable(Id\fR \fIid\fR\fB)\fR +\fI$solvable\fR \fB=\fR \fI$pool\fR\fB\->id2solvable(\fR\fI$id\fR\fB)\fR; +\fIsolvable\fR \fB=\fR \fIpool\fR\fB\&.id2solvable(\fR\fIid\fR\fB)\fR +\fIsolvable\fR \fB=\fR \fIpool\fR\fB\&.id2solvable(\fR\fIid\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Lookup an existing Repository by id\&. You can also do this by using the \fBsolvables\fR attribute\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBconst char *solvid2str(Id\fR \fIid\fR\fB)\fR +my \fI$str\fR \fB=\fR \fI$pool\fR\fB\->solvid2str(\fR\fI$id\fR\fB)\fR; +\fIstr\fR \fB=\fR \fIpool\fR\fB\&.solvid2str(\fR\fIid\fR\fB)\fR +\fIstr\fR \fB=\fR \fIpool\fR\fB\&.solvid2str(\fR\fIid\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Return a string describing the Solvable with the specified id\&. The string consists of the name, version, and architecture of the Solvable\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBId str2id(const char *\fR\fIstr\fR\fB, bool\fR \fIcreate\fR\fB=1)\fR +my \fI$id\fR \fB=\fR \fIpool\fR\fB\->str2id(\fR\fI$string\fR\fB)\fR; +\fIid\fR \fB=\fR \fIpool\fR\fB\&.str2id(\fR\fIstring\fR\fB)\fR +\fIid\fR \fB=\fR \fIpool\fR\fB\&.str2id(\fR\fIstring\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBconst char *id2str(Id\fR \fIid\fR\fB)\fR +\fI$string\fR \fB=\fR \fIpool\fR\fB\->id2str(\fR\fI$id\fR\fB)\fR; +\fIstring\fR \fB=\fR \fIpool\fR\fB\&.id2str(\fR\fIid\fR\fB)\fR +\fIstring\fR \fB=\fR \fIpool\fR\fB\&.id2str(\fR\fIid\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Convert a string into an Id and back\&. If the string is currently not in the pool and \fIcreate\fR is false, zero is returned\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBId rel2id(Id\fR \fIname\fR\fB, Id\fR \fIevr\fR\fB, int\fR \fIflags\fR\fB, bool\fR \fIcreate\fR\fB=1)\fR +my \fI$id\fR \fB=\fR \fIpool\fR\fB\->rel2id(\fR\fI$nameid\fR\fB,\fR \fI$evrid\fR\fB,\fR \fI$flags\fR\fB)\fR; +\fIid\fR \fB=\fR \fIpool\fR\fB\&.rel2id(\fR\fInameid\fR\fB,\fR \fIevrid\fR\fB,\fR \fIflags\fR\fB)\fR +\fIid\fR \fB=\fR \fIpool\fR\fB\&.rel2id(\fR\fInameid\fR\fB,\fR \fIevrid\fR\fB,\fR \fIflags\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Create a \(lqrelational\(rq dependency\&. Such dependencies consist of a name part, the \fIflags\fR describing the relation, and a version part\&. The flags are: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fB$solv::REL_EQ | $solv::REL_GT | $solv::REL_LT\fR +\fBsolv\&.REL_EQ | solv\&.REL_GT | solv\&.REL_LT\fR +\fBSolv::REL_EQ | Solv::REL_GT | Solv::REL_LT\fR +.fi +.if n \{\ +.RE +.\} +.sp +Thus, if you want a \(lq<=\(rq relation, you would use \fBREL_LT | REL_EQ\fR\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBId id2langid(Id\fR \fIid\fR\fB, const char *\fR\fIlang\fR\fB, bool\fR \fIcreate\fR\fB=1)\fR +my \fI$id\fR \fB=\fR \fI$pool\fR\fB\->id2langid(\fR\fI$id\fR\fB,\fR \fI$language\fR\fB)\fR; +\fIid\fR \fB=\fR \fIpool\fR\fB\&.id2langid(\fR\fIid\fR\fB,\fR \fIlanguage\fR\fB)\fR +\fIid\fR \fB=\fR \fIpool\fR\fB\&.id2langid(\fR\fIid\fR\fB,\fR \fIlanguage\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Create a language specific Id from some other id\&. This function simply converts the id into a string, appends a dot and the specified language to the string and converts the result back into an Id\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBconst char *dep2str(Id\fR \fIid\fR\fB)\fR +\fI$string\fR \fB=\fR \fIpool\fR\fB\->dep2str(\fR\fI$id\fR\fB)\fR; +\fIstring\fR \fB=\fR \fIpool\fR\fB\&.dep2str(\fR\fIid\fR\fB)\fR +\fIstring\fR \fB=\fR \fIpool\fR\fB\&.dep2str(\fR\fIid\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Convert a dependency id into a string\&. If the id is just a string, this function has the same effect as id2str()\&. For relational dependencies, the result is the correct \(lqname relation evr\(rq string\&. +.SH "THE DEPENDENCY CLASS" +.sp +The dependency class is an object orientated way to work with strings and dependencies\&. Internally, dependencies are represented as Ids, i\&.e\&. simple numbers\&. Dependency objects can be constructed by using the Pool\(cqs Dep() method\&. +.SS "ATTRIBUTES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBPool *pool;\fR /* read only */ +\fI$dep\fR\fB\->{\*(Aqpool\*(Aq}\fR +\fIdep\fR\fB\&.pool\fR +\fIdep\fR\fB\&.pool\fR +.fi +.if n \{\ +.RE +.\} +.sp +Back reference to the pool this dependency belongs to\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBId id;\fR /* read only */ +\fI$dep\fR\fB\->{\*(Aqid\*(Aq}\fR +\fIdep\fR\fB\&.id\fR +\fIdep\fR\fB\&.id\fR +.fi +.if n \{\ +.RE +.\} +.sp +The id of this dependency\&. +.SH "METHODS" +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBDep *Rel(int\fR \fIflags\fR\fB, DepId\fR \fIevrid\fR\fB, bool\fR \fIcreate\fR\fB=1)\fR +my \fI$reldep\fR \fB=\fR \fI$dep\fR\fB\->Rel(\fR\fI$flags\fR\fB,\fR \fI$evrdep\fR\fB)\fR; +\fIreldep\fR \fB=\fR \fIdep\fR\fB\&.Rel(\fR\fIflags\fR\fB,\fR \fIevrdep\fR\fB)\fR +\fIreldep\fR \fB=\fR \fIdep\fR\fB\&.Rel(\fR\fIflags\fR\fB,\fR \fIevrdep\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Create a relational dependency from to string dependencies and a flags argument\&. See the pool\(cqs rel2id method for a description of the flags\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBSelection *Selection_name(int\fR \fIsetflags\fR \fB= 0)\fR +my \fI$sel\fR \fB=\fR \fI$dep\fR\fB\->Selection_name()\fR; +\fIsel\fR \fB=\fR \fIdep\fR\fB\&.Selection_name()\fR +\fIsel\fR \fB=\fR \fIdep\fR\fB\&.Selection_name()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Create a Selection from a dependency\&. The selection consists of all packages that have a name equal to the dependency\&. If the dependency is of a relational type, the packages version must also fulfill the dependency\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBSelection *Selection_provides(int\fR \fIsetflags\fR \fB= 0)\fR +my \fI$sel\fR \fB=\fR \fI$dep\fR\fB\->Selection_provides()\fR; +\fIsel\fR \fB=\fR \fIdep\fR\fB\&.Selection_provides()\fR +\fIsel\fR \fB=\fR \fIdep\fR\fB\&.Selection_provides()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Create a Selection from a dependency\&. The selection consists of all packages that have at least one provides matching the dependency\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBconst char *str()\fR +my \fI$str\fR \fB=\fR \fI$dep\fR\fB\->str()\fR; +\fIstr\fR \fB=\fR \fI$dep\fR\fB\&.str()\fR +\fIstr\fR \fB=\fR \fI$dep\fR\fB\&.str()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Return a string describing the dependency\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fB\fR +my \fI$str\fR \fB= "\fR\fI$dep\fR\fB"\fR; +\fIstr\fR \fB= str(\fR\fIdep\fR\fB)\fR +\fIstr\fR \fB=\fR \fIdep\fR\fB\&.to_s\fR +.fi +.if n \{\ +.RE +.\} +.sp +Same as calling the str() method\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fB\fR +\fBif (\fR\fI$dep1\fR \fB==\fR \fI$dep2\fR\fB)\fR +\fBif\fR \fIdep1\fR \fB==\fR \fIdep2\fR\fB:\fR +\fBif\fR \fIdep1\fR \fB==\fR \fIdep2\fR +.fi +.if n \{\ +.RE +.\} +.sp +The dependencies are equal if they are part of the same pool and have the same ids\&. +.SH "THE REPOSITORY CLASS" +.sp +A Repository describes a group of packages, normally comming from the same source\&. Repositories are created by the Pool\(cqs add_repo() method\&. +.SS "ATTRIBUTES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBPool *pool;\fR /* read only */ +\fI$repo\fR\fB\->{\*(Aqpool\*(Aq}\fR +\fIrepo\fR\fB\&.pool\fR +\fIrepo\fR\fB\&.pool\fR +.fi +.if n \{\ +.RE +.\} +.sp +Back reference to the pool this dependency belongs to\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBId id;\fR /* read only */ +\fI$repo\fR\fB\->{\*(Aqid\*(Aq}\fR +\fIrepo\fR\fB\&.id\fR +\fIrepo\fR\fB\&.id\fR +.fi +.if n \{\ +.RE +.\} +.sp +Return the id of the repository\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBconst char *name;\fR /* read/write */ +\fI$repo\fR\fB\->{\*(Aqname\*(Aq}\fR +\fIrepo\fR\fB\&.name\fR +\fIrepo\fR\fB\&.name\fR +.fi +.if n \{\ +.RE +.\} +.sp +The repositories name\&. To libsolv, the name is just a string with no specific meaning\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBint prioprity;\fR /* read/write */ +\fI$repo\fR\fB\->{\*(Aqpriority\*(Aq}\fR +\fIrepo\fR\fB\&.priority\fR +\fIrepo\fR\fB\&.priority\fR +.fi +.if n \{\ +.RE +.\} +.sp +The priority of the repository\&. A higher number means that packages of this repository will be chosen over other repositories, even if they have a greater package version\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBint subprioprity;\fR /* read/write */ +\fI$repo\fR\fB\->{\*(Aqsubpriority\*(Aq}\fR +\fIrepo\fR\fB\&.subpriority\fR +\fIrepo\fR\fB\&.subpriority\fR +.fi +.if n \{\ +.RE +.\} +.sp +The sub\-priority of the repository\&. This value is compared when the priorities of two repositories are the same\&. It is useful to make the library prefer on\-disk repositories to remote ones\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBint nsolvables;\fR /* read only */ +\fI$repo\fR\fB\->{\*(Aqnsolvables\*(Aq}\fR +\fIrepo\fR\fB\&.nsolvables\fR +\fIrepo\fR\fB\&.nsolvables\fR +.fi +.if n \{\ +.RE +.\} +.sp +The number of solvables in this repository\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid *appdata;\fR /* read/write */ +\fI$repo\fR\fB\->{\*(Aqappdata\*(Aq}\fR +\fIrepo\fR\fB\&.appdata\fR +\fIrepo\fR\fB\&.appdata\fR +.fi +.if n \{\ +.RE +.\} +.sp +Application specific data that may be used in any way by the code using the repository\&. +.SS "CONSTANTS" +.PP +\fBREPO_REUSE_REPODATA\fR +.RS 4 +Reuse the last repository data aera (\(lqrepodata\(rq) instead of creating a new one\&. +.RE +.PP +\fBREPO_NO_INTERNALIZE\fR +.RS 4 +Do not internalize the added repository data\&. This is useful if you plan to add more data because internalization is a costly operation\&. +.RE +.PP +\fBREPO_LOCALPOOL\fR +.RS 4 +Use the repodata\(cqs pool for Id storage instead of the global pool\&. Useful if you don\(cqt want to pollute the global pool with many unneeded ids, like when storing the filelist\&. +.RE +.PP +\fBREPO_USE_LOADING\fR +.RS 4 +Use the repodata that is currently being loaded instead of creating a new one\&. This only makes sense if used in a load callback\&. +.RE +.PP +\fBREPO_EXTEND_SOLVABLES\fR +.RS 4 +Do not create new solvables for the new data, but match existing solvables and add the data to them\&. Repository metadata is often split into multiple parts, with one primary file describing all packages and other parts holding information that is normally not needed, like the changelog\&. +.RE +.PP +\fBREPO_USE_ROOTDIR\fR +.RS 4 +Prepend the pool\(cqs rootdir to the path when doing file operations\&. +.RE +.PP +\fBREPO_NO_LOCATION\fR +.RS 4 +Do not add a location element to the solvables\&. Useful if the solvables are not in the final position, so you can add the correct location later in your code\&. +.RE +.PP +\fBSOLV_ADD_NO_STUBS\fR +.RS 4 +Do not create stubs for repository parts that can be downloaded on demand\&. +.RE +.PP +\fBSUSETAGS_RECORD_SHARES\fR +.RS 4 +This is specific to the add_susetags() method\&. Susetags allows to refer to already read packages to save disk space\&. If this data sharing needs to work over multiple calls to add_susetags, you need to specify this flag so that the share information is made available to subsequent calls\&. +.RE +.SS "METHODS" +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid free(bool\fR \fIreuseids\fR \fB= 0)\fR +\fI$repo\fR\fB\->free()\fR; +\fIrepo\fR\fB\&.free()\fR +\fIrepo\fR\fB\&.free()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Free the repository and all solvables it contains\&. If \fIreuseids\fR is set to true, the solvable ids and the repository id may be reused by the library when added new solvables\&. Thus you should leave it false if you are not sure that somebody holds a reference\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid empty(bool\fR \fIreuseids\fR \fB= 0)\fR +\fI$repo\fR\fB\->empty()\fR; +\fIrepo\fR\fB\&.empty()\fR +\fIrepo\fR\fB\&.empty()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Free all the solvables in a repository\&. The repository will be empty after this call\&. See the free() method for the meaning of \fIreuseids\fR\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool isempty()\fR +\fI$repo\fR\fB\->isempty()\fR +\fIrepo\fR\fB\&.empty()\fR +\fIrepo\fR\fB\&.empty?\fR +.fi +.if n \{\ +.RE +.\} +.sp +Return true if there are no solvables in this repository\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid internalize()\fR +\fI$repo\fR\fB\->internalize()\fR; +\fIrepo\fR\fB\&.internalize()\fR +\fIrepo\fR\fB\&.internalize()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Internalize added data\&. Data must be internalized before it is available to the lookup and data iterator functions\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool write(FILE *\fR\fIfp\fR\fB)\fR +\fI$repo\fR\fB\->write(\fR\fI$fp\fR\fB)\fR +\fIrepo\fR\fB\&.write(\fR\fIfp\fR\fB)\fR +\fIrepo\fR\fB\&.write(\fR\fIfp\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Write a repo as a \(lqsolv\(rq file\&. These files can be read very fast and thus are a good way to cache repository data\&. Returns false if there was some error writing the file\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBSolvableiterator *solvables_iter()\fR +\fBfor my\fR \fI$solvable\fR \fB(\fR\fI@\fR\fB{\fR\fI$repo\fR\fB\->solvables_iter()})\fR +\fBfor\fR \fIsolvable\fR \fBin\fR \fIrepo\fR\fB\&.solvables_iter():\fR +\fBfor\fR \fIsolvable\fR \fBin\fR \fIrepo\fR\fB\&.solvables_iter()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Iterate over all solvables in a repository\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBRepodata *add_repodata(int\fR \fIflags\fR \fB= 0)\fR +my \fI$repodata\fR \fB=\fR \fI$repo\fR\fB\->add_repodata()\fR; +\fIrepodata\fR \fB=\fR \fIrepo\fR\fB\&.add_repodata()\fR +\fIrepodata\fR \fB=\fR \fIrepo\fR\fB\&.add_repodata()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add a new repodata area to the repository\&. This is normally automatically done by the repo_add methods, so you need this method only in very rare circumstances\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid create_stubs()\fR +\fI$repo\fR\fB\->create_stubs()\fR; +\fIrepo\fR\fB\&.create_stubs()\fR +\fIrepo\fR\fB\&.create_stubs()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Calls the create_stubs() repodata method for the last repodata of the repository\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool iscontiguous()\fR +\fI$repo\fR\fB\->iscontiguous()\fR +\fIrepo\fR\fB\&.iscontiguous()\fR +\fIrepo\fR\fB\&.iscontiguous?\fR +.fi +.if n \{\ +.RE +.\} +.sp +Return true if the solvables of this repository are all in a single block with no holes, i\&.e\&. they have consecutive ids\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBRepodata *first_repodata()\fR +my \fI$repodata\fR \fB=\fR \fI$repo\fR\fB\->first_repodata()\fR; +\fIrepodata\fR \fB=\fR \fIrepo\fR\fB\&.first_repodata()\fR +\fIrepodata\fR \fB=\fR \fIrepo\fR\fB\&.first_repodata()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Checks if all repodatas but the first repodata are extensions, and return the first repodata if this is the case\&. Useful if you want to do a store/retrive sequence on the repository to reduce the memory using and enable paging, as this does not work if the rpository contains multiple non\-extension repodata areas\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBSelection *Selection(int\fR \fIsetflags\fR \fB= 0)\fR +my \fI$sel\fR \fB=\fR \fI$repo\fR\fB\->Selection()\fR; +\fIsel\fR \fB=\fR \fIrepo\fR\fB\&.Selection()\fR +\fIsel\fR \fB=\fR \fIrepo\fR\fB\&.Selection()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Create a Selection consisting of all packages in the repository\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBDataiterator *Dataiterator(Id\fR \fIp\fR\fB, Id\fR \fIkey\fR\fB, const char *\fR\fImatch\fR\fB, int\fR \fIflags\fR\fB)\fR +my \fI$di\fR \fB=\fR \fI$repo\fR\fB\->Dataiterator(\fR\fI$solvid\fR\fB,\fR \fI$keyname\fR\fB,\fR \fI$match\fR\fB,\fR \fI$flags\fR\fB)\fR; +\fIdi\fR \fB=\fR \fIrepo\fR\fB\&.Dataiterator(\fR\fIsolvid\fR\fB,\fR \fIkeyname\fR\fB,\fR \fImatch\fR\fB,\fR \fIflags\fR\fB)\fR +\fIdi\fR \fB=\fR \fIrepo\fR\fB\&.Dataiterator(\fR\fIsolvid\fR\fB,\fR \fIkeyname\fR\fB,\fR \fImatch\fR\fB,\fR \fIflags\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBfor my\fR \fI$d\fR \fB(\fR\fI@$di\fR\fB)\fR +\fBfor\fR \fId\fR \fBin\fR \fIdi\fR\fB:\fR +\fBfor\fR \fId\fR \fBin\fR \fIdi\fR +.fi +.if n \{\ +.RE +.\} +.sp +Iterate over the matching data elements in this repository\&. See the Dataiterator class for more information\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fB\fR +my \fI$str\fR \fB= "\fR\fI$repo\fR\fB"\fR; +\fIstr\fR \fB= str(\fR\fIrepo\fR\fB)\fR +\fIstr\fR \fB=\fR \fIrepo\fR\fB\&.to_s\fR +.fi +.if n \{\ +.RE +.\} +.sp +Return the name of the repository, or "Repo#" if no name is set\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fB\fR +\fBif (\fR\fI$repo1\fR \fB==\fR \fI$repo2\fR\fB)\fR +\fBif\fR \fIrepo1\fR \fB==\fR \fIrepo2\fR\fB:\fR +\fBif\fR \fIrepo1\fR \fB==\fR \fIrepo2\fR +.fi +.if n \{\ +.RE +.\} +.sp +Two repositories are equal if they belong to the same pool and have the same id\&. +.SS "LOOKUP FUNCTIONS" +.sp +Those functions can be used to retrieve information from a repository\&. For Package data lookups the methods in the Solvable class are prefered, so you probably only need this funcions to lookup repository meta information with \fBSOLVID_META\fR\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBconst char *lookup_str(Id\fR \fIsolvid\fR\fB, Id\fR \fIkeyname\fR\fB)\fR +my \fI$str\fR \fB=\fR \fI$repo\fR\fB\->lookup_str(\fR\fI$solvid\fR\fB,\fR \fI$keyname\fR\fB)\fR; +\fIstr\fR \fB=\fR \fIrepo\fR\fB\&.lookup_str(\fR\fIsolvid\fR\fB,\fR \fIkeyname\fR\fB)\fR +\fIstr\fR \fB=\fR \fIrepo\fR\fB\&.lookup_str(\fR\fIsolvid\fR\fB,\fR \fIkeyname\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Lookup a string from the \fIkeyname\fR entry specified with \fIsolvid\fR\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBId lookup_id(Id\fR \fIsolvid\fR\fB, Id\fR \fIkeyname\fR\fB)\fR +my \fI$id\fR \fB=\fR \fI$repo\fR\fB\->lookup_id(\fR\fI$solvid\fR\fB,\fR \fI$keyname\fR\fB)\fR; +\fIid\fR \fB=\fR \fIrepo\fR\fB\&.lookup_id(\fR\fIsolvid\fR\fB,\fR \fIkeyname\fR\fB)\fR +\fIid\fR \fB=\fR \fIrepo\fR\fB\&.lookup_id(\fR\fIsolvid\fR\fB,\fR \fIkeyname\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Lookup an Id from the \fIkeyname\fR entry specified with \fIsolvid\fR\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBunsigned long long lookup_num(Id\fR \fIsolvid\fR\fB, Id\fR \fIkeyname\fR\fB, unsigned long long\fR \fInotfound\fR \fB= 0)\fR +my \fI$num\fR \fB=\fR \fI$repo\fR\fB\->lookup_num(\fR\fI$solvid\fR\fB,\fR \fI$keyname\fR\fB)\fR; +\fInum\fR \fB=\fR \fIrepo\fR\fB\&.lookup_num(\fR\fIsolvid\fR\fB,\fR \fIkeyname\fR\fB)\fR +\fInum\fR \fB=\fR \fIrepo\fR\fB\&.lookup_num(\fR\fIsolvid\fR\fB,\fR \fIkeyname\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Lookup a number from the \fIkeyname\fR entry specified with \fIsolvid\fR\&. +.SS "DATA ADD METHODS" +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBSolvable *add_solvable()\fR +\fI$repo\fR\fB\->add_solvable()\fR; +\fIrepo\fR\fB\&.add_solvable()\fR +\fIrepo\fR\fB\&.add_solvable()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add a single empty solvable to the repository\&. Returns a Solvable object, see the Solvable class for more information\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool add_solv(const char *\fR\fIname\fR\fB, int\fR \fIflags\fR \fB= 0)\fR +\fI$repo\fR\fB\->add_solv(\fR\fI$name\fR\fB,\fR \fI$flags\fR\fB)\fR; +\fIrepo\fR\fB\&.add_solv(\fR\fIname\fR\fB,\fR \fIflags\fR\fB)\fR +\fIrepo\fR\fB\&.add_solv(\fR\fIname\fR\fB,\fR \fIflags\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool add_solv(FILE *\fR\fIfp\fR\fB, int\fR \fIflags\fR \fB= 0)\fR +\fI$repo\fR\fB\->add_solv(\fR\fI$fp\fR\fB,\fR \fI$flags\fR\fB)\fR; +\fIrepo\fR\fB\&.add_solv(\fR\fIfp\fR\fB,\fR \fIflags\fR\fB)\fR +\fIrepo\fR\fB\&.add_solv(\fR\fIfp\fR\fB,\fR \fIflags\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Read a \(lqsolv\(rq file and add its contents to the repository\&. These files can be written with the write() method and are normally used as fast cache for repository metadata\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool add_rpmdb(int\fR \fIflags\fR \fB= 0)\fR +\fI$repo\fR\fB\->add_rpmdb(\fR\fI$flags\fR\fB)\fR; +\fIrepo\fR\fB\&.add_rpmdb(\fR\fIflags\fR\fB)\fR +\fIrepo\fR\fB\&.add_rpmdb(\fR\fIflags\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool add_rpmdb_reffp(FILE *\fR\fIreffp\fR\fB, int\fR \fIflags\fR \fB= 0)\fR +\fI$repo\fR\fB\->add_rpmdb_reffp(\fR\fI$reffp\fR\fB,\fR \fI$flags\fR\fB)\fR; +\fIrepo\fR\fB\&.add_rpmdb_reffp(\fR\fI$reffp\fR\fB,\fR \fIflags\fR\fB)\fR +\fIrepo\fR\fB\&.add_rpmdb_reffp(\fR\fI$reffp\fR\fB,\fR \fIflags\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add the contents of the rpm database to the repository\&. If a solv file containing an old version of the database is available, it can be passed as reffp to speed up reading\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool add_rpm(const char *\fR\fIname\fR\fB, int\fR \fIflags\fR \fB= 0)\fR +\fI$repo\fR\fB\->add_rpm(\fR\fI$name\fR\fB,\fR \fI$flags\fR\fB)\fR; +\fIrepo\fR\fB\&.add_rpm(\fR\fIname\fR\fB,\fR \fIflags\fR\fB)\fR +\fIrepo\fR\fB\&.add_rpm(\fR\fIname\fR\fB,\fR \fIflags\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add the metadata of a single rpm package to the repository\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool add_rpmdb_pubkeys(int\fR \fIflags\fR \fB= 0)\fR +\fI$repo\fR\fB\->add_rpmdb_pubkeys()\fR; +\fIrepo\fR\fB\&.add_rpmdb_pubkeys()\fR +\fIrepo\fR\fB\&.add_rpmdb_pubkeys()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add all pubkeys contained in the rpm database to the repository\&. Note that newer rpm versions also allow to store the pubkeys in some directory instead of the rpm database\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool add_pubkey(const char *\fR\fIkeyfile\fR\fB, int\fR \fIflags\fR \fB= 0)\fR +\fI$repo\fR\fB\->add_pubkey(\fR\fI$keyfile\fR\fB)\fR; +\fIrepo\fR\fB\&.add_pubkey(\fR\fI$keyfile\fR\fB)\fR +\fIrepo\fR\fB\&.add_pubkey(\fR\fI$keyfile\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add a pubkey from a file to the repository\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool add_rpmmd(FILE *\fR\fIfp\fR\fB, const char *\fR\fIlanguage\fR\fB, int\fR \fIflags\fR \fB= 0)\fR +\fI$repo\fR\fB\->add_rpmmd(\fR\fI$fp\fR\fB,\fR \fI$language\fR\fB)\fR; +\fIrepo\fR\fB\&.add_rpmmd(\fR\fIfp\fR\fB,\fR \fIlanguage\fR\fB)\fR +\fIrepo\fR\fB\&.add_rpmmd(\fR\fIfp\fR\fB,\fR \fIlanguage\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add metadata stored in the "rpm\-md" format (i\&.e\&. from files in the \(lqrepodata\(rq directory) to a repository\&. Supported files are "primary", "filelists", "other", "suseinfo"\&. Do not forget to specify the \fBREPO_EXTEND_SOLVABLES\fR for extension files like "filelists" and "other"\&. Use the \fIlanguage\fR parameter if you have language extension files, otherwise simply use a \fBundef\fR/\fBNone\fR/\fBnil\fR parameter\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool add_repomdxml(FILE *\fR\fIfp\fR\fB, int\fR \fIflags\fR \fB= 0)\fR +\fI$repo\fR\fB\->add_repomdxml(\fR\fI$fp\fR\fB)\fR; +\fIrepo\fR\fB\&.add_repomdxml(\fR\fIfp\fR\fB)\fR +\fIrepo\fR\fB\&.add_repomdxml(\fR\fIfp\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add the repomd\&.xml meta description from the "rpm\-md" format to the repository\&. This file contains information about the repository like keywords, and also a list of all database files with checksums\&. The data is added the the "meta" section of the repository, i\&.e\&. no package gets created\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool add_updateinfoxml(FILE *\fR\fIfp\fR\fB, int\fR \fIflags\fR \fB= 0)\fR +\fI$repo\fR\fB\->add_updateinfoxml(\fR\fI$fp\fR\fB)\fR; +\fIrepo\fR\fB\&.add_updateinfoxml(\fR\fIfp\fR\fB)\fR +\fIrepo\fR\fB\&.add_updateinfoxml(\fR\fIfp\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add the updateinfo\&.xml file containing available maintenance updates to the repository\&. All updates are created as special packages that have a "patch:" prefix in their name\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool add_deltainfoxml(FILE *\fR\fIfp\fR\fB, int\fR \fIflags\fR \fB= 0)\fR +\fI$repo\fR\fB\->add_deltainfoxml(\fR\fI$fp\fR\fB)\fR; +\fIrepo\fR\fB\&.add_deltainfoxml(\fR\fIfp\fR\fB)\fR +\fIrepo\fR\fB\&.add_deltainfoxml(\fR\fIfp\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add the deltainfo\&.xml file (also called prestodelta\&.xml) containing available delta\-rpms to the repository\&. The data is added to the "meta" section, i\&.e\&. no package gets created\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool add_debdb(int\fR \fIflags\fR \fB= 0)\fR +\fI$repo\fR\fB\->add_debdb()\fR; +\fIrepo\fR\fB\&.add_debdb()\fR +\fIrepo\fR\fB\&.add_debdb()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add the contents of the debian installed package database to the repository\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool add_debpackages(FILE *\fR\fIfp\fR\fB, int\fR \fIflags\fR \fB= 0)\fR +\fI$repo\fR\fB\->add_debpackages(\fR\fI$fp\fR\fB)\fR; +\fIrepo\fR\fB\&.add_debpackages(\fR\fI$fp\fR\fB)\fR +\fIrepo\fR\fB\&.add_debpackages(\fR\fI$fp\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add the contents of the debian repository metadata (the "packages" file) to the repository\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool add_deb(const char *\fR\fIfilename\fR\fB, int\fR \fIflags\fR \fB= 0)\fR +\fI$repo\fR\fB\->add_deb(\fR\fI$filename\fR\fB)\fR; +\fIrepo\fR\fB\&.add_deb(\fR\fIfilename\fR\fB)\fR +\fIrepo\fR\fB\&.add_deb(\fR\fIfilename\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add the metadata of a single deb package to the repository\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool add_mdk(FILE *\fR\fIfp\fR\fB, int\fR \fIflags\fR \fB= 0)\fR +\fI$repo\fR\fB\->add_mdk(\fR\fI$fp\fR\fB)\fR; +\fIrepo\fR\fB\&.add_mdk(\fR\fI$fp\fR\fB)\fR +\fIrepo\fR\fB\&.add_mdk(\fR\fI$fp\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add the contents of the mageia/mandriva repository metadata (the "synthesis\&.hdlist" file) to the repository\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool add_mdk_info(FILE *\fR\fIfp\fR\fB, int\fR \fIflags\fR \fB= 0)\fR +\fI$repo\fR\fB\->add_mdk(\fR\fI$fp\fR\fB)\fR; +\fIrepo\fR\fB\&.add_mdk(\fR\fI$fp\fR\fB)\fR +\fIrepo\fR\fB\&.add_mdk(\fR\fI$fp\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Extend the packages from the synthesis file with the info\&.xml and files\&.xml data\&. Do not forget to specify \fBREPO_EXTEND_SOLVABLES\fR\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool add_arch_repo(FILE *\fR\fIfp\fR\fB, int\fR \fIflags\fR \fB= 0)\fR +\fI$repo\fR\fB\->add_arch_repo(\fR\fI$fp\fR\fB)\fR; +\fIrepo\fR\fB\&.add_arch_repo(\fR\fI$fp\fR\fB)\fR +\fIrepo\fR\fB\&.add_arch_repo(\fR\fI$fp\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add the contents of the archlinux repository metadata (the "\&.db\&.tar" file) to the repository\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool add_arch_local(const char *\fR\fIdir\fR\fB, int\fR \fIflags\fR \fB= 0)\fR +\fI$repo\fR\fB\->add_arch_local(\fR\fI$dir\fR\fB)\fR; +\fIrepo\fR\fB\&.add_arch_local(\fR\fI$dir\fR\fB)\fR +\fIrepo\fR\fB\&.add_arch_local(\fR\fI$dir\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add the contents of the archlinux installed package database to the repository\&. The \fIdir\fR parameter is usually set to "/var/lib/pacman/local"\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool add_content(FILE *\fR\fIfp\fR\fB, int\fR \fIflags\fR \fB= 0)\fR +\fI$repo\fR\fB\->add_content(\fR\fI$fp\fR\fB)\fR; +\fIrepo\fR\fB\&.add_content(\fR\fIfp\fR\fB)\fR +\fIrepo\fR\fB\&.add_content(\fR\fIfp\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add the \(lqcontent\(rq meta description from the susetags format to the repository\&. This file contains information about the repository like keywords, and also a list of all database files with checksums\&. The data is added the the "meta" section of the repository, i\&.e\&. no package gets created\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool add_susetags(FILE *\fR\fIfp\fR\fB, Id\fR \fIdefvendor\fR\fB, const char *\fR\fIlanguage\fR\fB, int\fR \fIflags\fR \fB= 0)\fR +\fI$repo\fR\fB\->add_susetags(\fR\fI$fp\fR\fB,\fR \fI$defvendor\fR\fB,\fR \fI$language\fR\fB)\fR; +\fIrepo\fR\fB\&.add_susetags(\fR\fIfp\fR\fB,\fR \fIdefvendor\fR\fB,\fR \fIlanguage\fR\fB)\fR +\fIrepo\fR\fB\&.add_susetags(\fR\fIfp\fR\fB,\fR \fIdefvendor\fR\fB,\fR \fIlanguage\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add repository metadata in the susetags format to the repository\&. Like with add_rpmmd, you can specify a language if you have language extension files\&. The \fIdefvendor\fR parameter provides a default vendor for packages with missing vendors, it is usually provided in the content file\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool add_products(const char *\fR\fIdir\fR\fB, int\fR \fIflags\fR \fB= 0)\fR +\fI$repo\fR\fB\->add_products(\fR\fI$dir\fR\fB)\fR; +\fIrepo\fR\fB\&.add_products(\fR\fIdir\fR\fB)\fR +\fIrepo\fR\fB\&.add_products(\fR\fIdir\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add the installed SUSE products database to the repository\&. The \fIdir\fR parameter is usually "/etc/products\&.d"\&. +.SH "THE SOLVABLE CLASS" +.sp +xxx +.SH "THE DATAITERATOR CLASS" +.sp +xxx +.SH "THE SELECTION CLASS" +.sp +xxx +.SH "THE JOB CLASS" +.sp +xxx +.SH "THE SOLVER CLASS" +.sp +xxx +.SH "THE TRANSACTION CLASS" +.sp +xxx +.SH "CHECKSUMS" +.sp +Checksums (also called hashes) are used to make sure that downloaded data is not corrupt and also as a fingerprint mechanism to check if data has changed\&. +.SS "CLASS METHODS" +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBChksum *Chksum(Id\fR \fItype\fR\fB)\fR +my \fI$chksum\fR \fB= solv\&.Chksum\->new(\fR\fI$type\fR\fB)\fR; +\fIchksum\fR \fB= solv\&.Chksum(\fR\fItype\fR\fB)\fR +\fIchksum\fR \fB= solv\&.Chksum\&.new(\fR\fItype\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Create a checksum object\&. Currently the following types are supported: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBREPOKEY_TYPE_MD5\fR +\fBREPOKEY_TYPE_SHA1\fR +\fBREPOKEY_TYPE_SHA256\fR +.fi +.if n \{\ +.RE +.\} +.sp +These keys are constants in the \fBsolv\fR class\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBChksum *Chksum(Id\fR \fItype\fR\fB, const char *\fR\fIhex\fR\fB)\fR +my \fI$chksum\fR \fB= solv\&.Chksum\->new(\fR\fI$type\fR\fB,\fR \fI$hex\fR\fB)\fR; +\fIchksum\fR \fB= solv\&.Chksum(\fR\fItype\fR\fB,\fR \fIhex\fR\fB)\fR +\fIchksum\fR \fB= solv\&.Chksum\&.new(\fR\fItype\fR\fB,\fR \fIhex\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Create an already finalized checksum object\&. +.SS "ATTRIBUTES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBId type;\fR /* read only */ +\fI$chksum\fR\fB\->{\*(Aqtype\*(Aq}\fR +\fIchksum\fR\fB\&.type\fR +\fIchksum\fR\fB\&.type\fR +.fi +.if n \{\ +.RE +.\} +.sp +Return the type of the checksum object\&. +.SS "METHODS" +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid add(const char *\fR\fIstr\fR\fB)\fR +\fI$chksum\fR\fB\->add(\fR\fI$str\fR\fB)\fR; +\fIchksum\fR\fB\&.add(\fR\fIstr\fR\fB)\fR +\fIchksum\fR\fB\&.add(\fR\fIstr\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add a string to the checksum\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid add_fp(FILE *\fR\fIfp\fR\fB)\fR +\fI$chksum\fR\fB\->add_fp(\fR\fI$file\fR\fB)\fR; +\fIchksum\fR\fB\&.add_fp(\fR\fIfile\fR\fB)\fR +\fIchksum\fR\fB\&.add_fp(\fR\fIfile\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add the contents of a file to the checksum\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid add_stat(const char *\fR\fIfilename\fR\fB)\fR +\fI$chksum\fR\fB\->add_stat(\fR\fI$filename\fR\fB)\fR; +\fIchksum\fR\fB\&.add_stat(\fR\fIfilename\fR\fB)\fR +\fIchksum\fR\fB\&.add_stat(\fR\fIfilename\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Stat the file and add the dev/ino/size/mtime member to the checksum\&. If the stat fails, the members are zeroed\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid add_fstat(int\fR \fIfd\fR\fB)\fR +\fI$chksum\fR\fB\->add_fstat(\fR\fI$fd\fR\fB)\fR; +\fIchksum\fR\fB\&.add_fstat(\fR\fIfd\fR\fB)\fR +\fIchksum\fR\fB\&.add_fstat(\fR\fIfd\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Same as add_stat, but instead of the filename a file descriptor is used\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBunsigned char *raw()\fR +my \fI$raw\fR \fB=\fR \fI$chksum\fR\fB\->raw()\fR; +\fIraw\fR \fB=\fR \fIchksum\fR\fB\&.raw()\fR +\fIraw\fR \fB=\fR \fIchksum\fR\fB\&.raw()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Finalize the checksum and return the result as raw bytes\&. This means that the result can contain zero bytes or unprintable characters\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBunsigned char *hex()\fR +my \fI$raw\fR \fB=\fR \fI$chksum\fR\fB\->hex()\fR; +\fIraw\fR \fB=\fR \fIchksum\fR\fB\&.hex()\fR +\fIraw\fR \fB=\fR \fIchksum\fR\fB\&.hex()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Finalize the checksum and return the result as hex string\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fB\fR +\fBif (\fR\fI$chksum1\fR \fB==\fR \fI$chksum2\fR\fB)\fR +\fBif\fR \fIchksum1\fR \fB==\fR \fIchksum2\fR\fB:\fR +\fBif\fR \fIchksum1\fR \fB==\fR \fIchksum2\fR +.fi +.if n \{\ +.RE +.\} +.sp +Checksums are equal if they are of the same type and the finalized results are the same\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fB\fR +my \fI$str\fR \fB= "\fR\fI$chksum\fR\fB"\fR; +\fIstr\fR \fB= str(\fR\fIchksum\fR\fB)\fR +\fIstr\fR \fB=\fR \fIchksum\fR\fB\&.to_s\fR +.fi +.if n \{\ +.RE +.\} +.sp +If the checksum is finished, the checksum is returned as ":" string\&. Otherwise ":unfinished" is returned\&. +.SH "FILE MANAGEMENT" +.sp +This functions were added because libsolv uses standard \fBFILE\fR pointers to read/write files, but languages like perl have their own implementation of files\&. The libsolv functions also support decompression and compression, the algorithm is selected by looking at the file name extension\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBFILE *xfopen(char *\fR\fIfn\fR\fB, char *\fR\fImode\fR \fB= "r")\fR +my \fI$file\fR \fB= solv::xfopen(\fR\fI$path\fR\fB)\fR; +\fIfile\fR \fB= solv\&.xfopen(\fR\fIpath\fR\fB)\fR +\fIfile\fR \fB= Solv::xfopen(\fR\fIpath\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Open a file at the specified path\&. The mode argument is passed on to the stdio library\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBFILE *xfopen_fd(char *\fR\fIfn\fR\fB, int\fR \fIfileno\fR\fB)\fR +my \fI$file\fR \fB= solv::xfopen_fd(\fR\fI$path\fR\fB,\fR \fI$fileno\fR\fB)\fR; +\fIfile\fR \fB= solv\&.xfopen_fd(\fR\fIpath\fR\fB,\fR \fIfileno\fR\fB)\fR +\fIfile\fR \fB= Solv::xfopen_fd(\fR\fIpath\fR\fB,\fR \fIfileno\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Create a file handle from the specified file descriptor\&. The path argument is only used to select the correct (de\-)compression algorithm, use an empty path if you want to make sure to read/write raw data\&. +.SS "METHODS" +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBint fileno()\fR +my \fI$fileno\fR \fB=\fR \fI$file\fR\fB\->fileno()\fR; +\fIfileno\fR \fB=\fR \fIfile\fR\fB\&.fileno()\fR +\fIfileno\fR \fB=\fR \fIfile\fR\fB\&.fileno()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Return file file descriptor of the file\&. If the file is not open, \-1 is returned\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBint dup()\fR +my \fI$fileno\fR \fB=\fR \fI$file\fR\fB\->dup()\fR; +\fIfileno\fR \fB=\fR \fIfile\fR\fB\&.dup()\fR +\fIfileno\fR \fB=\fR \fIfile\fR\fB\&.dup()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Return a copy of the descriptor of the file\&. If the file is not open, \-1 is returned\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool flush()\fR +\fI$file\fR\fB\->flush()\fR; +\fIfile\fR\fB\&.flush()\fR +\fIfile\fR\fB\&.flush()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Flush the file\&. Returns false if there was an error\&. Flushing a closed file always returns true\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool close()\fR +\fI$file\fR\fB\->close()\fR; +\fIfile\fR\fB\&.close()\fR +\fIfile\fR\fB\&.close()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Close the file\&. This is needed for languages like Ruby, that do not destruct objects right after they are no longer referenced\&. In that case, it is good style to close open files so that the file descriptors are freed right away\&. Returns false if there was an error\&. +.SH "THE REPODATACLASS" +.sp +xxx +.SH "AUTHOR" +.sp +Michael Schroeder diff --git a/doc/libsolv-bindings.txt b/doc/libsolv-bindings.txt new file mode 100644 index 0000000..22e3a57 --- /dev/null +++ b/doc/libsolv-bindings.txt @@ -0,0 +1,1150 @@ +LIBSOLV-BINDINGS(3) +=================== +:man manual: LIBSOLV +:man source: libsolv + + +NAME +---- +libsolv-bindings - access libsolv from perl/python/ruby + +DESCRIPTION +----------- +bla bla bla + +THE POOL +-------- + +The pool is libsolv's central resource manager. A pool +consists of Solvables, Repositories, Dependencies, each +indexed by Ids. + +=== CLASS METHODS === + + Pool *Pool() + my $pool = solv::Pool->new(); + pool = solv.Pool() + pool = Solv::Pool.new() + +Create a new pool instance. In most cases you just need +one pool. + +=== ATTRIBUTES === + + void *appdata; /* read/write */ + $pool->{'appdata'} + pool.appdata + pool.appdata + +Application specific data that may be used in any way by the +code using the pool. + + Solvable solvables[]; /* read only */ + my $solvable = $pool->{'solvables'}->[$solvid]; + solvable = pool.solvables[solvid] + solvable = pool.solvables[solvid] + +Look up a Solvable by its id. + + Repo repos[]; /* read only */ + my $repo = $pool->{'repos'}->[$repoid]; + repo = pool.repos[repoid] + repo = pool.repos[repoid] + +Look up a Repository by its id. + + Repo *installed; /* read/write */ + $pool->{'installed'} = $repo; + pool.installed = repo + pool.installed = repo + +Define which repository contains all the installed +packages. + +=== METHODS === + + void free() + $pool->free(); + pool.free() + pool.free() + +Free a pool. This is currently done with a method +instead of relying on reference counting or garbage +collection because it's hard to track every reference +to a pool. + + void setdebuglevel(int level) + $pool->setdebuglevel($level); + pool.setdebuglevel(level) + pool.setdebuglevel(level) + +Set the debug level. A value of zero means no debug output, +the higher the value, the more output is generated. + + int set_flag(int flag, int value) + my $oldvalue = $pool->set_flag($flag, $value); + oldvalue = pool.set_flag(flag, value) + oldvalue = pool.set_flag(flag, value) + + int get_flag(int flag) + my $value = $pool->get_flag($flag); + value = pool.get_flag(flag) + value = pool.get_flag(flag) + +Set/get a pool specific flag. The flags define how the +system works, e.g. how the package manager treats +obsoletes. The default flags should be sane for most +applications, but in some cases you may want to tweak +a flag, for example if you want to solv package +dependencies for some other system than yours. + + void set_rootdir(const char *rootdir) + $pool->set_rootdir(rootdir); + pool.set_rootdir(rootdir) + pool.set_rootdir(rootdir) + + const char *get_rootdir() + my $rootdir = $pool->get_rootdir(); + rootdir = pool.get_rootdir() + rootdir = pool.get_rootdir() + +Set/get the rootdir to use. This is useful if you want +package management to work only in some directory, for +example if you want to setup a chroot jail. Note that +the rootdir will only be prepended to file paths if +the *REPO_USE_ROOTDIR* flag is used. + + void setarch(const char *arch = 0) + $pool->setarch(); + pool.setarch() + pool.setarch() + +Set the architecture for your system. The architecture +is used to determine which packages are installable. It +defaults to the result of ``uname -m''. + + Repo *add_repo(const char *name) + $repo = $pool->add_repo($name); + repo = pool.add_repo(name) + repo = pool.add_repo(name) + +Add a Repository with the specified name to the pool. +The reposiory is empty on creation, use the repository +methods to populate it with packages. + + Repoiterator *repos_iter() + for my $repo (@{$pool->repos_iter()}) + for repo in pool.repos_iter(): + for repo in pool.repos_iter() + +Iterate over the existing repositories. + + Solvableiterator *solvables_iter() + for my $solvable (@{$pool->solvables_iter()}) + for solvable in pool.solvables_iter(): + for solvable in pool.solvables_iter() + +Iterate over the existing solvables. + + Dep *Dep(const char *str, bool create=1) + my $dep = $pool->Dep($string); + dep = pool.Dep(string) + dep = pool.Dep(string) + +Create an object describing a string or dependency. +If the string is currently not in the pool and +_create_ is false, *undef*/*None*/*nil* is returned. + + void addfileprovides() + $pool->addfileprovides(); + pool.addfileprovides() + pool.addfileprovides() + + Queue addfileprovides_queue() + my @ids = $pool->addfileprovides_queue(); + ids = pool.addfileprovides_queue() + ids = pool.addfileprovides_queue() + +Some package managers like rpm allow dependencies on +files contained in other packages. To allow libsolv +to deal with those dependencies in an efficient way, +you need to call the addfileprovides method after +creating and reading all repositories. This method +will scan all dependency for file names and than +scan all packages for matching files. If a filename +has been matched, it will be added to the provides +list of the corresponding package. +The addfileprovides_queue variant works the same +way but returns an array containing all file +dependencies. This information can be stored +with the repository to speed up the next usage of +the repository. + + void createwhatprovides() + $pool->createwhatprovides(); + pool.createwhatprovides() + pool.createwhatprovides() + +Create the internal ``whatprovides'' hash over all +of the provides of all packages. This method must +be called before doing any lookups on provides. +It's encuraged to do it right after all repos +are set up, usually right after the call to +addfileprovides(). + + Queue whatprovides(DepId dep) + my @solvables = $pool->whatprovides($dep); + solvables = pool.whatprovides(dep) + solvables = pool.whatprovides(dep) + +Return all solvables that provide the specified +dependency. You can use either a Dep object or +an simple Id as argument. + + Queue matchprovidingids(const char *match, int flags) + my @ids = $pool->matchprovidingids($match, $flags); + ids = pool.matchprovidingids(match, flags) + ids = pool.matchprovidingids(match, flags) + +Search the names of all provides and return the ones +matching the specified string. See the Dataiterator class +for the allowed flags. + + Id towhatprovides(Queue ids) + my $offset = $pool->towhatprovides(\@ids); + offset = pool.towhatprovides(ids) + offset = pool.towhatprovides(ids) + +``Internalize'' an array containing Ids. The returned +value can be used to create solver jobs working on +a specific set of packages. See the Solver class for +more information. + + bool isknownarch(DepId id) + my $bool = $pool->isknownarch($id); + bool = pool.isknownarch(id) + bool = pool.isknownarch?(id) + +Return true if the specified Id describs a known +architecture. + + Solver *Solver() + my $solver = $pool->Solver(); + solver = pool.Solver() + solver = pool.Solver() + +Create a new solver object. + + Solver *Job(int how, Id what) + my $job = $pool->Job($how, $what); + job = pool.Job(how, what) + job = pool.Job(how, what) + +Create a new Job object. Kind of low level, in most cases +you would use a Selection or Dep job constructor instead. + + Selection *Selection() + my $sel = $pool->Selection(); + sel = pool.Selection() + sel = pool.Selection() + +Create an empty selection. Useful as a starting point for +merging other selections. + + Selection *Selection_all() + my $sel = $pool->Selection_all(); + sel = pool.Selection_all() + sel = pool.Selection_all() + +Create a selection containing all packages. Useful as +starting point for intersecting other selections or +for update/distupgrade jobs. + + Selection *select(const char *name, int flags) + my $sel = $pool->select($name, $flags); + sel = pool.select(name, flags) + sel = pool.select(name, flags) + +Create a selection by matching packages against the +specified string. See the Selection class for a +list of flags and how to create solver jobs from +a selection. + + void setpooljobs(Jobs *jobs) + $pool->setpooljobs(\@jobs); + pool.setpooljobs(jobs) + pool.setpooljobs(jobs) + + Jobs *getpooljobs() + @jobs = $pool->getpooljobs(); + jobs = pool.getpooljobs() + jobs = pool.getpooljobs() + +Get/Set fixed jobs stored in the pool. Those jobs +are automatically appended to all solver jobs, they +are meant for fixed configurations like which +packages can be multiversion installed, which packages +were userinstalled or must not be erased. + + void set_loadcallback(Callable *callback) + $pool->setloadcallback(\&callbackfunction); + pool.setloadcallback(callbackfunction) + pool.setloadcallback { |repodata| ... } + +Set the callback function called when repository +metadata needs to be loaded on demand. To make use +of this feature, you need to create repodata stubs +that tell the library which data is available but +not loaded. If later on the data needs to be +accessed, the callback function is called with a +repodata argument. You can then load the data +(maybe fetching it first from an remote server). +The callback should return true if the data has +been made available. + +=== DATA RETRIEVAL METHODS === + +In the following functions, the _keyname_ argument +describes what to retrive. For the standard cases you +can use the available Id constants. For example, + + $solv::SOLVABLE_SUMMARY + solv.SOLVABLE_SUMMARY + Solv::SOLVABLE_SUMMARY + +selects the ``Summary'' entry of a solvable. The +_solvid_ argument selects the desired solvable by +Id. + + const char *lookup_str(Id solvid, Id keyname) + my $string = $pool->lookup_str($solvid, $keyname); + string = pool.lookup_str(solvid, keyname) + string = pool.lookup_str(solvid, keyname) + + Id lookup_id(Id solvid, Id keyname) + my $id = $pool->lookup_id($solvid, $keyname); + id = pool.lookup_id(solvid, keyname) + id = pool.lookup_id(solvid, keyname) + + unsigned int lookup_num(Id solvid, Id keyname, unsigned int notfound = 0) + my $num = $pool->lookup_num($solvid, $keyname); + num = pool.lookup_num(solvid, keyname) + num = pool.lookup_num(solvid, keyname) + + bool lookup_void(Id solvid, Id keyname) + my $bool = $pool->lookup_void($solvid, $keyname); + bool = pool.lookup_void(solvid, keyname) + bool = pool.lookup_void(solvid, keyname) + + Chksum *lookup_checksum(Id solvid, Id keyname) + my $chksum = $pool->lookup_checksum($solvid, $keyname); + chksum = pool.lookup_checksum(solvid, keyname) + chksum = pool.lookup_checksum(solvid, keyname) + +Lookup functions. Return the data element stored in the +specified solvable. + + Dataiterator *Dataiterator(Id solvid, Id keyname, const char *match, int flags) + my $di = $pool->Dataiterator($solvid, $keyname, $match, $flags); + di = pool.Dataiterator(solvid, keyname, match, flags) + di = pool.Dataiterator(solvid, keyname, match, flags) + + for my $d (@$di) + for d in di: + for d in di + +Iterate over the matching data elements. See the Dataiterator class for +more information. + +=== ID METHODS === + +The following methods deal with Ids, i.e. integers +representing objects in the pool. They are considered +``low level'', in most cases you would not use them +but instead the object orientated methods. + + Repo *id2repo(Id id) + $repo = $pool->id2repo($id); + repo = pool.id2repo(id) + repo = pool.id2repo(id) + +Lookup an existing Repository by id. You can also do +this by using the *repos* attribute. + + Solvable *id2solvable(Id id) + $solvable = $pool->id2solvable($id); + solvable = pool.id2solvable(id) + solvable = pool.id2solvable(id) + +Lookup an existing Repository by id. You can also do +this by using the *solvables* attribute. + + const char *solvid2str(Id id) + my $str = $pool->solvid2str($id); + str = pool.solvid2str(id) + str = pool.solvid2str(id) + +Return a string describing the Solvable with the specified +id. The string consists of the name, version, and architecture +of the Solvable. + + Id str2id(const char *str, bool create=1) + my $id = pool->str2id($string); + id = pool.str2id(string) + id = pool.str2id(string) + + const char *id2str(Id id) + $string = pool->id2str($id); + string = pool.id2str(id) + string = pool.id2str(id) + +Convert a string into an Id and back. If the string is +currently not in the pool and _create_ is false, +zero is returned. + + Id rel2id(Id name, Id evr, int flags, bool create=1) + my $id = pool->rel2id($nameid, $evrid, $flags); + id = pool.rel2id(nameid, evrid, flags) + id = pool.rel2id(nameid, evrid, flags) + +Create a ``relational'' dependency. Such dependencies +consist of a name part, the _flags_ describing the +relation, and a version part. The flags are: + + $solv::REL_EQ | $solv::REL_GT | $solv::REL_LT + solv.REL_EQ | solv.REL_GT | solv.REL_LT + Solv::REL_EQ | Solv::REL_GT | Solv::REL_LT + +Thus, if you want a ``\<='' relation, you would use +*REL_LT | REL_EQ*. + + Id id2langid(Id id, const char *lang, bool create=1) + my $id = $pool->id2langid($id, $language); + id = pool.id2langid(id, language) + id = pool.id2langid(id, language) + +Create a language specific Id from some other id. This +function simply converts the id into a string, appends +a dot and the specified language to the string and +converts the result back into an Id. + + const char *dep2str(Id id) + $string = pool->dep2str($id); + string = pool.dep2str(id) + string = pool.dep2str(id) + +Convert a dependency id into a string. If the id +is just a string, this function has the same effect +as id2str(). For relational dependencies, the result +is the correct ``name relation evr'' string. + + +THE DEPENDENCY CLASS +-------------------- +The dependency class is an object orientated way to work with +strings and dependencies. Internally, dependencies are +represented as Ids, i.e. simple numbers. Dependency +objects can be constructed by using the Pool's Dep() +method. + +=== ATTRIBUTES === + + Pool *pool; /* read only */ + $dep->{'pool'} + dep.pool + dep.pool + +Back reference to the pool this dependency belongs to. + + Id id; /* read only */ + $dep->{'id'} + dep.id + dep.id + +The id of this dependency. + +== Methods == + + Dep *Rel(int flags, DepId evrid, bool create=1) + my $reldep = $dep->Rel($flags, $evrdep); + reldep = dep.Rel(flags, evrdep) + reldep = dep.Rel(flags, evrdep) + +Create a relational dependency from to string dependencies +and a flags argument. See the pool's rel2id method for a +description of the flags. + + Selection *Selection_name(int setflags = 0) + my $sel = $dep->Selection_name(); + sel = dep.Selection_name() + sel = dep.Selection_name() + +Create a Selection from a dependency. The selection +consists of all packages that have a name equal to the +dependency. If the dependency is of a relational type, +the packages version must also fulfill the dependency. + + Selection *Selection_provides(int setflags = 0) + my $sel = $dep->Selection_provides(); + sel = dep.Selection_provides() + sel = dep.Selection_provides() + +Create a Selection from a dependency. The selection +consists of all packages that have at least one provides +matching the dependency. + + const char *str() + my $str = $dep->str(); + str = $dep.str() + str = $dep.str() + +Return a string describing the dependency. + + + my $str = "$dep"; + str = str(dep) + str = dep.to_s + +Same as calling the str() method. + + + if ($dep1 == $dep2) + if dep1 == dep2: + if dep1 == dep2 + +The dependencies are equal if they are part of the +same pool and have the same ids. + +THE REPOSITORY CLASS +-------------------- +A Repository describes a group of packages, normally comming from +the same source. Repositories are created by the Pool's add_repo() +method. + +=== ATTRIBUTES === + + Pool *pool; /* read only */ + $repo->{'pool'} + repo.pool + repo.pool + +Back reference to the pool this dependency belongs to. + + Id id; /* read only */ + $repo->{'id'} + repo.id + repo.id + +Return the id of the repository. + + const char *name; /* read/write */ + $repo->{'name'} + repo.name + repo.name + +The repositories name. To libsolv, the name is just a string +with no specific meaning. + + int prioprity; /* read/write */ + $repo->{'priority'} + repo.priority + repo.priority + +The priority of the repository. A higher number means that +packages of this repository will be chosen over other +repositories, even if they have a greater package version. + + int subprioprity; /* read/write */ + $repo->{'subpriority'} + repo.subpriority + repo.subpriority + +The sub-priority of the repository. This value is compared when +the priorities of two repositories are the same. It is useful +to make the library prefer on-disk repositories to remote ones. + + int nsolvables; /* read only */ + $repo->{'nsolvables'} + repo.nsolvables + repo.nsolvables + +The number of solvables in this repository. + + void *appdata; /* read/write */ + $repo->{'appdata'} + repo.appdata + repo.appdata + +Application specific data that may be used in any way by the +code using the repository. + +=== CONSTANTS === + +*REPO_REUSE_REPODATA*:: + Reuse the last repository data aera (``repodata'') instead of creating a new + one. + +*REPO_NO_INTERNALIZE*:: + Do not internalize the added repository data. This is useful if + you plan to add more data because internalization is a costly + operation. + +*REPO_LOCALPOOL*:: + Use the repodata's pool for Id storage instead of the global pool. Useful + if you don't want to pollute the global pool with many unneeded ids, like + when storing the filelist. + +*REPO_USE_LOADING*:: + Use the repodata that is currently being loaded instead of creating a new one. + This only makes sense if used in a load callback. + +*REPO_EXTEND_SOLVABLES*:: + Do not create new solvables for the new data, but match existing solvables and + add the data to them. Repository metadata is often split into multiple parts, + with one primary file describing all packages and other parts holding + information that is normally not needed, like the changelog. + +*REPO_USE_ROOTDIR*:: + Prepend the pool's rootdir to the path when doing file operations. + +*REPO_NO_LOCATION*:: + Do not add a location element to the solvables. Useful if the solvables are + not in the final position, so you can add the correct location later in your code. + +*SOLV_ADD_NO_STUBS*:: + Do not create stubs for repository parts that can be downloaded on demand. + +*SUSETAGS_RECORD_SHARES*:: + This is specific to the add_susetags() method. Susetags allows to refer to already + read packages to save disk space. If this data sharing needs to work over multiple + calls to add_susetags, you need to specify this flag so that the share information + is made available to subsequent calls. + +=== METHODS === + + void free(bool reuseids = 0) + $repo->free(); + repo.free() + repo.free() + +Free the repository and all solvables it contains. If _reuseids_ is set to true, the +solvable ids and the repository id may be reused by the library when added new solvables. +Thus you should leave it false if you are not sure that somebody holds a reference. + + void empty(bool reuseids = 0) + $repo->empty(); + repo.empty() + repo.empty() + +Free all the solvables in a repository. The repository will be empty after this call. +See the free() method for the meaning of _reuseids_. + + bool isempty() + $repo->isempty() + repo.empty() + repo.empty? + +Return true if there are no solvables in this repository. + + void internalize() + $repo->internalize(); + repo.internalize() + repo.internalize() + +Internalize added data. Data must be internalized before it is available to the +lookup and data iterator functions. + + bool write(FILE *fp) + $repo->write($fp) + repo.write(fp) + repo.write(fp) + +Write a repo as a ``solv'' file. These files can be read very fast and thus are +a good way to cache repository data. Returns false if there was some error +writing the file. + + Solvableiterator *solvables_iter() + for my $solvable (@{$repo->solvables_iter()}) + for solvable in repo.solvables_iter(): + for solvable in repo.solvables_iter() + +Iterate over all solvables in a repository. + + Repodata *add_repodata(int flags = 0) + my $repodata = $repo->add_repodata(); + repodata = repo.add_repodata() + repodata = repo.add_repodata() + +Add a new repodata area to the repository. This is normally automatically +done by the repo_add methods, so you need this method only in very +rare circumstances. + + void create_stubs() + $repo->create_stubs(); + repo.create_stubs() + repo.create_stubs() + +Calls the create_stubs() repodata method for the last repodata of the +repository. + + bool iscontiguous() + $repo->iscontiguous() + repo.iscontiguous() + repo.iscontiguous? + +Return true if the solvables of this repository are all in a single +block with no holes, i.e. they have consecutive ids. + + Repodata *first_repodata() + my $repodata = $repo->first_repodata(); + repodata = repo.first_repodata() + repodata = repo.first_repodata() + +Checks if all repodatas but the first repodata are extensions, and return +the first repodata if this is the case. Useful if you want to do a +store/retrive sequence on the repository to reduce the memory using and +enable paging, as this does not work if the rpository contains multiple +non-extension repodata areas. + + Selection *Selection(int setflags = 0) + my $sel = $repo->Selection(); + sel = repo.Selection() + sel = repo.Selection() + +Create a Selection consisting of all packages in the repository. + + Dataiterator *Dataiterator(Id p, Id key, const char *match, int flags) + my $di = $repo->Dataiterator($solvid, $keyname, $match, $flags); + di = repo.Dataiterator(solvid, keyname, match, flags) + di = repo.Dataiterator(solvid, keyname, match, flags) + + for my $d (@$di) + for d in di: + for d in di + +Iterate over the matching data elements in this repository. See the +Dataiterator class for more information. + + + my $str = "$repo"; + str = str(repo) + str = repo.to_s + +Return the name of the repository, or "Repo#" if no name is set. + + + if ($repo1 == $repo2) + if repo1 == repo2: + if repo1 == repo2 + +Two repositories are equal if they belong to the same pool and have the same id. + +=== LOOKUP FUNCTIONS === +Those functions can be used to retrieve information from a repository. For +Package data lookups the methods in the Solvable class are prefered, so +you probably only need this funcions to lookup repository meta information +with *SOLVID_META*. + + const char *lookup_str(Id solvid, Id keyname) + my $str = $repo->lookup_str($solvid, $keyname); + str = repo.lookup_str(solvid, keyname) + str = repo.lookup_str(solvid, keyname) + +Lookup a string from the _keyname_ entry specified with _solvid_. + + Id lookup_id(Id solvid, Id keyname) + my $id = $repo->lookup_id($solvid, $keyname); + id = repo.lookup_id(solvid, keyname) + id = repo.lookup_id(solvid, keyname) + +Lookup an Id from the _keyname_ entry specified with _solvid_. + + unsigned long long lookup_num(Id solvid, Id keyname, unsigned long long notfound = 0) + my $num = $repo->lookup_num($solvid, $keyname); + num = repo.lookup_num(solvid, keyname) + num = repo.lookup_num(solvid, keyname) + +Lookup a number from the _keyname_ entry specified with _solvid_. + +=== DATA ADD METHODS === + + Solvable *add_solvable() + $repo->add_solvable(); + repo.add_solvable() + repo.add_solvable() + +Add a single empty solvable to the repository. Returns a Solvable object, see the +Solvable class for more information. + + bool add_solv(const char *name, int flags = 0) + $repo->add_solv($name, $flags); + repo.add_solv(name, flags) + repo.add_solv(name, flags) + + bool add_solv(FILE *fp, int flags = 0) + $repo->add_solv($fp, $flags); + repo.add_solv(fp, flags) + repo.add_solv(fp, flags) + +Read a ``solv'' file and add its contents to the repository. These +files can be written with the write() method and are normally +used as fast cache for repository metadata. + + bool add_rpmdb(int flags = 0) + $repo->add_rpmdb($flags); + repo.add_rpmdb(flags) + repo.add_rpmdb(flags) + + bool add_rpmdb_reffp(FILE *reffp, int flags = 0) + $repo->add_rpmdb_reffp($reffp, $flags); + repo.add_rpmdb_reffp($reffp, flags) + repo.add_rpmdb_reffp($reffp, flags) + +Add the contents of the rpm database to the repository. If a solv file +containing an old version of the database is available, it can be +passed as reffp to speed up reading. + + bool add_rpm(const char *name, int flags = 0) + $repo->add_rpm($name, $flags); + repo.add_rpm(name, flags) + repo.add_rpm(name, flags) + +Add the metadata of a single rpm package to the repository. + + bool add_rpmdb_pubkeys(int flags = 0) + $repo->add_rpmdb_pubkeys(); + repo.add_rpmdb_pubkeys() + repo.add_rpmdb_pubkeys() + +Add all pubkeys contained in the rpm database to the repository. Note that +newer rpm versions also allow to store the pubkeys in some directory instead +of the rpm database. + + bool add_pubkey(const char *keyfile, int flags = 0) + $repo->add_pubkey($keyfile); + repo.add_pubkey($keyfile) + repo.add_pubkey($keyfile) + +Add a pubkey from a file to the repository. + + bool add_rpmmd(FILE *fp, const char *language, int flags = 0) + $repo->add_rpmmd($fp, $language); + repo.add_rpmmd(fp, language) + repo.add_rpmmd(fp, language) + +Add metadata stored in the "rpm-md" format (i.e. from files in the ``repodata'' +directory) to a repository. Supported files are "primary", "filelists", "other", +"suseinfo". Do not forget to specify the *REPO_EXTEND_SOLVABLES* for extension +files like "filelists" and "other". Use the _language_ parameter if you have +language extension files, otherwise simply use a *undef*/*None*/*nil* parameter. + + bool add_repomdxml(FILE *fp, int flags = 0) + $repo->add_repomdxml($fp); + repo.add_repomdxml(fp) + repo.add_repomdxml(fp) + +Add the repomd.xml meta description from the "rpm-md" format to the repository. +This file contains information about the repository like keywords, and also +a list of all database files with checksums. The data is added the the "meta" +section of the repository, i.e. no package gets created. + + bool add_updateinfoxml(FILE *fp, int flags = 0) + $repo->add_updateinfoxml($fp); + repo.add_updateinfoxml(fp) + repo.add_updateinfoxml(fp) + +Add the updateinfo.xml file containing available maintenance updates to the +repository. All updates are created as special packages that have a "patch:" +prefix in their name. + + bool add_deltainfoxml(FILE *fp, int flags = 0) + $repo->add_deltainfoxml($fp); + repo.add_deltainfoxml(fp) + repo.add_deltainfoxml(fp) + +Add the deltainfo.xml file (also called prestodelta.xml) containing available +delta-rpms to the repository. The data is added to the "meta" section, i.e. no +package gets created. + + bool add_debdb(int flags = 0) + $repo->add_debdb(); + repo.add_debdb() + repo.add_debdb() + +Add the contents of the debian installed package database to the repository. + + bool add_debpackages(FILE *fp, int flags = 0) + $repo->add_debpackages($fp); + repo.add_debpackages($fp) + repo.add_debpackages($fp) + +Add the contents of the debian repository metadata (the "packages" file) +to the repository. + + bool add_deb(const char *filename, int flags = 0) + $repo->add_deb($filename); + repo.add_deb(filename) + repo.add_deb(filename) + +Add the metadata of a single deb package to the repository. + + bool add_mdk(FILE *fp, int flags = 0) + $repo->add_mdk($fp); + repo.add_mdk($fp) + repo.add_mdk($fp) + +Add the contents of the mageia/mandriva repository metadata (the "synthesis.hdlist" file) +to the repository. + + bool add_mdk_info(FILE *fp, int flags = 0) + $repo->add_mdk($fp); + repo.add_mdk($fp) + repo.add_mdk($fp) + +Extend the packages from the synthesis file with the info.xml and files.xml data. Do +not forget to specify *REPO_EXTEND_SOLVABLES*. + + bool add_arch_repo(FILE *fp, int flags = 0) + $repo->add_arch_repo($fp); + repo.add_arch_repo($fp) + repo.add_arch_repo($fp) + +Add the contents of the archlinux repository metadata (the ".db.tar" file) to the +repository. + + bool add_arch_local(const char *dir, int flags = 0) + $repo->add_arch_local($dir); + repo.add_arch_local($dir) + repo.add_arch_local($dir) + +Add the contents of the archlinux installed package database to the repository. +The _dir_ parameter is usually set to "/var/lib/pacman/local". + + bool add_content(FILE *fp, int flags = 0) + $repo->add_content($fp); + repo.add_content(fp) + repo.add_content(fp) + +Add the ``content'' meta description from the susetags format to the repository. +This file contains information about the repository like keywords, and also +a list of all database files with checksums. The data is added the the "meta" +section of the repository, i.e. no package gets created. + + bool add_susetags(FILE *fp, Id defvendor, const char *language, int flags = 0) + $repo->add_susetags($fp, $defvendor, $language); + repo.add_susetags(fp, defvendor, language) + repo.add_susetags(fp, defvendor, language) + +Add repository metadata in the susetags format to the repository. Like with +add_rpmmd, you can specify a language if you have language extension files. The +_defvendor_ parameter provides a default vendor for packages with missing +vendors, it is usually provided in the content file. + + bool add_products(const char *dir, int flags = 0) + $repo->add_products($dir); + repo.add_products(dir) + repo.add_products(dir) + +Add the installed SUSE products database to the repository. The _dir_ parameter is +usually "/etc/products.d". + +THE SOLVABLE CLASS +------------------ +xxx + +THE DATAITERATOR CLASS +---------------------- +xxx + +THE SELECTION CLASS +------------------- +xxx + +THE JOB CLASS +------------- +xxx + +THE SOLVER CLASS +---------------- +xxx + +THE TRANSACTION CLASS +--------------------- +xxx + +CHECKSUMS +--------- +Checksums (also called hashes) are used to make sure that +downloaded data is not corrupt and also as a fingerprint +mechanism to check if data has changed. + +=== CLASS METHODS === + + Chksum *Chksum(Id type) + my $chksum = solv.Chksum->new($type); + chksum = solv.Chksum(type) + chksum = solv.Chksum.new(type) + +Create a checksum object. Currently the following types +are supported: + + REPOKEY_TYPE_MD5 + REPOKEY_TYPE_SHA1 + REPOKEY_TYPE_SHA256 + +These keys are constants in the *solv* class. + + Chksum *Chksum(Id type, const char *hex) + my $chksum = solv.Chksum->new($type, $hex); + chksum = solv.Chksum(type, hex) + chksum = solv.Chksum.new(type, hex) + +Create an already finalized checksum object. + +=== ATTRIBUTES === + + Id type; /* read only */ + $chksum->{'type'} + chksum.type + chksum.type + +Return the type of the checksum object. + +=== METHODS === + + void add(const char *str) + $chksum->add($str); + chksum.add(str) + chksum.add(str) + +Add a string to the checksum. + + void add_fp(FILE *fp) + $chksum->add_fp($file); + chksum.add_fp(file) + chksum.add_fp(file) + +Add the contents of a file to the checksum. + + void add_stat(const char *filename) + $chksum->add_stat($filename); + chksum.add_stat(filename) + chksum.add_stat(filename) + +Stat the file and add the dev/ino/size/mtime member to the +checksum. If the stat fails, the members are zeroed. + + void add_fstat(int fd) + $chksum->add_fstat($fd); + chksum.add_fstat(fd) + chksum.add_fstat(fd) + +Same as add_stat, but instead of the filename a file +descriptor is used. + + unsigned char *raw() + my $raw = $chksum->raw(); + raw = chksum.raw() + raw = chksum.raw() + +Finalize the checksum and return the result as raw bytes. This +means that the result can contain zero bytes or +unprintable characters. + + unsigned char *hex() + my $raw = $chksum->hex(); + raw = chksum.hex() + raw = chksum.hex() + +Finalize the checksum and return the result as hex string. + + + if ($chksum1 == $chksum2) + if chksum1 == chksum2: + if chksum1 == chksum2 + +Checksums are equal if they are of the same type and the +finalized results are the same. + + + my $str = "$chksum"; + str = str(chksum) + str = chksum.to_s + +If the checksum is finished, the checksum is returned +as ":" string. Otherwise ":unfinished" +is returned. + + +FILE MANAGEMENT +--------------- +This functions were added because libsolv uses standard +*FILE* pointers to read/write files, but languages like +perl have their own implementation of files. The +libsolv functions also support decompression and +compression, the algorithm is selected by looking at +the file name extension. + + FILE *xfopen(char *fn, char *mode = "r") + my $file = solv::xfopen($path); + file = solv.xfopen(path) + file = Solv::xfopen(path) + +Open a file at the specified path. The `mode` argument is +passed on to the stdio library. + + FILE *xfopen_fd(char *fn, int fileno) + my $file = solv::xfopen_fd($path, $fileno); + file = solv.xfopen_fd(path, fileno) + file = Solv::xfopen_fd(path, fileno) + +Create a file handle from the specified file descriptor. +The path argument is only used to select the correct +(de-)compression algorithm, use an empty path if you want +to make sure to read/write raw data. + +=== METHODS === + + int fileno() + my $fileno = $file->fileno(); + fileno = file.fileno() + fileno = file.fileno() + +Return file file descriptor of the file. If the file is not +open, `-1` is returned. + + int dup() + my $fileno = $file->dup(); + fileno = file.dup() + fileno = file.dup() + +Return a copy of the descriptor of the file. If the file is not +open, `-1` is returned. + + bool flush() + $file->flush(); + file.flush() + file.flush() + +Flush the file. Returns false if there was an error. Flushing a +closed file always returns true. + + bool close() + $file->close(); + file.close() + file.close() + +Close the file. This is needed for languages like Ruby, that do +not destruct objects right after they are no longer referenced. +In that case, it is good style to close open files so that +the file descriptors are freed right away. Returns false if +there was an error. + +THE REPODATACLASS +----------------- +xxx + +Author +------ +Michael Schroeder + diff --git a/doc/libsolv.3 b/doc/libsolv.3 index d340f5e..0d042e6 100644 --- a/doc/libsolv.3 +++ b/doc/libsolv.3 @@ -1,104 +1,119 @@ -.\" See LICENSE.BSD for license -.TH LIBSOLV 7 "May 2011" -.SH NAME +'\" t +.\" Title: libsolv +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets v1.76.1 +.\" Date: 05/15/2013 +.\" Manual: LIBSOLV +.\" Source: libsolv +.\" Language: English +.\" +.TH "LIBSOLV" "3" "05/15/2013" "libsolv" "LIBSOLV" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" libsolv \- package dependency solver library using a satisfiability algorithm -.SH HISTORY -This project was started in May 2007 when the zypp folks decided to switch -to a database to speed up installation. As I am not a big fan of databases, -I (mls) wondered if there would be really some merit of using one for solving, -as package dependencies of all packages have to be read in anyway. -.PP -Back in 2002, I researched that using a dictionary approach for storing -dependencies can reduce the packages file to 1/3 of its size. Extending -this idea a bit more, I decided to store all strings and relations -as unique 32-bit numbers. This has three big advantages: -.IP - 2 -because of the unification, testing whether two strings are equal is the same as -testing the equality of two numbers, thus very fast -.IP - 2 -much space is saved, as numbers do not take up as much space as strings -.IP - 2 -the internal memory representation does not take more space on a -64-bit system where a pointer is twice the size of a 32-bit number -.PP -Thus, the solv format was created, which stores a repository as a string -dictionary, a relation dictionary and then all packages dependencies. -Tests showed that reading and merging multiple solv repositories takes -just some milliseconds. -.SS Early solver experiments -Having a new repository format was one big step, but the other area -where libzypp needed improvement was the solver. Libzypp's solver was -a port from the Red Carpet solver, which was written to update packages -in an already installed system. Using it for the complete installation -progress brought it to its limits. Also, the added extensions like -support for weak dependencies and patches made it fragile and -unpredictable. -.PP -As I was not very pleased with the way the solver worked, I looked at -other solver algorithms. I checked smart, yum and apt, but could not -find a convincing algorithm. My own experiments also were not very -convincing, they worked fine for some problems but failed miserably -for other corner cases. -.SS Using SAT for solving -SUSE's hack week at the end of June 2007 turned out to be a turning point -for the solver. Googling for solver algorithms, I stumbled over some note -saying that some people are trying to use SAT algorithms to improve -solving on Debian. Looking at the SAT entry in Wikipedia, it was easy -to see that this indeed was the missing piece: SAT algorithms are well -researched and there are quite some open source implementations. -I decided to look at the minisat code, as it is one of the fastest -solvers while consisting of too many lines of code. -.PP -Of course, directly using minisat would not work, as a package solver -does not need to find just one correct solution, but it also has to -optimize some metrics, i.e. keep as many packages installed as possible. -Thus, I needed to write my own solver incorporation the ideas and -algorithms used in minisat. This wasn't very hard, and at the end of -the hack week the solver calculated the first right solutions. -.SS Selling it to libzypp -With those encouraging results, I went to Klaus Kaempf, the system -management architect at SUSE. We spoke about how to convince the -team to make libzypp switch to the new solver. Fortunately, libzypp comes -with a plethora of solver test cases, so we decided to make the solver pass -most of the test cases first. Klaus wrote a "deptestomatic" implementation -to check the test cases. Together with Stephan Kulow, who is responsible for the -openSUSE distribution, we tweaked and extended the solver until most of -the test cases looked good. -.PP -Duncan Mac-Vicar Prett, the team lead of the YaST team, also joined -development by creating Ruby bindings for the solver. Later, Klaus -improved the bindings and ported them to some other languages. -.SS The attribute store -The progress with the repository format and the solver attracted another -hacker to the project: Michael Matz from the compiler team. He started -with improving the repository parsers so that patches and content files -also generate solvables. After that, he concentrated on storing all -of the other metadata of the repositories that are not used for solving, -like the package summaries and descriptions. At the end of October, a first -version of this "attribute store" was checked in. Its design goals were: -.IP - 2 +.SH "HISTORY" +.sp +This project was started in May 2007 when the zypp folks decided to switch to a database to speed up installation\&. As I am not a big fan of databases, I (mls) wondered if there would be really some merit of using one for solving, as package dependencies of all packages have to be read in anyway\&. +.sp +Back in 2002, I researched that using a dictionary approach for storing dependencies can reduce the packages file to 1/3 of its size\&. Extending this idea a bit more, I decided to store all strings and relations as unique 32\-bit numbers\&. This has three big advantages: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +because of the unification, testing whether two strings are equal is the same as testing the equality of two numbers, thus very fast +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +much space is saved, as numbers do not take up as much space as strings the internal memory representation does not take more space on a 64\-bit system where a pointer is twice the size of a 32\-bit number +.RE +.sp +Thus, the solv format was created, which stores a repository as a string dictionary, a relation dictionary and then all packages dependencies\&. Tests showed that reading and merging multiple solv repositories takes just some milliseconds\&. +.SS "Early solver experiments" +.sp +Having a new repository format was one big step, but the other area where libzypp needed improvement was the solver\&. Libzypp\(cqs solver was a port from the Red Carpet solver, which was written to update packages in an already installed system\&. Using it for the complete installation progress brought it to its limits\&. Also, the added extensions like support for weak dependencies and patches made it fragile and unpredictable\&. +.sp +As I was not very pleased with the way the solver worked, I looked at other solver algorithms\&. I checked smart, yum and apt, but could not find a convincing algorithm\&. My own experiments also were not very convincing, they worked fine for some problems but failed miserably for other corner cases\&. +.SS "Using SAT for solving" +.sp +SUSE\(cqs hack week at the end of June 2007 turned out to be a turning point for the solver\&. Googling for solver algorithms, I stumbled over some note saying that some people are trying to use SAT algorithms to improve solving on Debian\&. Looking at the SAT entry in Wikipedia, it was easy to see that this indeed was the missing piece: SAT algorithms are well researched and there are quite some open source implementations\&. I decided to look at the minisat code, as it is one of the fastest solvers while consisting of too many lines of code\&. +.sp +Of course, directly using minisat would not work, as a package solver does not need to find just one correct solution, but it also has to optimize some metrics, i\&.e\&. keep as many packages installed as possible\&. Thus, I needed to write my own solver incorporation the ideas and algorithms used in minisat\&. This wasn\(cqt very hard, and at the end of the hack week the solver calculated the first right solutions\&. +.SS "Selling it to libzypp" +.sp +With those encouraging results, I went to Klaus Kaempf, the system management architect at SUSE\&. We spoke about how to convince the team to make libzypp switch to the new solver\&. Fortunately, libzypp comes with a plethora of solver test cases, so we decided to make the solver pass most of the test cases first\&. Klaus wrote a "deptestomatic" implementation to check the test cases\&. Together with Stephan Kulow, who is responsible for the openSUSE distribution, we tweaked and extended the solver until most of the test cases looked good\&. +.sp +Duncan Mac\-Vicar Prett, the team lead of the YaST team, also joined development by creating Ruby bindings for the solver\&. Later, Klaus improved the bindings and ported them to some other languages\&. +.SS "The attribute store" +.sp +The progress with the repository format and the solver attracted another hacker to the project: Michael Matz from the compiler team\&. He started with improving the repository parsers so that patches and content files also generate solvables\&. After that, he concentrated on storing all of the other metadata of the repositories that are not used for solving, like the package summaries and descriptions\&. At the end of October, a first version of this "attribute store" was checked in\&. Its design goals were: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} space efficient storage of attributes -.IP - 2 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} paging/on demand loading of data -.IP - 2 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} page compression -.PP -The first version of the attribute store used a different format for -storing information, we later merged this format with the solv file -format. -.SS libzypp integration -Integration of the sat-solver into libzypp also started in October 2007 by -Stefan Schubert and Michael Andres from the YaST team. The first -versions supported both the old solver and the new one by using the -old repository read functions and converting the old package data -in-memory into a sat solver pool. Solvers could be switched with -the environment variable ZYPP_SAT_SOLVER. The final decision to -move to the new solver was made in January of 2008, first just by -making the new solver the default one, later by completely throwing out -the old solver code. This had the advantage that the internal solvable -storage could also be done by using the solver pool, something Michael -Matz already played with in a proof of concept implementation showing -some drastic speed gains. The last traces of the old database code -were removed in February. -.SH AUTHOR -Michael Schroeder +.RE +.sp +The first version of the attribute store used a different format for storing information, we later merged this format with the solv file format\&. +.SS "libzypp integration" +.sp +Integration of the sat\-solver into libzypp also started in October 2007 by Stefan Schubert and Michael Andres from the YaST team\&. The first versions supported both the old solver and the new one by using the old repository read functions and converting the old package data in\-memory into a sat solver pool\&. Solvers could be switched with the environment variable ZYPP_SAT_SOLVER\&. The final decision to move to the new solver was made in January of 2008, first just by making the new solver the default one, later by completely throwing out the old solver code\&. This had the advantage that the internal solvable storage could also be done by using the solver pool, something Michael Matz already played with in a proof of concept implementation showing some drastic speed gains\&. The last traces of the old database code were removed in February\&. +.SH "AUTHOR" +.sp +Michael Schroeder diff --git a/doc/libsolv.txt b/doc/libsolv.txt new file mode 100644 index 0000000..c23f0b4 --- /dev/null +++ b/doc/libsolv.txt @@ -0,0 +1,113 @@ +LIBSOLV(3) +========== +:man manual: LIBSOLV +:man source: libsolv + +NAME +---- +libsolv - package dependency solver library using a satisfiability algorithm + +HISTORY +------- +This project was started in May 2007 when the zypp folks decided to switch +to a database to speed up installation. As I am not a big fan of databases, +I (mls) wondered if there would be really some merit of using one for solving, +as package dependencies of all packages have to be read in anyway. + +Back in 2002, I researched that using a dictionary approach for storing +dependencies can reduce the packages file to 1/3 of its size. Extending +this idea a bit more, I decided to store all strings and relations +as unique 32-bit numbers. This has three big advantages: + +- because of the unification, testing whether two strings are equal is the + same as testing the equality of two numbers, thus very fast +- much space is saved, as numbers do not take up as much space as strings + the internal memory representation does not take more space on a + 64-bit system where a pointer is twice the size of a 32-bit number + +Thus, the solv format was created, which stores a repository as a string +dictionary, a relation dictionary and then all packages dependencies. +Tests showed that reading and merging multiple solv repositories takes +just some milliseconds. + +=== Early solver experiments === +Having a new repository format was one big step, but the other area +where libzypp needed improvement was the solver. Libzypp's solver was +a port from the Red Carpet solver, which was written to update packages +in an already installed system. Using it for the complete installation +progress brought it to its limits. Also, the added extensions like +support for weak dependencies and patches made it fragile and +unpredictable. + +As I was not very pleased with the way the solver worked, I looked at +other solver algorithms. I checked smart, yum and apt, but could not +find a convincing algorithm. My own experiments also were not very +convincing, they worked fine for some problems but failed miserably +for other corner cases. + +=== Using SAT for solving === +SUSE's hack week at the end of June 2007 turned out to be a turning point +for the solver. Googling for solver algorithms, I stumbled over some note +saying that some people are trying to use SAT algorithms to improve +solving on Debian. Looking at the SAT entry in Wikipedia, it was easy +to see that this indeed was the missing piece: SAT algorithms are well +researched and there are quite some open source implementations. +I decided to look at the minisat code, as it is one of the fastest +solvers while consisting of too many lines of code. + +Of course, directly using minisat would not work, as a package solver +does not need to find just one correct solution, but it also has to +optimize some metrics, i.e. keep as many packages installed as possible. +Thus, I needed to write my own solver incorporation the ideas and +algorithms used in minisat. This wasn't very hard, and at the end of +the hack week the solver calculated the first right solutions. + +=== Selling it to libzypp === +With those encouraging results, I went to Klaus Kaempf, the system +management architect at SUSE. We spoke about how to convince the +team to make libzypp switch to the new solver. Fortunately, libzypp comes +with a plethora of solver test cases, so we decided to make the solver pass +most of the test cases first. Klaus wrote a "deptestomatic" implementation +to check the test cases. Together with Stephan Kulow, who is responsible for the +openSUSE distribution, we tweaked and extended the solver until most of +the test cases looked good. + +Duncan Mac-Vicar Prett, the team lead of the YaST team, also joined +development by creating Ruby bindings for the solver. Later, Klaus +improved the bindings and ported them to some other languages. + +=== The attribute store === +The progress with the repository format and the solver attracted another +hacker to the project: Michael Matz from the compiler team. He started +with improving the repository parsers so that patches and content files +also generate solvables. After that, he concentrated on storing all +of the other metadata of the repositories that are not used for solving, +like the package summaries and descriptions. At the end of October, a first +version of this "attribute store" was checked in. Its design goals were: + +- space efficient storage of attributes +- paging/on demand loading of data +- page compression + +The first version of the attribute store used a different format for +storing information, we later merged this format with the solv file +format. + +=== libzypp integration === +Integration of the sat-solver into libzypp also started in October 2007 by +Stefan Schubert and Michael Andres from the YaST team. The first +versions supported both the old solver and the new one by using the +old repository read functions and converting the old package data +in-memory into a sat solver pool. Solvers could be switched with +the environment variable ZYPP_SAT_SOLVER. The final decision to +move to the new solver was made in January of 2008, first just by +making the new solver the default one, later by completely throwing out +the old solver code. This had the advantage that the internal solvable +storage could also be done by using the solver pool, something Michael +Matz already played with in a proof of concept implementation showing +some drastic speed gains. The last traces of the old database code +were removed in February. + +AUTHOR +------ +Michael Schroeder