[28616] trunk/doc/guide/new/xml/portfileref.xml
source_changes at macosforge.org
source_changes at macosforge.org
Tue Sep 4 22:40:49 PDT 2007
Revision: 28616
http://trac.macosforge.org/projects/macports/changeset/28616
Author: markd at macports.org
Date: 2007-09-04 22:40:49 -0700 (Tue, 04 Sep 2007)
Log Message:
-----------
Refine the terms and language in the StartupItems section.
Modified Paths:
--------------
trunk/doc/guide/new/xml/portfileref.xml
Modified: trunk/doc/guide/new/xml/portfileref.xml
===================================================================
--- trunk/doc/guide/new/xml/portfileref.xml 2007-09-05 03:45:05 UTC (rev 28615)
+++ trunk/doc/guide/new/xml/portfileref.xml 2007-09-05 05:40:49 UTC (rev 28616)
@@ -5,8 +5,8 @@
<title>Portfile Reference</title>
<para>This chapter serves as a reference for the major elements of a
- <filename>Portfile</filename>: port phases, variants, StartupItems,
- variables, keywords, and Tcl extensions.</para>
+ Portfile: port phases, dependencies, StartupItems, variables, keywords, and
+ Tcl extensions.</para>
<section id="reference.phases">
<title>Port Phases</title>
@@ -232,17 +232,19 @@
facility intoduced by Apple beginning with OS X 10.4, that starts, stops,
and manages daemons, programs and scripts. Port authors use StartupItem
keywords within Portfiles to instruct MacPorts to generate and install
- <command>launchd</command> scripts for ports when they are
- installed.</para>
+ <command>launchd</command> scripts for daemons during port
+ installation.</para>
- <para>There are two types of StartupItems, executable and wrapper, but
- first we'll list the StartupItem keywords common to both types.</para>
+ <para>There are three categories of StartupItem keywords. Those that
+ trigger StartupItem creation and logging, those that specify attributes of
+ <quote>executable</quote> StartupItems, and those that specify attributes
+ of <quote>wrapper</quote> StartupItems.</para>
- <section id="reference.startupitems.common">
- <title>Common StartupItem Keywords</title>
+ <section id="reference.startupitems.creation">
+ <title>StartupItem Creation & Logging</title>
- <para>The keywords in this section may be used with executable or
- wrapper StartupItems.</para>
+ <para>The keywords in this section may be used with either
+ <quote>executable</quote> or <quote>wrapper</quote> StartupItems.</para>
<variablelist>
<varlistentry>
@@ -286,7 +288,7 @@
<listitem>
<para>Path to a logfile for logging events about the lifetime of
- the startupitem. Depending on the type of startupitem, and the
+ the StartupItem. Depending on the type of StartupItem, and the
manner in which it is started, standard output from the daemon may
also be directed to the logfile.</para>
@@ -324,102 +326,88 @@
</variablelist>
</section>
- <section id="reference.startupitems.executable">
- <title>Executable StartupItems</title>
+ <section id="reference.startupitems.wrapper">
+ <title>Wrapper StartupItems</title>
- <para>The executable StartupItem is the preferred type —it merely
- specify the name of the daemon to be run in the background.
- <command>launchd</command> monitors the daemon to make sure it stays
- running. Executable StartupItem keywords may not be used together with
- any of the wrapper StartupItem keywords.</para>
+ <para>StartupItems of type <quote>wrapper</quote> use
+ <command>daemondo</command>, a wrapper program provided by MacPorts base
+ made to execute startup scripts for daemons. <command>daemondo</command>
+ works as an adapter between OS X's <command>launchd</command> and
+ daemons that are normally started via traditional rc.d style scripts.
+ Therefore a port author may use these StartupItems when startup scripts
+ are provided in the source distribution of ported software, or when a
+ port author chooses to write his or her own.</para>
+ <note>
+ <para>For a given port, StartupItem keywords in category
+ <quote>wrapper</quote> may not be mixed with any keywords in the
+ <quote>executable</quote> StartupItem category.</para>
+ </note>
+
<variablelist>
<varlistentry>
- <term>startupitem.executable</term>
+ <term>startupitem.init</term>
<listitem>
- <para>Specifies the name of the daemon to be run in the
- background. It may have multiple arguments, but they must be
- appropriate for a call to exec; arbitrary shell code may not be
- used.</para>
+ <para>Shell code that will be executed prior to any of the options
+ <code>startupitem.start</code>, <code>startupitem.stop</code> and
+ <code>startupitem.restart</code>.</para>
<simplelist>
<member>Type: optional</member>
<member>Default: <option>no</option></member>
- <member>Values: <option>yes no</option></member>
+ <member>Values: <literal>shell script</literal></member>
</simplelist>
- <programlisting>startupitem.executable "${prefix}/bin/nmicmpd"</programlisting>
+ <programlisting>startupitem.init "PID=/var/run/dhcpd.pid"</programlisting>
</listitem>
</varlistentry>
<varlistentry>
- <term>startupitem.pidfile</term>
+ <term>startupitem.start</term>
<listitem>
- <para>A specification for process id (PID) file handling that may
- be used in conjunction with the startupitem.executable key to
- inform the startupitem how to track the executable. This keyword
- specifies whether the daemon is not to use a pidfile
- (<option>none</option>), generates its own pidfile
- (<option>auto</option>), never generates one (so the startupitem
- should manage the pidfile on its own (<option>manual</option>), or
- generates its own but will not delete it (so the startupitem
- should delete it using <option>clean</option>).</para>
+ <para>Specify a shell script to start the daemon.</para>
<simplelist>
<member>Type: optional</member>
- <member>Default: <option>none</option> |
- <filename>${prefix}/var/run/${name}.pid</filename></member>
+ <member>Default: none</member>
- <member>Values: <option>none auto manual clean</option>
- [<replaceable>/path/to/pidfile</replaceable>]</member>
+ <member>Values: <literal>shell script</literal></member>
</simplelist>
- <programlisting>startupitem.pidfile auto ${prefix}/var/run/${name}.pidfile</programlisting>
+ <programlisting>startupitem.start ${prefix}/share/mysql/mysql.server start</programlisting>
</listitem>
</varlistentry>
- </variablelist>
- </section>
- <section id="reference.startupitems.wrapper">
- <title>Wrapper StartupItems</title>
-
- <para>Wrapper StartupItems use <command>daemondo</command>, a wrapper
- program provided by MacPorts base made to execute startup scripts for
- daemons. <command>daemondo</command> works as an adapter between OS X's
- launchd and daemons that are normally started via traditional rc.d style
- scripts.</para>
-
- <variablelist>
<varlistentry>
- <term>startupitem.init</term>
+ <term>startupitem.stop</term>
<listitem>
- <para>Shell code that will be executed prior to any of the options
- startupitem.start, startupitem.stop and
- startupitem.restart.</para>
+ <para>Specify a shell script to stop the daemon.</para>
<simplelist>
<member>Type: optional</member>
- <member>Default: <option>no</option></member>
+ <member>Default: none</member>
<member>Values: <literal>shell script</literal></member>
</simplelist>
- <programlisting>startupitem.init "PID=/var/run/dhcpd.pid"</programlisting>
+ <programlisting>startupitem.start ${prefix}/share/mysql/mysql.server stop</programlisting>
</listitem>
</varlistentry>
<varlistentry>
- <term>startupitem.start</term>
+ <term>startupitem.restart</term>
<listitem>
- <para>Specify a shell script to start the daemon.</para>
+ <para>Specify a shell script to restart the daemon. In the absence
+ of this key, the daemon will be restarted by taking the stop
+ action, followed by taking the start action.</para>
<simplelist>
<member>Type: optional</member>
@@ -429,45 +417,75 @@
<member>Values: <literal>shell script</literal></member>
</simplelist>
- <programlisting>startupitem.start ${prefix}/share/mysql/mysql.server start</programlisting>
+ <programlisting>startupitem.start ${prefix}/share/mysql/mysql.server restart</programlisting>
</listitem>
</varlistentry>
+ </variablelist>
+ </section>
+ <section id="reference.startupitems.executable">
+ <title>Executable StartupItems</title>
+
+ <para>StartupItems of type <quote>executable</quote> specify the name of
+ the daemon to be run in the background, and optionally a pidfile to
+ track the process ID. Use this StartupItem type when you want
+ <command>launchd</command> to monitor a daemon to make sure it stays
+ running, and restart it if necessary.</para>
+
+ <note>
+ <para>For a given port, StartupItem keywords in category
+ <quote>executable</quote> may not be mixed with any keywords in the
+ <quote>wrapper</quote> StartupItem category.</para>
+ </note>
+
+ <variablelist>
<varlistentry>
- <term>startupitem.stop</term>
+ <term>startupitem.executable</term>
<listitem>
- <para>Specify a shell script to stop the daemon.</para>
+ <para>Specifies the name of the daemon to be run in the
+ background. It may have multiple arguments, but they must be
+ appropriate for a call to exec; arbitrary shell code may not be
+ used.</para>
<simplelist>
<member>Type: optional</member>
- <member>Default: none</member>
+ <member>Default: <option>no</option></member>
- <member>Values: <literal>shell script</literal></member>
+ <member>Values: <option>yes no</option></member>
</simplelist>
- <programlisting>startupitem.start ${prefix}/share/mysql/mysql.server stop</programlisting>
+ <programlisting>startupitem.executable "${prefix}/bin/nmicmpd"</programlisting>
</listitem>
</varlistentry>
<varlistentry>
- <term>startupitem.restart</term>
+ <term>startupitem.pidfile</term>
<listitem>
- <para>Specify a shell script to restart the daemon. In the absence
- of this key, the daemon will be restarted by taking the stop
- action, followed by taking the start action.</para>
+ <para>A specification for process id (PID) file handling that may
+ be used in conjunction with the
+ <code>startupitem.executable</code> key to inform the startupitem
+ how to track the executable. This keyword specifies whether the
+ daemon is not to use a pidfile (<option>none</option>), generates
+ its own pidfile (<option>auto</option>), never generates one (so
+ the StartupItem should manage the pidfile on its own
+ (<option>manual</option>), or generates its own but will not
+ delete it (so the StartupItem should delete it using
+ <option>clean</option>).</para>
<simplelist>
<member>Type: optional</member>
- <member>Default: none</member>
+ <member>Default: <option>none</option> |
+ <filename>${prefix}/var/run/${name}.pid</filename></member>
- <member>Values: <literal>shell script</literal></member>
+ <member>Values: <option>none auto manual clean</option>
+ [<replaceable>/path/to/pidfile</replaceable>]</member>
</simplelist>
- <programlisting>startupitem.start ${prefix}/share/mysql/mysql.server restart</programlisting>
+ <programlisting>startupitem.pidfile auto ${prefix}/var/run/${name}.pidfile</programlisting>
</listitem>
</varlistentry>
</variablelist>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.macosforge.org/pipermail/macports-changes/attachments/20070904/940b9654/attachment.html
More information about the macports-changes
mailing list