Changeset 28491 for trunk/doc


Ignore:
Timestamp:
Sep 2, 2007, 2:48:44 AM (12 years ago)
Author:
markd@…
Message:

Improve the StartupItems section by adding more details from portfile.7.

File:
1 edited

Legend:

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

    r28269 r28491  
    216216  </section>
    217217
    218   <section id="reference.startupitems">
     218  <section>
    219219    <title>StartupItems</title>
    220220
    221     <para>StartupItems are keywords that create Mac OS X LaunchDaemon startup
    222     scripts. To create these startup scripts for a port, choose from the
    223     following keywords.</para>
    224 
    225     <para><variablelist>
     221    <para>StartupItems are keywords that create Mac OS X startup scripts for
     222    <ulink
     223    url="http://developer.apple.com/macosx/launchd.html">launchd</ulink>, the
     224    facility intoduced by Apple beginning with OS X 10.4, that starts, stops,
     225    and manages daemons, programs and scripts. Port authors use StartupItem
     226    keywords within Portfiles to instruct MacPorts to generate and install
     227    <command>launchd</command> scripts for ports when they are
     228    installed.</para>
     229
     230    <para>There are two types of StartupItems, executable and non-executable,
     231    but first we'll list the StartupItem keywords common to both types.</para>
     232
     233    <section>
     234      <title>StartupItem Common Keywords</title>
     235
     236      <para>The keywords in this section may be used with executable or
     237      non-executable StartupItems.</para>
     238
     239      <variablelist>
    226240        <varlistentry>
    227241          <term>startupitem.create</term>
    228242
    229243          <listitem>
    230             <para>This triggers the creation of a StartupItem, defaults to
    231             "no".</para>
    232           </listitem>
    233         </varlistentry>
    234       </variablelist><variablelist>
     244            <para>Trigger the creation of a StartupItem.</para>
     245
     246            <simplelist>
     247              <member>Type: optional</member>
     248
     249              <member>Default: <option>no</option></member>
     250
     251              <member>Values: <option>yes no</option></member>
     252            </simplelist>
     253
     254            <programlisting>startupitem.create  yes</programlisting>
     255          </listitem>
     256        </varlistentry>
     257
    235258        <varlistentry>
    236259          <term>startupitem.name</term>
    237260
    238261          <listitem>
    239             <para>Sets the name for the StartupItem, defaults to
    240             ${portname}.</para>
    241           </listitem>
    242         </varlistentry>
    243       </variablelist><variablelist>
    244         <varlistentry>
    245           <term>startupitem.executable</term>
    246 
    247           <listitem>
    248             <para>The name of the daemon to be run in the background. This is
    249             the preferred type of startup item and may not be used together
    250             with any other startupitem. This option may contain multiple
    251             arguments, but they must be appropriate for a call to exec; they
    252             may not contain arbitrary shell code.</para>
    253           </listitem>
    254         </varlistentry>
    255       </variablelist><variablelist>
    256         <varlistentry>
    257           <term>startupitem.init</term>
    258 
    259           <listitem>
    260             <para>Shell code that will be executed prior to any of the options
    261             startupitem.start, startupitem.stop and startupitem.restart.
    262             Typically a startup script is specified.</para>
    263           </listitem>
    264         </varlistentry>
    265       </variablelist><variablelist>
    266         <varlistentry>
    267           <term>startupitem.start</term>
    268 
    269           <listitem>
    270             <para>Shell code executed to start the daemon.</para>
    271           </listitem>
    272         </varlistentry>
    273       </variablelist><variablelist>
    274         <varlistentry>
    275           <term>startupitem.stop</term>
    276 
    277           <listitem>
    278             <para>Shell code executed to stop the daemon.</para>
    279           </listitem>
    280         </varlistentry>
    281       </variablelist><variablelist>
    282         <varlistentry>
    283           <term>startupitem.restart</term>
    284 
    285           <listitem>
    286             <para>Shell code executed to restart the daemon. In the absence of
    287             this key, the daemon will be restarted by taking the stop action,
    288             followed by taking the start action.</para>
    289           </listitem>
    290         </varlistentry>
    291       </variablelist><variablelist>
    292         <varlistentry>
    293           <term>startupitem.pidfile</term>
    294 
    295           <listitem>
    296             <para>Specification for pidfile handling. It is useful in
    297             conjunction with the startupitem.executable key, because it is
    298             important that the startupitem know how to track the executable.
    299             This keyword specifies whether the daemon generates its own
    300             pidfile (auto), whether it generates its own but forgets to delete
    301             it, so that the startupitem should delete it (clean), or whether
    302             it never generates one, in which case the startupitem should
    303             manage the pidfile on its own (manual), or whether no pidfile
    304             should be used at all (none).</para>
    305           </listitem>
    306         </varlistentry>
    307       </variablelist><variablelist>
     262            <para>Sets the name for the StartupItem.</para>
     263
     264            <simplelist>
     265              <member>Type: required</member>
     266
     267              <member>Default: none</member>
     268
     269              <member>Values:</member>
     270            </simplelist>
     271
     272            <programlisting>startupitem.name  OpenSSH</programlisting>
     273          </listitem>
     274        </varlistentry>
     275
    308276        <varlistentry>
    309277          <term>startupitem.logfile</term>
     
    314282            manner in which it is started, standard output from the daemon may
    315283            also be directed to the logfile.</para>
    316           </listitem>
    317         </varlistentry>
    318       </variablelist><variablelist>
     284
     285            <simplelist>
     286              <member>Type: optional</member>
     287
     288              <member>Default: <option>/dev/null</option></member>
     289
     290              <member>Values: <replaceable>/file/path/</replaceable></member>
     291            </simplelist>
     292
     293            <programlisting>startupitem.logfile  ${prefix}/var/log/mydaemon.log</programlisting>
     294          </listitem>
     295        </varlistentry>
     296
    319297        <varlistentry>
    320298          <term>startupitem.logevents</term>
     
    324302            logevents is set, events with timestamps are logged to the
    325303            logfile.</para>
    326           </listitem>
    327         </varlistentry>
    328       </variablelist></para>
     304
     305            <simplelist>
     306              <member>Type: optional</member>
     307
     308              <member>Default: <option>no</option></member>
     309
     310              <member>Values: <option>yes no</option></member>
     311            </simplelist>
     312
     313            <programlisting>startupitem.logevents   yes</programlisting>
     314          </listitem>
     315        </varlistentry>
     316      </variablelist>
     317    </section>
     318
     319    <section>
     320      <title>Executable StartupItems</title>
     321
     322      <para>The executable StartupItem is the preferred type —it merely
     323      specify the name of the daemon to be run in the background.
     324      <command>launchd</command> monitors the daemon to make sure it stays
     325      running. Executable StartupItems may not be used together with any of
     326      the non-executable StartupItem keywords.</para>
     327
     328      <variablelist>
     329        <varlistentry>
     330          <term>startupitem.executable</term>
     331
     332          <listitem>
     333            <para>Specifies the name of the daemon to be run in the
     334            background. It may have multiple arguments, but they must be
     335            appropriate for a call to exec; arbitrary shell code may not be
     336            used.</para>
     337
     338            <simplelist>
     339              <member>Type: optional</member>
     340
     341              <member>Default: <option>no</option></member>
     342
     343              <member>Values: <option>yes no</option></member>
     344            </simplelist>
     345
     346            <programlisting>startupitem.executable  "${prefix}/bin/nmicmpd"</programlisting>
     347          </listitem>
     348        </varlistentry>
     349
     350        <varlistentry>
     351          <term>startupitem.pidfile</term>
     352
     353          <listitem>
     354            <para>A specification for process id (PID) file handling that may
     355            be used in conjunction with the startupitem.executable key to
     356            inform the startupitem how to track the executable. This keyword
     357            specifies whether the daemon is not to use a pidfile
     358            (<option>none</option>), generates its own pidfile
     359            (<option>auto</option>), never generates one (so the startupitem
     360            should manage the pidfile on its own (<option>manual</option>), or
     361            generates its own but will not delete it (so the startupitem
     362            should delete it using <option>clean</option>).</para>
     363
     364            <simplelist>
     365              <member>Type: optional</member>
     366
     367              <member>Default: <option>none</option> |
     368              <filename>${prefix}/var/run/${name}.pid</filename></member>
     369
     370              <member>Values: <option>none auto manual clean</option>
     371              [<replaceable>/path/to/pidfile</replaceable>]</member>
     372            </simplelist>
     373
     374            <programlisting>startupitem.pidfile auto ${prefix}/var/run/${name}.pidfile</programlisting>
     375          </listitem>
     376        </varlistentry>
     377      </variablelist>
     378    </section>
     379
     380    <section>
     381      <title>Non-Executable StartupItems</title>
     382
     383      <para>Non-executable StartupItems use <command>daemondo</command>, a
     384      wrapper program provided by MacPorts base that runs daemons.
     385      <command>daemondo</command> works as an adapter between OS X's launchd
     386      and daemons that are normally started via traditional rc.d style
     387      scripts.</para>
     388
     389      <variablelist>
     390        <varlistentry>
     391          <term>startupitem.init</term>
     392
     393          <listitem>
     394            <para>Shell code that will be executed prior to any of the options
     395            startupitem.start, startupitem.stop and
     396            startupitem.restart.</para>
     397
     398            <simplelist>
     399              <member>Type: optional</member>
     400
     401              <member>Default: <option>no</option></member>
     402
     403              <member>Values: <option>shell code</option></member>
     404            </simplelist>
     405
     406            <programlisting>startupitem.init  "PID=/var/run/dhcpd.pid"</programlisting>
     407          </listitem>
     408        </varlistentry>
     409
     410        <varlistentry>
     411          <term>startupitem.start</term>
     412
     413          <listitem>
     414            <para>Specify a shell script to start the daemon.</para>
     415
     416            <simplelist>
     417              <member>Type: optional</member>
     418
     419              <member>Default: none</member>
     420
     421              <member>Values: <literal>shell script</literal></member>
     422            </simplelist>
     423
     424            <programlisting>startupitem.start ${prefix}/share/mysql/mysql.server start</programlisting>
     425          </listitem>
     426        </varlistentry>
     427
     428        <varlistentry>
     429          <term>startupitem.stop</term>
     430
     431          <listitem>
     432            <para>Specify a shell script to stop the daemon.</para>
     433
     434            <simplelist>
     435              <member>Type: optional</member>
     436
     437              <member>Default: none</member>
     438
     439              <member>Values: <literal>shell script</literal></member>
     440            </simplelist>
     441
     442            <programlisting>startupitem.start ${prefix}/share/mysql/mysql.server stop</programlisting>
     443          </listitem>
     444        </varlistentry>
     445
     446        <varlistentry>
     447          <term>startupitem.restart</term>
     448
     449          <listitem>
     450            <para>Specify a shell script to restart the daemon. In the absence
     451            of this key, the daemon will be restarted by taking the stop
     452            action, followed by taking the start action.</para>
     453
     454            <simplelist>
     455              <member>Type: optional</member>
     456
     457              <member>Default: none</member>
     458
     459              <member>Values: <literal>shell script</literal></member>
     460            </simplelist>
     461
     462            <programlisting>startupitem.start  ${prefix}/share/mysql/mysql.server restart</programlisting>
     463          </listitem>
     464        </varlistentry>
     465      </variablelist>
     466    </section>
    329467  </section>
    330468
     
    375513
    376514            <listitem>
    377               <para>Path to the directory containing the downloaded
    378               <filename>Portfile</filename>s. Read only.</para>
     515              <para>Path to the directory containing the downloaded Read
     516              only.</para>
    379517            </listitem>
    380518          </varlistentry>
     
    421559            <listitem>
    422560              <para>Location to store downloaded distfiles. Read only.</para>
     561            </listitem>
     562          </varlistentry>
     563
     564          <varlistentry>
     565            <term>install.user</term>
     566
     567            <listitem>
     568              <para>The Unix user at the time of port installation.</para>
     569            </listitem>
     570          </varlistentry>
     571
     572          <varlistentry>
     573            <term>install.group</term>
     574
     575            <listitem>
     576              <para>The Unix group at the time of port installation.</para>
    423577            </listitem>
    424578          </varlistentry>
Note: See TracChangeset for help on using the changeset viewer.