gendist(1M) gendist(1M) NAME gendist - generate a software distribution SYNOPSIS gendist [ -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, 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: 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. 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 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. 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 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 (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 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. 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 ALSO distcp(1M), inst(1M), install(1), showprods(1M), swpkg(1M), versions(1M). Software Packager User's Guide. Page 10