sbin/rcorder/rcorder.8

   1 .\"     $NetBSD: rcorder.8,v 1.3 2000/07/17 14:16:22 mrg Exp $
   2 .\"     $DragonFly: src/sbin/rcorder/rcorder.8,v 1.2 2003/12/11 20:50:21 dillon Exp $
   3 .\"
   4 .\" Copyright (c) 1998
   5 .\"     Perry E. Metzger.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. All advertising materials mentioning features or use of this software
  16 .\"    must display the following acknowledgment:
  17 .\"     This product includes software developed for the NetBSD Project
  18 .\"     by Perry E. Metzger.
  19 .\" 4. The name of the author may not be used to endorse or promote products
  20 .\"    derived from this software without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  23 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  24 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  25 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  26 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  27 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  31 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32 .\"
  33 .\" $FreeBSD: src/sbin/rcorder/rcorder.8,v 1.3 2002/11/25 16:23:03 ru Exp $
  34 .\"
  35 .Dd July 17, 2000
  36 .Dt RCORDER 8
  37 .Os
  38 .Sh NAME
  39 .Nm rcorder
  40 .Nd print a dependency ordering of interdependent files
  41 .Sh SYNOPSIS
  42 .Nm
  43 .Op Fl k Ar keep
  44 .Op Fl s Ar skip
  45 .Op Fl o Ar resolve_for_file
  46 .Ar
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 utility is designed to print out a dependency ordering of a set of
  51 interdependent files.
  52 Typically it is used to find an execution
  53 sequence for a set of shell scripts in which certain files must be
  54 executed before others.
  55 .Pp
  56 Each file passed to
  57 .Nm
  58 must be annotated with special lines (which look like comments to the
  59 shell) which indicate the dependencies the files have upon certain
  60 points in the sequence, known as
  61 .Dq conditions ,
  62 and which indicate, for each file, which
  63 .Dq conditions
  64 may be expected to be filled by that file.
  65 .Pp
  66 Within each file, a block containing a series of
  67 .Dq Li REQUIRE ,
  68 .Dq Li PROVIDE ,
  69 .Dq Li BEFORE
  70 and
  71 .Dq Li KEYWORD
  72 lines must appear.
  73 The format of the lines is rigid.
  74 Each line must begin with a single
  75 .Ql # ,
  76 followed by a single space, followed by
  77 .Dq Li PROVIDE: ,
  78 .Dq Li REQUIRE: ,
  79 .Dq Li BEFORE: ,
  80 or
  81 .Dq Li KEYWORD: .
  82 No deviation is permitted.
  83 Each dependency line is then followed by a series of conditions,
  84 separated by whitespace.
  85 Multiple
  86 .Dq Li PROVIDE ,
  87 .Dq Li REQUIRE ,
  88 .Dq Li BEFORE
  89 and
  90 .Dq Li KEYWORD
  91 lines may appear, but all such lines must appear in a sequence without
  92 any intervening lines, as once a line that does not follow the format
  93 is reached, parsing stops.
  94 .Pp
  95 The options are as follows:
  96 .Bl -tag -width indent
  97 .It Fl k
  98 Add the specified keyword to the
  99 .Dq "keep list" .
 100 If any
 101 .Fl k
 102 option is given, only those files containing the matching keyword are listed.
 103 .It Fl s
 104 Add the specified keyword to the
 105 .Dq "skip list" .
 106 If any
 107 .Fl s
 108 option is given, files containing the matching keyword are not listed.
 109 .It Fl o
 110 Generate the dependancy list required to execute this file, including this
 111 file.
 112 If several
 113 .Fl o
 114 options are specified, the results are merged.
 115 .El
 116 .Pp
 117  An example block follows:
 118 .Bd -literal -offset indent
 119 # REQUIRE: networking syslog
 120 # REQUIRE: usr
 121 # PROVIDE: dns nscd
 122 .Ed
 123 .Pp
 124 This block states that the file in which it appears depends upon the
 125 .Dq Li networking ,
 126 .Dq Li syslog ,
 127 and
 128 .Dq Li usr
 129 conditions, and provides the
 130 .Dq Li dns
 131 and
 132 .Dq Li nscd
 133 conditions.
 134 .Pp
 135 A file may contain zero
 136 .Dq Li PROVIDE
 137 lines, in which case it provides no conditions, and may contain zero
 138 .Dq Li REQUIRE
 139 lines, in which case it has no dependencies.
 140 There must be at least one file with no dependencies in the set of
 141 arguments passed to
 142 .Nm
 143 in order for it to find a starting place in the dependency ordering.
 144 .Sh DIAGNOSTICS
 145 The
 146 .Nm
 147 utility may print one of the following error messages and exit with a non-zero
 148 status if it encounters an error while processing the file list.
 149 .Bl -diag
 150 .It "Requirement %s has no providers, aborting."
 151 No file has a
 152 .Dq Li PROVIDE
 153 line corresponding to a condition present in a
 154 .Dq Li REQUIRE
 155 line in another file.
 156 .It "Circular dependency on provision %s, aborting."
 157 A set of files has a circular dependency which was detected while
 158 processing the stated condition.
 159 .It "Circular dependency on file %s, aborting."
 160 A set of files has a circular dependency which was detected while
 161 processing the stated file.
 162 .El
 163 .Sh SEE ALSO
 164 .Xr rc 8
 165 .Sh HISTORY
 166 The
 167 .Nm
 168 utility first appeared in
 169 .Nx 1.5 .
 170 .Sh AUTHORS
 171 .An -nosplit
 172 Written by
 173 .An Perry E. Metzger Aq perry@piermont.com
 174 and
 175 .An Matthew R. Green Aq mrg@eterna.com.au .