Changeset 28640 for trunk/doc


Ignore:
Timestamp:
Sep 6, 2007, 1:35:29 AM (12 years ago)
Author:
markd@…
Message:

Correct startupitems section according to jberry@ list message.

File:
1 edited

Legend:

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

    r28626 r28640  
    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 daemons during port
    236     installation.</para>
     235    <command>launchd</command> scripts for daemons during port installation.
     236    To support launchd, a wrapper program named <command>daemondo</command> is
     237    provided by MacPorts base that serves as an adapter between OS X's
     238    <command>launchd</command> and daemons that are normally started via
     239    traditional rc.d style scripts.</para>
    237240
    238241    <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    trigger StartupItem creation and attributes, those that specify attributes
     243    of <quote>executable</quote> StartupItems, and those that specify
     244    attributes of <quote>script</quote> StartupItems.</para>
    242245
    243246    <section id="reference.startupitems.creation">
    244       <title>StartupItem Creation &amp; Logging</title>
     247      <title>StartupItem Creation &amp; Attributes</title>
    245248
    246249      <para>The keywords in this section may be used with either
    247       <quote>executable</quote> or <quote>wrapper</quote> StartupItems.</para>
     250      <quote>executable</quote> or <quote>script</quote> StartupItems (see
     251      below).</para>
    248252
    249253      <variablelist>
     
    285289
    286290            <programlisting>startupitem.name  OpenSSH</programlisting>
     291          </listitem>
     292        </varlistentry>
     293
     294        <varlistentry>
     295          <term>startupitem.pidfile</term>
     296
     297          <listitem>
     298            <para>This keyword must be defined properly for
     299            <command>daemondo</command> to be able to monitor a daemon and
     300            restart it if it dies. This is true for both <quote>script</quote>
     301            and <quote>executable</quote> StartupItems. It specifies two
     302            things; a process id (PID) file handling type, and a pidfile name
     303            and path.</para>
     304
     305            <simplelist>
     306              <member>Type: optional</member>
     307
     308              <member>Default: <option>[none]</option> |
     309              <filename>[${prefix}/var/run/${name}.pid]</filename></member>
     310
     311              <member>Values: <option>[none auto manual clean]</option>
     312              [<replaceable>/path/to/pidfile</replaceable>]</member>
     313
     314              <member>Example:</member>
     315            </simplelist>
     316
     317            <programlisting>startupitem.pidfile auto ${prefix}/var/run/${name}.pidfile</programlisting>
     318
     319            <para>Pidfile handling options:</para>
     320
     321            <simplelist>
     322              <member><option>none</option> - The daemon is not to use a
     323              pidfile.</member>
     324
     325              <member><option>auto</option> - The daemon generates its own
     326              pidfile.</member>
     327
     328              <member><option>manual</option> - The daemon never generates a
     329              pidfile; the StartupItem must manage the pidfile on its
     330              own.</member>
     331
     332              <member><option>clean</option> - The daemon generates its own
     333              but will not delete it; the StartupItem must delete it.</member>
     334            </simplelist>
    287335          </listitem>
    288336        </varlistentry>
     
    335383    </section>
    336384
    337     <section id="reference.startupitems.wrapper">
    338       <title>Wrapper StartupItems</title>
    339 
    340       <para>StartupItems of type <quote>wrapper</quote> use
    341       <command>daemondo</command>, a wrapper program provided by MacPorts base
    342       made to execute startup scripts for daemons. <command>daemondo</command>
    343       works as an adapter between OS X's <command>launchd</command> and
    344       daemons that are normally started via traditional rc.d style scripts.
    345       Therefore a port author may use these StartupItems when startup scripts
    346       are provided in the source distribution of ported software, or when a
    347       port author chooses to write his or her own.</para>
    348 
    349       <note>
    350         <para>For a given port, StartupItem keywords in category
    351         <quote>wrapper</quote> may not be mixed with any keywords in the
    352         <quote>executable</quote> StartupItem category.</para>
    353       </note>
    354 
    355       <variablelist>
    356         <varlistentry>
    357           <term>startupitem.init</term>
    358 
    359           <listitem>
    360             <para>Shell code that will be executed prior to any of the options
    361             <code>startupitem.start</code>, <code>startupitem.stop</code> and
    362             <code>startupitem.restart</code>.</para>
    363 
    364             <simplelist>
    365               <member>Type: optional</member>
    366 
    367               <member>Default: <option>no</option></member>
    368 
    369               <member>Values: <literal>shell script</literal></member>
    370 
    371               <member>Example:</member>
    372             </simplelist>
    373 
    374             <programlisting>startupitem.init  "PID=/var/run/dhcpd.pid"</programlisting>
    375           </listitem>
    376         </varlistentry>
    377 
    378         <varlistentry>
    379           <term>startupitem.start</term>
    380 
    381           <listitem>
    382             <para>Specify a shell script to start the daemon.</para>
    383 
    384             <simplelist>
    385               <member>Type: optional</member>
    386 
    387               <member>Default: none</member>
    388 
    389               <member>Values: <literal>shell script</literal></member>
    390 
    391               <member>Example:</member>
    392             </simplelist>
    393 
    394             <programlisting>startupitem.start ${prefix}/share/mysql/mysql.server start</programlisting>
    395           </listitem>
    396         </varlistentry>
    397 
    398         <varlistentry>
    399           <term>startupitem.stop</term>
    400 
    401           <listitem>
    402             <para>Specify a shell script to stop the daemon.</para>
    403 
    404             <simplelist>
    405               <member>Type: optional</member>
    406 
    407               <member>Default: none</member>
    408 
    409               <member>Values: <literal>shell script</literal></member>
    410 
    411               <member>Example:</member>
    412             </simplelist>
    413 
    414             <programlisting>startupitem.start ${prefix}/share/mysql/mysql.server stop</programlisting>
    415           </listitem>
    416         </varlistentry>
    417 
    418         <varlistentry>
    419           <term>startupitem.restart</term>
    420 
    421           <listitem>
    422             <para>Specify a shell script to restart the daemon. In the absence
    423             of this key, the daemon will be restarted by taking the stop
    424             action, followed by taking the start action.</para>
    425 
    426             <simplelist>
    427               <member>Type: optional</member>
    428 
    429               <member>Default: none</member>
    430 
    431               <member>Values: <literal>shell script</literal></member>
    432 
    433               <member>Example:</member>
    434             </simplelist>
    435 
    436             <programlisting>startupitem.start  ${prefix}/share/mysql/mysql.server restart</programlisting>
    437           </listitem>
    438         </varlistentry>
    439       </variablelist>
    440     </section>
    441 
    442385    <section id="reference.startupitems.executable">
    443386      <title>Executable StartupItems</title>
    444387
    445       <para>StartupItems of type <quote>executable</quote> specify the name of
    446       the daemon to be run in the background, and optionally a pidfile to
    447       track the process ID. Use this StartupItem type when you want
    448       <command>launchd</command> to monitor a daemon to make sure it stays
    449       running, and restart it if necessary.</para>
     388      <para><quote>Executable</quote> StartupItems are slightly preferred over
     389      <quote>script</quote> StartupItems because <command>daemondo</command>
     390      may be better able to detect when a daemon has died when it launches it
     391      directly, rather than indirectly via a startup script, though for
     392      daemondo to monitor either type, the <code>startupitem.pidfile</code>
     393      keyword must be set (see above). The <quote>executable</quote>
     394      StartupItem specifies the path and name of the daemon to be run in the
     395      background.</para>
    450396
    451397      <note>
    452         <para>For a given port, StartupItem keywords in category
    453         <quote>executable</quote> may not be mixed with any keywords in the
    454         <quote>wrapper</quote> StartupItem category.</para>
     398        <para>For a given port, the <quote>executable</quote> StartupItem
     399        keyword may not be used with any keywords in the <quote>script</quote>
     400        StartupItem category.</para>
    455401      </note>
    456402
     
    470416              <member>Default: <option>no</option></member>
    471417
    472               <member>Values: <option>yes no</option></member>
     418              <member>Values:
     419              <replaceable>/path/to/executable</replaceable></member>
    473420
    474421              <member>Example:</member>
     
    478425          </listitem>
    479426        </varlistentry>
    480 
    481         <varlistentry>
    482           <term>startupitem.pidfile</term>
    483 
    484           <listitem>
    485             <para>This keyword may be used in conjunction with the
    486             <code>startupitem.executable</code> key to inform the StartupItem
    487             how to track the executable. It specifies two things; a process id
    488             (PID) file handling type, and a pidfile name and path.</para>
     427      </variablelist>
     428    </section>
     429
     430    <section id="reference.startupitems.script">
     431      <title>Script StartupItems</title>
     432
     433      <para>StartupItems of type <quote>script</quote> let
     434      <command>daemondo</command> launch daemons via startup scripts. When
     435      using this type of StartupItem, the <code>startupitem.pidfile</code>
     436      keyword should be used so <command>daemondo</command> can monitor the
     437      daemon's PID and restart it if it dies.</para>
     438
     439      <note>
     440        <para>For a given port, StartupItem keywords in category
     441        <quote>script</quote> may not be used with an
     442        <quote>executable</quote> StartupItem keyword.</para>
     443      </note>
     444
     445      <variablelist>
     446        <varlistentry>
     447          <term>startupitem.init</term>
     448
     449          <listitem>
     450            <para>Shell code that will be executed prior to any of the options
     451            <code>startupitem.start</code>, <code>startupitem.stop</code> and
     452            <code>startupitem.restart</code>.</para>
    489453
    490454            <simplelist>
    491455              <member>Type: optional</member>
    492456
    493               <member>Default: <option>[none]</option> |
    494               <filename>[${prefix}/var/run/${name}.pid]</filename></member>
    495 
    496               <member>Values: <option>[none auto manual clean]</option>
    497               [<replaceable>/path/to/pidfile</replaceable>]</member>
     457              <member>Default: <option>no</option></member>
     458
     459              <member>Values: <literal>shell_script</literal></member>
    498460
    499461              <member>Example:</member>
    500462            </simplelist>
    501463
    502             <programlisting>startupitem.pidfile auto ${prefix}/var/run/${name}.pidfile</programlisting>
    503 
    504             <para>Pidfile handling options:</para>
    505 
    506             <simplelist>
    507               <member><option>none</option> - The daemon is not to use a
    508               pidfile.</member>
    509 
    510               <member><option>auto</option> - The daemon generates its own
    511               pidfile.</member>
    512 
    513               <member><option>manual</option> - The daemon never generates a
    514               pidfile; the StartupItem must manage the pidfile on its
    515               own.</member>
    516 
    517               <member><option>clean</option> - The daemon generates its own
    518               but will not delete it; the StartupItem must delete it.</member>
    519             </simplelist>
     464            <programlisting>startupitem.init  "PID=/var/run/dhcpd.pid"</programlisting>
     465          </listitem>
     466        </varlistentry>
     467
     468        <varlistentry>
     469          <term>startupitem.start</term>
     470
     471          <listitem>
     472            <para>Specify a shell script to start the daemon.</para>
     473
     474            <simplelist>
     475              <member>Type: optional</member>
     476
     477              <member>Default: none</member>
     478
     479              <member>Values: <literal>shell_script</literal></member>
     480
     481              <member>Example:</member>
     482            </simplelist>
     483
     484            <programlisting>startupitem.start ${prefix}/share/mysql/mysql.server start</programlisting>
     485          </listitem>
     486        </varlistentry>
     487
     488        <varlistentry>
     489          <term>startupitem.stop</term>
     490
     491          <listitem>
     492            <para>Specify a shell script to stop the daemon.</para>
     493
     494            <simplelist>
     495              <member>Type: optional</member>
     496
     497              <member>Default: none</member>
     498
     499              <member>Values: <literal>shell_script</literal></member>
     500
     501              <member>Example:</member>
     502            </simplelist>
     503
     504            <programlisting>startupitem.start ${prefix}/share/mysql/mysql.server stop</programlisting>
     505          </listitem>
     506        </varlistentry>
     507
     508        <varlistentry>
     509          <term>startupitem.restart</term>
     510
     511          <listitem>
     512            <para>Specify a shell script to restart the daemon. In the absence
     513            of this key, the daemon will be restarted by taking the stop
     514            action, followed by taking the start action.</para>
     515
     516            <simplelist>
     517              <member>Type: optional</member>
     518
     519              <member>Default: none</member>
     520
     521              <member>Values: <literal>shell_script</literal></member>
     522
     523              <member>Example:</member>
     524            </simplelist>
     525
     526            <programlisting>startupitem.start  ${prefix}/share/mysql/mysql.server restart</programlisting>
    520527          </listitem>
    521528        </varlistentry>
Note: See TracChangeset for help on using the changeset viewer.