source: trunk/base/doc/INTERNALS @ 18777

Last change on this file since 18777 was 757, checked in by landonf (Landon Fuller), 18 years ago

Update to reflect package require -> PortSystem abstraction

  • Property svn:eol-style set to native
File size: 2.8 KB
Line 
1DARWIN PORTS INTERNALS
2
3The darwin ports system is composed of a three TCL libraries:
4        darwinports - public API
5        port - portfile parsing and execution
6        pextlib - neccesary C extensions to TCL
7
8    These three TCL libraries are grouped as a TCL "package". TCL packages
9allow for complex versioning and have a provide/require model of use, making
10them well suited for maintaining a backwards compatable ports system.
11
12    The "darwinports" TCL Library provides a public API into the darwin
13ports system. Any external application wishing to manipulate a port can
14load the "darwinports" TCL library. 'port', the included command line port
15utility, uses only the exported "darwinports" API.
16
17    The "darwinports" API provides very simple primitives for dealing with
18ports (ie, dportexec/dportopen/dportget). Also, the API has very little
19knowledge of the contents of a portfile; instead, it relies entirely upon
20the "port" TCL library. By keeping the high level API simple and generic,
21a revision of the underlying ports system will not neccesarily require
22a revision of the high level "darwinports" API.
23
24    TCL packages allow for complex versioning with a strong requires/provides
25model; this means that a revision of the API at any level will not break
26backwards compatibility.
27
28    When parsing a port, the "darwinports" library loads the Portfile into a
29sub-interpreter. The "port" library and all port-specific code is run
30entirely within this sub-interpreter, and thus can never pollute the TCL
31space of other ports, the "darwinports" library, or the calling application.
32
33    The "darwinports" library is also responsible for loading user specified
34options into the sub-interpreter to be evaluated by the "ports" library. In
35that case it sets the variable name in the sub-interpreter and adds the
36option to the sub-interpreter's global array user_options(). User options
37are passed as part of the call to dportopen.
38
39    The "port" TCL package provides all the primitives required for a darwin
40portfile to be parsed, queried, and its actions executed. It also provides
41a single procedure call that the "darwinports" TCL package uses to kick off
42execution: "eval_targets".
43
44    The port TCL package is loaded by every Portfile with the following line
45at the start of the Portfile:
46        PortSystem <version required>
47    The version should be set to the version of the port API required to build
48your port. Currently the only version supplied is 1.0.
49
50    Because a port is not actually parsed, but in fact executed in the TCL
51interpreter, every port option must be a TCL procedure. The ports library
52supplies all these procedures, all of which are generated at run-time using
53the "options" procedure in portutil.tcl.
54
55    The "pextlib" TCL library provides a variety of otherwise unavailable TCL
56procedures, such as an interface to flock(2) and mkstemp(3).
Note: See TracBrowser for help on using the repository browser.