Chapter 2. The swpkg Tutorial
Prev   Next

Chapter 2. The swpkg Tutorial

This chapter provides a brief (ten-minute) tutorial that takes you through the basic steps for installing a simple product. When you've finished, you'll have packaged an example application for installation. It's best to work along with the tutorial, completing the steps on your own workstation as you read through them.

Note: swpkg is a versatile tool that allows you a great deal of freedom in creating installable files. Many of swpkg's features are not required to package an average product for installation. Rather than present all the features, this tutorial focuses on the basics needed to package an application. Don't worry that we don't use some of the buttons and text entry fields that appear in the worksheets. swpkg's more advanced features are discussed in the remaining chapters of this book.

Step One: Setting Up the Example Application Used by This Tutorial

Before you begin this tutorial, make sure you have the example application on your system. The example application is a loan calculator called finance. Given a term in years, the principle loan amount and interest rate, finance computes the monthly payment.

The files you need to use this sample application are part of the swpkg product. Before you begin this tutorial, set up the finance application by following these steps:

  1. Become superuser:

    % su

  2. Change to the directory containing the finance files:

    # cd /usr/share/src/swpkg

  3. To create the Makefile, enter: 

    # xmkmf

  4. To compile the finance application, enter:

    # make

Step Two: Running swpkg

To run swpkg, enter:

# swpkg

A small dialog box appears with a copyright notice, requesting that you wait while the system initializes. Then swpkg appears.

When swpkg first appears, it displays the first of its five main worksheets: the Create Product Hierarchy worksheet, shown in Figure 2-1.

Figure 2-1. The Create Product Hierarchy Worksheet


Step Three: Creating a Product Hierarchy

The Create Product Hierarchy worksheet helps you structure your product into three levels: product, images, and subsystems. This is called creating a product hierarchy. swpkg stores this product structure information in the spec file. (If you want more information now about spec files and product hierarchies, see “What's a Spec File?”, and “About Product Hierarchies”.)

For our example program, finance, we're just going to use the simplest product hierarchy: a software image and a reference page image with one subsystem each. We enter this information into the Create Product Hierarchy worksheet and tell swpkg to save it in the spec file.

To create the product hierarchy, follow these steps:

  1. In the text field labeled Product Name, change the text from “my_product” to “finance,” then click the left mouse button on the Assign arrow button. (See “Setting the Product Name” for more detailed instructions on setting product names.)

    If you neglect to click the Assign arrow button, swpkg will ignore your changes. After you click the Assign arrow button, the name of the node originally labeled “my_product” reads “finance.”

  2. In the text field labeled My Product Description, change the product description from “My Product Description” to “Mortgage Calculation Program,” then click the Assign arrow button on your keyboard. (See “Setting the Product Description” for more detailed information on setting product descriptions.)

    Note: Remember to enclose the description within quotes. You can use either single or double quotes.

  3. It's a good idea to save the spec file at this point (although it is not necessary to do so, swpkg gives you a chance to save your spec and IDB files when you build your product). To save the spec file, open the File menu and select the “Save” menu item, then choose “Spec” from the rollover menu. (See “Using the File Menu” for instructions.) A dialog box labeled “Save Spec” appears. Click the Ok button to save the spec file.

That's it. You've created a product structure for your product and stored it in a spec file. Your completed worksheet should look like the one shown in Figure 2-2.

Figure 2-2. The Completed Product Hierarchy Worksheet


Note: The template in the Product Hierarchy graph follows Silicon Graphics conventions for structuring and naming a product. Silicon Graphics strongly recommends that you follow these conventions. Users are presented with this structure when they use Software Manager. The descriptions you provide for your product, images, and subsystems are the first information about your product that users see.

Step Four: Tagging the Files

The next step is tagging the files, so that swpkg knows which files belong in which subsystem. To keep track of this information, swpkg stores this information in an installation database file (IDB file).

swpkg uses the IDB file to keep track of all sorts of information about the files that comprise your product, such as which files are included in which subsystem, where the files are located, and where Software Manager should put the files when it installs them. (IDB files can include other information too—for a more detailed explanation of IDB files, see “What's an IDB File?”). For now, we'll use the Tag Files worksheet to create a simplest-case IDB file.

First, switch to the Tag Files worksheet by clicking the tab labeled “Tag Files” (the second of the five Worksheet Selection Tabs at the top of the worksheet). When you do this, the Create Product Hierarchy worksheet is replaced by the Tag Files worksheet, shown in Figure 2-3.

Figure 2-3. The Tag Files Worksheet


To create a simple IDB file for the Finance product, follow these steps:

  1. Change the text in the text field labeled “File Browser” to:

    /usr/share/src/swpkg

  2. Press the <Enter> key. The contents of the /usr/share/src/swpkg directory appear in the File Browser.

  3. Select the files named finance, Finance.ad, finance.ftr, and finance.man from the File Browser. (To do this, use the scroll bar to scroll through the list of files in the directory until you find the file named finance and click the left mouse button on the finance filename. The line listing finance is highlighted in black. Then, hold down the <Ctrl> key and click the left mouse button on the Finance.ad, finance.ftr, and finance.man filenames.)

  4. Click the Add arrow button (located just to the right of the File Browser). These lines appear in the IDB File Viewer:

    finance.sw.base usr/share/src/swpkg/Finance.ad
finance.sw.base usr/share/src/swpkg/finance
finance.sw.base usr/share/src/swpkg/finance.ftr
finance.sw.base usr/share/src/swpkg/finance.man

    (Don't worry about the lack of the slash before the usr directory. swpkg strips the source root from the pathname and uses the root that you specify in the Source Tree Root text field in the Edit Permissions & Destinations worksheet. The default source root is slash [/].)

    Notice that the lines listing the finance, Finance.ad, finance.ftr, and finance.man files now appear in bold in the File Browser. Files that are listed in the IDB File Viewer appear in bold in the File Browser so that they're easier to spot.

    Notice also that swpkg has assigned all four of these files to the finance.sw.base subsystem. This is because, when we added the files to the IDB File Viewer, the tag finance.sw.base was selected in the Tags Browser. The finance, finance.ftr, and Finance.ad files do belong in the finance.sw.base subsystem, but we'll need to switch the finance.man file to the finance.man.manpages subsystem.

  5. Click the left mouse button on the entry for finance.man in the IDB files list.

  6. In the Tags Browser, click the left mouse button on the finance.man.manpages tag. The line listing finance.man.manpages is highlighted in black.

  7. Click the left mouse button on the Assign arrow button.

    The IDB File Viewer now shows this line for the finance.man file: 

    finance.man.manpages usr/share/src/swpkg/finance.man

    Now the finance.man file is assigned to the finance.man.manpages subsystem.

  8. It's a good idea to save the IDB file at this point (although it is not necessary to do so, swpkg will give you a chance to save your spec and IDB files when you build your product). To save the IDB file, open the File menu and select the “Save” menu item, then choose “IDB” from the rollover menu. (See “Using the File Menu” for instructions.) A dialog box labeled “Save IDB” appears. Click the Ok button to save the IDB file.

Now swpkg knows which files belong in which subsystems, and it has stored that information in the IDB file for the finance product. Your completed Tag Files worksheet should look like the one shown in Figure 2-4.

Figure 2-4. The Completed Tag Files Worksheet


Step Five: Setting Permissions and Destinations

swpkg now knows which files are in which subsystems and where to find each file, but it doesn't know where you want the files installed or what the permissions should be. You provide this information using the Edit Permissions & Destinations worksheet, and swpkg stores it in the IDB file that you created in Step Four.

Open the Edit Permissions & Destinations worksheet by clicking the worksheet selection tab labeled “Edit Permissions & Destinations.” The Tag Files worksheet is replaced by the Edit Permissions & Destinations worksheet, shown in Figure 2-5.

Figure 2-5. The Edit Permissions & Destinations Worksheet


In the Edit Permissions & Destinations worksheet, you enter permissions and destination information for each file in your product. swpkg stores the information you enter in this worksheet in the IDB file. Later, when users install your product, Software Manager uses these lines to figure out where to install the files and how to set the file modes, owners, and groups.

To edit the permissions information for the Finance.ad file, follow these steps:

  1. Double-click the left mouse button on the first item in the IDB File Viewer, the Finance.ad file. The current values for all the fields in the worksheet appear.

  2. In the text field labeled “Mode,” change the mode to:

    444

  3. In the text field labeled “Owner,” change the owner to:

    root

  4. In the text field labeled “Group,” change the group to:

    sys

  5. In the text field labeled “Destination Directory,” change the destination directory to:

    usr/lib/X11/app-defaults

  6. In the text field labeled “Destination Filename,” change the destination filename to:

    Finance

  7. Click the left mouse button on the lower of the two Assign arrow buttons.

  8. Save the IDB file by selecting the “Save” menu item from the File menu. (See “Using the File Menu” for instructions.)

You've finished filling in the worksheet for the Finance.ad file. The Edit Permissions & Destinations worksheet should now look like the one shown in Figure 2-6. For more detailed information on working with the text fields in the Permissions and Destinations sheet, see “Setting Permissions and Destination Directories”.

Figure 2-6. The Completed Worksheet for the Finance.ad File


Now edit the permissions and destinations information for the finance executable file, by following these steps:

  1. Double-click the second IDB File Viewer item, the finance executable file.

  2. In the text field labeled “Mode,” change the mode to:

    775

  3. In the text field labeled “Owner,” change the owner to:

    root

  4. In the text field labeled “Group,” change the group to:

    sys

  5. In the text field labeled “Destination Directory,” change the destination directory to:

    usr/bin/X11

  6. Click the left mouse button on the lower of the two Assign arrow buttons.

  7. Save the IDB file by selecting the “Save” menu item from the File menu. (See “Using the File Menu” for instructions.)

You've finished filling in the worksheet for the finance executable. The Edit Permissions & Destinations worksheet should now look like the one shown in Figure 2-7.

Figure 2-7. The Completed Worksheet for the finance File


Edit the permissions and destinations information for the finance.ftr file by following these steps:

  1. Double-click the third IDB File Viewer item, the finance.ftr file.

  2. In the text field labeled “Mode,” change the mode to:

    444

  3. In the text field labeled “Owner,” change the owner to:

    root

  4. In the text field labeled “Group,” change the group to:

    sys

  5. In the text field labeled “Destination Directory,” change the destination directory to:

    usr/lib/filetype/install

  6. Click the left mouse button on the lower of the two Assign arrow buttons.

  7. Save the IDB file by selecting the “Save” menu item from the File menu. (See “Using the File Menu” for instructions.)

You've finished filling in the worksheet for the finance.ftr file. The Edit Permissions & Destinations worksheet should now look like the one shown in Figure 2-8.

Figure 2-8. The Completed Worksheet for the finance.ftr File


Edit the permissions and destinations information for the finance.man file by following these steps:

  1. Double-click the fourth IDB File Viewer item, the finance.man file.

  2. In the text field labeled “Mode,” change the mode to:

    644

  3. In the text field labeled “Owner,” change the owner to:

    root

  4. In the text field labeled “Group,” change the group to:

    sys

  5. In the text field labeled “Destination Directory,” change the destination directory to:

    usr/man/u_man/man1

  6. In the text field labeled “Destination Filename,” change the destination filename to:

    finance.1

  7. Click the left mouse button on the lower of the two Assign arrow buttons.

  8. Save the IDB file by selecting the “Save” menu item from the File menu. (See “Using the File Menu” for instructions.)

You've finished filling in the worksheet for the finance.man file. We're going to leave the Source Tree Root and Destination Tree Root text fields alone, since we want to use the default values (/). For information on setting source and destination tree roots, see “Setting Source and Destination Tree Roots”.

The Edit Permissions & Destinations worksheet should now look like the one shown in Figure 2-9.

Figure 2-9. The Completed Worksheet for the finance.man File


Now you have a complete IDB file, along with a spec file for your product. You're ready to build your product.

Step Six: Adding Attributes

The next step is to add any necessary installation attributes to the product's files. In this example, we'll go with the simplest case: we'll use the exitop installation attribute to tell Software Manager to install the application's icon in the Icon Catalog after the user gives the quit command.

To add an installation attribute, you need to switch from the Edit Permissions & Destinations worksheet to the Add Attributes worksheet. Click the left mouse button on the Worksheet Selection Tab labeled “Add Attributes.” The Add Attributes worksheet, shown in Figure 2-10, appears.

Figure 2-10. The Add Attributes Worksheet


This worksheet allows you to set up certain installation attributes for the files in your product. In the simplest case, you just use this worksheet to: 1) tag your executable file; 2) install your application's Desktop icon in the Icon Catalog; and 3) update the Desktop Database to include your Desktop Icon. (For more information on updating the Desktop database, see “Step Four: Compiling the Source Files” in Chapter 11 of the Indigo Magic Desktop Integration Guide.)

To use the exitop attribute to run these commands for you when your users quit Software Manager, follow these steps:

  1. Double-click the left mouse button on the first item in the IDB File Viewer, the finance executable.

  2. Click the left mouse button on the exitop check button under “Software Attributes” in the Add Attributes worksheet.

  3. In the text field under the exitop check button, type:

    "tag 0x000101A0 /usr/bin/X11/finance 
iconbookedit -add 'Category:File Name:/usr/bin/X11/finance' -syspage DesktopTools 
cd /usr/lib/filetype 
make -u"

    Note: The entire list of commands is enclosed in a pair of double-quotes (" ").

  4. Click the Assign arrow button.

  5. Save the IDB file by selecting the “Save” menu item from the File menu. (See “Using the File Menu” for instructions.)

(For more information on using the iconbookedit command, see Chapter 15, “Adding Your Application's Icon to the Icon Catalog,” in the Indigo Magic Desktop Integration Guide. For more information on updating the Desktop database, see “Step Four: Compiling the Source Files” in Chapter 11 of the Indigo Magic Desktop Integration Guide.)

You've finished filling in the Add Attributes worksheet. The worksheet should now look like the one shown in Figure 2-11.

Figure 2-11. The Completed Add Attributes Worksheet


Step Seven: Building the Product

To build, you need to switch from the Add Attributes worksheet to the Build Product worksheet. Click the left mouse button on the Worksheet Selection Tab labeled “Build Product.” The Build Product worksheet, shown in Figure 2-12, appears.

Figure 2-12. The Build Product Worksheet


This worksheet lists the lines in the IDB file and shows the settings for the source root, the destination root, and the distribution directory. (The distribution directory is the directory where you want swpkg to put all the installable files it creates. This directory is often named dist, which is short for distribution.)

For this simplest-case example, we're going to stick with the default distribution directory, /usr/dist and we won't select any of the Build Options check buttons (located below the distribution directory text field). For information on setting the distribution directory, see “Setting Tree Roots and the Distribution Directory”. For more information on the build options, see “Selecting Build Options”.

Before building the product, it's a good idea to try a test and see if any problems crop up without having swpkg actually try to build the product. Click the left mouse button on the button labeled Test Build at the bottom right corner of the worksheet. If swpkg runs into problems, it lists them in the Message Area near the top of the worksheet.

If no problems are listed, you're ready to build the product. To build the product, click the left mouse button on the Build All button at the bottom of the worksheet.

As swpkg builds your product, it displays any error messages in Message Area. When it's finished, it displays a message to that effect in the Message Area. Now you're ready to quit swpkg. Quit by selecting the “Quit” menu item from the File pull-down menu (described in “Using the File Menu”).

Step Eight: Installing and Running the Product

After you've built the product, use Software Manager to install it on your local workstation. Look at the short and long names Software Manager lists for your product, images, and subsystems—are they clear and distinct? After your product is installed, quit Software Manager. Did all the files all get installed in the correct places? Does the icon appear in the Icon Catalog?

Prev Table of Contents Next
Chapter 1. Packaging Software for Installation: An Overview  Chapter 3. Creating a Product Hierarchy