source: trunk/doc/guide/xml/internals/registry.xml @ 7649

Last change on this file since 7649 was 7649, checked in by wbb4, 16 years ago

Bug:
Submitted by:
Reviewed by:
Approved by:
Obtained from:

Completed the API documentation for the new registry.

  • Property svn:eol-style set to native
File size: 9.4 KB
Line 
1<?xml version="1.0" encoding="UTF-8" ?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<chapter id="registry">
5  <chapterinfo>
6    <keywordset>
7      <keyword>
8                                images
9      </keyword>
10    </keywordset>
11  </chapterinfo>
12 
13  <title>The DarwinPorts Registry</title> 
14
15  <sect1 id="about">
16    <title>About This Chapter</title>
17
18                <para>This chapter provides a detailed overview of the new DarwinPorts
19                        Registry package and its API.  This package is queried by the
20                        DarwinPorts tools for information about installed ports for
21                        information related to dependencies, port images, and simple user
22                        information about what is installed.</para>
23
24                <para>The DarwinPorts Registry contains an abstraction layer which
25                        allows for alternative storage mechanisms for receipts.  This
26                        chapter will also provide an overview of this, and how to write a
27                        receipt storage module.</para>
28  </sect1>
29
30        <sect1 id="registry_intro">
31                <title>Introduction To The New Registry</title>
32
33                <para>The new DarwinPorts Registry solves many problems with the old
34                        registry:</para>
35
36                <itemizedlist>
37                        <listitem><para>The old registry provided no mechanism for
38                                modifying a receipt after installation.</para></listitem>
39                        <listitem><para>The old registry kept no global database of
40                                all installed files and ports that could be queried by the port
41                                system to check for conflicts, or by the user to check which
42                                port installed a file.</para></listitem>
43                        <listitem><para>The old registry was tied to flat-file receipts,
44                                and provided no abstraction of open and close calls to receipt
45                                files.</para></listitem>
46                </itemizedlist>
47
48                <para>The new registry allows for modification of receipts, to
49                        reflect and changes made to installed ports being maintained by
50                        DarwinPorts.  It also provides global file and dependencies
51                        databases that can be queried to check if installed files conflict
52                        with each other, and to maintain dependency trees of installed
53                        ports.  It also provides abstraction over a modular receipt
54                        storage layer, allowing for flat-file receipts, as well as
55                        receipts stored in a SQLite database.</para>
56        </sect1>
57
58        <sect1 id="registry_api">
59                <title>API For Accessing The Registry</title>
60
61                <para>The DarwinPorts Registry provides a public API in the
62                        <varname>registry1.0</varname> Tcl package.  Using this API you
63                        can access the DarwinPorts Registry using the storage mechanism
64                        the DarwinPorts user has chosen for receipt storage.</para>
65
66                <variablelist>
67                        <varlistentry>
68                                <term><computeroutput>registry::new_entry {name version
69                                        {revision 0} {variants ""}}</computeroutput></term>
70
71                                <listitem>
72                                        <para>Begin the creation of a new registry entry for the given
73                                                port.</para>
74                                        <para>Returns a reference ID to the registry entry
75                                                created.</para>
76                                </listitem>
77                        </varlistentry>
78
79                        <varlistentry>
80                                <term><computeroutput>registry::open_entry {name {version 0}
81                                        {revision 0} {variants ""}}</computeroutput></term>
82
83                                <listitem>
84                                        <para>Opens an existing registry entry.</para>
85                                        <para>Returns a reference ID to the registry entry that was
86                                                opened.</para>
87                                </listitem>
88                        </varlistentry>
89
90                        <varlistentry>
91                                <term><computeroutput>registry::entry_exists {name version
92                                        {revision 0} {variants ""}}</computeroutput></term>
93
94                                <listitem>
95                                        <para>Checks to see if a port exists in the registry.</para>
96                                        <para>Returns 1 if the entry exists, 0 if not.</para>
97                                </listitem>
98                        </varlistentry>
99
100                        <varlistentry>
101                                <term><computeroutput>registry::write_entry
102                                        {ref}</computeroutput></term>
103
104                                <listitem>
105                                        <para>Writes the receipt associated with the given
106                                                reference.</para>
107                                </listitem>
108                        </varlistentry>
109                        <varlistentry>
110                                <term><computeroutput>registry::delete_entry
111                                        {ref}</computeroutput></term>
112
113                                <listitem>
114                                        <para>Deletes the receipt associated with the given
115                                                reference.</para>
116                                </listitem>
117                        </varlistentry>
118
119                        <varlistentry>
120                                <term><computeroutput>registry::property_store {ref property
121                                        value}</computeroutput></term>
122
123                                <listitem>
124                                        <para>Store the given value with the property name in the
125                                                receipt associated with the given reference.</para>
126                                </listitem>
127                        </varlistentry>
128
129                        <varlistentry>
130                                <term><computeroutput>registry::property_retrieve {ref
131                                        property}</computeroutput></term>
132
133                                <listitem>
134                                        <para>Retrieve the property name from the receipt associated
135                                                with the given reference.</para>
136                                        <para>Returns the value of the property, if the property
137                                                exists.</para>
138                                </listitem>
139                        </varlistentry>
140
141                        <varlistentry>
142                                <term><computeroutput>registry::installed {{name ""} {version
143                                        ""}}</computeroutput></term>
144
145                                <listitem>
146                                        <para>Get all installed ports, optionally all installed ports
147                                                matching the given name, or the given name and version.</para>
148                                        <para>Returns a list of the installed ports.</para>
149                                </listitem>
150                        </varlistentry>
151
152                        <varlistentry>
153                                <term><computeroutput>registry::location {portname
154                                        portversion}</computeroutput></term>
155
156                                <listitem>
157                                        <para>Returns the physical location the port is installed in on
158                                                the disk.  This is primarily useful for finding out where a
159                                                port image is installed.</para>
160                                </listitem>
161                        </varlistentry>
162
163                        <varlistentry>
164                                <term><computeroutput>registry::open_file_map
165                                        {args}</computeroutput></term>
166
167                                <listitem>
168                                        <para>Opens the file map that contains file-port
169                                                relationships.</para>
170                                </listitem>
171                        </varlistentry>
172
173                        <varlistentry>
174                                <term><computeroutput>registry::file_registered
175                                        {file}</computeroutput></term>
176
177                                <listitem>
178                                        <para>Returns the name of the port that owns the given file,
179                                                if the file is registered as installed, and 0 otherwise.</para>
180                                </listitem>
181                        </varlistentry>
182
183                        <varlistentry>
184                                <term><computeroutput>registry::port_registered
185                                        {name}</computeroutput></term>
186
187                                <listitem>
188                                        <para>Returns a list of all files associated with the given
189                                                port if that port is installed, and 0 otherwise.</para>
190                                </listitem>
191                        </varlistentry>
192
193                        <varlistentry>
194                                <term><computeroutput>registry::register_file {file
195                                        port}</computeroutput></term>
196
197                                <listitem>
198                                        <para>Registeres the given file in the file map as belonging
199                                                to the given port.</para>
200                                </listitem>
201                        </varlistentry>
202
203                        <varlistentry>
204                                <term><computeroutput>registry::unregister_file
205                                        {file}</computeroutput></term>
206
207                                <listitem>
208                                        <para>Removes the file from the file map.</para>
209                                </listitem>
210                        </varlistentry>
211
212                        <varlistentry>
213                                <term><computeroutput>registry::write_file_map
214                                        {args}</computeroutput></term>
215
216                                <listitem>
217                                        <para>Write the changes to the file map.</para>
218                                </listitem>
219                        </varlistentry>
220
221                        <varlistentry>
222                                <term><computeroutput>registry::open_dep_map
223                                        {args}</computeroutput></term>
224
225                                <listitem>
226                                        <para>Opens the dependency map that contains port dependency
227                                                relationships.</para>
228                                </listitem>
229                        </varlistentry>
230
231                        <varlistentry>
232                                <term><computeroutput>registry::fileinfo_for_file {fname}</computeroutput></term>
233
234                                <listitem>
235                                        <para>Returns a list for the given file name representing all
236                                                data currently known about the file.  This is a 6-tuple in the
237                                                form of:</para>
238                                        <orderedlist>
239                                                <listitem>file path</listitem>
240                                                <listitem>uid</listitem>
241                                                <listitem>gid</listitem>
242                                                <listitem>mode</listitem>
243                                                <listitem>size</listitem>
244                                                <listitem>md5 checksum</listitem>
245                                        </orderedlist>
246                                </listitem>
247                        </varlistentry>
248
249                        <varlistentry>
250                                <term><computeroutput>registry::fileinfo_for_index {flist}</computeroutput></term>
251
252                                <listitem>
253                                        <para>Returns a list of information concerning each file in
254                                                the given file list, if that file exists in the registry.  The
255                                                information if obtained through
256                                                <varname>registry::fileinfo_for_file</varname></para>
257                                </listitem>
258                        </varlistentry>
259
260                        <varlistentry>
261                                <term><computeroutput>registry::list_depends
262                                        {name}</computeroutput></term>
263
264                                <listitem>
265                                        <para>Returns a list of all the ports that given port name
266                                                depends on.</para>
267                                </listitem>
268                        </varlistentry>
269
270                        <varlistentry>
271                                <term><computeroutput>registry::list_dependents
272                                        {name}</computeroutput></term>
273
274                                <listitem>
275                                        <para>Returns a list of all the ports that depend on the given
276                                                port name.</para>
277                                </listitem>
278                        </varlistentry>
279
280                        <varlistentry>
281                                <term><computeroutput>registry::register_dep {dep type
282                                        port}</computeroutput></term>
283
284                                <listitem>
285                                        <para>Registers the given dependency as the given type of
286                                                dependency with the given port.</para>
287                                </listitem>
288                        </varlistentry>
289
290                        <varlistentry>
291                                <term><computeroutput>registry::unregister_dep {dep type
292                                        port}</computeroutput></term>
293
294                                <listitem>
295                                        <para>Unregisters the given dependency of the given type as a
296                                                dependency of the given port.</para>
297                                </listitem>
298                        </varlistentry>
299
300                        <varlistentry>
301                                <term><computeroutput>registry::write_dep_map
302                                        {args}</computeroutput></term>
303
304                                <listitem>
305                                        <para>Write changes to the dependency map.</para>
306                                </listitem>
307                        </varlistentry>
308                </variablelist>
309        </sect1>
310
311        <!-- <sect1 id="receipt_modules">
312                <title>New Registry Receipt Modules</title>
313
314                <para>Writing a receipt module for the new registry is very easy.
315                        The new registry makes </para>
316        </sect1> -->
317
318</chapter>
Note: See TracBrowser for help on using the repository browser.