sbin/rcorder/rcorder.8

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