usr/src/man/man4/prototype.4

   1 '\" te
   2 .\" Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved
   3 .\" Copyright 1989 AT&T
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH PROTOTYPE 4 "May 3, 2008"
   8 .SH NAME
   9 prototype \- package information file
  10 .SH DESCRIPTION
  11 .sp
  12 .LP
  13 \fBprototype\fR is an \fBASCII\fR file used to specify package information.
  14 Each entry in the file describes a single deliverable object. An object can be
  15 a data file, directory, source file, executable object, and so forth. This file
  16 is generated by the package developer.
  17 .sp
  18 .LP
  19 Entries in a \fBprototype\fR file consist of several fields of information
  20 separated by white space. Comment lines begin with a ``\fB#\fR'' and are
  21 ignored. The fields are described below and must appear in the order shown.
  22 .sp
  23 .ne 2
  24 .na
  25 \fB\fIpart\fR\fR
  26 .ad
  27 .RS 12n
  28 An optional field designating the part number in which the object resides. A
  29 part is a collection of files and is the atomic unit by which a package is
  30 processed. A developer can choose criteria for grouping files into a part (for
  31 example, based on class). If this field is not used, part 1 is assumed.
  32 .RE
  33
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fIftype\fR\fR
  38 .ad
  39 .RS 12n
  40 A one-character field that indicates the file type. Valid values are:
  41 .sp
  42 .ne 2
  43 .na
  44 \fB\fBb\fR\fR
  45 .ad
  46 .RS 5n
  47 block special device
  48 .RE
  49
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fBc\fR\fR
  54 .ad
  55 .RS 5n
  56 character special device
  57 .RE
  58
  59 .sp
  60 .ne 2
  61 .na
  62 \fB\fBd\fR\fR
  63 .ad
  64 .RS 5n
  65 directory
  66 .RE
  67
  68 .sp
  69 .ne 2
  70 .na
  71 \fB\fBe\fR\fR
  72 .ad
  73 .RS 5n
  74 a file to be edited upon installation or removal (can be shared by several
  75 packages)
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fBf\fR\fR
  82 .ad
  83 .RS 5n
  84 a standard executable or data file
  85 .RE
  86
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fBi\fR\fR
  91 .ad
  92 .RS 5n
  93 installation script or information file
  94 .RE
  95
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fBl\fR\fR
 100 .ad
 101 .RS 5n
 102 linked file
 103 .RE
 104
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fBp\fR\fR
 109 .ad
 110 .RS 5n
 111 named pipe
 112 .RE
 113
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fBs\fR\fR
 118 .ad
 119 .RS 5n
 120 symbolic link
 121 .RE
 122
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fBv\fR\fR
 127 .ad
 128 .RS 5n
 129 volatile file (one whose contents are expected to change, like a log file)
 130 .RE
 131
 132 .sp
 133 .ne 2
 134 .na
 135 \fB\fBx\fR\fR
 136 .ad
 137 .RS 5n
 138 an exclusive directory accessible only by this package
 139 .RE
 140
 141 .RE
 142
 143 .sp
 144 .ne 2
 145 .na
 146 \fB\fIclass\fR\fR
 147 .ad
 148 .RS 12n
 149 The installation class to which the file belongs. This name can be no longer
 150 than 64 characters. The field is not specified for installation scripts.
 151 (\fBadmin\fR and all classes beginning with capital letters are reserved class
 152 names.)
 153 .RE
 154
 155 .sp
 156 .ne 2
 157 .na
 158 \fB\fIpathname\fR\fR
 159 .ad
 160 .RS 12n
 161 The pathname where the file resides on the target machine, for example,
 162 \fB/usr/bin/mail\fR or \fBbin/ras/proc\fR. Relative pathnames (those that do
 163 not begin with a slash) indicate that the file is relocatable. The form
 164 .sp
 165 \fIpath1\fR\fB=\fR\fIpath2\fR
 166 .sp
 167 can be used for two purposes: to define a link and to define local pathnames.
 168 .sp
 169 For linked files, \fIpath1\fR indicates the destination of the link and
 170 \fIpath2\fR indicates the source file. (This format is mandatory for linked
 171 files.)
 172 .sp
 173 For local pathnames, \fIpath1\fR indicates the pathname an object should have
 174 on the machine where the entry is to be installed and \fIpath2\fR indicates
 175 either a relative or fixed pathname to a file on the host machine which
 176 contains the actual contents.
 177 .sp
 178 A pathname can contain a variable specification of the form
 179 \fB$\fR\fIvariable.\fR If \fIvariable\fR begins with a lower case letter, it is
 180 a build variable. If \fIvariable\fR begins with an upper case letter, it is an
 181 install variable. Build variables are bound at build time. If an install
 182 variable is known at build time, its definition is inserted into the
 183 \fBpkginfo\fR(4) file so that it is available at install time. If an install
 184 variable is not known at build time, it is bound at install time.
 185 .RE
 186
 187 .sp
 188 .ne 2
 189 .na
 190 \fB\fImajor\fR\fR
 191 .ad
 192 .RS 12n
 193 The major device number. The field is only specified for block or character
 194 special devices.
 195 .RE
 196
 197 .sp
 198 .ne 2
 199 .na
 200 \fB\fIminor\fR\fR
 201 .ad
 202 .RS 12n
 203 The minor device number. The field is only specified for block or character
 204 special devices.
 205 .RE
 206
 207 .sp
 208 .ne 2
 209 .na
 210 \fB\fImode\fR\fR
 211 .ad
 212 .RS 12n
 213 The octal mode of the file (for example, 0664). A question mark (\fB?\fR)
 214 indicates that the mode is left unchanged, implying that the file already
 215 exists on the target machine. This field is not used for linked files or
 216 packaging information files.
 217 .sp
 218 The mode can be a variable specification of the form \fB$\fR\fIvariable.\fR If
 219 \fIvariable\fR begins with a lower case letter, it is a build variable. If
 220 \fIvariable\fR begins with an upper case letter, it is an install variable.
 221 Build variables are bound at build time. If an install variable is known at
 222 build time, its definition is inserted into the \fBpkginfo\fR(4) file so that
 223 it is available at install time. If an install variable is not known at build
 224 time, it is bound at install time.
 225 .RE
 226
 227 .sp
 228 .ne 2
 229 .na
 230 \fB\fIowner\fR\fR
 231 .ad
 232 .RS 12n
 233 The owner of the file (for example, \fBbin\fR or \fBroot\fR). The field is
 234 limited to 14 characters in length. A question mark (\fB?\fR) indicates that
 235 the owner is left unchanged, implying that the file already exists on the
 236 target machine. This field is not used for linked files or packaging
 237 information files.
 238 .sp
 239 The owner can be a variable specification of the form \fB$\fR\fIvariable.\fR If
 240 \fIvariable\fR begins with a lower case letter, it is a build variable. If
 241 \fIvariable\fR begins with an upper case letter, it is an install variable.
 242 Build variables are bound at build time. If an install variable is known at
 243 build time, its definition is inserted into the \fBpkginfo\fR(4) file so that
 244 it is available at install time. If an install variable is not known at build
 245 time, it is bound at install time.
 246 .RE
 247
 248 .sp
 249 .ne 2
 250 .na
 251 \fB\fIgroup\fR\fR
 252 .ad
 253 .RS 12n
 254 The group to which the file belongs (for example, \fBbin\fR or \fBsys\fR). The
 255 field is limited to 14 characters in length. A question mark (\fB?\fR)
 256 indicates that the group is left unchanged, implying that the file already
 257 exists on the target machine. This field is not used for linked files or
 258 packaging information files.
 259 .sp
 260 The group can be a variable specification of the form \fB$\fR\fIvariable.\fR If
 261 \fIvariable\fR begins with a lower case letter, it is a build variable. If
 262 \fIvariable\fR begins with an upper case letter, it is an install variable.
 263 Build variables are bound at build time. If an install variable is known at
 264 build time, its definition is inserted into the \fBpkginfo\fR(4) file so that
 265 it is available at install time. If an install variable is not known at build
 266 time, it is bound at install time.
 267 .RE
 268
 269 .sp
 270 .LP
 271 An exclamation point (\fB!\fR) at the beginning of a line indicates that the
 272 line contains a command. These commands are used to incorporate files in other
 273 directories, to locate objects on a host machine, and to set permanent
 274 defaults. The following commands are available:
 275 .sp
 276 .ne 2
 277 .na
 278 \fB\fBsearch\fR\fR
 279 .ad
 280 .RS 15n
 281 Specifies a list of directories (separated by white space) to search for when
 282 looking for file contents on the host machine. The base name of the \fIpath\fR
 283 field is appended to each directory in the ordered list until the file is
 284 located. Searches are not recursive.
 285 .RE
 286
 287 .sp
 288 .ne 2
 289 .na
 290 \fB\fBinclude\fR\fR
 291 .ad
 292 .RS 15n
 293 Specifies a pathname which points to another prototype file to include. Note
 294 that \fBsearch\fR requests do not span \fBinclude\fR files.
 295 .RE
 296
 297 .sp
 298 .ne 2
 299 .na
 300 \fB\fBdefault\fR\fR
 301 .ad
 302 .RS 15n
 303 Specifies a list of attributes (mode, owner, and group) to be used by default
 304 if attribute information is not provided for prototype entries which require
 305 the information. The defaults do not apply to entries in \fBinclude\fR
 306 prototype files.
 307 .RE
 308
 309 .sp
 310 .ne 2
 311 .na
 312 \fB\fIparam\fR\fB=\fR\fIvalue\fR\fR
 313 .ad
 314 .RS 15n
 315 Places the indicated parameter in the current environment. Spans to subsequent
 316 included prototype files.
 317 .RE
 318
 319 .sp
 320 .LP
 321 The above commands can have variable substitutions embedded within them, as
 322 demonstrated in the two example prototype files below.
 323 .sp
 324 .LP
 325 Before files are overwritten during installation, they are copied to a
 326 temporary pathname. The exception to this rule is files whose mode includes
 327 execute permission, unless the file is editable (that is, \fIftype\fR is
 328 \fBe\fR). For files which meet this exception, the existing version is linked
 329 to a temporary pathname, and the original file is removed. This allows
 330 processes which are executing during installation to be overwritten.
 331 .SH EXAMPLES
 332 .LP
 333 \fBExample 1 \fRExample 1:
 334 .sp
 335 .in +2
 336 .nf
 337 !PROJDIR=/usr/proj
 338 !BIN=$PROJDIR/bin
 339 !CFG=$PROJDIR/cfg
 340 !LIB=$PROJDIR/lib
 341 !HDRS=$PROJDIR/hdrs
 342 !search /usr/myname/usr/bin /usr/myname/src /usr/myname/hdrs
 343 i pkginfo=/usr/myname/wrap/pkginfo
 344 i depend=/usr/myname/wrap/depend
 345 i version=/usr/myname/wrap/version
 346 d none /usr/wrap 0755 root bin
 347 d none /usr/wrap/usr/bin 0755 root bin
 348 ! search $BIN
 349 f none /usr/wrap/bin/INSTALL 0755 root bin
 350 f none /usr/wrap/bin/REMOVE 0755 root bin
 351 f none /usr/wrap/bin/addpkg 0755 root bin
 352 !default 755 root bin
 353 f none /usr/wrap/bin/audit
 354 f none /usr/wrap/bin/listpkg
 355 f none /usr/wrap/bin/pkgmk
 356 # the following file starts out zero length but grows
 357 v none /usr/wrap/logfile=/dev/null 0644 root bin
 358 # the following specifies a link (dest=src)
 359 l none /usr/wrap/src/addpkg=/usr/wrap/bin/rmpkg
 360 ! search $SRC
 361 !default 644 root other
 362 f src /usr/wrap/src/INSTALL.sh
 363 f src /usr/wrap/src/REMOVE.sh
 364 f src /usr/wrap/src/addpkg.c
 365 f src /usr/wrap/src/audit.c
 366 f src /usr/wrap/src/listpkg.c
 367 f src /usr/wrap/src/pkgmk.c
 368 d none /usr/wrap/data 0755 root bin
 369 d none /usr/wrap/save 0755 root bin
 370 d none /usr/wrap/spool 0755 root bin
 371 d none /usr/wrap/tmp 0755 root bin
 372 d src /usr/wrap/src 0755 root bin
 373 .fi
 374 .in -2
 375 .sp
 376
 377 .LP
 378 \fBExample 2 \fRExample 2:
 379 .sp
 380 .in +2
 381 .nf
 382 \fB# this prototype is generated by 'pkgproto' to refer
 383 # to all prototypes in my src directory
 384 !PROJDIR=/usr/dew/projx
 385 !include $PROJDIR/src/cmd/prototype
 386 !include $PROJDIR/src/cmd/audmerg/protofile
 387 !include $PROJDIR/src/lib/proto\fR
 388 .fi
 389 .in -2
 390 .sp
 391
 392 .SH SEE ALSO
 393 .sp
 394 .LP
 395 \fBpkgmk\fR(1), \fBpkginfo\fR(4)
 396 .sp
 397 .LP
 398 \fIApplication Packaging Developer\&'s Guide\fR
 399 .SH NOTES
 400 .sp
 401 .LP
 402 Normally, if a file is defined in the \fBprototype\fR file but does not exist,
 403 that file is created at the time of package installation. However, if the file
 404 pathname includes a directory that does not exist, the file is not created. For
 405 example, if the \fBprototype\fR file has the following entry:
 406 .sp
 407 .in +2
 408 .nf
 409 \fBf none /usr/dev/bin/command\fR
 410 .fi
 411 .in -2
 412 .sp
 413
 414 .sp
 415 .LP
 416 and that file does not exist, it is created if the directory \fB/usr/dev/bin\fR
 417 already exists or if the \fBprototype\fR also has an entry defining the
 418 directory:
 419 .sp
 420 .in +2
 421 .nf
 422 \fBd none /usr/dev/bin\fR
 423 .fi
 424 .in -2
 425 .sp
 426