Here's an example of how you might create a product hierarchy for a simple application. Suppose you want to package a paint application called magritte. Let's say that the magritte application includes the basic application software, some clip art, a reference page, and some release notes. Here's a good way to structure your files for installation:

In this example, our product hierarchy would be one product (magritte) containing two images (sw and man), with each image containing two subsystems (base and optional, and manpages and relnotes, respectively). Figure 3-1 illustrates the structure of this example product hierarchy.

Figure 3-1. Example Product Hierarchy

Image and subsystem names must reflect the product hierarchy by following these naming conventions:

Figure 3-2 shows the correct product, image, and subsystem names, for the example introduced in “About Product Hierarchies”.

Figure 3-2. Example Product Hierarchy Names

This section lists the Silicon Graphics conventions for structuring your product hierarchy.

Silicon Graphics conventions strongly recommend that:

You are not required to follow these conventions, but Silicon Graphics strongly recommends that you do.

The Product Hierarchy graph provides a graphical display of your product hierarchy, in which products, images, and subsystems are shown as rectangles (or nodes) and relationships as connecting lines (or arcs). (If the graph is larger than the viewing area, scroll bars are enabled.)

When you select a node, the Specification sheet associated with that node appears to the right of the Product Hierarchy Graph. (The Specification sheets are groups of text fields and/or check buttons that you can use to provide the relevant installation information about each product, image, and subsystem in your installation plan.)

To select a node, click it with the left mouse button. The Specification sheet for that node appears to the right of the Product Hierarchy Graph. The Create Product Hierarchy worksheet has three different types of Specification sheets: the Product Specification sheet (described in “Entering Product Specifications”), the Image Specification sheet (described in “Entering Image Specifications”), and the Subsystem Specification sheet (described in“Entering Subsystem Specifications”).

The spec file path label shows the current spec file pathname. If no valid spec file is identified, the path is left blank. For information on creating a spec file or changing the spec file path, see “Using the File Menu”. For a definition of a spec file, read “What's a Spec File?”.

Use the Add button (located at the top of the product hierarchy graph) to add products, images, and subsystems to your product hierarchy (spec file):

Use the Delete button to delete a product, image or subsystem by selecting the relevant node and clicking the Delete button.

The product hierarchy graph has a control area containing a row of graph controls, shown in Figure 3-5.

Figure 3-5. Graph Display Controls

These graphical view controls are:

Zoom menu		Shows the current scale of the graph. If clicked, a popup menu appears displaying other available scales. The scaling range is between 15% and 300% of the normal (100%) size.
Zoom Out button		Resets the scale of the graph to the next available smaller size in the range.
Zoom In button		Resets the scale of the graph to the next available larger size in the range. Note: If you drag a node into a new position and then use one of the Zoom buttons, the node returns to its initial position.
Overview button		Displays the Overview window, which lets you view the entire graph at a reduced scale. The Overview window has a movable viewport that lets you select the portion of the graph displayed in the main window. The Overview window also has an Admin menu with these three selections: “Scale to Fit” scales the graph to match the aspect ratio of the overview window. “Show Arcs” displays or hides the arcs between the nodes. “Close” closes the Overview window.
Multiple Arcs button		Toggles between single and multiple arc mode. (This button is not useful in the Product Hierarchy Graph.)
Realign button		Redraws the graph, restoring the positions of any nodes that were repositioned.
Rotate button		Flips the orientation of the graph between horizontal (calling nodes at the left) and vertical (calling nodes at the top). Note: If you reposition the nodes by dragging and then change orientation, the nodes will return to their initial positioning relative to each other.

To name the product, follow these steps:

The product name is the short name for the product—this is the “short” name that appears in Software Manager listings (the “long” name is the product description). Because the display length for both long and short names in Software Manager is typically 30 characters, the product name should be short so that subsystem names are less likely to overflow their column in versions and Software Manager listings. Short product names are also easier for users to enter. Do not choose a product name that begins with a digit.

To change the product description, follow these steps:

The product description is a brief description of your product that begins with the product name. This description is the “long” name that appears in Software Manager listings (the description also appears in versions listings). The description should be brief but informative, since this might be the only information users have to help them to decide whether to install your software.

In particular, the product description should begin with the marketing name of the product. Do not use the words “option,” “version,” “system,” or “release,” unless they are part of the name of the product (for example, Maintenance Release and Network File System).

Here are some general guidelines for creating descriptions:

So, for example, assume your product is a mortgage calculation application called Mortgage Calculator, that this is the first version of the product, and that its marketing code is M3-486. A good product description would be: “Mortgage Calculator 1.0”—a bad one would be: “Mort.Cal.M3-486.”

To change the name of an image, follow these steps:

Refer to “Naming Images and Subsystems” for guidelines.

To change the description of an image, follow these steps:

---

Note: Always enclose your description within quotes. You can use either single or double quotes. You can use one type of quotes as part of your description if you use the other type of quotes to quote the description. For example, `Acme 1/2” Tape Support' is a valid description as long as you enclose it in single quotes.

---

If the image in question is the sw or man image, you can just leave the description as it is in the corresponding (sw or man) template.

The image description is a brief description of the image. Since this description appears in Software Manager listings, it's important that the description be informative and distinct from the product and subsystem descriptions.

Like the product description, the image description should begin with the marketing name of the product. This is because Software Manager lists the products, images, and subsystem according to these descriptions—if your product, image, and subsystem names begin differently, they aren't listed together.

Image descriptions should include the product name and a description of the image (for example, Software, Documentation, or Manual Pages). Do not include a version or release number.

Here are some general guidelines for creating descriptions:

Choose a version number for your images. You can keep the existing, default value for the version number or you can create a version number of your own. Some rules and suggestions for selecting version numbers are:

Type the version number directly into the text field labeled “Version,” then click the Assign arrow button.

The number in the text field labeled Installation Order tells Software Manager the order in which to install the various images. If you want to specify that some of your images be installed before others, select the installation order numbers accordingly. (Remember to click the Assign arrow button after typing in each order number.)

Installation order is specified by numbers in the range of 0 to 9999. The lower the order number, the earlier that image will be installed. If you do not specify an order number, the default is 9999 (the highest order, meaning the last to be installed). Images with equal order numbers are installed in alphabetical order.

Software Manager installs products in alphabetical order by default. Within each product, images are also installed in alphabetical order. Similarly, the subsystems in each image are installed in alphabetical order. For example, suppose there are two products, a and b. Each of them contains two images, sw and man. Each image has two subsystems, x and y. The installation order of these subsystems is:

a.man.x
a.man.y
a.sw.x
a.sw.y
b.man.x
b.man.y
b.sw.x
b.sw.y

You can control the order in which images are installed. In the example above, for instance, when you package the b product you can specify that the subsystems in the b.sw image should be installed before the subsystems in the a.sw image.

In the example above, to force b.sw to be installed before a.sw, give the b.sw image an order number less than 9999. The installation order of the subsystems would then be:

b.sw.x
b.sw.y
a.man.x
a.man.y
a.sw.x
a.sw.y
b.man.x
b.man.y

To change the name of the selected subsystem, follow these steps:

Refer to “Naming Images and Subsystems” for guidelines.

To change the description of the selected subsystem, follow these steps:

---

Note: Always enclose your description within quotes. You can use either single or double quotes. You can use one type of quotes as part of your description if you use the other type of quotes to quote the description. For example, `Acme 1/2” Tape Support' is a valid description as long as you enclose it in single quotes.

---

The subsystem description is a brief description of the image. Since this description appears in Software Manager listings, it's important that the description be informative and distinct from the product and image descriptions.

Like the product and image descriptions, the subsystem description must begin with the marketing name of the product. This is because Software Manager lists the products, images, and subsystem according to these descriptions—if your product, image, and subsystem names begin differently, they aren't listed together. (The image description also appears in versions listings.)

Here are some general guidelines for creating descriptions:

The Installation Options check buttons that appear in the Subsystem Specification sheet represent three installation options. The first two options—Default and reboot—are user selected. The third option—Patch—is selected automatically when you create a patch through the “Create Patch...” menu item in the File menu. You can select none, one, or all of these options.

The Default option specifies that each time a product is installed, some or all of the subsystems are automatically selected for installation (these subsystems are called “default” subsystems). Users can deselect these subsystems if they choose. If you have a lot of subsystems, some of which are not necessary for the average user, you might want to tag the essential subsystems as default.

To set this option, click the left mouse button with the cursor over the option. After making your selection, click the Assign button to assign the option(s) to the selected subsystem.

The Reboot option specifies that the machine must be rebooted after installation of the subsystem. This option is only for subsystems that involve kernel code or other software that cannot be installed normally. Use the Reboot button only when absolutely necessary!

To set this option, click the left mouse button with the cursor over the option. After making your selection, click the Assign button to assign the option(s) to the selected subsystem.

---

Note: When using Software Manager to install your product, this option is shown as a flag type of `b'.

---

The Patch option specifies that a subsystem is part of a patch product and must have a follows rule. swpkg automatically assigns the Patch option to all subsystems that are part of a patch product. This option is insensitive to user selection. See Chapter 8, “Creating a Patch Product.”

The Rules text field allows you to specify, for each subsystem in your product, those subsystems that:

In order to make these specifications, you need to use the special syntax required for writing these rules. The syntax is described in the sections below and examples are provided.

To use the Rules text field, follow these steps:

Adding Replacement Statements

You can tell Software Manager to remove a specified subsystem when it installs the currently selected subsystem. Essentially, this means telling Software Manager to replace one subsystem with another, usually newer, subsystem. You do this using the replaces statement.

Replaces statements are powerful and flexible—taking the time now to learn how they work will help you later when you need to make changes to your product. The replaces line is critical when a product is repackaged (for example, when files in the product get moved around, when subsystems get new names, and so on).

A replaces line simply specifies that you want to replace an older subsystem with a newer subsystem. Specify the name of the subsystem and the range of version numbers you want replaced. Here's the format of the replaces statement:

replaces name lowvers highvers 

or

replaces self

where

You can specify as many replaces statements as you need.

For each subsystem that has a replaces line, Software Manager looks to see if the subsystem specified in the replaces line is installed and if its version falls in the range given in the replaces line. If the installed version is in the range, the new subsystem is selected for installation automatically. If the new subsystem is installed, the old version is removed automatically.

There are four typical ways to use replaces:

Here are some examples of replaces statements:

A subsystem gets a name change. Suppose that the subsystem rfind.man.rfind is split into two subsystems, rfind.man.client and rfind.man.server. To make sure that rfind.man.rfind is replaced properly, you could create a replaces statement that looks like this:

replaces rfind.man.rfind 0 oldvers 

Alternately, you could specify an exact old version number so that your replaces statement would look something like this:

replaces rfind.man.rfind 0 1006000106 

Or, suppose two or more subsystems get repackaged into a single subsystem. For example, say the rfind.sw.client subsystem and the rfind.sw.server subsystem are combined and the new subsystem is called rfind.sw.rfind. To replace the old client and server, you would use these replaces statements:

replaces rfind.sw.client 0 oldvers 
replaces rfind.sw.server 0 oldvers 

If either of the old subsystems rfind.sw.client or rfind.sw.server is installed, rfind.sw.rfind will replace them.

Finally, suppose you want to replace a maintenance release of rfind.sw.client with a new base release. You need to replace both the maintenance release and the previous base release. Your replacement statements would look like this:

replaces maint.rfind_sw.client 0 oldvers 
replaces rfind.sw.client 0 oldvers 

Setting Incompatibilities

You can specify that a subsystem in your product can be installed on a user's workstation only if one or more other subsystems are not installed. This is known as specifying incompatibilities.

---

Note: Do not specify incompatibilities unless absolutely necessary.

---

When incompatibilities are specified, Software Manager does not allow users to install subsystems that are incompatible. It checks for incompatibilities at two different times:

The format for incompatibility statements is the same as for replaces statements. Specify the name of the subsystem and the range of version numbers you want to declare incompatible. The format of the incompatibilities statement is:

incompat name lowvers highvers 

where

Here are some examples of incompatibility statements:

To specify that the rfind.man.rfind subsystem is incompatible with the selected subsystem, you could create a incompatibility statement that looks like this:

incompat rfind.man.rfind 0 oldvers 

Alternately, you could specify an exact old version number so that your incompatibility statement would look something like this:

incompat rfind.man.rfind 0 1006000106 

Setting Prerequisites

You can specify that a subsystem in your product can be installed on a user's workstation only if one or more other subsystems are also installed. That is, you can set prerequisites for the installation of a subsystem.

Do not specify subsystems outside your product as prerequisites unless absolutely necessary. Prerequisites can be a real problem, because the prerequisite product can change names or versions, making your prerequisite statement obsolete—which can prevent installation of your product!

To set prerequisites for a subsystem, first select the appropriate subsystem node in the Product Hierarchy Graph. Then type the text specifying the prerequisites into the Rules text field.

You can specify a list of subsystems that must all be installed in order for users to install the new subsystem:

prereq (
        name lowvers highvers 
        name lowvers highvers 
        name lowvers highvers 
        )

where

You can also write a prereq that specifies that only one of the listed subsystems must be installed for the new subsystem:

prereq (
        name lowvers highvers 
       )
prereq (
        name lowvers highvers 
       )

Remember to press the Assign arrow button to update the subsystem node after filling in the text area.

Here are some examples of prerequisite statements:

To specify that the rfind.man.rfind subsystem is a prerequisite for the selected subsystem, you could create a prerequisite statement that looks like this:

prereq rfind.man.rfind 0 oldvers 	

Alternately, you could specify an exact old version number so that your prerequisite statement would look something like this:

prereq rfind.man.rfind 0 1006000106

To specify that the rfind.man.server subsystem and the rfind.man.client subsystem must both be installed in order for the selected subsystem to be installed, you could write a prerequisite statement that looks like this:

prereq (
         rfind.sw.server 0 oldvers
         rfind.sw.client 0 oldvers
        )

To specify that either the rfind.man.server subsystem or the rfind.man.client subsystem must be installed in order for the selected subsystem to be installed, you would need to write two prerequisite statements. They might look like this:

prereq (
         rfind.sw.server 0 oldvers
        )
prereq (
         rfind.sw.client 0 oldvers
        )