start with the bindings documentation

1 files changed, 1150 insertions, 0 deletions

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.
+
+	<stringification>
+	my $str = "$dep";
+	str = str(dep)
+	str = dep.to_s
+
+Same as calling the str() method.
+
+	<comparisons ==, !=>
+	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.
+
+	<stringification>
+	my $str = "$repo";
+	str = str(repo)
+	str = repo.to_s
+
+Return the name of the repository, or "Repo#<id>" if no name is set.
+
+	<comparisons ==, !=>
+	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.
+
+	<comparisons ==, !=>
+	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.
+
+	<stringification>
+	my $str = "$chksum";
+	str = str(chksum)
+	str = chksum.to_s
+
+If the checksum is finished, the checksum is returned
+as "<type>:<hex>" string. Otherwise "<type>: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 <mls@suse.de>
+