This chapter explains how to build your product. It contains these sections:
“Building the Product: Before You Begin” provides some background information and lists the prerequisites for building your product.
“Building the Product: The Basic Steps” lists the basic steps for building your product.
“Using the Build Product Worksheet” describes the features of the worksheet and explains how to use it to build your product.
“After the First Build” describes how to change a product that you've built, how to merge two or more existing products into a single product, and how to divide an existing product into two or more separate products.
This section lists the prerequisites for building a product and explains how swpkg builds a product.
Before you build your product, you must first create a product hierarchy using the Create Product Hierarchy worksheet (see Chapter 3), tag the files using the Tag Files worksheet (see Chapter 4), and edit permissions and destinations for the files using the Edit Permissions & Destinations worksheet (see Chapter 5). Also, you must specify installation attributes, if any, for each file in your product (see Chapter 6).
In particular, make sure that all your product's files are listed in the IDB Viewer. If some are missing, go back to the Tag Files worksheet to tag them and include them in the IDB file (see “Tagging the Files: The Basic Steps” for instructions).
 | Note: You only need to complete the above steps once for each product (unless you need to change the product hierarchy). After that, you can use the Build Product worksheet to build the product as often as necessary. |
swpkg builds a product using the gendist command, which generates the primary components for software products: the product descriptor, the product IDB, and the images.
To build a product, gendist needs three things:
a tree containing all the files to be shipped
a master IDB file containing a description of each file or directory to be included in the product
a distribution specification (spec) file that describes the product structure
swpkg takes your selections and input for each worksheet and uses them to create the required spec and IDB files for gendist. You can generate and/or edit these files by hand, if you like.
For more information on the gendist command, see the gendist(1M) reference page.
To build a product, follow these steps:
Select one or more items from the IDB file list.
Specify the desired build options for the selected item(s) by clicking the appropriate Build Options check buttons. (See “Selecting Build Options” for descriptions of the build options.)
Save the spec and IDB files using the “Save” menu item from the File pull-down menu.
Try a test of the build by clicking the Test Build button.
Resolve any error messages that appear in the Message Area during the test. Appendix B, “Troubleshooting,” provides some troubleshooting information.
Build the product by clicking the Build All button.
This section describes the features of the Build Product worksheet, shown in Figure 7-1, and explains how to use the worksheet to build a product.
The Build Product worksheet contains these major parts:
Worksheet Selection Tabs (described in “Using the Worksheet Selection Tabs”)
Message Area (described in “Using the Message Area”)
The IDB File Viewer (described in “Accessing Your IDB File Using the IDB File Viewer”)
The Spec File Path Label (described in “The Spec File Path Label”)
The Source, Destination, and Distribution text fields (described in “Setting Tree Root and the Distribution Directory”)
The Build Options check buttons (described in “Selecting Build Options”)
The Test Build button (described in “Running a Test Build”)
The Build All button (described in “Building the Product”)
The spec file path label shows the current spec file pathname. Until a valid spec file is identified, no path is listed. 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?”.
If you haven't already specified a source root in the Edit Permissions & Destinations worksheet, you can do so using the Source Tree Root text field. It is not necessary to specify this tree root. You do, however, need to specify the distribution directory for your product. This section explains how to set the tree root and the distribution directory.
Typically, you'll have already specified the source tree root in the Edit Permissions & Destinations worksheet. You can also set the source tree root here. Before changing the source tree root, you should read “Setting Source Tree Roots”, which tells you what the source tree root is and warns you of the risks involved.
To set a source tree root, type the source tree root path in the Source Tree Root text field and press <Enter>.
If the source tree root you specify is invalid, then you will see one of the following dialogs when you build the product:
No files found under Source Root /newroot.
10 (of 20 entries) not found under Source Root /root.
| Note: Instead of the numbers 10 and 20, you see numbers appropriate for your product. The number of files found varies—swpkg might think it has found some files but they are probably the wrong ones. |
The distribution directory is the directory in which swpkg puts the built, installable product files. The default distribution directory is /usr/dist.
To set a distribution directory for all the files in your product, first select all the files in your product by clicking the All button in the IDB File Viewer). Then type your desired distribution directory path in the Distribution Directory text field and press <Enter>.
The Build Options check buttons allow you to select any or all of these four build options for each of your product's files:
Verbose
Maint
No Compress
No Strip
To select an option, just click the left mouse button on the appropriate option check button. The option is selected when a red check mark appears on the button.
Check the Verbose button when you want swpkg to work in verbose mode—providing more output as the distribution is created. This output appears in the Message Area.
Checking the Maint button tells swpkg to generate a maintenance product. Silicon Graphics recommends that you do not use this option at this time. It is included in swpkg for compatibility with the previous tools, but it might be replaced in future releases. In general, rather than creating a maintenance product, it's better to create a new version of your product.
A maintenance product contains only files that include bug fixes, new features, or support for new hardware. When users install a maintenance release, the files in the maintenance release overwrite existing versions of those files. If a previously installed file does not have a replacement file in the maintenance release, it is not removed.
A maintenance release can include files from many products, but is packaged as one or sometimes two products. Product names for maintenance releases are usually of the form “maint” followed by a digit (this digit has no inherent meaning). Image names are created by taking the original product names and image names and joining them with an underscore (_) rather than a period. Subsystem names remain the same. For example, the maintenance version of the subsystem eoe1.sw.unix is named maint1.eoe1_sw.unix.
Check the No compress button to tell swpkg not to compress the images being built.
The Test Build button initiates a dry run, which reads the files and checks their validity without writing anything. Error messages, if any, appear in the Message Area.Appendix B, “Troubleshooting” provides some troubleshooting information.
After you've built your product the first time, subsequent builds for that product are much easier, since you already have a spec and IDB file. This section discusses subsequent swpkg builds. It contains these sections:
“Building the Product After the First swpkg Build” explains how to build a product that's been built (using swpkg) before.
“Combining Existing Products Into a Single Product” explains how to take two existing products that have both been built using swpkg and merge them into a single product.
“Incorporating the Help Subsystem into a Product” describes how to merge an online help subsystem with your product.
“Breaking an Existing Product Into Two Products” explains how to break apart an existing product (that's been built with swpkg) into two or more products.
| Note: If you have existing spec and IDB files that were not generated with swpkg, you can use them with swpkg. However, you'll have to remove any includes or defines from the IDB file, because swpkg doesn't handle them. |
 | Warning: Do not copy files from the source directory into the distribution directory: you will be overwriting important files. Your spec and idb files are saved in the source directory. When your product is built, gendist saves files of the same name in the distribution directory. Though these files are identically named, they are not the same. |
This section explains what to do under these circumstances:
You've already built your product at least once using swpkg and you don't want to make any changes to the spec and IDB files (for example, changing filenames, adding new files, or changing the product hierarchy).
You've used swpkg to build your product once, but you want to make some changes to the spec and IDB files.
The first case is the easiest. After making changes to the files that comprise your product (fixing bugs, adding features, and so on), you want to build the product again. Since you haven't changed any of the filenames and you don't want to alter the product hierarchy, you can go straight to the Build Product Worksheet. Follow these steps:
Start swpkg and open the Build Product worksheet.
From the File menu, open the “Open” cascade menu and select “Both.” The Open Spec window appears.
Use the file browser and text field to select the spec file for your product and click the OK button. The Open Idb window appears.
Use the file browser and text field to select the IDB file for your product and click the OK button.
If, in the previous build of your product, you specified a source tree root, enter the root in the corresponding text field now. Source roots are discussed in “Setting Source Tree Roots”. (swpkg does not save the source tree root in the spec and IDB files, so you have to re-enter this information each time you build the product.)
Select the desired build options. The build options are described in “Selecting Build Options”. (swpkg does not save build option selections in the spec and IDB files, so you have to re-enter this information each time you build the product.)
Try a test of the build by clicking the Test Build button.
Resolve any error messages that appear in the Message Area during the test. Appendix B, “Troubleshooting,” provides some troubleshooting information.
Build the product by clicking the Build All button.
If you do need to change the spec and/or IDB file, then you'll have to make those changes before you build the product again. The exact steps depend on the changes you want to make, but in general:
Start swpkg.
From the File menu, open the “Open” cascade menu and select “Both.” The Open Spec window appears.
Use the file browser and text field to select the spec file for your product and click the OK button. The Open Idb window appears.
Use the file browser and text field to select the IDB file for your product and click the OK button.
Use whatever worksheets you need in order to make the desired changes. For example, if you just want to change installation attributes for a particular file or files, then open the Add Attributes worksheet, make your changes, and build the product.
If you also need to add a new file, then you'll need to open the Tag Files worksheet to tag the file and the Edit Permissions and Destinations worksheet to set the permissions and destinations for the new file.
If you need to set installation attributes for the new file, you'll need to use the Add Attributes worksheet as well.
Open the Build Product worksheet.
If, in the previous build of your product, you specified a source tree root, enter that root in the corresponding text field now. Source tree roots are discussed in “Setting Source Tree Roots”. (swpkg does not save the source tree root in the spec and IDB files, so you have to re-enter this information each time you build the product.)
Select the desired build options. The build options are described in “Selecting Build Options”. (swpkg does not save build option selections in the spec and IDB files, so you have to re-enter this information each time you build the product.)
Try a test of the build by clicking the Test Build button.
Resolve any error messages that appear in the Message Area during the test. Appendix B, “Troubleshooting,” provides some troubleshooting information.
Build the product by clicking the Build All button.
This section explains how to merge two existing products (that were both originally built with swpkg) into a single product. You can merge more than two products, if you like, by appending more than one spec and IDB file to the spec and IDB files for the first product (see Step 2). To merge two existing products into a single product, follow these steps:
Start swpkg.
From the File menu, open the “Open” cascade menu and select “Both.” The Open Spec window appears.
Use the file browser and text field to select the spec file for the first product and click the OK button. The Open Idb window appears.
Use the file browser and text field to select the IDB file for the first product and click the OK button.
From the File menu, open the “Append” cascade menu and select “Spec.” The Open Spec window appears. Use the file browser and text field to select the spec file for the second product and click the OK button.
From the File menu, open the “Append” cascade menu and select “Idb.” The Open Idb window appears. Use the file browser and text field to select the IDB file for the second product and click the OK button.
Now you have a single spec file and a single IDB file. Each file contains everything that was in each of the corresponding files for the two original products. Use the Create Product Hierarchy to set up a product hierarchy for the new product, choose a new product name, and so on.
Use the Tag Files worksheet to make sure each filename is tagged correctly.
If the two original products used different source tree roots, open the Edit Permissions and Destinations worksheet and correct the pathnames so that they agree with whatever source tree root you're going to use for the new product. Set the source tree root for the product, if you don't plan to use the default values (/).
If you want to change permissions, destinations, or installation attributes for a particular file, open the appropriate worksheet and make your changes.
Open the Build Product worksheet. If the two original products used the same source tree root, enter that root in the corresponding text field now (if you didn't already do this in Step 9). Source tree roots are discussed in “Setting Source Tree Roots”. (swpkg does not save the source tree root in the spec and IDB files, so you have to re-enter this information each time you build the product.)
Select the desired build options. The build options are described in “Selecting Build Options”. (swpkg does not save build option selections in the spec and IDB files, so you have to re-enter this information each time you build the product.)
Try a test of the build by clicking the Test Build button. When you're asked where to save the Spec and IDB files, choose new filenames so that you don't overwrite the spec and IDB files for the original products.
Resolve any error messages that appear in the Message Area during the test. Appendix B, “Troubleshooting,” provides some troubleshooting information.
Build the product by clicking the Build All button.
If you've created online help for your product as described in Chapter 9, “Providing Online Help With SGIHelp,” in the Indigo Magic Desktop Integration Guide, you should incorporate the help into your installable images. “Producing the Final Product” in that chapter describes how to create an installable help subsystem, which you should do before incorporating it with the rest of your product. That process automatically creates appropriate spec and IDB files for the help subsystem; tags the files; sets the permissions and destinations; and assigns the necessary attributes. The tools that create the online help subsystem use “/” as the Source Tree Root directory.
If you've already created the spec and IDB files for your product using swpkg, you can merge the help subsystem with the existing files as described in “Combining Existing Products Into a Single Product”.
If you've not already created the spec and IDB files for your product, you can open the existing help subsystem spec and IDB files, and expand them as needed to handle the rest of your product.
To break apart an existing product (built with swpkg) into two or more products, follow these steps:
Start swpkg.
From the File menu, open the “Open” cascade menu and select “Both.” The Open Spec window appears. Use the file browser and text field to select the spec file for the product and click the OK button. The Open Idb window appears. Use the file browser and text field to select the IDB file for the product and click the OK button.
Open the Create Product Hierarchy worksheet and delete nodes from the Product Hierarchy graph until you have the structure you want for the first of your two “new” products.
Open the Tag Files worksheet and delete all the files that don't belong in the first product. Re-tag any remaining files, if necessary.
Use the other worksheets to make any other changes necessary to the remaining files (such as changing the product name, changing installation attributes, and so on).
If, in the previous build of the (whole) product, you specified a source tree root, enter that root in the corresponding text field now. Source tree roots are discussed in “Setting Source Tree Roots”. (swpkg does not save the source tree root in the spec and IDB files, so you have to re-enter this information each time you build the product.)
Select the desired build options. The build options are described in “Selecting Build Options”. (swpkg does not save build option selections in the spec and IDB files, so you have to re-enter this information each time you build the product.)
Try a test of the build by clicking the Test Build button. When you're asked where to save the Spec and IDB files, choose new filenames so that you don't overwrite the spec and IDB files for the original product.
Resolve any error messages that appear in the Message Area during the test. Appendix B, “Troubleshooting,” provides some troubleshooting information.
Build the first of the two new products by clicking the Build All button.
Go back to the Create Product Hierarchy worksheet and open the Spec and IDB files for the original (whole) product.
Repeat Steps 2 through 10 for the second of your two “new” products.