From: Michael Schroeder Date: Tue, 28 May 2013 16:32:49 +0000 (+0200) Subject: document Selection and Job classes X-Git-Tag: upstream/0.4.0~121 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=7119fc7b5341c2338d033ccf1ef2acf9641cf4b5;p=platform%2Fupstream%2Flibsolv.git document Selection and Job classes --- diff --git a/bindings/solv.i b/bindings/solv.i index f09426b..ec59609 100644 --- a/bindings/solv.i +++ b/bindings/solv.i @@ -861,9 +861,6 @@ typedef struct { int flags() { return $self->flags; } - void make(const char *name, int flags) { - $self->flags = selection_make($self->pool, &$self->q, name, flags); - } #ifdef SWIGRUBY %rename("isempty?") isempty; #endif @@ -2617,6 +2614,8 @@ rb_eval_string( static const int SOLVER_FLAG_IGNORE_RECOMMENDED = SOLVER_FLAG_IGNORE_RECOMMENDED; static const int SOLVER_FLAG_ADD_ALREADY_RECOMMENDED = SOLVER_FLAG_ADD_ALREADY_RECOMMENDED; static const int SOLVER_FLAG_NO_INFARCHCHECK = SOLVER_FLAG_NO_INFARCHCHECK; + static const int SOLVER_FLAG_BEST_OBEY_POLICY = SOLVER_FLAG_BEST_OBEY_POLICY; + static const int SOLVER_FLAG_NO_AUTOTARGET = SOLVER_FLAG_NO_AUTOTARGET; ~Solver() { solver_free($self); diff --git a/doc/libsolv-bindings.3 b/doc/libsolv-bindings.3 index 43f191d..5ed7ae9 100644 --- a/doc/libsolv-bindings.3 +++ b/doc/libsolv-bindings.3 @@ -2352,10 +2352,506 @@ my \fI$str\fR \fB= "\fR\fI$d\fR\fB"\fR; Return the stringification of the matched value\&. Stringification depends on the search flags, for file list entries it will return just the base name unless SEARCH_FILES is used, for checksums it will return an empty string unless SEARCH_CHECKSUMS is used\&. Numeric values are currently stringified to an empty string\&. .SH "THE SELECTION CLASS" .sp -xxx +Selections are a way to easily deal with sets of packages\&. There are multiple constructors to create them, the most useful is probably the select() method in the Pool class\&. +.SS "CONSTANTS" +.PP +\fBSELECTION_NAME\fR +.RS 4 +Create the selection by matching package names +.RE +.PP +\fBSELECTION_PROVIDES\fR +.RS 4 +Create the selection by matching package provides +.RE +.PP +\fBSELECTION_FILELIST\fR +.RS 4 +Create the selection by matching package files +.RE +.PP +\fBSELECTION_CANON\fR +.RS 4 +Create the selection by matching the canonical representation of the package\&. This is normally a combination of the name, the version, and the architecture of a package\&. +.RE +.PP +\fBSELECTION_DOTARCH\fR +.RS 4 +Allow an \(lq\&.\(rq suffix when matching names or provides\&. +.RE +.PP +\fBSELECTION_REL\fR +.RS 4 +Allow the specification of a relation when matching names or provides, e\&.g\&. "name >= 1\&.2"\&. +.RE +.PP +\fBSELECTION_INSTALLED_ONLY\fR +.RS 4 +Limit the package search to installed packages\&. +.RE +.PP +\fBSELECTION_SOURCE_ONLY\fR +.RS 4 +Limit the package search to source packages only\&. +.RE +.PP +\fBSELECTION_WITH_SOURCE\fR +.RS 4 +Extend the package search to also match source packages\&. The default is only to match binary packages\&. +.RE +.PP +\fBSELECTION_GLOB\fR +.RS 4 +Allow glob matching for package names, package provides, and file names\&. +.RE +.PP +\fBSELECTION_NOCASE\fR +.RS 4 +Ignore case when matching package names, package provides, and file names\&. +.RE +.PP +\fBSELECTION_FLAT\fR +.RS 4 +Return only one selection element describing the selected packages\&. The default is to create multiple elements for all globbed packages\&. Multiple elements are useful if you want to turn the selection into an install job, in that case you want an install job for every globbed package\&. +.RE +.SS "ATTRIBUTES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBPool *pool;\fR /* read only */ +\fI$d\fR\fB\->{\*(Aqpool\*(Aq}\fR +\fId\fR\fB\&.pool\fR +\fId\fR\fB\&.pool\fR +.fi +.if n \{\ +.RE +.\} +.sp +Back pointer to pool\&. +.SS "METHODS" +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBint flags()\fR; +my \fI$flags\fR \fB=\fR \fI$sel\fR\fB\->flags()\fR; +\fIflags\fR \fB=\fR \fIsel\fR\fB\&.flags()\fR +\fIflags\fR \fB=\fR \fIsel\fR\fB\&.flags()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Return the result flags of the selection\&. The flags are a subset of the ones used when creating the selection, they describe which method was used to get the result\&. For example, if you create the selection with \(lqSELECTION_NAME | SELECTION_PROVIDES\(rq, the resulting flags will either be SELECTION_NAME or SELECTION_PROVIDES depending if there was a package that matched the name or not\&. If there was no match at all, the flags will be zero\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool isempty()\fR; +\fI$sel\fR\fB\->isempty()\fR +\fIsel\fR\fB\&.isempty()\fR +\fIsel\fR\fB\&.isempty?\fR +.fi +.if n \{\ +.RE +.\} +.sp +Return true if the selection is empty, i\&.e\&. no package could be matched\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid filter(Selection *\fR\fIother\fR\fB)\fR +\fI$sel\fR\fB\->filter(\fR\fI$other\fR\fB)\fR; +\fIsel\fR\fB\&.filter(\fR\fIother\fR\fB)\fR +\fIsel\fR\fB\&.filter(\fR\fIother\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Intersect two selections\&. Packages will only stay in the selection if there are also included in the other selecting\&. Does an in\-place modification\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid add(Selection *\fR\fIother\fR\fB)\fR +\fI$sel\fR\fB\->add(\fR\fI$other\fR\fB)\fR; +\fIsel\fR\fB\&.add(\fR\fIother\fR\fB)\fR +\fIsel\fR\fB\&.add(\fR\fIother\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Build the union of two selections\&. All packages of the other selection will be added to the set of packages of the selection object\&. Does an in\-place modification\&. Note that the selection flags are no longer meaningful after the add operation\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBvoid add_raw(Id\fR \fIhow\fR\fB, Id\fR \fIwhat\fR\fB)\fR +\fI$sel\fR\fB\->add_raw(\fR\fI$how\fR\fB,\fR \fI$what\fR\fB)\fR; +\fIsel\fR\fB\&.add_raw(\fR\fIhow\fR\fB,\fR \fIwhat\fR\fB)\fR +\fIsel\fR\fB\&.add_raw(\fR\fIhow\fR\fB,\fR \fIwhat\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Add a raw element to the selection\&. Check the Job class for information about the how and what parameters\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBJob *jobs(int\fR \fIaction\fR\fB)\fR +my \fI@jobs\fR \fB=\fR \fI$sel\fR\fB\->jobs(\fR\fI$action\fR\fB)\fR; +\fIjobs\fR \fB=\fR \fIsel\fR\fB\&.jobs(\fR\fIaction\fR\fB)\fR +\fIjobs\fR \fB=\fR \fIsel\fR\fB\&.jobs(\fR\fIaction\fR\fB)\fR +.fi +.if n \{\ +.RE +.\} +.sp +Convert a selection into an array of Job objects\&. The action parameter is or\-ed to the \(lqhow\(rq part of the job, it describes the type of job (e\&.g\&. install, erase)\&. See the Job class for the action and action modifier constants\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBSolvable *solvables()\fR +my \fI@solvables\fR \fB=\fR \fI$sel\fR\fB\->solvables()\fR; +\fIsolvables\fR \fB=\fR \fIsel\fR\fB\&.solvables()\fR +\fIsolvables\fR \fB=\fR \fIsel\fR\fB\&.solvables()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Convert a selection into an array of Solvable objects\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fB\fR +my \fI$str\fR \fB= "\fR\fI$sel\fR\fB"\fR; +\fIstr\fR \fB= str(\fR\fIsel\fR\fB)\fR +\fIstr\fR \fB=\fR \fIsel\fR\fB\&.to_s\fR +.fi +.if n \{\ +.RE +.\} +.sp +Return a string describing the selection\&. .SH "THE JOB CLASS" .sp -xxx +Jobs are the way to specify to the dependency solver what to do\&. Most of the times jobs will get created by calling the jobs() method on a Selection object, but there is also a Job() constructor in the Pool class\&. +.SS "CONSTANTS" +.sp +Selection constants: +.PP +\fBSOLVER_SOLVABLE\fR +.RS 4 +The \(lqwhat\(rq part is the id of a solvable\&. +.RE +.PP +\fBSOLVER_SOLVABLE_NAME\fR +.RS 4 +The \(lqwhat\(rq part is the id of a package name\&. +.RE +.PP +\fBSOLVER_SOLVABLE_PROVIDES\fR +.RS 4 +The \(lqwhat\(rq part is the id of a package provides\&. +.RE +.PP +\fBSOLVER_SOLVABLE_ONE_OF\fR +.RS 4 +The \(lqwhat\(rq part is an offset into the \(lqwhatprovides\(rq data, created by calling the towhatprovides() pool method\&. +.RE +.PP +\fBSOLVER_SOLVABLE_REPO\fR +.RS 4 +The \(lqwhat\(rq part is the id of a repository\&. +.RE +.PP +\fBSOLVER_SOLVABLE_ALL\fR +.RS 4 +The \(lqwhat\(rq part is ignored, all packages are selected\&. +.RE +.PP +\fBSOLVER_SOLVABLE_SELECTMASK\fR +.RS 4 +A mask containing all the above selection bits\&. +.RE +.sp +Action constants: +.PP +\fBSOLVER_NOOP\fR +.RS 4 +Do nothing\&. +.RE +.PP +\fBSOLVER_INSTALL\fR +.RS 4 +Install a package of the specified set of packages\&. It tries to install the best matching package (i\&.e\&. the highest version of the packages from the repositories with the highest priority)\&. +.RE +.PP +\fBSOLVER_ERASE\fR +.RS 4 +Erase all of the packages from the specified set\&. If a package is not installed, erasing it will keep it from getting installed\&. +.RE +.PP +\fBSOLVER_UPDATE\fR +.RS 4 +Update the matching installed packages to their best version\&. If none of the specified packages are installed, try to update the installed packages to the specified versions\&. See the section about targeted updates about more information\&. +.RE +.PP +\fBSOLVER_WEAKENDEPS\fR +.RS 4 +Allow to break the dependencies of the matching packages\&. Handle with care\&. +.RE +.PP +\fBSOLVER_MULTIVERSION\fR +.RS 4 +Mark the matched packages for multiversion install\&. If they get to be installed because of some other job, the installation will keep the old version of the package installed (for rpm by using \(oq`\-i\*(Aq\*(Aq instead of ``\-U\(cq\*(Aq)\&. +.RE +.PP +\fBSOLVER_LOCK\fR +.RS 4 +Do not change the state of the matched packages, i\&.e\&. when they are installed they stay installed, if not they are not selected for installation\&. +.RE +.PP +\fBSOLVER_DISTUPGRADE\fR +.RS 4 +Update the matching installed packages to the best version included in one of the repositories\&. After this operation, all come from one of the available repositories except orphaned packages\&. Orphaned packages are packages that have no relation to the packages in the repositories, i\&.e\&. no package in the repositories have the same name or obsolete the orphaned package\&. This action brings the installed packages in sync with the ones in the repository\&. It also turns of arch/vendor/version locking for the affected packages to simulate a fresh installation\&. This means that distupgrade can actually downgrade packages if only lower versions of a package are available in the repositories\&. +.RE +.PP +\fBSOLVER_DROP_ORPHANED\fR +.RS 4 +Erase all the matching installed packages if they are orphaned\&. This only makes sense if there is a \(lqdistupgrade all packages\(rq job\&. The default is to erase orphaned packages only if they block the installation of other packages\&. +.RE +.PP +\fBSOLVER_VERIFY\fR +.RS 4 +Fix dependency problems of matching installed packages\&. The default is to ignore dependency problems for installed packages\&. +.RE +.PP +\fBSOLVER_USERINSTALLED\fR +.RS 4 +The matching installed packages are considered to be installed by a user, thus not installed to fulfil some dependency\&. This is needed input for the calculation of unneeded packages for jobs that have the SOLVER_CLEANDEPS flag set\&. +.RE +.PP +\fBSOLVER_JOBMASK\fR +.RS 4 +A mask containing all the above action bits\&. +.RE +.sp +Action modifier constants: +.PP +\fBSOLVER_WEAK\fR +.RS 4 +Makes the job a weak job\&. The solver tries to fulfil weak jobs, but does not report a problem if it is not possible to do so\&. +.RE +.PP +\fBSOLVER_ESSENTIAL\fR +.RS 4 +Makes the job an essential job\&. If there is a problem with the job, the solver will not propose to remove the job as one solution (unless all other solutions are also to remove essential jobs)\&. +.RE +.PP +\fBSOLVER_CLEANDEPS\fR +.RS 4 +The solver will try to also erase all packages dragged in through dependencies when erasing the package\&. This needs SOLVER_USERINSTALLED jobs to maximize user satisfaction\&. +.RE +.PP +\fBSOLVER_FORCEBEST\fR +.RS 4 +Insist on the best package for install, update, and distupgrade jobs\&. If this flag is not used, the solver will use the second\-best package if the best package cannot be installed for some reason\&. When this flag is used, the solver will generate a problem instead\&. +.RE +.PP +\fBSOLVER_TARGETED\fR +.RS 4 +Forces targeted operation update and distupgrade jobs\&. See the section about targeted updates about more information\&. +.RE +.sp +Set constants\&. +.PP +\fBSOLVER_SETEV\fR +.RS 4 +The job specified the exact epoch and version of the package set\&. +.RE +.PP +\fBSOLVER_SETEVR\fR +.RS 4 +The job specified the exact epoch, version, and release of the package set\&. +.RE +.PP +\fBSOLVER_SETARCH\fR +.RS 4 +The job specified the exact architecture of the packages from the set\&. +.RE +.PP +\fBSOLVER_SETVENDOR\fR +.RS 4 +The job specified the exact vendor of the packages from the set\&. +.RE +.PP +\fBSOLVER_SETREPO\fR +.RS 4 +The job specified the exact repository of the packages from the set\&. +.RE +.PP +\fBSOLVER_SETNAME\fR +.RS 4 +The job specified the exact name of the packages from the set\&. +.RE +.PP +\fBSOLVER_NOAUTOSET\fR +.RS 4 +Turn of automatic set flag generation for SOLVER_SOLVABLE jobs\&. +.RE +.PP +\fBSOLVER_SETMASK\fR +.RS 4 +A mask containing all the above set bits\&. +.RE +.sp +See the section about set bits for more information\&. +.SS "ATTRIBUTES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBPool *pool;\fR /* read only */ +\fI$job\fR\fB\->{\*(Aqpool\*(Aq}\fR +\fId\fR\fB\&.pool\fR +\fId\fR\fB\&.pool\fR +.fi +.if n \{\ +.RE +.\} +.sp +Back pointer to pool\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBId how;\fR /* read/write */ +\fI$job\fR\fB\->{\*(Aqhow\*(Aq}\fR +\fId\fR\fB\&.how\fR +\fId\fR\fB\&.how\fR +.fi +.if n \{\ +.RE +.\} +.sp +Union of the selection, action, action modifier, and set flags\&. The selection part describes the semantics of the \(lqwhat\(rq Id\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBId what;\fR /* read/write */ +\fI$job\fR\fB\->{\*(Aqwhat\*(Aq}\fR +\fId\fR\fB\&.what\fR +\fId\fR\fB\&.what\fR +.fi +.if n \{\ +.RE +.\} +.sp +Id describing the set of packages, the meaning depends on the selection part of the \(lqhow\(rq attribute\&. +.SS "METHODS" +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBSolvable *solvables()\fR +my \fI@solvables\fR \fB=\fR \fI$job\fR\fB\->solvables()\fR; +\fIsolvables\fR \fB=\fR \fIjob\fR\fB\&.solvables()\fR +\fIsolvables\fR \fB=\fR \fIjob\fR\fB\&.solvables()\fR +.fi +.if n \{\ +.RE +.\} +.sp +Return the set of solvables of the job as an array of Solvable objects\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBbool isemptyupdate()\fR; +\fI$job\fR\fB\->isemptyupdate()\fR +\fIjob\fR\fB\&.isemptyupdate()\fR +\fIjob\fR\fB\&.isemptyupdate?\fR +.fi +.if n \{\ +.RE +.\} +.sp +Convenience function to find out if the job describes an update job with no matching packages, i\&.e\&. a job that does nothing\&. Some package managers like \(lqzypper\(rq like to turn those jobs into install jobs, i\&.e\&. an update of a not\-installed package will result into the installation of the package\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fB\fR +my \fI$str\fR \fB= "\fR\fI$job\fR\fB"\fR; +\fIstr\fR \fB= str(\fR\fIjob\fR\fB)\fR +\fIstr\fR \fB=\fR \fIjob\fR\fB\&.to_s\fR +.fi +.if n \{\ +.RE +.\} +.sp +Return a string describing the job\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fB\fR +\fBif (\fR\fI$job1\fR \fB==\fR \fI$job2\fR\fB)\fR +\fBif\fR \fIjob1\fR \fB==\fR \fIjob2\fR\fB:\fR +\fBif\fR \fIjob1\fR \fB==\fR \fIjob2\fR +.fi +.if n \{\ +.RE +.\} +.sp +Two jobs are equal if they belong to the same pool and both the \(lqhow\(rq and the \(lqwhat\(rq attributes are the same\&. +.SS "TARGETED UPDATES" +.sp +Libsolv has two modes for upgrades and distupgrade: targeted and untargeted\&. Untargeted mode means that the installed packages from the specified set will be updated to the best version\&. Targeted means that packages that can be updated to a package in the specified set will be updated to the best package of the set\&. +.sp +Here\(cqs an example to explain the subtle difference\&. Suppose that you have package A installed in version "1\&.1", "A\-1\&.2" is available in one of the repositories and there is also package "B" that obsoletes package A\&. +.sp +An untargeted update of "A" will update the installed "A\-1\&.1" to package "B", because that is the newest version (B obsoletes A and is thus newer)\&. +.sp +A targeted update of "A" will update "A\-1\&.1" to "A\-1\&.2", as the set of packages contains both "A\-1\&.1" and "A\-1\&.2", and "A\-1\&.2" is the newer one\&. +.sp +An untargeted update of "B" will do nothing, as "B" is not installed\&. +.sp +An targeted update of "B" will update "A\-1\&.1" to "B"\&. +.sp +Note that the default is to do "auto\-targeting", thus if the specified set of packages does not include an installed package, the solver will assume targeted operation even if SOLVER_TARGETED is not used\&. You can turn off auto\-targeting with the SOLVER_FLAG_NO_AUTOTARGET solver option, see the Solver class for details\&. +.SS "SET BITS" +.sp +Set bits specify which parts of the specified packages where specified by the user\&. It is used by the solver when checking if an operation is allowed or not\&. For example, the solver will normally not allow the downgrade of an installed package\&. But it will not report a problem if the SOLVER_SETEVR flag is used, as it then assumes that the user specified the exact version and thus knows what he is doing\&. +.sp +So if a package "screen\-1\-1" is installed for the x86_64 architecture and version "2\-1" is only available for the i586 architecture, installing package "screen\-2\&.1" will ask the user for confirmation because of the different architecture\&. When using the Selection class to create jobs the set bits are automatically added, e\&.g\&. selecting \(lqscreen\&.i586\(rq will automatically add SOLVER_SETARCH, and thus no problem will be reported\&. .SH "THE SOLVER CLASS" .sp xxx @@ -2501,13 +2997,13 @@ my \fI$raw\fR \fB=\fR \fI$chksum\fR\fB\->raw()\fR; .RE .\} .sp -Finalize the checksum and return the result as raw bytes\&. This means that the result can contain zero bytes or unprintable characters\&. +Finalize the checksum and return the result as raw bytes\&. This means that the result can contain NUL bytes or unprintable characters\&. .sp .if n \{\ .RS 4 .\} .nf -\fBunsigned char *hex()\fR +\fBconst 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 diff --git a/doc/libsolv-bindings.txt b/doc/libsolv-bindings.txt index 4acec0f..7a8068a 100644 --- a/doc/libsolv-bindings.txt +++ b/doc/libsolv-bindings.txt @@ -1328,13 +1328,395 @@ just the base name unless SEARCH_FILES is used, for checksums it will return an empty string unless SEARCH_CHECKSUMS is used. Numeric values are currently stringified to an empty string. + THE SELECTION CLASS ------------------- -xxx +Selections are a way to easily deal with sets of packages. +There are multiple constructors to create them, the most useful +is probably the select() method in the Pool class. + +=== CONSTANTS === + +*SELECTION_NAME*:: + Create the selection by matching package names + +*SELECTION_PROVIDES*:: + Create the selection by matching package provides + +*SELECTION_FILELIST*:: + Create the selection by matching package files + +*SELECTION_CANON*:: + Create the selection by matching the canonical representation + of the package. This is normally a combination of the name, + the version, and the architecture of a package. + +*SELECTION_DOTARCH*:: + Allow an ``.'' suffix when matching names or + provides. + +*SELECTION_REL*:: + Allow the specification of a relation when matching names + or provides, e.g. "name >= 1.2". + +*SELECTION_INSTALLED_ONLY*:: + Limit the package search to installed packages. + +*SELECTION_SOURCE_ONLY*:: + Limit the package search to source packages only. + +*SELECTION_WITH_SOURCE*:: + Extend the package search to also match source packages. The + default is only to match binary packages. + +*SELECTION_GLOB*:: + Allow glob matching for package names, package provides, and + file names. + +*SELECTION_NOCASE*:: + Ignore case when matching package names, package provides, + and file names. + +*SELECTION_FLAT*:: + Return only one selection element describing the selected packages. + The default is to create multiple elements for all globbed packages. + Multiple elements are useful if you want to turn the selection into + an install job, in that case you want an install job for every + globbed package. + +=== ATTRIBUTES === + + Pool *pool; /* read only */ + $d->{'pool'} + d.pool + d.pool + +Back pointer to pool. + +=== METHODS === + + int flags(); + my $flags = $sel->flags(); + flags = sel.flags() + flags = sel.flags() + +Return the result flags of the selection. The flags are a subset +of the ones used when creating the selection, they describe which +method was used to get the result. For example, if you create the +selection with ``SELECTION_NAME | SELECTION_PROVIDES'', the resulting +flags will either be SELECTION_NAME or SELECTION_PROVIDES depending +if there was a package that matched the name or not. If there was +no match at all, the flags will be zero. + + bool isempty(); + $sel->isempty() + sel.isempty() + sel.isempty? + +Return true if the selection is empty, i.e. no package could be matched. + + void filter(Selection *other) + $sel->filter($other); + sel.filter(other) + sel.filter(other) + +Intersect two selections. Packages will only stay in the selection if there +are also included in the other selecting. Does an in-place modification. + + void add(Selection *other) + $sel->add($other); + sel.add(other) + sel.add(other) + +Build the union of two selections. All packages of the other selection will +be added to the set of packages of the selection object. Does an in-place +modification. Note that the selection flags are no longer meaningful after the +add operation. + + void add_raw(Id how, Id what) + $sel->add_raw($how, $what); + sel.add_raw(how, what) + sel.add_raw(how, what) + +Add a raw element to the selection. Check the Job class for information about +the how and what parameters. + + Job *jobs(int action) + my @jobs = $sel->jobs($action); + jobs = sel.jobs(action) + jobs = sel.jobs(action) + +Convert a selection into an array of Job objects. The action parameter is or-ed +to the ``how'' part of the job, it describes the type of job (e.g. install, +erase). See the Job class for the action and action modifier constants. + + Solvable *solvables() + my @solvables = $sel->solvables(); + solvables = sel.solvables() + solvables = sel.solvables() + +Convert a selection into an array of Solvable objects. + + + my $str = "$sel"; + str = str(sel) + str = sel.to_s + +Return a string describing the selection. THE JOB CLASS ------------- -xxx +Jobs are the way to specify to the dependency solver what to do. +Most of the times jobs will get created by calling the jobs() method +on a Selection object, but there is also a Job() constructor in the +Pool class. + +=== CONSTANTS === + +Selection constants: + +*SOLVER_SOLVABLE*:: + The ``what'' part is the id of a solvable. + +*SOLVER_SOLVABLE_NAME*:: + The ``what'' part is the id of a package name. + +*SOLVER_SOLVABLE_PROVIDES*:: + The ``what'' part is the id of a package provides. + +*SOLVER_SOLVABLE_ONE_OF*:: + The ``what'' part is an offset into the ``whatprovides'' data, created + by calling the towhatprovides() pool method. + +*SOLVER_SOLVABLE_REPO*:: + The ``what'' part is the id of a repository. + +*SOLVER_SOLVABLE_ALL*:: + The ``what'' part is ignored, all packages are selected. + +*SOLVER_SOLVABLE_SELECTMASK*:: + A mask containing all the above selection bits. + +Action constants: + +*SOLVER_NOOP*:: + Do nothing. + +*SOLVER_INSTALL*:: + Install a package of the specified set of packages. It tries to install + the best matching package (i.e. the highest version of the packages from + the repositories with the highest priority). + +*SOLVER_ERASE*:: + Erase all of the packages from the specified set. If a package is not + installed, erasing it will keep it from getting installed. + +*SOLVER_UPDATE*:: + Update the matching installed packages to their best version. If none + of the specified packages are installed, try to update the installed + packages to the specified versions. See the section about targeted + updates about more information. + +*SOLVER_WEAKENDEPS*:: + Allow to break the dependencies of the matching packages. Handle with care. + +*SOLVER_MULTIVERSION*:: + Mark the matched packages for multiversion install. If they get to be installed + because of some other job, the installation will keep the old version of the + package installed (for rpm by using ``-i'' instead of ``-U''). + +*SOLVER_LOCK*:: + Do not change the state of the matched packages, i.e. when they are installed + they stay installed, if not they are not selected for installation. + +*SOLVER_DISTUPGRADE*:: + Update the matching installed packages to the best version included in one + of the repositories. After this operation, all come from one of the available + repositories except orphaned packages. Orphaned packages are packages that + have no relation to the packages in the repositories, i.e. no package in the + repositories have the same name or obsolete the orphaned package. + This action brings the installed packages in sync with the ones in the + repository. It also turns of arch/vendor/version locking for the affected + packages to simulate a fresh installation. This means that distupgrade can + actually downgrade packages if only lower versions of a package are available + in the repositories. + +*SOLVER_DROP_ORPHANED*:: + Erase all the matching installed packages if they are orphaned. This only makes + sense if there is a ``distupgrade all packages'' job. The default is to erase + orphaned packages only if they block the installation of other packages. + +*SOLVER_VERIFY*:: + Fix dependency problems of matching installed packages. The default is to ignore + dependency problems for installed packages. + +*SOLVER_USERINSTALLED*:: + The matching installed packages are considered to be installed by a user, thus + not installed to fulfil some dependency. This is needed input for the calculation + of unneeded packages for jobs that have the SOLVER_CLEANDEPS flag set. + +*SOLVER_JOBMASK*:: + A mask containing all the above action bits. + +Action modifier constants: + +*SOLVER_WEAK*:: + Makes the job a weak job. The solver tries to fulfil weak jobs, but does not + report a problem if it is not possible to do so. + +*SOLVER_ESSENTIAL*:: + Makes the job an essential job. If there is a problem with the job, the solver + will not propose to remove the job as one solution (unless all other solutions + are also to remove essential jobs). + +*SOLVER_CLEANDEPS*:: + The solver will try to also erase all packages dragged in through dependencies + when erasing the package. This needs SOLVER_USERINSTALLED jobs to maximize user + satisfaction. + +*SOLVER_FORCEBEST*:: + Insist on the best package for install, update, and distupgrade jobs. If this + flag is not used, the solver will use the second-best package if the best + package cannot be installed for some reason. When this flag is used, the solver + will generate a problem instead. + +*SOLVER_TARGETED*:: + Forces targeted operation update and distupgrade jobs. See the section about + targeted updates about more information. + +Set constants. + +*SOLVER_SETEV*:: + The job specified the exact epoch and version of the package set. + +*SOLVER_SETEVR*:: + The job specified the exact epoch, version, and release of the package set. + +*SOLVER_SETARCH*:: + The job specified the exact architecture of the packages from the set. + +*SOLVER_SETVENDOR*:: + The job specified the exact vendor of the packages from the set. + +*SOLVER_SETREPO*:: + The job specified the exact repository of the packages from the set. + +*SOLVER_SETNAME*:: + The job specified the exact name of the packages from the set. + +*SOLVER_NOAUTOSET*:: + Turn of automatic set flag generation for SOLVER_SOLVABLE jobs. + +*SOLVER_SETMASK*:: + A mask containing all the above set bits. + +See the section about set bits for more information. + +=== ATTRIBUTES === + + Pool *pool; /* read only */ + $job->{'pool'} + d.pool + d.pool + +Back pointer to pool. + + Id how; /* read/write */ + $job->{'how'} + d.how + d.how + +Union of the selection, action, action modifier, and set flags. +The selection part describes the semantics of the ``what'' Id. + + Id what; /* read/write */ + $job->{'what'} + d.what + d.what + +Id describing the set of packages, the meaning depends on the +selection part of the ``how'' attribute. + +=== METHODS === + + Solvable *solvables() + my @solvables = $job->solvables(); + solvables = job.solvables() + solvables = job.solvables() + +Return the set of solvables of the job as an array of Solvable +objects. + + bool isemptyupdate(); + $job->isemptyupdate() + job.isemptyupdate() + job.isemptyupdate? + +Convenience function to find out if the job describes an update +job with no matching packages, i.e. a job that does nothing. +Some package managers like ``zypper'' like to turn those jobs +into install jobs, i.e. an update of a not-installed package +will result into the installation of the package. + + + my $str = "$job"; + str = str(job) + str = job.to_s + +Return a string describing the job. + + + if ($job1 == $job2) + if job1 == job2: + if job1 == job2 + +Two jobs are equal if they belong to the same pool and both the +``how'' and the ``what'' attributes are the same. + +=== TARGETED UPDATES === +Libsolv has two modes for upgrades and distupgrade: targeted and +untargeted. Untargeted mode means that the installed packages from +the specified set will be updated to the best version. Targeted means +that packages that can be updated to a package in the specified set +will be updated to the best package of the set. + +Here's an example to explain the subtle difference. Suppose that +you have package A installed in version "1.1", "A-1.2" is available +in one of the repositories and there is also package "B" that +obsoletes package A. + +An untargeted update of "A" will update the installed "A-1.1" to +package "B", because that is the newest version (B obsoletes A and +is thus newer). + +A targeted update of "A" will update "A-1.1" to "A-1.2", as the +set of packages contains both "A-1.1" and "A-1.2", and "A-1.2" is +the newer one. + +An untargeted update of "B" will do nothing, as "B" is not installed. + +An targeted update of "B" will update "A-1.1" to "B". + +Note that the default is to do "auto-targeting", thus if the specified +set of packages does not include an installed package, the solver +will assume targeted operation even if SOLVER_TARGETED is not used. +You can turn off auto-targeting with the SOLVER_FLAG_NO_AUTOTARGET +solver option, see the Solver class for details. + +=== SET BITS === +Set bits specify which parts of the specified packages where specified +by the user. It is used by the solver when checking if an operation is +allowed or not. For example, the solver will normally not allow the +downgrade of an installed package. But it will not report a problem if +the SOLVER_SETEVR flag is used, as it then assumes that the user specified +the exact version and thus knows what he is doing. + +So if a package "screen-1-1" is installed for the x86_64 architecture and +version "2-1" is only available for the i586 architecture, installing +package "screen-2.1" will ask the user for confirmation because of the +different architecture. When using the Selection class to create jobs +the set bits are automatically added, e.g. selecting ``screen.i586'' will +automatically add SOLVER_SETARCH, and thus no problem will be reported. THE SOLVER CLASS ----------------