Changeset 30384 for trunk/doc-new/man


Ignore:
Timestamp:
Oct 26, 2007, 6:46:32 AM (12 years ago)
Author:
markd@…
Message:

Clarify distinction between "executable" and "script" StartupItems.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc-new/man/xml/portfile.7.xml

    r29475 r30384  
    356356            <para>Optional keyword (default is 0) that is used if the new port
    357357            version looks older than the previous version (for example 1.10
    358             -> 1.2). Often the epoch is formatted like a date, but it can
     358            -&gt; 1.2). Often the epoch is formatted like a date, but it can
    359359            simple a number like 1.</para>
    360360
    361361            <programlisting>epoch        20070924</programlisting>
     362
    362363            <programlisting>epoch        1</programlisting>
    363364          </listitem>
     
    912913      <title>StartupItems</title>
    913914
    914       <para>StartupItems are keywords that create Mac OS X startup scripts for
    915       <ulink
     915      <para><quote>Daemons</quote> is a Unix term for programs that run
     916      continuously in the background, rather than under the direct control of
     917      a user; for example, mail servers, network listeners, etc. MacPorts
     918      StartupItems are used for ported applications that use daemons; these
     919      keywords create Mac OS X startup scripts for <ulink
    916920      url="http://developer.apple.com/macosx/launchd.html">launchd</ulink>,
    917921      the facility introduced by Apple beginning with OS X 10.4, that starts,
    918       stops, and manages daemons, programs and scripts. Port authors use
     922      stops, and manages daemons, programs, and scripts. Port authors use
    919923      StartupItem keywords within Portfiles to instruct MacPorts to generate
    920       and install <command>launchd</command> scripts for daemons during port
    921       installation. To support launchd, a wrapper program named
    922       <command>daemondo</command> is provided by MacPorts base that serves as
    923       an adapter between OS X's <command>launchd</command> and daemons that
    924       are normally started via traditional rc.d style scripts.</para>
     924      and install <command>launchd</command> scripts during port installation.
     925      To support launchd, a wrapper program named <command>daemondo</command>
     926      is provided by MacPorts base that serves as an adapter between OS X's
     927      <command>launchd</command> and daemons started via traditional rc.d
     928      style scripts.</para>
    925929
    926930      <para>There are three categories of StartupItem keywords. Those that
    927       trigger StartupItem creation and setup logging, those that specify
    928       attributes of <quote>executable</quote> StartupItems, and those that
    929       specify attributes of <quote>script</quote> StartupItems.</para>
     931      trigger StartupItem creation and logging, those that specify attributes
     932      of <quote>executable</quote> StartupItems, and those that specify
     933      attributes of <quote>script</quote> StartupItems.</para>
    930934
    931935      <refsection>
     
    10591063        <title>Executable StartupItems</title>
    10601064
    1061         <para><quote>Executable</quote> StartupItems are slightly preferred
    1062         over <quote>script</quote> StartupItems because
    1063         <command>daemondo</command> launches the daemon directly, rather than
    1064         indirectly via a startup script, and therefore it automatically knows
    1065         how to monitor the daemon to restart it if it dies. The
    1066         <quote>executable</quote> StartupItem specifies the path and name of
    1067         the daemon to be run in the background.</para>
     1065        <para>Daemons run continuously, so monitoring the health of daemon
     1066        processes and restarting them if they die is an important
     1067        StartupItems' feature. <quote>Executable</quote> StartupItems are
     1068        preferred over <quote>script</quote> StartupItems because
     1069        <command>daemondo</command> launches the daemon
     1070        <emphasis>directly</emphasis>, rather than
     1071        <emphasis>indirectly</emphasis> via a script, and therefore it
     1072        automatically knows how to monitor a daemon process and restart it if
     1073        it dies. Daemons used with <quote>executable</quote> StartupItems may
     1074        be programs or scripts (shell, perl, python, etc.), but when a script
     1075        the script <emphasis>itself</emphasis> must be the daemon, rather than
     1076        a script that launches a daemon. <quote>Script</quote> StartupItems
     1077        are to be used for the latter.</para>
    10681078
    10691079        <note>
     
    11121122
    11131123        <para>StartupItems of type <quote>script</quote> use
    1114         <command>daemondo</command> to launch a daemon via a startup script
    1115         provided in port distributions containing daemons. When using this
    1116         type of StartupItem, the <code>startupitem.pidfile</code> keyword may
    1117         be used so <command>daemondo</command> can monitor the daemon's PID
    1118         and restart it if it dies.</para>
     1124        <command>daemondo</command> to launch a daemon
     1125        <emphasis>indirectly</emphasis> via a startup script. A typical
     1126        snippet of a startup script that may be used with a
     1127        <quote>script</quote> StartupItem is shown below. Notice that the
     1128        script is not a daemon; rather the script indirectly launches the
     1129        vm-pop3d daemon.</para>
     1130
     1131        <programlisting>#!/bin/sh
     1132#
     1133case "$1" in
     1134  start)
     1135       echo -n "Starting vm-pop3d: "
     1136       /opt/local/sbin/vm-pop3d -d 10 -t 600
     1137
     1138
     1139[... trimmed ...]</programlisting>
     1140
     1141        <para>But if a script itself is a daemon, use the executable
     1142        StartupItem type since that way it will be launched directly and its
     1143        health tracked automatically. When using <quote>script</quote>
     1144        StartupItems, the <code>startupitem.pidfile</code> keyword must be
     1145        used if you want <command>daemondo</command> to monitor a daemon
     1146        process and restart it if it dies.</para>
    11191147
    11201148        <note>
Note: See TracChangeset for help on using the changeset viewer.