Mailinglist Archive: zypp-commit (606 mails)

[kkaempf@xxxxxxxxxxxxxxxx]

Author: kkaempf
Date: Tue Apr  8 12:17:40 2008
New Revision: 9446

URL: http://svn.opensuse.org/viewcvs/zypp?rev=9446&view=rev
Log:
Initial documentation on how to use the attribute store (aka repodata)

Added:
    trunk/sat-solver/doc/README.attr

Added: trunk/sat-solver/doc/README.attr
URL: 
http://svn.opensuse.org/viewcvs/zypp/trunk/sat-solver/doc/README.attr?rev=9446&view=auto
==============================================================================
--- trunk/sat-solver/doc/README.attr (added)
+++ trunk/sat-solver/doc/README.attr Tue Apr  8 12:17:40 2008
@@ -0,0 +1,151 @@
+All about attributes
+====================
+
+
+Why attributes ?
+----------------
+
+The .solv files contain Solvables, as defined in src/solvable.h
+These are the basic objects for the solver, containing name,
+architecture, evr (epoch-version-release), vendor and dependencies.
+
+However, a (RPM) package has many more properties. Like summary,
+description, license, package group, etc.
+All theses properties are not needed for dependency resolution and
+hence are stored outside of Solvables.
+
+Sat-solver provides the 'Attribute Store' for these properties,
+internally called 'repodata'. See src/repodata.h
+
+
+What are attributes ?
+---------------------
+
+An attribute is a quadruple containing
+
+ - solvable (to which this attribute belongs)
+ - name (describing the content, like 'solvable:description')
+ - type (like 'number' or 'string')
+ - value (according to the type)
+ 
+
+How to set attributes ?
+-----------------------
+
+1. You need a Solvable
+
+  Attributes belong to a solvable. So you need a solvable first. And
+  solvables belong to a repo which belongs to a pool.
+
+    /* create a pool */
+    Pool *pool = pool_create();
+    
+    /* create a repo */
+    Repo *repo = repo_create(pool, "demo");
+    
+    /* create a solvable */
+    Id s = repo_add_solvable(repo);
+
+
+2. You need to create the attribute store
+
+  By default .solv files don't contain additional attributes. So you
+  have to add the attribute store to the repository:
+
+    Repodata *data = repo_add_repodata(repo, 0);
+
+
+3. You need space for the attributes
+
+  Space for the attribute store must be explicitly requested. Not for
+  every attribute but you have to signal that a solvable has
+  attributes.
+
+  First you compute the datanum:
+
+    Solvable *solvable = pool_id2solvable(pool, s);
+    Id datanum = (solvable - pool->solvables) - repo->start;
+
+  datanum is the reference from the attribute store back to the
+  solvable.
+
+  As you can see, the datanum is basically the offset of the solvable
+  within the repo. Remember that the attributes are per-repository (as
+  is the solvable. When calling 'repodata_*' function, use the datanum
+  to represent the solvable.
+
+  Extending the store is done with repodata_extend():
+
+    repodata_extend(data, solvable - pool->solvables);
+
+
+4. Set attributes
+
+  Now you can set attributes. You do this with repodata_set_*()
+  passing the store (data), the solvable reference (datanum), the name
+  of the solvable and the value.
+
+  See src/repodata.h for a complete list of all the repodata_set_*()
+  functions.
+
+  Attributes are named and in good sat-solver tradition, everything is
+  an Id.
+
+    Id attr_name = str2id(pool, "name_of_attribute", 1);
+
+  See knownid.h for predefined attribute names.
+
+
+4.1 Setting a boolean attribute
+
+  A boolean attribute derives is value from its presence. So you don't
+  pass an explicit true/false value but call repodata_set_void() if
+  the attribute is 'true'.
+
+    repodata_set_void(data, datanum, attr_name);
+
+
+4.2 Setting a numeric attribute
+
+  Storing a numeric value is done with repodata_set_num, passing an
+  unsinged integer:
+
+    unsigned int value = 123456;
+    repodata_set_num(data, datanum, attr_name, value);
+
+
+4.3 Setting a string attribute
+
+  Strings are 'const char' pointers and set like:
+  
+    const char *s = "This is a string";
+    repodata_set_str(data, datanum, attr_name, s);
+  
+  If the same string is used multiple times as an attribute value, its
+  more efficient to store it once and use its Id.
+  
+
+4.4 Setting an Id attribute
+
+    Id id = str2id(pool, "value_of_attribute", 1);
+    repodata_set_id(data, datanum, attr_name, id);
+
+
+5. Writing the .solv file
+
+  Before writing out a .solv file, you need to internalize the
+  attribute store so it gets stored together with the solvables.
+
+    repodata_internalize(data);
+
+  Thats black MM magic. Don't ask.
+
+
+A. About attribute names
+
+  You are free to choose any name for the attributes. However, when
+  dealing with (RPM) packages, there are a lot of standard attributes
+  in use. src/knownid.h defines most of them, e.g. SOLVABLE_SUMMARY (a
+  string) or SOLVABLE_BUILDTIME (a number). Use the predefined
+  attribute names whenever applicable.
+  
\ No newline at end of file

--
To unsubscribe, e-mail: zypp-commit+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: zypp-commit+help@xxxxxxxxxxxx