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

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

Guide: revert inadvertedly introduced change to Makefile

File size: 21.9 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 rudimentary port registry in
177          <filename>${prefix}/var/macports/receipts/</filename>.</para>
178
179          <itemizedlist>
180            <listitem>
181              <para><code>mportregistry::new:</code> create a new port
182              registry entry.</para>
183            </listitem>
184
185            <listitem>
186              <para><code>mportregistry::exists:</code> check if a port
187              registry entry exists (either versioned or not).</para>
188            </listitem>
189
190            <listitem>
191              <para><code>mportregistry::delete:</code> delete an existing
192              registry entry.</para>
193            </listitem>
194
195            <listitem>
196              <para><code>mportregistry::close:</code> closes a new registry
197              entry.</para>
198            </listitem>
199          </itemizedlist>
200        </listitem>
201
202        <listitem>
203          <para>Exports the MacPorts API for use by client
204          applications.</para>
205
206          <para>The following routines are defined.</para>
207
208          <itemizedlist>
209            <listitem>
210              <para><code>mportinit:</code> Initializes the MacPorts system.
211              Should be called before trying to use any other
212              procedure.</para>
213            </listitem>
214
215            <listitem>
216              <para><code>mportsearch:</code> Given a regexp, searches the
217              <filename>PortIndex</filename> for ports with matching
218              names.</para>
219            </listitem>
220
221            <listitem>
222              <para><code>mportopen:</code> Given a URI to a port, opens a
223              Portfile and returns an opaque handle to it.</para>
224            </listitem>
225
226            <listitem>
227              <para><code>portclose:</code> Given a port handle, closes a
228              Portfile.</para>
229            </listitem>
230
231            <listitem>
232              <para><code>mportexec:</code> Given a port handle, executes a
233              target (i.e. install).</para>
234            </listitem>
235
236            <listitem>
237              <para><code>mportinfo:</code> Given a port handle, this returns
238              the PortInfo array (as a flat list of array elements). This is a
239              little tricky and unstable and only used by the
240              <command>portindex</command> command.</para>
241            </listitem>
242
243            <listitem>
244              <para><code>mportdepends:</code> Given a port handle, returns a
245              list of ports upon which the specified port depends.</para>
246            </listitem>
247          </itemizedlist>
248        </listitem>
249      </itemizedlist>
250
251      <para>For an example of the MacPorts API, when one executes
252      <command>port search cm3</command>, the port utility:</para>
253
254      <itemizedlist>
255        <listitem>
256          <para>Calls the <code>mportsearch</code> function to find all ports
257          containing <quote>cm3</quote>.</para>
258        </listitem>
259
260        <listitem>
261          <para>Returns Tcl array(s) containing data from the
262          <filename>PortIndex</filename>: port name, version, revision,
263          variants, etc.</para>
264        </listitem>
265
266        <listitem>
267          <para>Formats the list of arrays in the standard viewing
268          format.</para>
269        </listitem>
270      </itemizedlist>
271
272      <para>For another MacPorts API example, when one executes <command>port
273      install cm3</command>, the port utility:</para>
274
275      <itemizedlist>
276        <listitem>
277          <para>Calls the <code>mportsearch</code> function to find the first
278          port that matches the name <quote>cm3</quote>.</para>
279        </listitem>
280
281        <listitem>
282          <para>Calls the <code>mportopen</code> function to open the
283          port.</para>
284        </listitem>
285
286        <listitem>
287          <para>Calls the <code>mportexec</code> function to execute the
288          install target in the port.</para>
289        </listitem>
290
291        <listitem>
292          <para>Calls the <code>mportclose</code> function to close the
293          port.</para>
294        </listitem>
295      </itemizedlist>
296    </section>
297
298    <section id="internals.apis.pextlib">
299      <title>pextlib</title>
300
301      <para>The pextlib TCL library provides a variety of C extensions to add
302      capabilities to TCL procedures; for example, an interface to flock(2)
303      and mkstemp(3).</para>
304    </section>
305  </section>
306
307  <section id="internals.registry">
308    <title>The MacPorts Registry</title>
309
310    <para>This chapter provides an overview of the MacPorts registry and its
311    API. The registry is queried by MacPorts utilities for information about
312    installed ports related to dependencies, port images, and simple user
313    information about what is installed. It provides abstraction over a
314    modular receipt storage layer; this allows for flat file receipts as well
315    as receipts stored in a SQLite database.</para>
316
317    <para>The registry allows MacPorts utilities to:</para>
318
319    <itemizedlist>
320      <listitem>
321        <para>Modify receipts to reflect changes made to installed ports being
322        maintained by MacPorts.</para>
323      </listitem>
324
325      <listitem>
326        <para>Query the global file and dependency databases for file
327        conflicts between a port being installed and a port already
328        installed.</para>
329      </listitem>
330
331      <listitem>
332        <para>Maintain dependency trees of installed ports.</para>
333      </listitem>
334    </itemizedlist>
335
336    <section id="internals.registry.files">
337      <title>Registry Files</title>
338
339      <para>The flat file registry (MacPorts default registry) files are
340      contained in <filename>${portdbpath}/receipts</filename>, which by
341      default is location
342      <filename>${prefix}/var/macports/receipts</filename>. File mappings and
343      dependency mappings are tracked in the flat file registry by two
344      files:</para>
345
346      <itemizedlist>
347        <listitem>
348          <para>file_map.db</para>
349        </listitem>
350
351        <listitem>
352          <para>dep_map.bz2</para>
353        </listitem>
354      </itemizedlist>
355    </section>
356
357    <section id="internals.registry.api">
358      <title>The Registry API</title>
359
360      <para>The MacPorts registry provides a public API in the registry1.0 Tcl
361      package. Using this API listed below you can access the MacPorts
362      Registry using the default receipt storage mechanism chosen in
363      <filename>macports.conf</filename>.</para>
364
365      <variablelist>
366        <varlistentry>
367          <term><computeroutput>registry::new_entry {name version {revision 0}
368          {variants ""}}</computeroutput></term>
369
370          <listitem>
371            <para>Begin the creation of a new registry entry for the given
372            port. Returns a reference ID to the registry entry created.</para>
373          </listitem>
374        </varlistentry>
375      </variablelist>
376
377      <variablelist>
378        <varlistentry>
379          <term><computeroutput>registry::open_entry {name {version 0}
380          {revision 0} {variants ""}}</computeroutput></term>
381
382          <listitem>
383            <para>Opens an existing registry entry. Returns a reference ID to
384            the registry entry that was opened.</para>
385          </listitem>
386        </varlistentry>
387      </variablelist>
388
389      <variablelist>
390        <varlistentry>
391          <term><computeroutput>registry::entry_exists {name version {revision
392          0} {variants ""}}</computeroutput></term>
393
394          <listitem>
395            <para>Checks to see if a port exists in the registry. Returns 1 if
396            the entry exists, 0 if not.</para>
397          </listitem>
398        </varlistentry>
399      </variablelist>
400
401      <variablelist>
402        <varlistentry>
403          <term><computeroutput>registry::write_entry
404          {ref}</computeroutput></term>
405
406          <listitem>
407            <para>Writes the receipt associated with the given
408            reference.</para>
409          </listitem>
410        </varlistentry>
411      </variablelist>
412
413      <variablelist>
414        <varlistentry>
415          <term><computeroutput>registry::delete_entry
416          {ref}</computeroutput></term>
417
418          <listitem>
419            <para>Deletes the receipt associated with the given
420            reference.</para>
421          </listitem>
422        </varlistentry>
423      </variablelist>
424
425      <variablelist>
426        <varlistentry>
427          <term><computeroutput>registry::property_store {ref property
428          value}</computeroutput></term>
429
430          <listitem>
431            <para>Store the given value with the property name in the receipt
432            associated with the given reference.</para>
433          </listitem>
434        </varlistentry>
435      </variablelist>
436
437      <variablelist>
438        <varlistentry>
439          <term><computeroutput>registry::property_retrieve {ref
440          property}</computeroutput></term>
441
442          <listitem>
443            <para>Retrieve the property name from the receipt associated with
444            the given reference. Returns the value of the property, if the
445            property exists.</para>
446          </listitem>
447        </varlistentry>
448      </variablelist>
449
450      <variablelist>
451        <varlistentry>
452          <term><computeroutput>registry::installed {{name ""} {version
453          ""}}</computeroutput></term>
454
455          <listitem>
456            <para>Get all installed ports, optionally all installed ports
457            matching the given name, or the given name and version. Returns a
458            list of the installed ports.</para>
459          </listitem>
460        </varlistentry>
461      </variablelist>
462
463      <variablelist>
464        <varlistentry>
465          <term><computeroutput>registry::location {portname
466          portversion}</computeroutput></term>
467
468          <listitem>
469            <para>Returns the physical location the port is installed in on
470            the disk. This is primarily useful for finding out where a port
471            image is installed.</para>
472          </listitem>
473        </varlistentry>
474      </variablelist>
475
476      <variablelist>
477        <varlistentry>
478          <term><computeroutput>registry::open_file_map
479          {args}</computeroutput></term>
480
481          <listitem>
482            <para>Opens the file map that contains file-port
483            relationships.</para>
484          </listitem>
485        </varlistentry>
486      </variablelist>
487
488      <variablelist>
489        <varlistentry>
490          <term><computeroutput>registry::file_registered
491          {file}</computeroutput></term>
492
493          <listitem>
494            <para>Returns the name of the port that owns the given file, if
495            the file is registered as installed, and 0 otherwise.</para>
496          </listitem>
497        </varlistentry>
498      </variablelist>
499
500      <variablelist>
501        <varlistentry>
502          <term><computeroutput>registry::port_registered
503          {name}</computeroutput></term>
504
505          <listitem>
506            <para>Returns a list of all files associated with the given port
507            if that port is installed, and 0 otherwise.</para>
508          </listitem>
509        </varlistentry>
510      </variablelist>
511
512      <variablelist>
513        <varlistentry>
514          <term><computeroutput>registry::register_file {file
515          port}</computeroutput></term>
516
517          <listitem>
518            <para>Registers the given file in the file map as belonging to the
519            given port.</para>
520          </listitem>
521        </varlistentry>
522      </variablelist>
523
524      <variablelist>
525        <varlistentry>
526          <term><computeroutput>registry::unregister_file
527          {file}</computeroutput></term>
528
529          <listitem>
530            <para>Removes the file from the file map.</para>
531          </listitem>
532        </varlistentry>
533      </variablelist>
534
535      <variablelist>
536        <varlistentry>
537          <term><computeroutput>registry::write_file_map
538          {args}</computeroutput></term>
539
540          <listitem>
541            <para>Write the changes to the file map.</para>
542          </listitem>
543        </varlistentry>
544      </variablelist>
545
546      <variablelist>
547        <varlistentry>
548          <term><computeroutput>registry::open_dep_map
549          {args}</computeroutput></term>
550
551          <listitem>
552            <para>Opens the dependency map that contains port dependency
553            relationships.</para>
554          </listitem>
555        </varlistentry>
556      </variablelist>
557
558      <variablelist>
559        <varlistentry>
560          <term><computeroutput>registry::fileinfo_for_file
561          {fname}</computeroutput></term>
562
563          <listitem>
564            <para>Returns a list for the given file name representing all data
565            currently known about the file. This is a 6-tuple in the form
566            of:</para>
567
568            <orderedlist>
569              <listitem>
570                <para>file path</para>
571              </listitem>
572
573              <listitem>
574                <para>uid</para>
575              </listitem>
576
577              <listitem>
578                <para>gid</para>
579              </listitem>
580
581              <listitem>
582                <para>mode</para>
583              </listitem>
584
585              <listitem>
586                <para>size</para>
587              </listitem>
588
589              <listitem>
590                <para>md5 checksum</para>
591              </listitem>
592            </orderedlist>
593          </listitem>
594        </varlistentry>
595      </variablelist>
596
597      <variablelist>
598        <varlistentry>
599          <term><computeroutput>registry::fileinfo_for_index
600          {flist}</computeroutput></term>
601
602          <listitem>
603            <para>Returns a list of information concerning each file in the
604            given file list, if that file exists in the registry. The
605            information if obtained through registry::fileinfo_for_file</para>
606          </listitem>
607        </varlistentry>
608      </variablelist>
609
610      <variablelist>
611        <varlistentry>
612          <term><computeroutput>registry::list_depends
613          {name}</computeroutput></term>
614
615          <listitem>
616            <para>Returns a list of all the ports that given port name depends
617            on.</para>
618          </listitem>
619        </varlistentry>
620      </variablelist>
621
622      <variablelist>
623        <varlistentry>
624          <term><computeroutput>registry::list_dependents
625          {name}</computeroutput></term>
626
627          <listitem>
628            <para>Returns a list of all the ports that depend on the given
629            port name.</para>
630          </listitem>
631        </varlistentry>
632      </variablelist>
633
634      <variablelist>
635        <varlistentry>
636          <term><computeroutput>registry::register_dep {dep type
637          port}</computeroutput></term>
638
639          <listitem>
640            <para>Registers the given dependency as the given type of
641            dependency with the given port.</para>
642          </listitem>
643        </varlistentry>
644      </variablelist>
645
646      <variablelist>
647        <varlistentry>
648          <term><computeroutput>registry::unregister_dep {dep type
649          port}</computeroutput></term>
650
651          <listitem>
652            <para>Unregister the given dependency of the given type as a
653            dependency of the given port.</para>
654          </listitem>
655        </varlistentry>
656      </variablelist>
657
658      <variablelist>
659        <varlistentry>
660          <term><computeroutput>registry::write_dep_map
661          {args}</computeroutput></term>
662
663          <listitem>
664            <para>Write changes to the dependency map.</para>
665          </listitem>
666        </varlistentry>
667      </variablelist>
668    </section>
669  </section>
670 
671</chapter>
Note: See TracBrowser for help on using the repository browser.