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

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

guide:
Fix compilation by removing stray closing tag

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