source: trunk/doc/guide/xml/internals/internals.xml

Last change on this file was 26420, checked in by boeyms@…, 13 years ago

A few extra Darwinports -> MacPorts links, dport -> mport instances and
Bugzilla -> Trac conversions that I missed last time.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 7.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  <chapterinfo>
6    <keywordset>
7      <keyword>
8      </keyword>
9    </keywordset>
10  </chapterinfo>
11 
12  <title>MacPorts APIs</title> 
13
14  <sect1 id="about">
15    <title>About This Chapter</title>
16
17    <para>MacPorts contains two application programming interfaces
18    (APIs), written in Tcl.</para>
19   
20    <para>The Ports API is an internal API used to run individual
21      Portfiles.  The MacPorts (mport*) API is a high-level API used by
22      client applications such as MacPorts Manager.app or
23      <command>port</command>.</para>
24  </sect1>
25
26  <sect1 id="ports-api">
27    <title>Ports API</title>
28
29    <para>The code for the Port API is located in
30      <filename>base/src/port1.0</filename>.  The Port API performs the
31      following functions:</para>
32
33    <para>
34      <itemizedlist>
35        <listitem>
36          <para>Manages target registrations.  All targets register
37            themselves with the Port API.  Accordingly, the Port API
38            creates pre-/post-/main overrides for each of the targets.</para>
39        </listitem>
40
41        <listitem>
42          <para>Option/Default handling.  All
43            <filename>Portfile</filename> options
44            (<function>name</function>, <function>version</function>,
45            <function>revision</function> ...) are registered by targets.
46            The Port API creates procedures for these options, and sets
47            up the complex variable traces necessary to support option
48            defaults.</para>
49        </listitem>
50
51        <listitem>
52          <para>Executes target procedures, including the pre/post/main
53            routines.</para>
54        </listitem>
55
56        <listitem>
57          <para>Manages a state file containing information about what
58            variants were specified and what targets have run
59            successfully.</para>
60        </listitem>
61
62        <listitem>
63          <para>Provides essential portfile primitives (such as
64            <function>reinplace</function>).</para>
65        </listitem>
66
67        <listitem>
68          <para>Provides simple access to the ui_event mechanism by
69            providing the various ui_ procedures (i.e.,
70            <function>ui_msg</function>,
71            <function>ui_error</function>).</para>
72        </listitem>
73
74      </itemizedlist>
75    </para>
76
77  </sect1>
78
79  <sect1 id="dp_api">
80    <title>MacPorts API</title>
81
82    <para>The code for the MacPorts API is located in
83      base/src/macports1.0. The MacPorts API performs the
84      following functions:</para>
85
86    <para>
87      <itemizedlist>
88        <listitem>
89          <para>Dependency implementation. This portion is implemented
90            in a highly generic fashion, and is used throughout the
91            system. The dependency functions are exported to the Port
92            API, and the Port API uses them execute targets in the
93            correct order.</para>
94        </listitem>
95
96        <listitem>
97          <para>Software dependencies. Software dependencies are handled
98            at this layer using the dependency implementation.</para>
99        </listitem>
100
101        <listitem>
102          <para>UI abstractions. UI Abstractions are handled at this
103            layer. Each port action is provided a context, and a
104            mechanism for posting user interface events is exported to
105            the Port API (<function>ui_event</function>).</para>
106        </listitem>
107
108        <listitem>
109          <para>Registry management routines. Manages the rudimentary
110            port registry in
111            <filename>${prefix}/var/db/mports/receipts/</filename>.</para>
112
113          <para>
114            <itemizedlist>
115              <listitem>
116                <para><function>mportregistry::new</function>: create a
117                  new port registry entry</para>
118              </listitem>
119
120              <listitem>
121                <para><function>mportregistry::exists</function>: check
122                  if a port registry entry exists (either versioned or
123                  not)</para>
124              </listitem>
125
126              <listitem>
127                <para><function>mportregistry::delete</function>: delete
128                  an existing registry entry</para>
129              </listitem>
130
131              <listitem>
132                <para><function>mportregistry::close</function>: closes
133                  a new registry entry</para>
134              </listitem>
135            </itemizedlist>
136          </para>
137        </listitem>
138
139        <listitem>
140          <para>Exports the "macports" API for use by client
141            applications:</para>
142
143          <para>
144            <itemizedlist>
145              <listitem>
146                <para><function>mportinit</function>: Initializes the
147                  macports system. Should be called before trying to
148                  use any other procedure</para>
149              </listitem>
150
151              <listitem>
152                <para><function>mportsearch</function>: Given a regexp,
153                  searches the PortIndex for ports with matching
154                  names</para>
155              </listitem>
156
157              <listitem>
158                <para><function>mportopen</function>: Given a URI to a
159                  port, opens the port and returns an opaque handle to
160                  it</para>
161              </listitem>
162
163              <listitem>
164                <para><function>mportclose</function>: Given a port
165                  handle, closes the port.</para>
166              </listitem>
167
168              <listitem>
169                <para><function>mportexec</function>: Given a port
170                  handle, executes a target (i.e. install)</para>
171              </listitem>
172
173              <listitem>
174                <para><function>mportinfo</function>: Given a port
175                  handle, this returns the PortInfo array (as a flat
176                  list of array elements). This is a little tricky and
177                  unstable and only used by the 'portindex'
178                  command</para>
179              </listitem>
180
181              <listitem>
182                <para><function>mportdepends</function>: Given a port
183                  handle, returns a list of ports the specified port
184                  depends upon</para>
185              </listitem>
186            </itemizedlist>
187          </para>
188        </listitem>
189      </itemizedlist>
190    </para>
191   
192    <para>An example of how the MacPorts API is used:</para>
193
194    <para><function>mportsearch</function> returns an arbitrary number
195      of Tcl arrays containing data from the
196      <filename>PortIndex</filename>. The returned data includes the
197      port name, version, revision, epoch, variants, depends, etc. When
198      one executes <userinput>port install cm3</userinput>, the
199      <command>port</command> utility uses the
200      <function>mportsearch</function> function to find the first port
201      that matches the name "cm3", uses <function>mportopen</function>
202      to open the port, and then uses <function>mportexec</function> to
203      execute the install target in the port. Then, it uses
204      <function>mportclose</function> to close the port. When one
205      executes <userinput>port search cm3</userinput>, the port utility
206      uses <function>mportsearch</function>, takes the list of arrays,
207      and formats the data for human consumption.</para>
208  </sect1>
209</chapter>
Note: See TracBrowser for help on using the repository browser.