source: trunk/doc-new/guide/xml/internals.xml @ 112882

Last change on this file since 112882 was 112882, checked in by raimue@…, 7 years ago

guide:
Remove outdated registry API reference

File size: 21.3 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
4<chapter id="internals">
5  <title>MacPorts Internals</title>
6
7  <para>This chapter contains information about the MacPorts file layout,
8  configuration files, a few fundamental port installation concepts, and the
9  MacPorts APIs.</para>
10
11  <section id="internals.hierarchy">
12    <title>File Hierarchy</title>
13
14    <xi:include href="../../man/xml/porthier.7.xml"
15                xmlns:xi="http://www.w3.org/2001/XInclude" />
16  </section>
17
18  <xi:include href="macports.conf.xml"
19              xmlns:xi="http://www.w3.org/2001/XInclude" />
20
21  <section id="internals.images">
22    <title>Port Images</title>
23
24    <para>MacPorts has a unique ability to allow multiple versions,
25    revisions, and variants of the same port to be installed at the same time, so
26    you may test new port versions without uninstalling a previous working
27    version.</para>
28
29    <para>This capability derives from the fact that a MacPorts port by
30    default is not installed into its final or <quote>activated</quote> location, but
31    rather to an intermediate location that is only made available to other
32    ports and end-users after an activation phase that extracts all
33    its files from the image repository. Deactivating a port
34    only removes the files from their activated
35    locations (usually under <varname>${prefix}</varname>)
36    —the deactivated port's image is not disturbed.</para>
37
38    <para>The location of an installed port's image can be seen
39    by running:
40    <programlisting><prompt>%%</prompt> <userinput>port location PORTNAME</userinput></programlisting>
41    </para>
42  </section>
43
44  <section id="internals.apis">
45    <title>APIs and Libs</title>
46
47    <para>The MacPorts system is composed of three Tcl libraries:</para>
48
49    <itemizedlist>
50      <listitem>
51        <para>MacPorts API - MacPorts public API for handling Portfiles,
52        dependencies, and registry</para>
53      </listitem>
54
55      <listitem>
56        <para>Ports API - API for Portfile parsing and execution</para>
57      </listitem>
58
59      <listitem>
60        <para>pextlib - C extensions to Tcl</para>
61      </listitem>
62    </itemizedlist>
63
64    <section id="internals.apis.ports">
65      <title>Ports API</title>
66
67      <para>The code for the Port API is located in
68      <filename>base/src/port1.0</filename>. The Port API provides all the
69      primitives required for a Portfile to be parsed, queried, and executed.
70      It also provides a single procedure call that the MacPorts API uses to
71      kick off execution: <code>eval_targets</code>. The port Tcl library supplies these
72      procedures, all of which are generated at run-time using the
73      <code>options</code> procedure in portutil.tcl.</para>
74
75      <para>The macports Tcl library loads the Portfile into a
76      sub-interpreter, within which all port-specific code is run. This
77      process ensures that there will never be pollution of the Tcl space of
78      other ports, nor the MacPorts libraries, nor the calling
79      application.</para>
80
81      <note>
82        <para>Portfiles are executed in a Tcl interpreter as Tcl code (and not
83        truly parsed strictly speaking), so every Portfile option must be a
84        TCL procedure.</para>
85      </note>
86
87      <para>The Ports API performs the following functions:</para>
88
89      <itemizedlist>
90        <listitem>
91          <para>Manages target registrations. All targets register themselves
92          with the Port API. Accordingly, the Port API creates pre-/post-/main
93          overrides for each of the targets.</para>
94        </listitem>
95
96        <listitem>
97          <para>Option/Default handling. All Portfile options (name, version,
98          revision ...) are registered by targets. The Port API creates
99          procedures for these options, and sets up the complex variable
100          traces necessary to support option defaults.</para>
101        </listitem>
102
103        <listitem>
104          <para>Executes target procedures, including the pre/post/main
105          routines.</para>
106        </listitem>
107
108        <listitem>
109          <para>Manages a state file containing information about what
110          variants were specified and what targets have run
111          successfully.</para>
112        </listitem>
113
114        <listitem>
115          <para>Provides essential Portfile Tcl extensions (reinplace,
116          xinstall, etc).</para>
117        </listitem>
118
119        <listitem>
120          <para>Provides simple access to the ui_event mechanism by providing
121          the various ui_ procedures (i.e., ui_msg, ui_error).</para>
122        </listitem>
123      </itemizedlist>
124    </section>
125
126    <section id="internals.apis.macports">
127      <title>MacPorts API</title>
128
129      <para>The code for the MacPorts API is located in
130      <filename>base/src/macports1.0</filename>. The MacPorts API provides a
131      public API into the MacPorts system by providing simple primitives for
132      handling Portfiles, dependencies, and registry operations, and exports
133      the MacPorts API for the <command>port</command> command line utility,
134      or any other. The API has very little information about the contents
135      Portfiles; instead, it relies entirely upon the <command>port</command>
136      Tcl library. By keeping the high level API simple and generic, revisions
137      to the underlying ports system will not necessarily require a revision
138      of the high level MacPorts API.</para>
139
140      <para>The MacPorts API is also responsible for loading user specified
141      options into a sub-interpreter to be evaluated by the ports API. In that
142      case it sets the variable name in the sub-interpreter and adds the
143      option to the sub-interpreter's global array user_options(). User
144      options are passed as part of the call to <code>mportopen</code>.</para>
145
146      <para>The MacPorts API performs the following functions:</para>
147
148      <itemizedlist>
149        <listitem>
150          <para>Dependency support.</para>
151
152          <para>This is implemented in a highly generic fashion, and is used
153          throughout the system. The dependency functions are exported to the
154          Port API, and the Port API uses them to execute targets in the
155          correct order.</para>
156        </listitem>
157
158        <listitem>
159          <para>Dependency processing.</para>
160
161          <para>Software dependencies are handled at this layer using the
162          dependency support layer.</para>
163        </listitem>
164
165        <listitem>
166          <para>UI abstractions.</para>
167
168          <para>UI Abstractions are handled at this layer. Each port action is
169          provided a context, and a mechanism for posting user interface
170          events is exported to the Port API (ui_event).</para>
171        </listitem>
172
173        <listitem>
174          <para>Registry management routines.</para>
175
176          <para>Manages the SQLite port registry in
177              <filename>${prefix}/var/macports/registry/</filename>. See also
178              <xref linkend="internals.registry" />.</para>
179          </itemizedlist>
180        </listitem>
181
182        <listitem>
183          <para>Exports the MacPorts API for use by client
184          applications.</para>
185
186          <para>The following routines are defined.</para>
187
188          <itemizedlist>
189            <listitem>
190              <para><code>mportinit:</code> Initializes the MacPorts system.
191              Should be called before trying to use any other
192              procedure.</para>
193            </listitem>
194
195            <listitem>
196              <para><code>mportsearch:</code> Given a regexp, searches the
197              <filename>PortIndex</filename> for ports with matching
198              names.</para>
199            </listitem>
200
201            <listitem>
202              <para><code>mportopen:</code> Given a URI to a port, opens a
203              Portfile and returns an opaque handle to it.</para>
204            </listitem>
205
206            <listitem>
207              <para><code>portclose:</code> Given a port handle, closes a
208              Portfile.</para>
209            </listitem>
210
211            <listitem>
212              <para><code>mportexec:</code> Given a port handle, executes a
213              target (i.e. install).</para>
214            </listitem>
215
216            <listitem>
217              <para><code>mportinfo:</code> Given a port handle, this returns
218              the PortInfo array (as a flat list of array elements). This is a
219              little tricky and unstable and only used by the
220              <command>portindex</command> command.</para>
221            </listitem>
222
223            <listitem>
224              <para><code>mportdepends:</code> Given a port handle, returns a
225              list of ports upon which the specified port depends.</para>
226            </listitem>
227          </itemizedlist>
228        </listitem>
229      </itemizedlist>
230
231      <para>For an example of the MacPorts API, when one executes
232      <command>port search cm3</command>, the port utility:</para>
233
234      <itemizedlist>
235        <listitem>
236          <para>Calls the <code>mportsearch</code> function to find all ports
237          containing <quote>cm3</quote>.</para>
238        </listitem>
239
240        <listitem>
241          <para>Returns Tcl array(s) containing data from the
242          <filename>PortIndex</filename>: port name, version, revision,
243          variants, etc.</para>
244        </listitem>
245
246        <listitem>
247          <para>Formats the list of arrays in the standard viewing
248          format.</para>
249        </listitem>
250      </itemizedlist>
251
252      <para>For another MacPorts API example, when one executes <command>port
253      install cm3</command>, the port utility:</para>
254
255      <itemizedlist>
256        <listitem>
257          <para>Calls the <code>mportsearch</code> function to find the first
258          port that matches the name <quote>cm3</quote>.</para>
259        </listitem>
260
261        <listitem>
262          <para>Calls the <code>mportopen</code> function to open the
263          port.</para>
264        </listitem>
265
266        <listitem>
267          <para>Calls the <code>mportexec</code> function to execute the
268          install target in the port.</para>
269        </listitem>
270
271        <listitem>
272          <para>Calls the <code>mportclose</code> function to close the
273          port.</para>
274        </listitem>
275      </itemizedlist>
276    </section>
277
278    <section id="internals.apis.pextlib">
279      <title>pextlib</title>
280
281      <para>The pextlib TCL library provides a variety of C extensions to add
282      capabilities to TCL procedures; for example, an interface to flock(2)
283      and mkstemp(3).</para>
284    </section>
285  </section>
286
287  <section id="internals.registry">
288    <title>The MacPorts Registry</title>
289
290    <para>This chapter provides an overview of the MacPorts registry and its
291    API. The registry is queried by MacPorts utilities for information about
292    installed ports related to dependencies, port images, and simple user
293    information about what is installed. It provides abstraction over a
294    modular receipt storage layer; this allows for flat file receipts as well
295    as receipts stored in a SQLite database.</para>
296
297    <para>The registry allows MacPorts utilities to:</para>
298
299    <itemizedlist>
300      <listitem>
301        <para>Modify receipts to reflect changes made to installed ports being
302        maintained by MacPorts.</para>
303      </listitem>
304
305      <listitem>
306        <para>Query the global file and dependency databases for file
307        conflicts between a port being installed and a port already
308        installed.</para>
309      </listitem>
310
311      <listitem>
312        <para>Maintain dependency trees of installed ports.</para>
313      </listitem>
314    </itemizedlist>
315
316    <section id="internals.registry.files">
317      <title>Registry Files</title>
318
319      <para>The flat file registry (MacPorts default registry) files are
320      contained in <filename>${portdbpath}/receipts</filename>, which by
321      default is location
322      <filename>${prefix}/var/macports/receipts</filename>. File mappings and
323      dependency mappings are tracked in the flat file registry by two
324      files:</para>
325
326      <itemizedlist>
327        <listitem>
328          <para>file_map.db</para>
329        </listitem>
330
331        <listitem>
332          <para>dep_map.bz2</para>
333        </listitem>
334      </itemizedlist>
335    </section>
336
337    <section id="internals.registry.api">
338      <title>The Registry API</title>
339
340      <para>The MacPorts registry provides a public API in the registry1.0 Tcl
341      package. Using this API listed below you can access the MacPorts
342      Registry using the default receipt storage mechanism chosen in
343      <filename>macports.conf</filename>.</para>
344
345      <variablelist>
346        <varlistentry>
347          <term><computeroutput>registry::new_entry {name version {revision 0}
348          {variants ""}}</computeroutput></term>
349
350          <listitem>
351            <para>Begin the creation of a new registry entry for the given
352            port. Returns a reference ID to the registry entry created.</para>
353          </listitem>
354        </varlistentry>
355      </variablelist>
356
357      <variablelist>
358        <varlistentry>
359          <term><computeroutput>registry::open_entry {name {version 0}
360          {revision 0} {variants ""}}</computeroutput></term>
361
362          <listitem>
363            <para>Opens an existing registry entry. Returns a reference ID to
364            the registry entry that was opened.</para>
365          </listitem>
366        </varlistentry>
367      </variablelist>
368
369      <variablelist>
370        <varlistentry>
371          <term><computeroutput>registry::entry_exists {name version {revision
372          0} {variants ""}}</computeroutput></term>
373
374          <listitem>
375            <para>Checks to see if a port exists in the registry. Returns 1 if
376            the entry exists, 0 if not.</para>
377          </listitem>
378        </varlistentry>
379      </variablelist>
380
381      <variablelist>
382        <varlistentry>
383          <term><computeroutput>registry::write_entry
384          {ref}</computeroutput></term>
385
386          <listitem>
387            <para>Writes the receipt associated with the given
388            reference.</para>
389          </listitem>
390        </varlistentry>
391      </variablelist>
392
393      <variablelist>
394        <varlistentry>
395          <term><computeroutput>registry::delete_entry
396          {ref}</computeroutput></term>
397
398          <listitem>
399            <para>Deletes the receipt associated with the given
400            reference.</para>
401          </listitem>
402        </varlistentry>
403      </variablelist>
404
405      <variablelist>
406        <varlistentry>
407          <term><computeroutput>registry::property_store {ref property
408          value}</computeroutput></term>
409
410          <listitem>
411            <para>Store the given value with the property name in the receipt
412            associated with the given reference.</para>
413          </listitem>
414        </varlistentry>
415      </variablelist>
416
417      <variablelist>
418        <varlistentry>
419          <term><computeroutput>registry::property_retrieve {ref
420          property}</computeroutput></term>
421
422          <listitem>
423            <para>Retrieve the property name from the receipt associated with
424            the given reference. Returns the value of the property, if the
425            property exists.</para>
426          </listitem>
427        </varlistentry>
428      </variablelist>
429
430      <variablelist>
431        <varlistentry>
432          <term><computeroutput>registry::installed {{name ""} {version
433          ""}}</computeroutput></term>
434
435          <listitem>
436            <para>Get all installed ports, optionally all installed ports
437            matching the given name, or the given name and version. Returns a
438            list of the installed ports.</para>
439          </listitem>
440        </varlistentry>
441      </variablelist>
442
443      <variablelist>
444        <varlistentry>
445          <term><computeroutput>registry::location {portname
446          portversion}</computeroutput></term>
447
448          <listitem>
449            <para>Returns the physical location the port is installed in on
450            the disk. This is primarily useful for finding out where a port
451            image is installed.</para>
452          </listitem>
453        </varlistentry>
454      </variablelist>
455
456      <variablelist>
457        <varlistentry>
458          <term><computeroutput>registry::open_file_map
459          {args}</computeroutput></term>
460
461          <listitem>
462            <para>Opens the file map that contains file-port
463            relationships.</para>
464          </listitem>
465        </varlistentry>
466      </variablelist>
467
468      <variablelist>
469        <varlistentry>
470          <term><computeroutput>registry::file_registered
471          {file}</computeroutput></term>
472
473          <listitem>
474            <para>Returns the name of the port that owns the given file, if
475            the file is registered as installed, and 0 otherwise.</para>
476          </listitem>
477        </varlistentry>
478      </variablelist>
479
480      <variablelist>
481        <varlistentry>
482          <term><computeroutput>registry::port_registered
483          {name}</computeroutput></term>
484
485          <listitem>
486            <para>Returns a list of all files associated with the given port
487            if that port is installed, and 0 otherwise.</para>
488          </listitem>
489        </varlistentry>
490      </variablelist>
491
492      <variablelist>
493        <varlistentry>
494          <term><computeroutput>registry::register_file {file
495          port}</computeroutput></term>
496
497          <listitem>
498            <para>Registers the given file in the file map as belonging to the
499            given port.</para>
500          </listitem>
501        </varlistentry>
502      </variablelist>
503
504      <variablelist>
505        <varlistentry>
506          <term><computeroutput>registry::unregister_file
507          {file}</computeroutput></term>
508
509          <listitem>
510            <para>Removes the file from the file map.</para>
511          </listitem>
512        </varlistentry>
513      </variablelist>
514
515      <variablelist>
516        <varlistentry>
517          <term><computeroutput>registry::write_file_map
518          {args}</computeroutput></term>
519
520          <listitem>
521            <para>Write the changes to the file map.</para>
522          </listitem>
523        </varlistentry>
524      </variablelist>
525
526      <variablelist>
527        <varlistentry>
528          <term><computeroutput>registry::open_dep_map
529          {args}</computeroutput></term>
530
531          <listitem>
532            <para>Opens the dependency map that contains port dependency
533            relationships.</para>
534          </listitem>
535        </varlistentry>
536      </variablelist>
537
538      <variablelist>
539        <varlistentry>
540          <term><computeroutput>registry::fileinfo_for_file
541          {fname}</computeroutput></term>
542
543          <listitem>
544            <para>Returns a list for the given file name representing all data
545            currently known about the file. This is a 6-tuple in the form
546            of:</para>
547
548            <orderedlist>
549              <listitem>
550                <para>file path</para>
551              </listitem>
552
553              <listitem>
554                <para>uid</para>
555              </listitem>
556
557              <listitem>
558                <para>gid</para>
559              </listitem>
560
561              <listitem>
562                <para>mode</para>
563              </listitem>
564
565              <listitem>
566                <para>size</para>
567              </listitem>
568
569              <listitem>
570                <para>md5 checksum</para>
571              </listitem>
572            </orderedlist>
573          </listitem>
574        </varlistentry>
575      </variablelist>
576
577      <variablelist>
578        <varlistentry>
579          <term><computeroutput>registry::fileinfo_for_index
580          {flist}</computeroutput></term>
581
582          <listitem>
583            <para>Returns a list of information concerning each file in the
584            given file list, if that file exists in the registry. The
585            information if obtained through registry::fileinfo_for_file</para>
586          </listitem>
587        </varlistentry>
588      </variablelist>
589
590      <variablelist>
591        <varlistentry>
592          <term><computeroutput>registry::list_depends
593          {name}</computeroutput></term>
594
595          <listitem>
596            <para>Returns a list of all the ports that given port name depends
597            on.</para>
598          </listitem>
599        </varlistentry>
600      </variablelist>
601
602      <variablelist>
603        <varlistentry>
604          <term><computeroutput>registry::list_dependents
605          {name}</computeroutput></term>
606
607          <listitem>
608            <para>Returns a list of all the ports that depend on the given
609            port name.</para>
610          </listitem>
611        </varlistentry>
612      </variablelist>
613
614      <variablelist>
615        <varlistentry>
616          <term><computeroutput>registry::register_dep {dep type
617          port}</computeroutput></term>
618
619          <listitem>
620            <para>Registers the given dependency as the given type of
621            dependency with the given port.</para>
622          </listitem>
623        </varlistentry>
624      </variablelist>
625
626      <variablelist>
627        <varlistentry>
628          <term><computeroutput>registry::unregister_dep {dep type
629          port}</computeroutput></term>
630
631          <listitem>
632            <para>Unregister the given dependency of the given type as a
633            dependency of the given port.</para>
634          </listitem>
635        </varlistentry>
636      </variablelist>
637
638      <variablelist>
639        <varlistentry>
640          <term><computeroutput>registry::write_dep_map
641          {args}</computeroutput></term>
642
643          <listitem>
644            <para>Write changes to the dependency map.</para>
645          </listitem>
646        </varlistentry>
647      </variablelist>
648    </section>
649  </section>
650 
651</chapter>
Note: See TracBrowser for help on using the repository browser.