usr.sbin/pkg_install/create/pkg_create.1

   1 .\"
   2 .\" FreeBSD install - a package for the installation and maintainance
   3 .\" of non-core utilities.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" Jordan K. Hubbard
  15 .\"
  16 .\"
  17 .\"     @(#)pkg_create.1
  18 .\"
  19 .TH pkg_create 1 "July 18, 1993" "" "FreeBSD"
  20
  21 .SH NAME
  22 pkg_create - a utility for creating software package distributions.
  23 .SH SYNOPSIS
  24 .na
  25 .B pkg_create
  26 .RB [options]
  27 .RB pkg-name
  28
  29 .SH DESCRIPTION
  30 The
  31 .B pkg_create
  32 command is used to create packages that will subsequently be fed to
  33 one of the package extraction/info utilities.  The input description
  34 and command line arguments for the creation of a package are not
  35 really meant to be human-generated, though it is easy enough to
  36 do so.  It is more expected that you will use a front-end tool for
  37 the job rather than muddling through it yourself. Nonetheless, a short
  38 description of the input syntax is included in this document.
  39
  40 .SH OPTIONS
  41 .TP
  42 The following command line options are supported.
  43 .TP
  44 .B \-v
  45 Turns on verbose output.
  46 .B "Optional."
  47 .TP
  48 .BI "\-c\ " [-]desc
  49 Fetch package "one line description" from file
  50 .I desc
  51 or, if preceeded by
  52 .B -
  53 , the argument itself.  This string should also
  54 give some idea of which version of the product (if any) the package
  55 represents.
  56 .B "Mandatory."
  57 .TP
  58 .BI "\-d\ " [-]desc
  59 Fetch long description for package from file
  60 .I desc
  61 or, if preceeded by
  62 .B -
  63 , the argument itself.
  64 .B "Mandatory."
  65 .TP
  66 .BI "\-f\ " file
  67 Fetch "packing list" for package from
  68 .I file
  69 or
  70 .B stdin
  71 if
  72 .I file
  73 is a
  74 .B -
  75 (dash).
  76 .B "Mandatory."
  77 .TP
  78 .BI "\-i\ " script
  79 Sets
  80 .I script
  81 to be the install procedure for the package.  This can be any
  82 executable program (or shell script).  It will be invoked automatically
  83 when the package is later installed.
  84 .B "Optional."
  85 .TP
  86 .BI "\-p\ " prefix
  87 Sets
  88 .I prefix
  89 As the initial directory "base" to start from in selecting files for
  90 the package.
  91 .B "Optional."
  92 .TP
  93 .BI "\-k\ " script
  94 Sets
  95 .I script
  96 to be the de-install procedure for the package.  This can be any
  97 executable program (or shell script).  It will be invoked automatically
  98 when the package is later (if ever) de-installed.
  99 .B "Optional."
 100 .TP
 101 .BI "\-r\ " script
 102 Sets
 103 .I script
 104 to be the "requirements" procedure for the package.  This can be any
 105 executable program (or shell script).  It will be invoked automatically
 106 at installation/deinstallation time to determine whether or not
 107 installation/deinstallation should proceed.
 108 .B "Optional."
 109 .TP
 110 .BI "\-t\ " template
 111 Use
 112 .I template
 113 as the input to mktemp(3).  By default, this is the string
 114 .B /tmp/instmp.XXXXXX,
 115 but it may be necessary to override it in the situation where
 116 space in your
 117 .B /tmp
 118 directory is limited.  Be sure to leave some number of `X' characters
 119 for mktemp(3) to fill in with a unique ID.
 120 .B "Optional."
 121 .TP
 122 .BI "\-X\ " file
 123 Pass
 124 .I file
 125 as a
 126 .B \-exclude-from
 127 argument to
 128 .B tar
 129 when creating final package.  See
 130 .B tar
 131 man page (or run
 132 .B tar
 133 with
 134 .B --help
 135 flag) for further information on using this flag.
 136 .PP
 137 .SH "TECHNICAL DETAILS"
 138 The "packing list" format (see \fB-f\fR) is fairly simple, being
 139 nothing more than a single column of filenames to include in the
 140 package.  However, since absolute pathnames are generally a bad idea
 141 for a package that could be installed potentially anywhere, there is
 142 another method of specifying where things are supposed to go
 143 and, optionally, what ownership and mode information they should be
 144 installed with.  This is done by imbeding specialized command sequences
 145 in the packing list. Briefly described, these sequences are:
 146 .TP
 147 .BI "@cwd\ " directory
 148 Sets the internal directory pointer to point to
 149 .I directory.
 150 All subsequent filenames will be assumed relative to this directory.
 151 Note:
 152 .BI @cd
 153 is also an alias for this command.
 154 .TP
 155 .BI "@exec\ " command
 156 Execute
 157 .I command
 158 as part of the unpacking process.  If
 159 .I command
 160 contains a any of the following sequences somewhere in it, they will
 161 be expanded inline.  For the following examples, assume that
 162 .B @cwd
 163 is set to
 164 .B /usr/local
 165 and the last extracted file was
 166 .B bin/emacs.
 167 .TP
 168 .I "%F"
 169 Expands to the last filename extracted (as specified), in the example case
 170 .B bin/emacs
 171 .TP
 172 .I "%D"
 173 Expands to the current directory prefix, as set with
 174 .B @cwd,
 175 in the example case
 176 .B /usr/local.
 177 .TP
 178 .I "%B"
 179 Expands to the "basename" of the fully qualified filename, that
 180 is the current directory prefix, plus the last filespec, minus
 181 the trailing filename.  In the example case, that would be
 182 .B /usr/local/bin.
 183 .TP
 184 .I "%f"
 185 Expands to the "filename" part of the fully qualified name, or
 186 the converse of
 187 .B %B
 188 , being in the example case,
 189 .B emacs.
 190 .TP
 191 .BI "@unexec\ " command
 192 Execute
 193 .I command
 194 as part of the deinstallation process.  Expansion of special
 195 .B %
 196 sequences is the same as for
 197 .B @exec.
 198 This command is not executed during the package add, as
 199 .B @exec
 200 is, but rather when the package is deleted.  This is useful
 201 for creating links and other ancillary files that were created
 202 as a result of adding the package, but not directly known to
 203 the package's table of contents (and hence not automatically
 204 removable).  The advantage of using
 205 .B @unexec
 206 over a deinstallation script is that you can use the "special
 207 sequence expansion" to get at files regardless of where they've
 208 been potentially redirected (see
 209 .B -p)
 210 .TP
 211 .BI "@mode\ " mode
 212 Sets default permission for all subsequently extracted files to
 213 .I mode.
 214 Format is the same as that used by the
 215 .B chmod
 216 command (well, considering that it's later handed off to it, that's
 217 no surprise).  Use without an arg to set back to default (extraction)
 218 permissions.
 219 .TP
 220 .BI "@owner\ " user
 221 Sets default ownership for all subsequently extracted files to
 222 .I user.
 223 Use without an arg to set back to default (extraction)
 224 ownership.
 225 .TP
 226 .BI "@group\ " group
 227 Sets default group ownership for all subsequently extracted files to
 228 .I group.
 229 Use without an arg to set back to default (extraction)
 230 group ownership.
 231 .TP
 232 .BI "@comment\ " string
 233 Imbed a comment in the packing list.  Useful in
 234 trying to document some particularly hairy sequence that
 235 may trip someone up later.
 236 .TP
 237 .BI "@ignore\ " file
 238 Used internally to tell extraction to ignore the next file (don't
 239 copy it anywhere), as it's used for some special purpose.  Also useful
 240 if you want to pack some specialized datafiles in with a distribution
 241 for your install script (or something) and want to have the installer
 242 ignore it.
 243 .TP
 244 .BI "@name\ " name
 245 Sets the name of the package.  This is mandatory and is usually
 246 put at the top.  This name is potentially different than the name of
 247 the file it came in, and is used when keeping track of the package
 248 for later deinstallation.  Note that
 249 .B pkg_create
 250 will derive this field from the package name and add it automatically
 251 if none is given.
 252
 253 .SH BUGS
 254 Sure to be some.
 255 .SH "SEE ALSO"
 256 .BR pkg_add "(" 1 "),"
 257 .BR pkg_info "(" 1 "),"
 258 .BR pkg_delete "(" 1 "),"
 259 .SH AUTHORS
 260 Jordan Hubbard
 261