gendist(1M)gendist(1M)NAMEgendist - generate a software distribution
SYNOPSISgendist [ -rbase rbase ] [ -root rbase ] [ -sbase sbase ]
[ -source sbase ] [ -idb idbfile ] [ -spec specfile ]
[ -dist distdir ] [ -mr file ] [ -sa file ]
[ -creator name ] [ -verbose ] [ -maint ]
[ -nocompress ] [ -nostrip ] [ -genidb ]
[ -genspec ] [ -all ] [ -ignoreempty ] [ patterns ... ]
DESCRIPTION
Gendist generates the primary components for software products. These
are the product descriptor, the product idb, and the images. The
required input is a tree containing all of the files to be shipped, a
master idb containing a description of each file or directory to be
included in the product, and a distribution specification (spec) file
that describes the product structure.
Gendist reads the distribution specification file and generates products
as defined in that file. For each product, the product descriptor file
is created with the name prod (for example), then the product idb is
generated with the name prod.idb, and then the images with the name
prod.image for each image defined in the distribution specification file.
Normally, all components of all products defined in the specfile are
generated. The optional patterns at the end of the command line are
shell-style patterns that identify particular files to be generated.
Note that these patterns are matched against the name to be created, not
against existing files on the disk. Such patterns should be protected
from the shell expansion mechanisms. For example, to generate all of the
components of the ftn product, use:
gendist ... "ftn*"
Files are created in the distdir, which is ``$rbase/usr/dist'' by
default.
Options:
-rbase rbase
-root rbase
Set the ``root base,'' which is the pathname of the top of the
destination tree. The default rbase is /root, overridden by
the environment variable rbase.
-sbase sbase
-source sbase
Set the ``source base,'' which is the pathname of the top of
the source (or build) tree. The default sbase is /usr/src,
Page 1
gendist(1M)gendist(1M)
overridden by the environment variable sbase.
-idb idbfile
Set the pathname of the idb. The default is $rbase/etc/idb,
overridden by the environment variable idb. The idbfile must
be sorted on the 5th and 6th fields.
-spec specfile
Set the pathname of the spec file. The default is
$rbase/etc/spec.
-dist distdir
Create the product components in distdir. The default is
$rbase/usr/dist, overridden by the environment variable dist.
-sa safile
Set the pathname of safile. The default is sa.
-mr mrfile
Set the pathname of the mrfile. The default is mr.
-creator name
Set the "created by" field in the product to name.
-verbose Work verbosely, with more output as the distribution is
created.
-nocompress
Do not compress the images being built.
-nostrip Do not strip any of the executables.
-maint Generate maintenance product.
-genidb Generate an idb from the rbase tree to $rbase/etc/idb.
-genspec Generate a simple spec file to $rbase/etc/spec.
-all Generate the product distribution as well as the spec file and
the idb file.
-ignoreempty
Do not add empty subsystems to the image and do not emit a
warning message.
There is a predefined sequence for building and installing software
releases, one part of which is to use gendist to generate the software
images. Before and after using gendist, there are other commands to use.
The simplified sequence of events is:
Page 2
gendist(1M)gendist(1M)
1. Build the software with ``make install'' and the environment variable
RAWIDB set.
2. Sort the idb file with ``sort +4u -6 <$RAWIDB >idb''.
3. Use gendist on idb file (created in step 2) and spec file; output
includes images.
4. Use distcp to copy images to other places.
5. Use inst to install the images.
DISTRIBUTION SPECIFICATION
The distribution spec file is a text description of the product, image
and subsystem hierarchy, in the following form:
include file
define variable value
product pp
attribute ...
image ii
attribute ...
subsystem ss
attribute ...
endsubsys
endimage
endproduct
Products may contain multiple images. Images may contain multiple
subsystems. Attributes apply to the nearest enclosing product, image or
subsystem (see descriptions below). When specifying an attribute's
value(s), use double-quotes to protect whitespace, and single-quotes to
prevent expansion of ${variables}.
In the attribute descriptions that follow, a subsystem-range is a three-
part product.image.subsystem identifier, followed by a low version number
and a high version number, all separated by whitespace. Except within a
replaces statement (see below) the keyword maxint may be used to indicate
the highest possible version number. For example:
x.y.z 1000 2000
x.y.z 1 maxint
x.books.eoe 2000 2000
The following attributes may be used.
id "id-string"
A one-line description or title of the enclosing product, image, or
subsystem.
version version-number
A version number should be specified at the image level. All
subsystems in that image inherit this version number. Version
numbers normally increase with each new release of the product, so
that inst can properly identify upgrade subsystems.
Page 3
gendist(1M)gendist(1M)
exp expression
This attribute is placed at the subsystem level, and specifies which
files belong to that subsystem. All files in the idb having one or
more group-tags that match expression are included in that subsystem
when the distribution is created.
The group-tags in the idb are identifiers that categorize the files
is some convenient way (MAN or DSO for example). The expression is
a boolean function written using these tags, and the C logical
operators ||, &&, ! and (). For example:
exp MAN
exp EOE
exp "!noship && (EOE || BITMAPS || DSO)"
order order-number
This attribute is placed at image level to control the order of
installations. Images with lower order numbers are installed before
images with higher order numbers.
default
default (expression)
The subsystem is marked for default installation by inst. If a
parenthesized expression is given, the subsystem is default only on
hardware platforms matching that expression. See HARDWARE
EXPRESSIONS.
required
required (expression)
The subsystem is required for installation by inst. Removal of the
subsystem is disallowed (upgrade is permitted). Only subsystems
containing critical operating system functions should be marked as
required. If a parenthesized expression is given, the subsystem is
default only on hardware platforms matching that expression. See
HARDWARE EXPRESSIONS.
miniroot
miniroot (expression)
A miniroot installation is recommended (not required) or a reboot is
required to complete the installation. If a parenthesized
expression is given, the subsystem is miniroot only on hardware
platforms matching that expression. See HARDWARE EXPRESSIONS.
autominiroot (subsystem-range)
A miniroot installation is required if any subsystem in the
specified subsystem-range is currently installed. This keyword
should be used whenever a "live" installation (in multi-user mode)
causes failures in or harmfully affects other user processes that
may be executing during the inst session.
mach "expression"
Specify that the enclosing product, image or subsystem is suitable
for installation only on certain hardware platforms matching the
Page 4
gendist(1M)gendist(1M)
expression. Multiple mach expressions for a single product, image
or subsystem are OR'd. See HARDWARE EXPRESSIONS.
prereq (subsystem-range ...)
Installation of the subsystem also requires installation of the
prerequisite subsystems specified in the ranges. If a subsystem has
multiple prereq rules, inst permits its installation if any one of
those rules is satisfied. In the following example, subsystem s can
be installed if either: both p.q.r (any version between 100-200,
inclusive) and x.y.z (any version greater than 400) are also
installed; or, a.b.c version 1000 is also installed:
subsystem s
prereq ( p.q.r 100 200
x.y.z 400 maxint)
prereq ( a.b.c 1000 1000 )
endsubsys
replaces subsystem-range
obsoletes subsys
Installation of the subsystem automatically causes the removal of
subsystems specified by the range. A subsystem may have multiple
replaces rules. It is not necessary to supply a replacement rule
for other versions of subsystems by the same name (this is enforced
automatically be inst).
Wildcards (*) are permitted in the subsystem identifier in
subsystem-range. If the maxint keyword is used as the high version
number, it will automatically be converted to one less than the
version number of the containing subsystem. The shorthand obsoletes
x.y.z is interpreted as replaces x.y.z 0 maxint. The following
rules are equivalent:
image i
version N
subsystem s
replaces x.y.z 0 N-1
replaces x.y.z 0 maxint
obsoletes x.y.z
endsubsys
endimage
During installation, a subsystem is labeled upgrade (downgrade) if
it replaces any other currently installed subsystem with a lesser
(greater) version number, even if the two subsystems have different
names.
Whenever a subsystem is upgraded or downgraded, its patches are also
removed. For this reason, a subsystem X need not declare
replacement rules for patches that follow subsystems replaced by X.
Page 5
gendist(1M)gendist(1M)
incompat subsystem-range
The subsystem is incompatible with the subsystem specified in the
subsystem-range. This rule should be used when two subsystems
cannot coexist on the same system. A conflict will result if the
user attempts any installation that will result in both subsystems
being installed on the system.
updates subsystem-range
The subsystem automatically satisfies all prerequisite rules for any
subsystem X which has a prereq rule for subsystems specified in the
subsystem-range. This is useful for honoring the prerequisite rules
of previously released (hence unchangeable) products, when the
subsystem name is changed in the newer version. The updates rule
does not imply replaces.
patch
Declare the subsystem to be a patch that replaces files in another
subsystem. A patch can also introduce new files. When a patch is
installed, any previously installed versions of its files are
achived under $rbase/var/inst/patchbase. When a patch is removed,
the original files are restored. A patch subsystem must have a
follows rule. A patch may replace other patches, but may not
replace other non-patch subsystems.
follows subsystem-range
Specify that a patch subsystem can only be installed if the base
subsystem (specified by subsystem-range) is also installed. A patch
may have multiple follows rules, provided that they all reference
the same base subsystem. This allows disjoint version ranges to be
specified. A follows rule can only be used within a patch
subsystem.
cutpoint directory
This attribute may only be used at the outermost product level (not
at the image or subsystem level). It declares directory to be a
cutpoint that is owned by the enclosing product, and that it is safe
for inst to move the entire directory to an alternate drive when
disk space on the system drive is limited.
When choosing cutpoints, identify the highest-level directories that
contain only files or sub-directories owned by your product.
Directories that consume large amounts of disk space are good
candidates. Multiple cutpoints are permitted. For example
product gizmo
cutpoint /usr/Gizmo
...
endproduct
could be used if all files under /usr/Gizmo are owned by the gizmo
product. The inst command
Page 6
gendist(1M)gendist(1M)
Inst> admin relocate gizmo /disk3
will move the contents of /usr/Gizmo to /disk3/usr/Gizmo, and then
replace /usr/Gizmo with a symbolic link to ../disk3/usr/Gizmo.
It is desirable, but not required, for a product to install all of
its files underneath cutpoints. This property simplifies the task
of sharing software in a network environment using NFS mounts. For
example if gizmo installs
/usr/lib/X11/app-defaults/Gizmo
then that file will not be moved when /usr/Gizmo is relocated.
Before declaring a cutpoint directory, it is advisable to check for
self-containment. Problems may arise with relative symbolic links
which follow a path up through the cutpoint itself, as in:
/usr/Gizmo/bin/ls -> ../../../bin/ls
If the directory /usr/Gizmo is moved to a new location at a
different depth, such as /disk3/usr/Gizmo, then the path
/usr/Gizmo/bin/ls might no longer be valid.
IDB FILE
The idb contains one line for each file or directory in an entire
product. The following optional attributes can be specified.
config([update|suggest|noupdate])
Inst gives special treatment to configuration files if a version
already exists on disk and and either: the file has been altered
since it was last installed (modified); or the file is not present
in the installation history (foreign).
During removals, inst does not remove modified config files. During
installations, config files are installed normally, except when a
modified or foreign version already exists on disk. In that case
the following variations occur:
config(update) before the file is installed, the modified/foreign
version is saved as file.O.
config(suggest) the file is installed under the name file.N. The
modified/foreign version remains unchanged.
config(noupdate) no new version of the file is installed. The
modified/foreign version remains unchanged.
nohist
After the file is installed, no record of it is kept in the
installation history. Useful for scripts which delete themselves
Page 7
gendist(1M)gendist(1M)
(for example during a postop), so that showfiles -B does not report
them as missing.
delhist
The file is completely ignored by inst. Provided only for backwards
compatibility.
dev(maj min)
Specify the major and minor device numbers. This attribute is
required if the file is a block or character special device.
symval(value)
Specifies the link value. Required when the file is a symbolic
link.
mach(expr)
Install the file only on hardware platforms matching expr (see
HARDWARE EXPRESSIONS below).
exitop(cmd)
If the file is installed, execute cmd in a bourne shell, at the end
of the installation. Inst sets the following variables in the
environment for exitops, preops, postops and removeops:
rbase is set to the root installation directory (see the -r option
of inst). Exitops typically conduct all their activity relative to
$rbase.
dist is set to the location of the software distribution.
instmode is set to normal for miniroot installs into /root and live
installs into /, or client for diskless client-tree installations
using client_inst(1M), or prototype during all other installations.
diskless is set to client during diskless installations using
client_inst(1M), or share during diskless installations using
share_inst(1M), or none for other, non-diskless installations.
mr is set to true during miniroot installations, set to false
otherwise.
preop(cmd)
Like an exitop, except that Execute cmd just before the file is
installed.
postop(cmd)
Execute cmd just after the file is installed.
removeop(cmd)
Execute cmd if its subsystem is removed. Removeops are executed at
the end of an install/remove run, along with any exitops. Removeops
are only executed after strict subsystem removals, and not during an
Page 8
gendist(1M)gendist(1M)
upgrade. During an upgrade, any cleanup tasks should be performed
in the exitop of the upgrade product.
shadow
Causes the file to be installed as file.shd during "live"
installations when rbase is /. When the system is shutdown,
file.shd is renamed to file and only then are its exitops, preops
and postops executed. During other installations (for example in
the miniroot) no special actions are taken.
nostrip
Do not invoke strip(1M) on the file, so that its symbol table is
preserved.
stripdso
Invoke strip(1M) on the file using the -f (force) option. Useful
for dynamic shared objects. See the strip(1M) manual page.
norqs
Suppress requickstarting for the file after it is installed.
tag(value)
At build time, invoke tag(1) with an argument of value on the file.
value may be a decimal or hex number. The tag idb keyword is not
copied to the final idb file since it is of no use at install time.
HARDWARE EXPRESSIONS
Hardware expressions, or machtags, are boolean expressions evaluated at
installation time against the current architecture and IRIX version
number of the system on which the installation occurs, or against the
machtag values given on the command line when inst -m is used.
Hardware expressions are used in the spec file to restrict installation
of a subsystem, image or entire product, to specific hardware platforms
or IRIX releases, and to mark subsystems as default, miniroot, or
required only for specific platforms.
Hardware expressions in the idb file make it possible to install
different versions of the same file (including no version at all),
depending on the target platform. Each version of the file appears on
its own idb line. At most one version of a file can be installed in a
single subsystem.
When multiple versions of a file are specified, inst installs the one
whose machtag matches the target platform. If no matching machtag is
found, inst installs the version that has no machtag (if specified).
There are two distinct syntaxes for hardware expressions. The two
syntaxes may not be intermixed. In both forms the construct attr=value
may not be reversed, for example IP22=CPUBOARD does not work. If the
leading attr= is omitted, attr is assumed to be CPUBOARD.
Page 9
gendist(1M)gendist(1M)
The valid attributes are CPUBOARD, CPUARCH, GFXBOARD, SUBGR, VIDEO, MODE,
TARGOS and DISTOS. During an inst session the variable TARGOS refers to
the currently installed IRIX release, as displayed by the command
"showprods -n eoe*.sw.unix". DISTOS is the version of eoe*.sw.unix on
the current software distribution. These variables will have the value
-1 if eoe*sw.unix is not present.
First form
The first form is a whitespace-separated list of attribute/value
expressions written as: attr=value attr=value ...
An expression evalues to true if there is at least one match for
every unique attribute referenced in the expression. For example
"CPUBOARD=IP22 GFXBOARD=EXPRESS GFXBOARD=NEWPRESS" evalutes to true
if the cpu is IP22 and the graphics board is either EXPRESS or
NEWPRESS.
Second form
The second form is a C-like syntax in which attr=value pairs can be
combined with the logical operators &&, ||, and !. The relational
operators <, <=, !=, >, > may be used instead of =. Grouping with
parentheses is permitted. Note: whitespace does not imply logical
AND as it does in the first form. If any of the operators except =
are used, then the entire expression must be written in the second
form. The first-form example above could be rewritten as
"CPUBOARD=IP22 && GFXBOARD=EXPRESS || GFXBOARD=NEWPRESS".
SEE ALSOdistcp(1M), inst(1M), install(1), showprods(1M), swpkg(1M), versions(1M).
Software Packager User's Guide.
Page 10
