Changeset 28577 for trunk/doc


Ignore:
Timestamp:
Sep 3, 2007, 11:51:48 PM (12 years ago)
Author:
markd@…
Message:

Refinements and inclusions from base/doc/INTERNALS.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/guide/new/xml/internals.xml

    r28261 r28577  
    299299
    300300  <section id="internals.apis">
    301     <title>MacPorts APIs</title>
    302 
    303     <para>MacPorts contains two application programming interfaces (APIs),
    304     written in Tcl: The Ports API and the MacPorts (mport*) API. The former is
    305     an internal API used for individual Portfiles. The latter is a high-level
    306     API used by client applications such as the MacPorts port utility.</para>
     301    <title>MacPorts APIs and Libraries</title>
     302
     303    <para>The MacPorts system is composed of three Tcl libraries:</para>
     304
     305    <itemizedlist>
     306      <listitem>
     307        <para>MacPorts API - MacPorts public API for handling Portfiles,
     308        dependencies, and registry</para>
     309      </listitem>
     310
     311      <listitem>
     312        <para>Ports API - API for Portfile parsing and execution</para>
     313      </listitem>
     314
     315      <listitem>
     316        <para>pextlib - C extensions to Tcl</para>
     317      </listitem>
     318    </itemizedlist>
    307319
    308320    <section id="internals.apis.ports">
     
    310322
    311323      <para>The code for the Port API is located in
    312       <filename>base/src/port1.0</filename> and performs the following
    313       functions:</para>
     324      <filename>base/src/port1.0</filename>. The Port API provides all the
     325      primitives required for a Portfile to be parsed, queried, and executed.
     326      It also provides a single procedure call that the MacPorts API uses to
     327      kick off execution: "eval_targets". The port Tcl library supplies these
     328      procedures, all of which are generated at run-time using the
     329      <code>options</code> procedure in portutil.tcl.</para>
     330
     331      <para>The macports Tcl library loads the Portfile into a
     332      sub-interpreter, within which all port-specific code is run. This
     333      process ensures that there will never be pollution of the Tcl space of
     334      other ports, nor the MacPorts libraries, nor the calling
     335      application.</para>
     336
     337      <note>
     338        <para>Portfiles are executed in a Tcl interpreter as Tcl code (and not
     339        truly parsed strictly speaking), so every Portfile option must be a
     340        TCL procedure.</para>
     341      </note>
     342
     343      <para>The Ports API performs the following functions:</para>
    314344
    315345      <itemizedlist>
     
    321351
    322352        <listitem>
    323           <para>Option/Default handling. All <filename>Portfile</filename>
    324           options (name, version, revision ...) are registered by targets. The
    325           Port API creates procedures for these options, and sets up the
    326           complex variable traces necessary to support option defaults.</para>
     353          <para>Option/Default handling. All Portfile options (name, version,
     354          revision ...) are registered by targets. The Port API creates
     355          procedures for these options, and sets up the complex variable
     356          traces necessary to support option defaults.</para>
    327357        </listitem>
    328358
     
    354384
    355385      <para>The code for the MacPorts API is located in
    356       <filename>base/src/macports1.0</filename>. The MacPorts API performs the
    357       following functions:</para>
     386      <filename>base/src/macports1.0</filename>. The MacPorts API provides a
     387      public API into the MacPorts system by providing simple primitives for
     388      handling Portfiles, dependencies, and registry operations, and exports
     389      the MacPorts API for the <command>port</command> command line utility,
     390      or any other. The API has very little information about the contents
     391      Portfiles; instead, it relies entirely upon the <command>port</command>
     392      Tcl library. By keeping the high level API simple and generic, revisions
     393      to the underlying ports system will not necessarily require a revision
     394      of the high level MacPorts API.</para>
     395
     396      <para>The MacPorts API is also responsible for loading user specified
     397      options into a sub-interpreter to be evaluated by the ports API. In that
     398      case it sets the variable name in the sub-interpreter and adds the
     399      option to the sub-interpreter's global array user_options(). User
     400      options are passed as part of the call to mportopen. </para>
     401
     402      <para>The MacPorts API performs the following functions:</para>
    358403
    359404      <itemizedlist>
     
    490535        </listitem>
    491536      </itemizedlist>
     537    </section>
     538
     539    <section>
     540      <title>pextlib</title>
     541
     542      <para>The pextlib TCL library provides a variety of C extensions to add
     543      capabilities to TCL procedures; for example, an interface to flock(2)
     544      and mkstemp(3).</para>
    492545    </section>
    493546  </section>
     
    546599      <title>The Registry API</title>
    547600
    548       <para>The MacPorts Registry provides a public API in the registry1.0 Tcl
     601      <para>The MacPorts registry provides a public API in the registry1.0 Tcl
    549602      package. Using this API listed below you can access the MacPorts
    550603      Registry using the default receipt storage mechanism chosen in
Note: See TracChangeset for help on using the changeset viewer.