Ignore:
Timestamp:
Sep 5, 2007, 5:40:49 AM (12 years ago)
Author:
markd@…
Message:

Refine the terms and language in the StartupItems section.

File:
1 edited

Legend:

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

    r28584 r28616  
    66
    77  <para>This chapter serves as a reference for the major elements of a
    8   <filename>Portfile</filename>: port phases, variants, StartupItems,
    9   variables, keywords, and Tcl extensions.</para>
     8  Portfile: port phases, dependencies, StartupItems, variables, keywords, and
     9  Tcl extensions.</para>
    1010
    1111  <section id="reference.phases">
     
    233233    and manages daemons, programs and scripts. Port authors use StartupItem
    234234    keywords within Portfiles to instruct MacPorts to generate and install
    235     <command>launchd</command> scripts for ports when they are
    236     installed.</para>
    237 
    238     <para>There are two types of StartupItems, executable and wrapper, but
    239     first we'll list the StartupItem keywords common to both types.</para>
    240 
    241     <section id="reference.startupitems.common">
    242       <title>Common StartupItem Keywords</title>
    243 
    244       <para>The keywords in this section may be used with executable or
    245       wrapper StartupItems.</para>
     235    <command>launchd</command> scripts for daemons during port
     236    installation.</para>
     237
     238    <para>There are three categories of StartupItem keywords. Those that
     239    trigger StartupItem creation and logging, those that specify attributes of
     240    <quote>executable</quote> StartupItems, and those that specify attributes
     241    of <quote>wrapper</quote> StartupItems.</para>
     242
     243    <section id="reference.startupitems.creation">
     244      <title>StartupItem Creation &amp; Logging</title>
     245
     246      <para>The keywords in this section may be used with either
     247      <quote>executable</quote> or <quote>wrapper</quote> StartupItems.</para>
    246248
    247249      <variablelist>
     
    287289          <listitem>
    288290            <para>Path to a logfile for logging events about the lifetime of
    289             the startupitem. Depending on the type of startupitem, and the
     291            the StartupItem. Depending on the type of StartupItem, and the
    290292            manner in which it is started, standard output from the daemon may
    291293            also be directed to the logfile.</para>
     
    325327    </section>
    326328
     329    <section id="reference.startupitems.wrapper">
     330      <title>Wrapper StartupItems</title>
     331
     332      <para>StartupItems of type <quote>wrapper</quote> use
     333      <command>daemondo</command>, a wrapper program provided by MacPorts base
     334      made to execute startup scripts for daemons. <command>daemondo</command>
     335      works as an adapter between OS X's <command>launchd</command> and
     336      daemons that are normally started via traditional rc.d style scripts.
     337      Therefore a port author may use these StartupItems when startup scripts
     338      are provided in the source distribution of ported software, or when a
     339      port author chooses to write his or her own.</para>
     340
     341      <note>
     342        <para>For a given port, StartupItem keywords in category
     343        <quote>wrapper</quote> may not be mixed with any keywords in the
     344        <quote>executable</quote> StartupItem category.</para>
     345      </note>
     346
     347      <variablelist>
     348        <varlistentry>
     349          <term>startupitem.init</term>
     350
     351          <listitem>
     352            <para>Shell code that will be executed prior to any of the options
     353            <code>startupitem.start</code>, <code>startupitem.stop</code> and
     354            <code>startupitem.restart</code>.</para>
     355
     356            <simplelist>
     357              <member>Type: optional</member>
     358
     359              <member>Default: <option>no</option></member>
     360
     361              <member>Values: <literal>shell script</literal></member>
     362            </simplelist>
     363
     364            <programlisting>startupitem.init  "PID=/var/run/dhcpd.pid"</programlisting>
     365          </listitem>
     366        </varlistentry>
     367
     368        <varlistentry>
     369          <term>startupitem.start</term>
     370
     371          <listitem>
     372            <para>Specify a shell script to start the daemon.</para>
     373
     374            <simplelist>
     375              <member>Type: optional</member>
     376
     377              <member>Default: none</member>
     378
     379              <member>Values: <literal>shell script</literal></member>
     380            </simplelist>
     381
     382            <programlisting>startupitem.start ${prefix}/share/mysql/mysql.server start</programlisting>
     383          </listitem>
     384        </varlistentry>
     385
     386        <varlistentry>
     387          <term>startupitem.stop</term>
     388
     389          <listitem>
     390            <para>Specify a shell script to stop the daemon.</para>
     391
     392            <simplelist>
     393              <member>Type: optional</member>
     394
     395              <member>Default: none</member>
     396
     397              <member>Values: <literal>shell script</literal></member>
     398            </simplelist>
     399
     400            <programlisting>startupitem.start ${prefix}/share/mysql/mysql.server stop</programlisting>
     401          </listitem>
     402        </varlistentry>
     403
     404        <varlistentry>
     405          <term>startupitem.restart</term>
     406
     407          <listitem>
     408            <para>Specify a shell script to restart the daemon. In the absence
     409            of this key, the daemon will be restarted by taking the stop
     410            action, followed by taking the start action.</para>
     411
     412            <simplelist>
     413              <member>Type: optional</member>
     414
     415              <member>Default: none</member>
     416
     417              <member>Values: <literal>shell script</literal></member>
     418            </simplelist>
     419
     420            <programlisting>startupitem.start  ${prefix}/share/mysql/mysql.server restart</programlisting>
     421          </listitem>
     422        </varlistentry>
     423      </variablelist>
     424    </section>
     425
    327426    <section id="reference.startupitems.executable">
    328427      <title>Executable StartupItems</title>
    329428
    330       <para>The executable StartupItem is the preferred type —it merely
    331       specify the name of the daemon to be run in the background.
    332       <command>launchd</command> monitors the daemon to make sure it stays
    333       running. Executable StartupItem keywords may not be used together with
    334       any of the wrapper StartupItem keywords.</para>
     429      <para>StartupItems of type <quote>executable</quote> specify the name of
     430      the daemon to be run in the background, and optionally a pidfile to
     431      track the process ID. Use this StartupItem type when you want
     432      <command>launchd</command> to monitor a daemon to make sure it stays
     433      running, and restart it if necessary.</para>
     434
     435      <note>
     436        <para>For a given port, StartupItem keywords in category
     437        <quote>executable</quote> may not be mixed with any keywords in the
     438        <quote>wrapper</quote> StartupItem category.</para>
     439      </note>
    335440
    336441      <variablelist>
     
    361466          <listitem>
    362467            <para>A specification for process id (PID) file handling that may
    363             be used in conjunction with the startupitem.executable key to
    364             inform the startupitem how to track the executable. This keyword
    365             specifies whether the daemon is not to use a pidfile
    366             (<option>none</option>), generates its own pidfile
    367             (<option>auto</option>), never generates one (so the startupitem
    368             should manage the pidfile on its own (<option>manual</option>), or
    369             generates its own but will not delete it (so the startupitem
    370             should delete it using <option>clean</option>).</para>
     468            be used in conjunction with the
     469            <code>startupitem.executable</code> key to inform the startupitem
     470            how to track the executable. This keyword specifies whether the
     471            daemon is not to use a pidfile (<option>none</option>), generates
     472            its own pidfile (<option>auto</option>), never generates one (so
     473            the StartupItem should manage the pidfile on its own
     474            (<option>manual</option>), or generates its own but will not
     475            delete it (so the StartupItem should delete it using
     476            <option>clean</option>).</para>
    371477
    372478            <simplelist>
     
    381487
    382488            <programlisting>startupitem.pidfile auto ${prefix}/var/run/${name}.pidfile</programlisting>
    383           </listitem>
    384         </varlistentry>
    385       </variablelist>
    386     </section>
    387 
    388     <section id="reference.startupitems.wrapper">
    389       <title>Wrapper StartupItems</title>
    390 
    391       <para>Wrapper StartupItems use <command>daemondo</command>, a wrapper
    392       program provided by MacPorts base made to execute startup scripts for
    393       daemons. <command>daemondo</command> works as an adapter between OS X's
    394       launchd and daemons that are normally started via traditional rc.d style
    395       scripts.</para>
    396 
    397       <variablelist>
    398         <varlistentry>
    399           <term>startupitem.init</term>
    400 
    401           <listitem>
    402             <para>Shell code that will be executed prior to any of the options
    403             startupitem.start, startupitem.stop and
    404             startupitem.restart.</para>
    405 
    406             <simplelist>
    407               <member>Type: optional</member>
    408 
    409               <member>Default: <option>no</option></member>
    410 
    411               <member>Values: <literal>shell script</literal></member>
    412             </simplelist>
    413 
    414             <programlisting>startupitem.init  "PID=/var/run/dhcpd.pid"</programlisting>
    415           </listitem>
    416         </varlistentry>
    417 
    418         <varlistentry>
    419           <term>startupitem.start</term>
    420 
    421           <listitem>
    422             <para>Specify a shell script to start the daemon.</para>
    423 
    424             <simplelist>
    425               <member>Type: optional</member>
    426 
    427               <member>Default: none</member>
    428 
    429               <member>Values: <literal>shell script</literal></member>
    430             </simplelist>
    431 
    432             <programlisting>startupitem.start ${prefix}/share/mysql/mysql.server start</programlisting>
    433           </listitem>
    434         </varlistentry>
    435 
    436         <varlistentry>
    437           <term>startupitem.stop</term>
    438 
    439           <listitem>
    440             <para>Specify a shell script to stop the daemon.</para>
    441 
    442             <simplelist>
    443               <member>Type: optional</member>
    444 
    445               <member>Default: none</member>
    446 
    447               <member>Values: <literal>shell script</literal></member>
    448             </simplelist>
    449 
    450             <programlisting>startupitem.start ${prefix}/share/mysql/mysql.server stop</programlisting>
    451           </listitem>
    452         </varlistentry>
    453 
    454         <varlistentry>
    455           <term>startupitem.restart</term>
    456 
    457           <listitem>
    458             <para>Specify a shell script to restart the daemon. In the absence
    459             of this key, the daemon will be restarted by taking the stop
    460             action, followed by taking the start action.</para>
    461 
    462             <simplelist>
    463               <member>Type: optional</member>
    464 
    465               <member>Default: none</member>
    466 
    467               <member>Values: <literal>shell script</literal></member>
    468             </simplelist>
    469 
    470             <programlisting>startupitem.start  ${prefix}/share/mysql/mysql.server restart</programlisting>
    471489          </listitem>
    472490        </varlistentry>
Note: See TracChangeset for help on using the changeset viewer.