docs.oracle.comcontents preface ix 1. designing a package 1 where to find packaging tasks 1 what are...

Application Packaging Developer’sGuide

Sun Microsystems, Inc.2550 Garcia Avenue

Mountain View, CA 94043-1100U.S.A.

Part No: 802-5892–10August, 1997

Copyright 1997 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California 94303-4900 U.S.A. All rights reserved.This product or document is protected by copyright and distributed under licenses restricting its use, copying, distribution, anddecompilation. No part of this product or document may be reproduced in any form by any means without prior written authorization ofSun and its licensors, if any. Third-party software, including font technology, is copyrighted and licensed from Sun suppliers.Parts of the product may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is a registeredtrademark in the U.S. and other countries, exclusively licensed through X/Open Company, Ltd.Sun, Sun Microsystems, the Sun logo, SunSoft, SunDocs, SunExpress, SunOS, JumpStart, and Solaris are trademarks, registeredtrademarks, or service marks of Sun Microsystems, Inc. in the U.S. and other countries. All SPARC trademarks are used under license andare trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries. Products bearing SPARC trademarksare based upon an architecture developed by Sun Microsystems, Inc.The OPEN LOOK and SunTM Graphical User Interface was developed by Sun Microsystems, Inc. for its users and licensees. Sunacknowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user interfaces for thecomputer industry. Sun holds a non-exclusive license from Xerox to the Xerox Graphical User Interface, which license also covers Sun’slicensees who implement OPEN LOOK GUIs and otherwise comply with Sun’s written license agreements.

RESTRICTED RIGHTS: Use, duplication, or disclosure by the U.S. Government is subject to restrictions of FAR 52.227–14(g)(2)(6/87) andFAR 52.227–19(6/87), or DFAR 252.227–7015(b)(6/95) and DFAR 227.7202–3(a).DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES,INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE ORNON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLYINVALID.

Copyright 1997 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, Californie 94303-4900 Etats-Unis. Tous droits réservés.

Ce produit ou document est protégé par un copyright et distribué avec des licences qui en restreignent l’utilisation, la copie, ladistribution, et la décompilation. Aucune partie de ce produit ou document ne peut être reproduite sous aucune forme, par quelquemoyen que ce soit, sans l’autorisation préalable et écrite de Sun et de ses bailleurs de licence, s’il y en a. Le logiciel détenu par des tiers, etqui comprend la technologie relative aux polices de caractères, est protégé par un copyright et licencié par des fournisseurs de Sun.Des parties de ce produit pourront être dérivées du système Berkeley BSD licenciés par l’Université de Californie. UNIX est une marquedéposée aux Etats-Unis et dans d’autres pays et licenciée exclusivement par X/Open Company, Ltd.Sun, Sun Microsystems, le logo Sun, SunSoft, SunDocs, SunExpress, SunOS, JumpStart et Solaris sont des marques de fabrique ou desmarques déposées, ou marques de service, de Sun Microsystems, Inc. aux Etats-Unis et dans d’autres pays. Toutes les marques SPARC sontutilisées sous licence et sont des marques de fabrique ou des marques déposées de SPARC International, Inc. aux Etats-Unis et dansd’autres pays. Les produits portant les marques SPARC sont basés sur une architecture développée par Sun Microsystems, Inc.L’interface d’utilisation graphique OPEN LOOK et SunTM a été développée par Sun Microsystems, Inc. pour ses utilisateurs et licenciés.Sun reconnaît les efforts de pionniers de Xerox pour la recherche et le développement du concept des interfaces d’utilisation visuelle ougraphique pour l’industrie de l’informatique. Sun détient une licence non exclusive de Xerox sur l’interface d’utilisation graphique Xerox,cette licence couvrant également les licenciés de Sun qui mettent en place l’interface d’utilisation graphique OPEN LOOK et qui en outrese conforment aux licences écrites de Sun.CETTE PUBLICATION EST FOURNIE “EN L’ETAT” ET AUCUNE GARANTIE, EXPRESSE OU IMPLICITE, N’EST ACCORDEE, YCOMPRIS DES GARANTIES CONCERNANT LA VALEUR MARCHANDE, L’APTITUDE DE LA PUBLICATION A REPONDRE A UNEUTILISATION PARTICULIERE, OU LE FAIT QU’ELLE NE SOIT PAS CONTREFAISANTE DE PRODUIT DE TIERS. CE DENI DEGARANTIE NE S’APPLIQUERAIT PAS, DANS LA MESURE OU IL SERAIT TENU JURIDIQUEMENT NUL ET NON AVENU.

PleaseRecycle

Contents

Preface ix

1. Designing a Package 1

Where to Find Packaging Tasks 1

What Are Packages? 2

Package Components 2

Required Package Components 3

Optional Package Components 4

Things to Think About Before Building a Package 5

Make Packages Installable Remotely 6

Optimize for Client-Server Configurations 6

Package by Functional Boundaries 6

Package Along Royalty Boundaries 6

Package by System Dependencies 6

Eliminate Overlap in Packages 7

Package Along Localization Boundaries 7

Packaging Commands, Files, and Scripts 7

2. Building a Package 11

Task Map: The Process of Building a Package 11

Package Environment Variables 13

Contents iii

General Rules on Using Environment Variables 13

Package Environment Variables Summary 14

Creating a pkginfo File 15

Defining a Package Instance 15

Defining a Package Name (NAME) 16

Defining a Package Category (CATEGORY) 17

H How to Create a pkginfo File 17

Organizing a Package’s Contents 18

H How to Organize A Package’s Contents 18

Creating a prototype File 20

The Format of the prototype File 20

Creating a prototype File From Scratch 26

Creating a prototype File With the pkgproto Command 26

Fine-Tuning a prototype File Created With the pkgprotoCommand 27

Adding Functionality to a prototype File 29

H How to Create a prototype File Using the pkgproto Command 32

Building a Package 34

Using the Simplest pkgmk Command 34

The pkgmap File 34

H How to Build a Package 35

3. Enhancing the Functionality of a Package 41

Task Map: Creating Information Files and Installation Scripts 41

Creating Information Files 43

Defining Package Dependencies 44

H How to Define Package Dependencies 44

Writing a Copyright Message 47

H How to Write a Copyright Message 47

iv Application Packaging Developer’s Guide ♦ August, 1997

Reserving Additional Space on a Target System 48

H How to Reserve Additional Space on a Target System 48

Creating Installation Scripts 50

Script Processing During Package Installation 51

Script Processing During Package Removal 51

Package Environment Variables Available to Scripts 52

Obtaining Package Information for a Script 54

Exit Codes for Scripts 54

Writing a request Script 55

H How to Write a request Script 56

Gathering Data With the checkinstall Script 57

H How to Gather File System Data 58

Writing Procedure Scripts 60

H How to Write Procedure Scripts 61

Writing Class Action Scripts 62

H How to Write Class Action Scripts 68

4. Verifying and Transferring a Package 71

Task Map: Verifying and Transferring a Package 71

Installing Software Packages 72

The Installation Software Database 73

Interacting with the pkgadd Command 73

Installing Packages on Standalones or Servers in a HomogeneousEnvironment 74

H How to Install a Package on a Standalone or Server 74

Installing Packages for Diskless Clients and AutoClient Systems on aServer 75

H How to Add a Package to a Diskless or AutoClient System’s Root File System 75

Verifying the Integrity of a Package 76

H How to Verify the Integrity of Your Package 77

Contents v

Displaying Additional Information About Installed Packages 79

The pkgparam Command 79

H How to Obtain Information With the pkgparam Command 79

The pkginfo Command 81

H How to Obtain Information With the pkginfo Command 84

Removing a Package 85

H How to Remove a Package 85

H How to Remove a Package From a Diskless or AutoClient System 86

Transferring a Package to a Distribution Medium 87

H How to Transfer Your Package to a Distribution Medium 87

5. Package Creation Case Studies 89

Soliciting Input From the Administrator 89

Techniques 90

Approach 90

Case Study Files 91

Creating a File at Installation and Saving It During Removal 93

Techniques 93

Approach 94

Case Study Files 95

Defining Package Compatibilities and Dependencies 97

Techniques 97

Approach 97

Case Study Files 98

Modifying a File Using Standard Classes and Class Action Scripts 99

Techniques 100

Approach 100

Case Study Files 101

Modifying a File Using the sed Class and a postinstall Script 103

vi Application Packaging Developer’s Guide ♦ August, 1997

Techniques 103

Approach 103


Modifying a File Using the build Class 105

Techniques 105

Approach 106


Modifying crontab Files During Installation 108

Techniques 108

Approach 108


Installing and Removing a Driver With Procedure Scripts 111

Techniques 111

Approach 111


Installing a Driver Using the sed Class and Procedure Scripts 114

Techniques 114

Approach 115


6. Advanced Package Creation Techniques 121

Specifying the Base Directory 121

The Administrative Defaults File 122

Using the BASEDIR Parameter 123

Using Parametric Base Directories 124

Managing the Base Directory 126

Accommodating Relocation 126

Walking Base Directories 127

Supporting Relocation in a Heterogeneous Environment 135

Contents vii

Traditional Approach 136

Beyond Tradition 140

Making Packages Installable Remotely 146

Example—Installing to a Client 146

Example—Installing to a Server or Standalone 147

Example—Mounting Shared File Systems 148

Patching Packages 148

The checkinstall Script 150

The preinstall Script 154

The Class Action Script 158

The postinstall Script 163

The patch_checkinstall Script 168

The patch_postinstall Script 170

Upgrading Packages 171

The request Script 172

The postinstall Script 173

Glossary 175

Index 179

viii Application Packaging Developer’s Guide ♦ August, 1997

Preface

The Application Packaging Developer’s Guide provides step-by-step instructions andrelevant background information for designing, building, and verifying packages.This guide also includes information on and examples of advanced techniques thatyou may find helpful during the package creation process.

Who Should Use This BookThis book is intended for application developers whose responsibilities includedesigning and building packages.

Though much of the book is directed towards novice package developers, it alsocontains information useful to more experienced package developers.

Note - The term “x86” refers to the Intel 8086 family of microprocessor chips,including the Pentium and Pentium Pro processors and compatible microprocessorchips made by AMD and Cyrix. In this document the term “x86” refers to the overallplatform architecture, whereas “Intel Platform Edition” appears in the product name.

How This Book Is OrganizedChapter 1, describes package components, package design criteria, and relatedcommands, files, and scripts.

Preface ix

Chapter 2, describes the process and required tasks for building a package, andprovides step-by-step instructions for each task.

Chapter 3, describes how to add optional features to a package, and providesstep-by-step instructions for each.

Chapter 4, describes how to verify the integrity of a package and transfer a packageto a distribution medium.

Chapter 5, provides case studies for creating packages.

Chapter 6, describes various advanced package creation techniques.

Glossary is a list of words and phrases found in this book and their definitions.

Related BooksThe following documentation may provide additional background information onbuilding System V packages.

� Solaris Porting Guide

� System V Application Binary Interface

� System V Application Binary Interface - SPARC Processor Supplement

� System V Application Binary Interface - Intel386 Processor Supplement

� System V Application Binary Interface - MIPS Processor Supplement

� System V Application Binary Interface - Motorola 88000 Processor Supplement

Ordering Sun DocumentsThe SunDocsSM program provides more than 250 manuals from Sun Microsystems,Inc. If you live in the United States, Canada, Europe, or Japan, you can purchasedocumentation sets or individual manuals using this program.

For a list of documents and how to order them, see the catalog section of theSunExpressTM Internet site at http://www.sun.com/sunexpress .

x Application Packaging Developer’s Guide ♦ August, 1997

What Typographic Changes MeanThe following table describes the typographic changes used in this book.

TABLE P–1 Typographic Conventions

Typeface orSymbol

Meaning Example

AaBbCc123 The names of commands,files, and directories;on-screen computer output

Edit your .login file.

Use ls -a to list all files.

machine_name% You have mail.

AaBbCc123 What you type, contrastedwith on-screen computeroutput

machine_name% su

Password:

AaBbCc123 Command-line placeholder:

replace with a real name orvalue

To delete a file, type rm filename.

AaBbCc123 Book titles, new words orterms, or words to beemphasized

Read Chapter 6 in User’s Guide. Theseare called class options.

You must be root to do this.

Shell Prompts in Command ExamplesThe following table shows the default system prompt and superuser prompt for theC shell, Bourne shell, and Korn shell.

xi

TABLE P–2 Shell Prompts

Shell Prompt

C shell prompt machine_name%

C shell superuser prompt machine_name#

Bourne shell and Korn shell prompt $

Bourne shell and Korn shell superuser prompt #

xii Application Packaging Developer’s Guide ♦ August, 1997

CHAPTER 1

Designing a Package

Before you build a package, you need to know which files you need to create and thecommands you need to execute. You also need to consider your applicationsoftware’s requirements, and the needs of your customer—the administrators whowill be installing your package. This chapter discusses the files, commands, andcriteria you should know and think about, before building a package.

This is a list of the overview information in this chapter.

� “Where to Find Packaging Tasks” on page 1

� “What Are Packages?” on page 2

� “Package Components” on page 2

� “Things to Think About Before Building a Package” on page 5

� “Packaging Commands, Files, and Scripts” on page 7

Where to Find Packaging TasksUse these references to find step-by-step instructions for building and verifyingpackages.

� “Task Map: The Process of Building a Package” on page 11

� “Task Map: Creating Information Files and Installation Scripts” on page 41

� “Task Map: Verifying and Transferring a Package” on page 71

1

What Are Packages?Application software is delivered in units called packages. A package is a collection offiles and directories required for a software product, and is usually designed andbuilt by the application developer after completing the development of theapplication code. A software product needs to be built into one or more packages sothat it can easily be transferred to a distribution medium, be mass produced, andinstalled by administrators.

Package ComponentsThe components of a package fall into two categories: package objects, the applicationfiles to be installed, and control files, which control how, where, and if the package isinstalled.

The control files are also divided into two categories: information files andinstallation scripts. Some of these control files are required and some are optional.

To package your applications, you must first create the required components, andany optional components, that make up your package. Then you can build thepackage using the pkgmk command.

To build a package, you must provide the following:

� Package objects (the application software files)

� Two required information files (the pkginfo and prototype files)

� Optional information files and installation scripts

Figure 1–1 describes the contents of a package.

2 Application Packaging Developer’s Guide ♦ August, 1997

Optional Information Files(compver , depend ,

Optional Installation Scripts(request , checkinstall ,

Procedure, and Class Action)

space , copyright )

Required Components

Thepkginfo

File

Theprototype

File

PackageObjects

Figure 1–1 The Contents of a Package

Required Package ComponentsYou must create the following components before you build your package:

� Package Objects

These are the components that make up the application. They can be:

� Files (executable or data)

� Directories

� Named pipes

� Links

� Devices

� The pkginfo file

The pkginfo file is a required package information file defining parameter valuessuch as the package abbreviation, the full package name, and the packagearchitecture. For more information, see “Creating a pkginfo File” on page 15 andthe pkginfo (4) man page.

Designing a Package 3

Note - There are two pkginfo man pages. The first is a section 1 command, whichdisplays information about installed packages. The second is a section 4 file, whichdescribes the characteristics of a package. When accessing the man pages, be sure tospecify from which section you want the man page. For example:man -s 4 pkginfo

� The prototype file

The prototype file is a required package information file that lists thecomponents of the package. It describes the location, attributes, and file type foreach component within a package.

In the prototype file, there is one entry for each package object, information file,and installation script. An entry consists of several fields of information describingthe object. For more information, see “Creating a prototype File” on page 20andthe prototype (4) man page.

Optional Package Components

Package Information FilesThere are four optional package information files you can include in your package:

� The compver file

Defines previous versions of the package that are compatible with this version.

� The depend file

Indicates other packages with which this package has special relationships.

� The space file

Defines disk space requirements for the target environment, beyond what isneeded by the objects defined in the prototype file. For example, additionalspace might be needed for files that are dynamically created at installation time.

� The copyright file

Defines the text for a copyright message displayed at the time of packageinstallation.

Each package information file should have an entry in the prototype file. See“Creating Information Files” on page 43for more information on creating these files.


Package Installation ScriptsInstallation scripts are not required. However, you can provide scripts that performcustomized actions during the installation of your package. An installation script hasthe following characteristics.

� It is composed of Bourne shell commands.

� Its file permissions should be set to 0644.

� It does not need to contain the shell identifier (#! /bin/sh ).

The four script types are as follows:

� The request script

The request script requests input from the administrator installing the package.

� The checkinstall script

The checkinstall script performs special file system verification.

Note - The checkinstall script is only available with the SolarisTM 2.5 and laterreleases.

� Procedure scripts

Procedure scripts define actions that occur at particular points during packageinstallation and removal. There are four procedure scripts you can create withthese predefined names: preinstall , postinstall , preremove , andpostremove .

� Class Action scripts

Class Action scripts define a set of actions to be performed on a group of objects.

See “Creating Installation Scripts” on page 50for a more information on installationscripts.

Things to Think About Before Buildinga PackageBefore building a package, you need to decide whether your product is going to bemade up of one or more packages. (Note that many small packages take longer toinstall than one big package.) Although it is a good idea to create a single package, itis not always possible. If you decide to build more than one package, you need todetermine how to segment the application code. This section provides a list ofcriteria to use when planning to build packages.

Many of the good packaging criteria present trade-offs among themselves. It willoften be difficult to satisfy all requirements equally. These criteria are presented in


order of importance; however, this sequence is meant to serve as a flexible guidedepending on the circumstances. Although each of these criteria is important, it is upto you to optimize these requirements to produce a good set of packages.

For more design ideas, see Chapter 6.

Make Packages Installable RemotelyAll packages must be installable remotely. Being installable remotely means that theadministrator installing your package might be trying to install it on a client system,not necessarily to the root file system where the pkgadd command is being executed.

Optimize for Client-Server ConfigurationsIf you are designing a package for a Solaris 2.5 or earlier release, you shouldconsider the various types of system software configurations (for example,standalone, diskless, and server) when laying out packages. Good packaging designdivides the affected files to optimize installation of each configuration type. Forexample, the contents of root (/ ) and usr should be segmented so that dataless andserver configurations can easily be supported.

Package by Functional BoundariesPackages should be self-contained and distinctly identified with a set of functionality.For example, a package containing UFS should contain all UFS utilities and belimited to only UFS binaries.

Packages should be organized from a customer’s point of view into functional units.

Package Along Royalty BoundariesPut code that requires royalty payments due to contractual agreements in adedicated package or group of packages. Do not disperse the code into morepackages than necessary.

Package by System DependenciesKeep system-dependent binaries in dedicated packages. For example, the kernel codeshould be in a dedicated package with each implementation architecturecorresponding to a distinct package instance. This rule also applies to binaries for


different architectures. For example, SPARCTM binaries would be in one package andbinaries for an x86 system would be in another.

Eliminate Overlap in PackagesWhen constructing packages, eliminate duplicate files whenever possible.Unnecessary duplication of files results in support and version difficulties. If yourproduct has multiple packages, repeatedly compare the contents of these packagesfor redundancies.

Package Along Localization BoundariesLocalization-specific items should be in their own package. An ideal packagingmodel would have a product’s localizations delivered as one package per locale.Unfortunately, in some cases organizational boundaries may conflict with thefunctional and product boundaries criteria.

International defaults can also be delivered in a package. This would isolate the filesnecessary for localization changes and standardize delivery format of localizationpackages.

Packaging Commands, Files, and ScriptsThe purpose of this section is to describe the commands, files, and scripts you mightuse when manipulating packages. They are described in man pages and in detailthroughout this book, in relation to the specific task they perform.

Table 1–1 shows the commands available to help you build, verify, install, and obtaininformation about a package.


TABLE 1–1 Packaging Commands

Function Command Description For More Information, Go To ...

pkgproto (1)Generate aprototype file forinput to the pkgmkcommand

“Creating a prototype File Withthe pkgproto Command” onpage 26

Create packages

pkgmk(1)Create an installablepackage “Building a Package” on page 34

pkgadd (1M)Install a softwarepackage onto a system “Installing Software Packages” on

page 72

pkgask (1M)Store answers to arequest script “Design Rules for request

Scripts” on page 55

pkgtrans (1)Copy packages onto adistribution medium “Transferring a Package to a

Distribution Medium” on page 87

Install, remove,and transferpackages

pkgrm (1M)Remove a packagefrom a system “Removing a Package” on page 85

pkgchk (1M)Check consistency of asoftware package “Verifying the Integrity of a

Package” on page 76

pkginfo (1)Display softwarepackage information “The pkginfo Command” on

page 81

Obtaininformationabout packages

pkgparam (1)Display packageparameter values

“The pkgparam Command” onpage 79

installf (1M)Incorporate a newpackage object into analready installedpackage

“Design Rules for ProcedureScripts” on page 60 and Chapter 5

Modify installedpackages

removef (1M)Remove a packageobject from an alreadyinstalled package

“Design Rules for ProcedureScripts” on page 60


Table 1–2 shows the information files available to help you build a package.

TABLE 1–2 Package Information Files

Files DescriptionFor More Information, GoTo ...

admin (4)Package installation defaults file “The Administrative

Defaults File” on page 122

compver (4)Package compatibility file “Defining Package

Dependencies” on page 44

copyright (4)Package copyright information file “Writing a Copyright

Message ” on page 47

depend (4)Package dependencies file “Defining Package

Dependencies” on page 44

pkginfo (4)Package characteristics file “Creating a pkginfo File”

on page 15

pkgmap(4)Package contents description file “The pkgmap File” on page

34

prototype (4)Package information file “Creating a prototype

File” on page 20

space (4)Package disk space requirements file “Reserving Additional Space

on a Target System” on page48

Table 1–3 describes optional installation scripts that you can write that affect if andhow a package is installed.


TABLE 1–3 Package Installation Scripts

Scripts DescriptionFor More Information, GoTo ...

request Solicit information from the installer. “Writing a request Script”on page 55

checkinstall Gather file system data. “Gathering Data With thecheckinstall Script” onpage 57

preinstall Perform any custom installationrequirements before class installation. “Writing Procedure Scripts”

on page 60

postinstall Perform any custom installationrequirements after all volumes areinstalled.

“Writing Procedure Scripts”on page 60

preremove Perform any custom removalrequirements before class removal. “Writing Procedure Scripts”

on page 60

postremove Perform any custom removalrequirements after all classes have beenremoved.

“Writing Procedure Scripts”on page 60

Class Action Perform a series of actions on a specificgroup of objects. “Writing Class Action

Scripts” on page 62


CHAPTER 2

Building a Package

This chapter describes a process, as well as the tasks, on how to build a package.Some of these tasks are required and some are optional. The required tasks are theminimum of what you must do to create a package, and are discussed in detail inthis chapter. For information on the optional tasks, which enable you to add morefeatures to your package, see Chapter 3 and Chapter 6.


� “Task Map: The Process of Building a Package” on page 11

� “Package Environment Variables” on page 13

� “Creating a pkginfo File” on page 15

� “Organizing a Package’s Contents” on page 18

� “Creating a prototype File” on page 20

� “Building a Package” on page 34

Task Map: The Process of Building aPackageTable 2–1 describes a process for you to follow when building packages, especially ifyou are inexperienced at building them. Although it is not mandatory for you tocomplete the first four tasks in the exact order listed, it will make your packagebuilding experience easier if you do. Once you are an experienced package designer,you can shuffle the sequence of these tasks to your preference.

11

As an experienced package designer, you can automate the package building processusing the make command and makefiles. For more information see the make(1S)man page and the Programming Utilities Guide.

TABLE 2–1 Task Map: The Process of Building a Package

Task Description For Instructions, Go To

Create a pkginfoFile

You must create thepkginfo file to describethe characteristics of yourpackage.

“How to Create a pkginfo File” on page17

Organize PackageContents

You should arrange yourpackage components intoa hierarchical directorystructure.

“Organizing a Package’s Contents” onpage 18

Create InformationFiles

Optional. Define packagedependencies, include acopyright message, andreserve additional spaceon a target system.

Chapter 3

Create InstallationScripts

Optional. Customize theinstallation and removalprocesses of a package.

Chapter 3

Create aprototype File

Describe each object inyour package in aprototype file.

“Creating a prototype File” on page 20

Build the Package Build your package usingthe pkgmk command. “Building a Package” on page 34

Verify and Transferthe Package

Verify the integrity of apackage before copying itto a distribution medium.

Chapter 4


TABLE 2–1 Task Map: The Process of Building a Package (continued)

Package Environment VariablesYou can use variables in the required information files, pkginfo and prototype , aswell as an option to the pkgmk command (which is used to build a package). Aseach of these files and commands are discussed in this chapter, morecontext-sensitive information on variables is provided. However, before you beginbuilding your package, you should understand the different types of variables andhow they can affect a package’s successful creation.

There are two types of variables:

� Build variables

Build variables begin with a lowercase letter and are evaluated at build time (as thepackage is being built with the pkgmk command).

� Install variables

Install variables begin with an uppercase letter and are evaluated at install time (asthe package is being installed with the pkgadd command).

General Rules on Using Environment VariablesIn the pkginfo file, a variable definition is of the form PARAM=value, where the firstletter of PARAM is an uppercase letter. These variables are evaluated only at installtime, and if any cannot be evaluated, the pkgadd command will abort with an error.

In the prototype file, a variable definition can take the form ! PARAM=value or$variable. Both PARAM and variable can begin with either an uppercase or lowercaseletter; however, only variables whose values are known at build time will beevaluated. This means that if PARAM or variable is a build or install variable whosevalue is not known at build time, the pkgmk command will abort with an error.

You can also include the option PARAM=value as an option to the pkgmk command.This option works the same as in the prototype file, except that its scope is globalto the entire package. The ! PARAM=value definition in a prototype file is local tothat file and the part of the package it defines.

If PARAM is an install variable, and variable is an install or build variable with aknown value, the pkgmk command inserts the definition into the pkginfo file sothat it will be available at install time. However, it will not evaluate PARAM in anypath names specified in the prototype file.


Package Environment Variables SummaryTable 2–2 summarizes variable specification formats, location, and scope.

TABLE 2–2 Package Environment Variables Summary

VariableDefined InThe ...

VariableDefinitionFormat

VariableType BeingDefined

When TheVariable IsResolved

Where TheVariable IsResolved

The VariableMay Be UsedAs Part OfThe ...

Build Ignored atbuild time

N/A Nonepkginfo file PARAM=value

Install Install time In thepkgmap file

owner, group,path, or linktarget

Build Build time In theprototypefile and anyincluded files

mode, owner,group, or path

prototypefile

! PARAM=value

Install Build time In theprototypefile and anyincluded files

!search and!commandcommandsonly

Build Build time In theprototypefile

mode, owner,group, or path

Build time In theprototypefile

!searchcommandonly

pkgmkcommand line

PARAM=value

Install

Install time In thepkgmap file

owner, group,path, or linktarget


Creating a pkginfo FileThe pkginfo file is an ASCII file that describes the characteristics of a package alongwith information that helps control the flow of installation.

Each entry in the pkginfo file is a line that establishes the value of a parameterusing the format PARAM=value. PARAM can be any of the 19 standard parametersdescribed in the pkginfo (4) man page, and there is no required order in which theparameters must be specified.

Note - Each value can be enclosed with single or double quotation marks (forexample, ’value’ or “value”). If value contains any characters that are consideredspecial to a shell environment, you should use quotation marks. The examples andcase studies in this book do not use quotation marks. See the pkginfo (4) man pagefor an example that uses double quotation marks.

You can also create your own package parameters by assigning a value to them inthe pkginfo file. Your parameters must begin with a capital letter followed by eitheruppercase or lowercase letters. An uppercase letter indicates that the parameter(variable) will be evaluated at install time (as opposed to build time). Forinformation on the difference between install and build variables, see “PackageEnvironment Variables” on page 13.

Note - Trailing whitespace after any parameter value is ignored.

There are five parameters that you must define in a pkginfo file: PKG, NAME, ARCH,VERSION, and CATEGORY. For information on the remaining parameters, see thepkginfo (4) man page.

Defining a Package InstanceThe same package can have different versions, be compatible with differentarchitectures, or both. Each variation of a package is known as a package instance. Apackage instance is determined by combining the definitions of the PKG, ARCH, andVERSIONparameters in the pkginfo file.

The pkgadd command assigns a package identifier to each package instance atinstallation time. The package identifier is the package abbreviation with a numericalsuffix, for example SUNWadm.2. This identifier distinguishes a package instance fromany other package, including instances of the same package.


Defining a Package Abbreviation (PKG)A package abbreviation is a short name for a package that is defined via the PKGparameter in the pkginfo file, and must:

� Be alphanumeric, but the first cannot be numeric.

� Be nine or fewer characters.

� Not be one of the reserved abbreviations install , new, and all .

Note - The first four characters should be unique to your company, such as yourcompany’s stock symbol. For example, packages built by Sun MicrosystemsTM allhave “SUNW” as the first four characters of their package abbreviation.

An example package abbreviation entry in a pkginfo file might be:

PKG=SUNWcadap

Specifying a Package Architecture (ARCH)The ARCHparameter in the pkginfo file identifies which architectures are associatedwith the package. The architecture name has a maximum length of 16 alphanumericcharacters. If a package is associated with more than one architecture, specify themin a comma-separated list.

For example, a package architecture specification in a pkginfo file might be:

ARCH=sparc

Specifying a Package Version (VERSION)The VERSIONparameter in the pkginfo file identifies the version of the package.The version has a maximum length of 256 ASCII characters, and cannot begin with aleft parenthesis.

An example version specification in a pkginfo file might be:

VERSION=release 1.0

Defining a Package Name (NAME)A package name is the full name of the package, which is defined via the NAMEparameter in the pkginfo file.

Because system administrators often use package names to determine whether or nota package needs to be installed, it is important to write clear, concise, and completepackage names. Package names should

� State when a package is needed (for example, to provide certain commands orfunctionality, or state if it is needed for specific hardware).

� State what the package is used for (for example, the development of devicedrivers).


� Include a description of the package abbreviation mnemonic, using key words thatindicate the abbreviation is a short form of the description (for example, thepackage name for the package abbreviation SUNWbnuuis “Basic NetworkingUUCP Utilities, (Usr)”).

� Name the partition into which the package is installed.

� Use terms consistently with their industry meaning.

� Take advantage of the 256 character limit.

An example package name defined in a pkginfo file might be:

NAME=Chip designers need CAD application software to designabc chips. Runs only on xyz hardware and is installed in theusr partition.

Defining a Package Category (CATEGORY)The CATEGORYparameter in the pkginfo file specifies in which categories apackage belongs. At a minimum, a package must belong to either the system orapplication category. Category names:

� Are alphanumeric.

� Have a maximum length of 16 characters.

� Are case insensitive.

If a package belongs to more than one category, specify them in a comma-separatedlist.

An example CATEGORYspecification in a pkginfo file might be:

CATEGORY=system

How to Create a pkginfo File1. Using your favorite text editor, create a file named pkginfo .

You can create this file anywhere on your system.

2. Edit the file and define the five required parameters.

The five required parameters are: PKG, ARCH, VERSION, NAME, and CATEGORY. Formore information on these parameters, see “Creating a pkginfo File” on page 15.

3. Add any other parameters that you like to the file.

Create your own parameters or see the pkginfo (4) man page for information onthe 19 standard parameters.


4. Save your changes and quit the editor.

Where to Go Next

If you are ready to go to the next task, see “How to Organize A Package’s Contents”on page 18.

Example—Creating a pkginfo File

This example shows the contents of a valid pkginfo file, with the five requiredparameters defined, as well as the BASEDIR parameter. The BASEDIR parameter isdiscussed in more detail in “The path Field” on page 22.

PKG=SUNWcadapNAME=Chip designers need CAD application software to design abc chips.Runs only on xyz hardware and is installed in the usr partition.ARCH=sparcVERSION=release 1.0CATEGORY=systemBASEDIR=/opt

Organizing a Package’s ContentsOrganize your package objects in a hierarchical directory structure that mimics howyou want them to be on the target system after installation. If you do this step beforeyou create a prototype file, you can save yourself some time and effort whencreating that file.

How to Organize A Package’s Contents1. Determine how many packages you need to create and determine which

package objects shall be located in each package.

For help in completing this step, see “Things to Think About Before Building aPackage” on page 5.

2. For each package you need to build, make a directory.

You can create this directory anywhere on your system and name it anything youlike. The examples in this chapter assume that a package directory has the samename as the package abbreviation.


$ cd /home/jane$ mkdir SUNWcadap

3. For each package, organize package objects into a directory structure beneaththeir corresponding package directory, which mimics how they will be locatedon the target system.

For example, the CAD application package, SUNWcadap, requires the followingdirectory structure.

man srcfiles

windex man1

file3.1 file4.1

file5 file6

/home/jane

SUNWcadap

lib

file2

demo

file1

4. Decide where you will keep your information files and, if appropriate, make adirectory to keep them in one location.

This example assumes that the example pkginfo file from “How to Create apkginfo File” on page 17 was created in Jane’s home directory.

$ cd /home/jane$ mkdir InfoFiles$ mv pkginfo InfoFiles

Where to Go NextIf you are ready to go to the next task, see “How to Create a prototype File Usingthe pkgproto Command” on page 32.


Creating a prototype FileThe prototype file is an ASCII file used to specify information about the objects ina package. Each entry in the prototype file describes a single object, such as a datafile, directory, source file, or executable object. Entries in a prototype file consist ofseveral fields of information separated by white space. Note that the fields mustappear in a specific order. Comment lines begin with a pound sign (#) and areignored.

You can create a prototype file with a text editor or by using the pkgprotocommand. When you first create this file, it is probably easier to do so with thepkgproto command, because it creates the file based on the directory hierarchy youcreated previously. If you have not organized your files as described in “Organizinga Package’s Contents” on page 18, you have the cumbersome task of creating theprototype file from scratch with your favorite text editor. However, even when youcreate the prototype file using the pkgproto command, you will most likely needto make modifications to the file with your favorite text editor, so it is important tounderstand the format and contents of this file.

The Format of the prototype FileThe format for each line in the prototype file is:

part ftype class path major minor mode owner group

For each object,

part Is an optional, numeric field that enables you to grouppackage objects into parts. The default value is part 1.

ftype Is a one-character field that specifies the object’s type. See“The ftype Field” on page 21.

class Is the installation class to which the object belongs. See “Theclass Field” on page 22.

path Is the absolute or relative path name indicating where thepackage object will reside on the target system. See “Thepath Field” on page 22.

major Is the major device number for block or character specialdevices.


minor Is the minor device number for block or character specialdevices.

mode Is the octal mode of the object (for example, 0644). See “Themode Field” on page 25.

owner Is the owner of the object (for example, bin or root ). See“The owner Field” on page 25.

group Is the group to which the object belongs (for example, binor sys ). See “The group Field” on page 26.

Usually, only the ftype, class, path, mode, owner, and group fields are defined, and aredescribed in the following sections. For additional information on these fields, seethe prototype (4) man page.

The ftype Field

The ftype, or file type, field is a one-character field that specifies a package object’stype. Valid file types are described in Table 2–3.

TABLE 2–3 Valid File Types in the prototype File

Use ftype ... To Define A ...

f Standard executable or data file

e File to be edited upon installation or removal (may be shared byseveral packages)

v Volatile file (whose contents are expected to change, like a log file)

d Directory

x Exclusive directory accessible only by this package (may containunregistered logs or database information)

l Linked file

p Named pipe

c Character special device

b Block special device


TABLE 2–3 Valid File Types in the prototype File (continued)

Use ftype ... To Define A ...

i Information file or installation script

s Symbolic link

The class FieldThe class field names the class to which an object belongs. Using classes is anoptional package design feature, and is discussed in detail in “Writing Class ActionScripts” on page 62.

If you do not use classes, an object belongs to the none class, and when you executethe pkgmk command to build your package, it will insert the CLASSES=noneparameter in the pkginfo file for you. Files with file type i should leave the classfield blank.

The path FieldThe path field is used to define where the package object will reside on the targetsystem. You may indicate the location with either an absolute path name (forexample, /usr/bin/mail ) or a relative path name (for example, bin/mail ). Usingan absolute path name means that the object’s location on the target system isdefined by the package and cannot be changed. Package objects with relative pathnames indicate that the object is relocatable.

A relocatable object is one that does not need an absolute path location on the targetsystem. Instead, its location is determined during the installation process.

All or some of a package’s objects can be defined as relocatable. You should decide ifpackage objects will have fixed locations (such as start-up scripts in /etc ) or berelocatable before you write any installation scripts and before you create theprototype file.

There are two kinds of relocatable objects, collectively relocatable andindividually relocatable.

Collectively Relocatable ObjectsCollectively relocatable objects are located relative to a common installation basecalled the base directory. A base directory is defined in the pkginfo file, using theBASEDIR parameter. For example, a relocatable object in the prototype file named


tests/generic requires that the pkginfo file define the default BASEDIRparameter. For example:

BASEDIR=/opt

This means that when the object is installed, it will be located in/opt/tests/generic .

Note - /opt is the only directory to which software that is not part of base Solarismay be delivered.

Use collectively relocatable objects whenever possible. In general, the major part of apackage can be relocatable with a few files (such as those in /etc or /var ) specifiedas absolute. However, if a package contains many different relocations, considerdividing your package into multiple packages, each with a different BASEDIR valuein its pkginfo file.

Individually Relocatable ObjectsIndividually relocatable objects are not restricted to the same directory location ascollectively relocatable objects. To define an individually relocatable object, you needto specify an install variable in the path field in the prototype file, and then create arequest script to prompt the installer for the relocatable base directory, or acheckinstall script to determine the path name from file system data. For moreinformation on request scripts, see “Writing a request Script” on page 55 and forinformation on checkinstall scripts, see “How to Gather File System Data” onpage 58.

Note - Individually relocatable objects are difficult to manage and should beavoided. This is because they could result in widely scattered package componentsthat may be difficult to isolate when installing multiple versions or architectures ofthe package. Try to use collectively relocatable objects whenever possible.

Parametric Path NamesA parametric path name is a path name that includes a variable specification. Forexample, /opt/$PKGINST/ filename is a parametric path name because of the$PKGINST variable specification. A default value for the variable specification mustbe defined in the pkginfo file. The value may then be changed by a request orcheckinstall script.

A variable specification in a path must begin or end the path name, or be boundedby slashes (/). For example, valid parametric path names look like:


$PARAM/teststests/$PARAM/generic

/tests/$PARAM

The variable specification, once defined, may cause the path to be evaluated asabsolute or relocatable. For example, given this entry in a prototype file:

f none $DIRLOC/tests/generic

and this entry in the pkginfo file:

DIRLOC=/myopt

the path name, $DIRLOC/tests/generic , will evaluate to the absolute path name/myopt/tests/generic , regardless of whether the BASEDIR parameter is set inthe pkginfo file.

However, if the pkginfo file contains these entries

DIRLOC=firstcutBASEDIR=/opt

then the path name, $DIRLOC/tests/generic , will evaluate to the relocatable pathname /opt/firstcut/tests/generic .

For more information on parametric path names, see “Using Parametric BaseDirectories” on page 124.

A Brief Word on an Object’s Source and Destination LocationsThe path name field in the prototype file defines where the object will be locatedon the target system. However, if you did not organize your package’s objects onyour system in a directory structure that mimics their location on the target system(see “Organizing a Package’s Contents” on page 18), then you also need to specifytheir present location in the prototype file.

If your development area is not structured in the same way that you want yourpackage structured, you can use the path1=path2 format in the path field, where path1is the location it should have on the target system, and path2 is the location it has onyour system.

You can also use the path1=path2 path name format with path1 as a relocatable objectname and path2 a full path name to that object on your system.


Note - path1 may not contain undefined build variables, but may contain undefinedinstall variables. path2 may not contain any undefined variables, although both buildand install variables may be used. For information on the difference between installand build variables, see “Package Environment Variables” on page 13.

Links must use the path1= path2 format since they are created by the pkgaddcommand. As a general rule, path2 of a link should never be absolute, but shouldinstead be relative to the directory portion of path1.

An option to using the path1=path2 format is to use the !search command. For moreinformation, see “Providing a Search Path for the pkgmk Command” on page 31.

The mode FieldThe mode field may contain an octal number, a question mark (?), or a variablespecification. An octal number specifies the mode of the object when it is installed onthe target system. A ? means that the mode will be unchanged as the object isinstalled, implying that the object of the same name already exists on the targetsystem.

A variable specification of the form $mode, where the first letter of the variable mustbe a lowercase letter, means that this field will be set as the package is built. Notethat this variable must be defined at build time in either the prototype file or as anoption to the pkgmk command. For information on the difference between install andbuild variables, see “Package Environment Variables” on page 13.

Files with file type i (information file), l (hard link), and s (symbolic link), shouldleave this field blank.

The owner FieldThe owner field may contain a user name, a question mark (?), or a variablespecification. A user name has a maximum of 14 characters and should be a namethat already exists on the target system (such as, bin or root ). A ? means that theowner will be unchanged as the object is installed, implying that the object of thesame name already exists on the target system.

A variable specification can be of the form $Owner or $owner, where the first letter ofthe variable is either an uppercase letter or a lowercase letter. If the variable beginswith a lowercase letter, it must be defined as the package is built, either in theprototype file or as an option to the pkgmk command. If the variable begins withan uppercase letter, the variable specification will be inserted into the pkginfo fileas a default value, and may be redefined at install time via a request script. Forinformation on the difference between install and build variables, see “PackageEnvironment Variables” on page 13.


Files with file type i (information file) and l (hard link) should leave this field blank.

The group FieldThe group field may contain a group name, a question mark (?), or a variablespecification. A group name has a maximum of 14 characters and should be a namethat already exists on the target system (such as, bin or sys ). A ? means that thegroup will be unchanged as the object is installed, implying that the object of thesame name already exists on the target system.

A variable specification can be of the form $Group or $group, where the first letter ofthe variable is either an uppercase letter or a lowercase letter. If the variable beginswith a lowercase letter, it must be defined as the package is built, either in theprototype file or as an option to the pkgmk command. If the variable begins withan uppercase letter, the variable specification will be inserted into the pkginfo fileas a default value, and may be redefined at install time via a request script. Forinformation on the difference between install and build variables, see “PackageEnvironment Variables” on page 13.

Files with file type i (information file) and l (hard link) should leave this field blank.

Creating a prototype File From ScratchIf you want to create a prototype file from scratch, you can do so with yourfavorite text editor, adding one entry per package object. See “The Format of theprototype File” on page 20 and the prototype (4) man page for more informationon the format of the file. However, after you have defined each package object, youmight want to include some of the features described in “Adding Functionality to aprototype File” on page 29.

Creating a prototype File With the pkgprotoCommandYou can use the pkgproto command to build a basic prototype file, as long asyou have organized your package directory structure as described in “Organizing aPackage’s Contents” on page 18. For example, using the sample directory structureand pkginfo file described in previous sections, the commands for creating theprototype file are:

$ cd /home/jane$ pkgproto ./SUNWcadap > InfoFiles/prototype


The prototype file looks like:

d none SUNWcadap 0755 jane staffd none SUNWcadap/demo 0755 jane stafff none SUNWcadap/demo/file1 0555 jane staffd none SUNWcadap/srcfiles 0755 jane stafff none SUNWcadap/srcfiles/file5 0555 jane stafff none SUNWcadap/srcfiles/file6 0555 jane staffd none SUNWcadap/lib 0755 jane stafff none SUNWcadap/lib/file2 0644 jane staffd none SUNWcadap/man 0755 jane stafff none SUNWcadap/man/windex 0644 jane staffd none SUNWcadap/man/man1 0755 jane stafff none SUNWcadap/man/man1/file4.1 0444 jane stafff none SUNWcadap/man/man1/file3.1 0444 jane staff

Note - The actual owner and group of the person building the package is recordedby the pkgproto command. A good technique is to use the chown -R and thechgrp -R commands, setting the owner and group as intended before running thepkgproto command.

This prototype file is not yet complete. See “Fine-Tuning a prototype File CreatedWith the pkgproto Command” on page 27 for information on completing this file.

Fine-Tuning a prototype File Created With thepkgproto CommandAlthough the pkgproto command is useful in creating an initial prototype file, itdoes not create entries for every package object that needs to be defined, or makecomplete entries. The pkgproto command does not:

� Create complete entries for objects with file types v (volatile files), e (editablefiles), x (exclusive directories), or i (information files or installation scripts).

� Support multiple classes with a single invocation.

Therefore, you probably need to modify the prototype file to include at least someof these object definitions, possibly redefine path names and other field settings, andinclude some of the features described in “Adding Functionality to a prototypeFile” on page 29.


Creating Object Entries With File Types v , e, x , and i

At the very least, you need to modify the prototype file to add objects with filetype i . If you stored your information files and installation scripts in the first level ofyour package directory (for example, /home/jane/SUNWcadap/pkginfo ), then anentry in the prototype file would look like:

i pkginfo

If you did not store your information files and installation scripts in the first level ofyour package directory, then you need to specify their source location. For example:

i pkginfo=/home/jane/InfoFiles/pkginfo

Or, you can use the !search command to specify the location for the pkgmkcommand to look when building the package. See “Providing a Search Path for thepkgmk Command” on page 31 for more information.

To add entries for objects with file types v , e, and x , follow the format described in“The Format of the prototype File” on page 20, or refer to the prototype (4) manpage.

Note - Remember to always assign a class to files with a file type of e (editable) andhave an associated class action script for that class. Otherwise, the files will beremoved during package removal, even if the path name is shared with otherpackages.

Using Multiple Class DefinitionsIf you use the pkgproto command to create your basic prototype file, you canassign all of the package objects to the none class or one, specific class. As shown in“Creating a prototype File With the pkgproto Command” on page 26, the basicpkgproto command assigns all objects to the none class. To assign all objects to aspecific class, you can use the −c option. For example:

$ pkgproto -c classname /home/jane/SUNWcadap > /home/jane/InfoFiles/prototype

If you use multiple classes, you may need to manually edit the prototype file andmodify the class field for each object. If you use classes, you also need to define theCLASSESparameter in the pkginfo file and write class action scripts. As mentionedpreviously, using classes is an optional feature and is discussed in detail in “WritingClass Action Scripts” on page 62.


Example—Fine-Tuning a prototype File Created Using thepkgproto CommandGiven the prototype file created by the pkgproto command in “Creating aprototype File With the pkgproto Command” on page 26, there are severalmodifications that need to be made.

� There needs to be an entry for the pkginfo file.

� The path fields need to be modified to be the path1=path2 format, since the packagesource is in /home/jane . (Since the package source is a hierarchical directory, andthe !search command does not search recursively, it may be easier to use thepath1=path2 format.)

� The owner and group fields should contain the names of existing users and groupson the target system. That is, the owner jane will result in an error since thisowner is not part of the SunOSTM operating system.

The modified prototype file looks like:

i pkginfo=/home/jane/InfoFiles/pkginfod none SUNWcadap=/home/jane/SUNWcadap 0755 root sysd none SUNWcadap/demo=/home/jane/SUNWcadap/demo 0755 root binf none SUNWcadap/demo/file1=/home/jane/SUNWcadap/demo/file1 0555 root bind none SUNWcadap/srcfiles=/home/jane/SUNWcadap/srcfiles 0755 root binf none SUNWcadap/srcfiles/file5=/home/jane/SUNWcadap/srcfiles/file5 0555 root binf none SUNWcadap/srcfiles/file6=/home/jane/SUNWcadap/srcfiles/file6 0555 root bind none SUNWcadap/lib=/home/jane/SUNWcadap/lib 0755 root binf none SUNWcadap/lib/file2=/home/jane/SUNWcadap/lib/file2 0644 root bind none SUNWcadap/man=/home/jane/SUNWcadap/man 0755 bin binf none SUNWcadap/man/windex=/home/jane/SUNWcadap/man/windex 0644 root otherd none SUNWcadap/man/man1=/home/jane/SUNWcadap/man/man1 0755 bin binf none SUNWcadap/man/man1/file4.1=/home/jane/SUNWcadap/man/man1/file4.1 0444 bin binf none SUNWcadap/man/man1/file3.1=/home/jane/SUNWcadap/man/man1/file3.1 0444 bin bin

Adding Functionality to a prototype FileBesides defining every package object in the prototype file, you can also:

� Define additional objects to be created at install time.

� Create links at install time.

� Distribute packages over multiple volumes.

� Nest prototype files.

� Set a default value for the mode, owner, and group fields.

� Provide a search path for the pkgmk command.

� Set environment variables.

See the following sections for information on making these changes.


Defining Additional Objects to Be Created at Install TimeYou can use the prototype file to define objects that are not actually delivered onthe installation medium. During installation, using the pkgadd command, theseobjects are created with the required file types, if they do not already exist at thetime of installation.

To specify that an object be created on the target system, add an entry for it in theprototype file with the appropriate file type.

For example, if you want a directory created on the target system, but do not want todeliver it on the installation medium, make the following entry for the directory inthe prototype file:

d none / directory 0644 root other

If you want to create an empty file on the target system, an entry for the file in theprototype file might look like:

f none filename=/dev/null 0644 bin bin

The only objects that must be delivered on the installation medium are regular filesand edit scripts (file types e, v , f ) and the directories required to contain them. Anyadditional objects are created without reference to the delivered objects, directories,named pipes, devices, hard links, and symbolic links.

Creating Links at Install TimeTo create links during package installation, define the following in the prototypefile entry for the linked object:

� Its file type as l (a link) or s (a symbolic link).

� Its path name with the format path1=path2 where path1 is the destination and path2is the source file. As a general rule, path2 of a link should never be absolute, butshould instead be relative to the directory portion of path1. For example, aprototype file entry defining a symbolic link could be:

s none etc/mount=../usr/etc/mount

Relative links would be specified in this manner whether the package is installed asabsolute or relocatable.

Distributing Packages Over Multiple VolumesWhen you build your package with the pkgmk command, it performs thecalculations and actions necessary to organize a multiple volume package. Amultiple volume package is called a segmented package.


However, you can use the optional part field in the prototype file to define inwhich part you want an object to be located. A number in this field overrides thepkgmk command and forces the placement of the component into the part given inthe field. Note that there is a one-to-one correspondence between parts and volumesfor removable media formatted as file systems. If the volumes are preassigned by thedeveloper, the pkgmk command will issue an error if there is insufficient space onany volume.

Nesting prototype FilesYou can create multiple prototype files and then include them, using the !includecommand in the prototype file. You might want to do this for easier maintenance.

In the following example there are three prototype files, the main one (prototype )being edited, and the two (proto2 and proto3 ) that are being included.

!include / source-dir/proto2!include / source-dir/proto3

Setting Default Values for the mode, owner, and group FieldsTo set default values for the mode, owner, and group fields for specific package objects,you can insert the !default command into the prototype file. For example,

!default 0644 root other

Note - This command’s range starts from where it is inserted and extends to the endof the file, but does not span to included files.

However, for directories (file type d) and editable files (file type e) that you knowexist on target systems (like /usr or /etc/vfstab ), make sure that the mode, owner,and group fields in the prototype file are set to question marks (?). That way youwill not destroy existing settings that a site administrator may have modified.

Providing a Search Path for the pkgmk CommandIf the source location for package objects is different than their destination location,and you do not want to use the path1=path2 format as described in “A Brief Word onan Object’s Source and Destination Locations” on page 24, then you can use the!search command in the prototype file. For example, if you created a directory,pkgfiles , in your home directory, and it contains all of your information files andinstallation scripts, you can specify that that directory be searched when the packageis built with the pkgmk command.


The command in the prototype file would look like:

!search / home-dir/pkgfiles

Note - Search requests do not span to included files. In addition, a search is limitedto the specific directories listed, and will not search recursively.

Set Environment Variables

You can also add commands to the prototype file of the form ! PARAM=value.Commands of this form define variables in the current environment. If you havemultiple prototype files, the scope of this command is local to the prototype filewhere it is defined.

The variable PARAM can begin with either a lowercase or uppercase letter, but itsvalue must be known at build time, or the pkgmk command will abort with an error.For more information on the difference between build and install variables, see“Package Environment Variables” on page 13.

How to Create a prototype File Using thepkgproto Command

Note - It is easier to create information files and installation scripts before creating aprototype file. However, this is not required, and you can always edit theprototype file after changing your package contents. For more information oninformation files and installation scripts, see Chapter 3.

1. Determine which package objects will be absolute and which will berelocatable, if not done already.

For information that will help you complete this task, see “The path Field” onpage 22.

2. Organize your package’s objects to mimic their location on the target system.

If you already organized your packages as described in “Organizing a Package’sContents” on page 18, note that you may need to make some changes based onyour decisions in Step 1 on page 32. If you have not organized your package yet,you should do so now (otherwise you cannot use the pkgproto command tocreate a basic prototype file).

3. If your package has collectively relocatable objects, edit the pkginfo file to setthe BASEDIR parameter to the appropriate value.

For example,


BASEDIR=/opt

For information on collectively relocatable objects, see “Collectively RelocatableObjects” on page 22.

4. If your package has individually relocatable objects, create a request script toprompt the installer for the appropriate path name or a checkinstall scriptto determine the appropriate path from file system data.

For information on creating a request script, see “How to Write a requestScript” on page 56. For information on creating a checkinstall script, see“How to Gather File System Data” on page 58. For information on individuallyrelocatable objects, see “Individually Relocatable Objects” on page 23.

5. Change the owner and group on all of your package components to be theintended owner and group on the target systems.

Use the chown -R and the chgrp -R commands on your package directory andinformation files directory.

6. Execute the pkgproto command to create a basic prototype file.

The pkgproto command scans your directories to create a basic file. For example,

$ cd package-directory$ pkgproto ./ package-directory > prototype

Like the pkginfo file, the prototype file can be located anywhere on yoursystem. However, it might be a good idea to keep your information files andinstallation scripts in one place, for easy access and maintenance. For additionalinformation on the pkgproto command, see the pkgproto (1) man page.

7. Edit the prototype file using your favorite text editor, and add entries for filesof type v , e, x , and i .

For information on the specific changes you may need to make, see “Fine-Tuninga prototype File Created With the pkgproto Command” on page 27.

8. Optional. If you are using multiple classes, edit the prototype and pkginfofiles using your favorite text editor to make the necessary changes, and createcorresponding class action scripts.

For information on the specific changes you may need to make, see “Fine-Tuninga prototype File Created With the pkgproto Command” on page 27 and“Writing Class Action Scripts” on page 62.


9. Edit the prototype file using your favorite text editor to redefine path namesand change other field settings.

For more information, see “Fine-Tuning a prototype File Created With thepkgproto Command” on page 27.

10. Optional. Edit the prototype file using your favorite text editor to addfunctionality to your prototype file.

For more information, see “Adding Functionality to a prototype File” on page29.


Where to Go NextIf you are ready to go to the next task, see “How to Build a Package” on page 35.

Building a PackageUse the pkgmk command to build your package. This command takes all of theobjects defined in the prototype file, puts them into directory format, creates thepkgmap file (replacing the prototype file), and produces an installable package tobe used as input to the pkgadd command.

Using the Simplest pkgmk CommandThe simplest form of this command is the pkgmk command itself, without anyoptions. Before using the pkgmk command without options, make sure your currentworking directory contains the package’s prototype file. The output of thecommand, files and directories, are written to the /var/spool/pkg directory.

The pkgmap FileWhen you build a package with the pkgmk command, it creates a pkgmap file thatreplaces the prototype file. The pkgmap file from the previous example looks like:

$ more pkgmap: 1 3170

(continued)


(Continuation)

1 d none SUNWcadap 0755 root sys1 d none SUNWcadap/demo 0755 root bin1 f none SUNWcadap/demo/file1 0555 root bin 14868 45617 8375274961 d none SUNWcadap/lib 0755 root bin1 f none SUNWcadap/lib/file2 0644 root bin 1551792 62372 8375274991 d none SUNWcadap/man 0755 bin bin1 d none SUNWcadap/man/man1 0755 bin bin1 f none SUNWcadap/man/man1/file3.1 0444 bin bin 3700 42989 8375275001 f none SUNWcadap/man/man1/file4.1 0444 bin bin 1338 44010 8375274991 f none SUNWcadap/man/windex 0644 root other 157 13275 8375274991 d none SUNWcadap/srcfiles 0755 root bin1 f none SUNWcadap/srcfiles/file5 0555 root bin 12208 20280 8375274971 f none SUNWcadap/srcfiles/file6 0555 root bin 12256 63236 8375274971 i pkginfo 140 10941 837531104$

The format of this file is very similar to that of the prototype file. However, thepkgmap file includes the following information.

� The first line indicates the number of volumes that the package spans, and theapproximate size the package will be when installed.

For example, : 1 3170 indicates that the package spans one volume and will useapproximately 3170 512-byte blocks when it is installed.

� There are three additional fields defining the size, checksum, and modificationtime for each package object.

� The package objects are listed in alphabetical order by class and by path name toenhance the time it takes to install the package.

How to Build a Package1. Create a pkginfo file, if not done already.

For step-by-step instructions, see “How to Create a pkginfo File” on page 17.

2. Create a prototype file, if not done already.

For step-by-step instructions, see “How to Create a prototype File Using thepkgproto Command” on page 32.

3. Make your current working directory the same directory that contains yourpackage’s prototype file.

4. Build the package.


pkgmk [-o] [-a arch] [-b base-src-dir] [-d device][-f filename] [-l limit] [-p pstamp] [-r rootpath]

[-v version] [ PARAM=value] [ pkginst]

−oOverwrites the existing version of the package.

−a arch Overrides the architecture information in the pkginfo file.

−b base-src-dir Requests that base-src-dir be added to the beginning ofrelocatable path names when the pkgmk command issearching for objects on the development system.

−d device Specifies that the package should be copied onto device,which may be a an absolute directory path name, diskette,or removable disk.

−f filename Names a file, filename, that is used as your prototypefile. The default names are prototype or Prototype .

−l limit Specifies the maximum size, in 512-byte blocks, of theoutput device.

−p pstamp Overrides the production stamp definition in thepkginfo file.

−r rootpath Requests that the root directory rootpath be used to locateobjects on the development system.

−v version Overrides the version information in the pkginfo file.

PARAM=value Sets global environment variables. Variables beginningwith lowercase letters are resolved at build time. Thosebeginning with uppercase letters are placed into thepkginfo file for use at install time.

pkginst Specifies a package by its package abbreviation or aspecific instance (for example, SUNWcadap.4)

For more information, see the pkgmk(1) man page.

5. Verify the contents of the package.


$ pkgchk -d pkg-dir pkg-abbrevChecking uninstalled directory format package pkg-abbrev

from pkg-dir## Checking control scripts.## Checking package objects.## Checking is complete.$

−d device-name Specifies the location of the package. Note that device-namecan be a full directory path name or the identifiers for atape, floppy disk, or removable disk.

pkgid Is the name of one or more packages (separated byspaces) to be checked. If omitted, pkgchk checks allavailable packages.

The pkgchk command prints what aspects of the package are being checked anddisplays warnings or errors, as appropriate. For more information on the pkgchkcommand, see “Verifying the Integrity of a Package” on page 76.”

Note - Errors should be considered very seriously; it may mean that a script needsfixing. However, a warning may just be a comment on the style of a script. Checkit and move on if you disagree with the output from the pkgchk command.

Where to Go NextIf you want to add any optional information files and installation scripts to yourpackage, see Chapter 3. Otherwise, after you build the package, you should verify itsintegrity. Chapter 4 explains how to do this, and provides step-by-step instructionson how to transfer your verified package to a distribution medium.

Example—Building a PackageThis example uses the prototype file created in “Fine-Tuning a prototype FileCreated With the pkgproto Command” on page 27.

$ cd /home/jane/InfoFiles$ pkgmk## Building pkgmap from package prototype file.## Processing pkginfo file.WARNING: parameter set to " system960716093144"WARNING: parameter set to "none"


(Continuation)

## Attempting to volumize 13 entries in pkgmap.part 1 -- 3170 blocks, 17 entries## Packaging one part./var/spool/pkg/SUNWcadap/pkgmap/var/spool/pkg/SUNWcadap/pkginfo/var/spool/pkg/SUNWcadap/reloc/SUNWcadap/demo/file1/var/spool/pkg/SUNWcadap/reloc/SUNWcadap/lib/file2/var/spool/pkg/SUNWcadap/reloc/SUNWcadap/man/man1/file3.1/var/spool/pkg/SUNWcadap/reloc/SUNWcadap/man/man1/file4.1/var/spool/pkg/SUNWcadap/reloc/SUNWcadap/man/windex/var/spool/pkg/SUNWcadap/reloc/SUNWcadap/srcfiles/file5/var/spool/pkg/SUNWcadap/reloc/SUNWcadap/srcfiles/file6## Validating control scripts.## Packaging complete.$

Example—Specifying a Source Directory for Relocatable Files

If your package contains relocatable files, you can use the −b base-src-dir option to thepkgmk command to specify a path name to be added to the beginning of therelocatable path names while the package is being created. This is useful if youhaven’t used the path1=path2 format for relocatable files or specified a search pathwith the !search command in the prototype file.

For example, to build a package using the sample prototype file created by thepkgproto command (see “Creating a prototype File With the pkgprotoCommand” on page 26), without modifying the path fields, and just adding an entryfor the pkginfo file, the pkgmk command is:

$ cd /home/jane/InfoFiles$ pkgmk -o -b /home/jane## Building pkgmap from package prototype file.## Processing pkginfo file.WARNING: parameter set to " system960716102636"WARNING: parameter set to "none"## Attempting to volumize 13 entries in pkgmap.part 1 -- 3170 blocks, 17 entries## Packaging one part./var/spool/pkg/SUNWcadap/pkgmap/var/spool/pkg/SUNWcadap/pkginfo/var/spool/pkg/SUNWcadap/reloc/SUNWcadap/demo/file1/var/spool/pkg/SUNWcadap/reloc/SUNWcadap/lib/file2/var/spool/pkg/SUNWcadap/reloc/SUNWcadap/man/man1/file3.1/var/spool/pkg/SUNWcadap/reloc/SUNWcadap/man/man1/file4.1/var/spool/pkg/SUNWcadap/reloc/SUNWcadap/man/windex/var/spool/pkg/SUNWcadap/reloc/SUNWcadap/srcfiles/file5/var/spool/pkg/SUNWcadap/reloc/SUNWcadap/srcfiles/file6## Validating control scripts.

(continued)


(Continuation)

## Packaging complete.

In this example, the package is built in the default directory, /var/spool/pkg , byspecifying the −o option (to overwrite the package we created in“Example—Building a Package” on page 37).

Example—Specifying Different Source Directories forInformation Files and Package ObjectsIf you put package information files (such as pkginfo and prototype ) and thepackage objects in two different directories, you can create your package by usingthe −b base-src-dir and −r rootpath options to the pkgmk command. If you have yourpackage objects in a directory called /product/pkgbin and the other packageinformation files in a directory called /product/pkgsrc , you could use thefollowing command to place the package in the /var/spool/pkg directory:

$ pkgmk -b /product/pkgbin -r /product/pkgsrc -f /product/pkgsrc/prototype

Optionally, you could use this command to do the same:

$ cd /product/pkgsrc$ pkgmk -o -b /product/pkgbin

In this example, the pkgmk command uses the current working directory to find theremaining parts of the package (like the prototype and pkginfo information files).


CHAPTER 3

Enhancing the Functionality of aPackage

This chapter describes how to create optional information files and installationscripts for a package. While Chapter 2 discussed the minimum requirements formaking a package, this chapter discusses additional functionality that you can buildinto a package, based on the criteria you considered when planning how to designyour package (for more information, see “Things to Think About Before Building aPackage” on page 5).


� “Task Map: Creating Information Files and Installation Scripts” on page 41

� “Creating Information Files” on page 43

� “Creating Installation Scripts” on page 50

Task Map: Creating Information Filesand Installation ScriptsTable 3–1 lists and describes the optional features you can build into a package.

41

TABLE 3–1 Task Map: Creating Information Files and Installation Scripts


Define Package Dependencies.A definition of packagedependencies allows you tospecify whether yourpackage is compatible withprevious versions,dependent on otherpackages, or whether otherpackages are dependent onyours.

“How to Define Package Dependencies”on page 44

Provide a Copyright Message.A copyright file provideslegal protection for yoursoftware application.

“How to Write a Copyright Message” onpage 47

Create InformationFiles

Create Additional Space on theTarget System. A space filesets aside blocks on thetarget system, whichenables you to create filesduring installation that arenot defined in the pkgmapfile.

“How to Reserve Additional Space on aTarget System” on page 48


TABLE 3–1 Task Map: Creating Information Files and Installation Scripts (continued)


Obtain Information From theInstaller. A request scriptenables you to obtaininformation from the personinstalling your package.

“How to Write a request Script” onpage 56

Gather File System DataNeeded For Installation. Acheckinstall scriptenables you to perform ananalysis of the target systemand set up the correctenvironment for, or cleanlyhalt, the installation.

“How to Gather File System Data” onpage 58

Write Procedure Scripts.Enables you to providecustomized installationinstructions during specificphases of the installation orremoval process.

“How to Write Procedure Scripts” onpage 61

Create InstallationScripts

Write Class Action Scripts.Enables you to specify a setof instructions to beexecuted during packageinstallation and removal onspecific groups of packageobjects.

“How to Write Class Action Scripts” onpage 68

Creating Information FilesThis section discusses optional package information files. With these files you candefine package dependencies, provide a copyright message, and reserve additionalspace on a target system.

Enhancing the Functionality of a Package 43

Defining Package DependenciesYou need to determine whether your package has dependencies on other packagesand if any other packages depend on yours. Package dependencies andincompatibilities can be defined with two of the optional package information files,compver and depend . Delivering a compver file lets you name previous versions ofyour package that are compatible with the one being installed. Delivering a dependfile lets you define three types of dependencies associated with your package. Thesedependency types are:

� A prerequisite package – meaning your package depends on the existence of anotherpackage

� A reverse dependency – meaning another package depends on the existence of yourpackage

Note - Use the reverse dependency type only when a package that cannot deliver adepend file relies on your package.

� An incompatible package (meaning your package is incompatible with the namedpackage)

The depend file resolves only very basic dependencies. If your package dependsupon a specific file or its contents or behavior, the depend file does not supplyadequate precision. In this case a request script or (for the Solaris 2.5 and lateroperating environments) the checkinstall script should be used for detaileddependency checking. The checkinstall script is also the only script capable ofcleanly halting the package installation process.

Note - Be certain that your depend and compver files have entries in theprototype file. The file type should be i (for package information file).

Refer to the depend (4) and compver (4) man pages for more information.

How to Define Package Dependencies1. Make the directory containing your information files the current working

directory.

2. If previous versions of your package exist and you need to specify that yournew package is compatible with them, create a file named compver with yourfavorite text editor.

List the versions with which your package is compatible, using this format:

string string . . .

where


string Is identical to the value assigned to the VERSIONparameter in the pkginfo file, for each compatiblepackage.


4. If your package depends on the existence of other packages, other packagesdepend on the existence of your package, or your package is incompatible withanother package, create a file named depend with your favorite text editor.

Add an entry for each dependency, using this format:

type pkg-abbrev pkg-name( arch) version( arch) version . . .

where

type Defines the dependency type. Must be one of thefollowing characters: P (prerequisite package), I(incompatible package), or R (reverse dependency).

pkg-abbrev Specifies the package abbreviation, such as SUNWcadap.

pkg-name Sepcifies the full package name, such as Chipdesigners need CAD application software todesign abc chips. Runs only on xyz hardware andis installed in the usr partition.

( arch) Optional. Specifies the type of hardware on which thepackage runs. For example, sparc or x86 . If you specifyan architecture, you must use the parentheses asdelimeters.

version Optional. Specifies the value assigned to the VERSIONparameter in the pkginfo file.

For more information, see the depend (4) man page.


6. Complete one of the following tasks:


� If you want to create additional information files and installation scripts, skipto the next task, “How to Write a Copyright Message” on page 47.

� If you have not created your prototype file, complete the procedure “How toCreate a prototype File Using the pkgproto Command” on page 32, andskip to Step 7 on page 46.

� If you have already created your prototype file, edit it and add an entry foreach file you just created.

7. Build your package.

See “How to Build a Package” on page 35, if needed.

Where to Go NextAfter you build the package, install it to confirm that it installs correctly and verifyits integrity. Chapter 4 explains how to do this and provides step-by-step instructionson how to transfer your verified package to a distribution medium.

Example—compver FileIn this example, there are four versions of a package: 1.0, 1.1, 2.0, and the newpackage, 3.0, which is compatible with all the three previous versions. The compverfile for the newest version might look like:

release 3.0release 2.0version 1.11.0

Note - The entries do not have to be in sequential order. However, they shouldexactly match the definition of the VERSIONparameter in each package’s pkginfofile. In this example, the package designers used different formats in the first threeversions.

Example—depend FileThis example assumes that the sample package, SUNWcadap, requires that theSUNWcsr and SUNWcsupackages already be installed on a target system. Thedepend file for SUNWcadaplooks like:


P SUNWcsr Core Solaris, (Root)P SUNWcsu Core Solaris, (Usr)

Writing a Copyright MessageYou need to decide whether your package should display a copyright message whileit is being installed. If so, create the copyright file.

Note - You should include a copyright file to provide legal protection for yoursoftware application. It might be a good idea to check with the legal department ofyour company for the exact wording of the message.

To deliver a copyright message, you must create a file named copyright . Duringinstallation, the message is displayed exactly as it appears in the file (with noformatting). See the copyright (4) man page for more information.

Note - Be certain that your copyright file has an entry in the prototype file. Itsfile type should be i (for package information file).

How to Write a Copyright Message1. Make the directory containing your information files the current working

directory.

2. Create a file named copyright with your favorite text editor.

Enter the text of the copyright message exactly as you want it to appear as yourpackage is installed.


4. Complete one of the following tasks.

� If you want to create additional information files and installation scripts, skipto the next task, “How to Reserve Additional Space on a Target System” onpage 48.


� If you have already created your prototype file, edit it and add an entry forthe information file you just created.





Example—copyright FileFor example, a partial copyright message might look like:

Copyright (c) 1996 Company NameAll Rights Reserved

This product is protected by copyright and distributed underlicenses restricting copying, distribution and decompilation.

Reserving Additional Space on a Target SystemYou need to determine whether your package needs additional disk space on thetarget system (space in addition to that required by the package objects). If so, createthe space information file. This is different than creating empty files and directoriesat installation time as discussed in “Defining Additional Objects to Be Created atInstall Time” on page 30.

While the pkgadd command ensures that there is enough disk space to install yourpackage based on the object definitions in the pkgmap file, a package may requireadditional disk space beyond that needed by the objects defined in the pkgmap file.For example, your package might create a file after installation, which may contain adatabase, log files, or some other growing file that consumes disk space. To be surethat there is space set aside for it, you should include a space file specifying thedisk space requirements. The pkgadd command checks for the additional spacespecified in a space file. Refer to the space (4) man page for more information.

Note - Be certain that your space file has an entry in the prototype file. Its filetype should be i (for package information file).

How to Reserve Additional Space on a TargetSystem1. Make the directory containing your information files the current working

directory.

2. Create a file named space with your favorite text editor.


Enter any additional disk space requirements needed by your package, using thisformat:

pathname blocks inodes

where

pathname Specifies a directory name, which may or may not be themount point for a file system.

blocks Specifies the number of 512-byte blocks that you wantreserved.

inodes Specifies the number of required inodes.

For more information, see the space (4) man page.



� If you want to create installation scripts, skip to the next task, “How to Write arequest Script” on page 56.

� If you have not created your prototype file, complete the procedure in “Howto Create a prototype File Using the pkgproto Command” on page 32, andskip to Step 5 on page 49.

� If you have already created your prototype file, edit it and add an entry forthe information file you just created.




Example—space FileThis example space file specifies that 1000 512-byte blocks and 1 inode be set asidein /opt on the target system.


/opt 1000 1

Creating Installation ScriptsThis section discusses optional package installation scripts. The pkgadd commandautomatically performs all the actions necessary to install a package using thepackage information files as input. You do not have to supply any packageinstallation scripts. However, if you want to create customized installation proceduresfor your package, you can do so with installation scripts. Installation scripts:

� Must be executable by the Bourne shell (sh ).

� Must contain Bourne shell commands and text.

� Do not need to contain the #!/bin/sh shell identifier.

� Need not be an executable file.

There are four types of installation scripts with which you can perform customizedactions:

� The request script

The request script solicits data from the administrator installing a package forassigning or redefining environment variables.

� The checkinstall script

The checkinstall script examines the target system for needed data, can set ormodify package environment variables, and determines whether or not theinstallation proceeds.

Note - The checkinstall script is only available with the Solaris 2.5 and lateroperating environments.

� Procedure scripts

Procedure scripts identify a procedure to be invoked before or after the installationor removal of a package. The four procedure scripts are preinstall ,postinstall , preremove , and postremove .

� Class action scripts

Class action scripts define an action or set of actions that should be applied to aclass of files during installation or removal. You can define your own classes oruse one of the three standard classes (sed , awk, and build ).


Script Processing During Package InstallationThe type of scripts you use depends on when the action of the script is neededduring the installation process. As a package is installed, the pkgadd commandperforms the following steps:

1. Executes the request script.

This is the only point at which your package can solicit input from theadministrator installing the package.

2. Executes the checkinstall script.

The checkinstall script gathers file system data and can create or alterenvironment variable definitions to control the subsequent installation. For moreinformation on package environment variables, see “Package EnvironmentVariables” on page 13.

3. Executes the preinstall script.

4. Installs package objects, for each class to be installed.

Installation of these files occurs class by class, and class action scripts are executedaccordingly. The list of classes operated on and the order in which they should beinstalled is initially defined with the CLASSESparameter in your pkginfo file.However, your request script or checkinstall script can change the value ofthe CLASSESparameter. For more information on how classes are processedduring installation, see “How Classes Are Processed During Installation” on page62.

a. Creates symbolic links, devices, named pipes, and required directories.

b. Installs the regular files (file types e, v , f ), based on their class.

The class action script is passed only regular files to install. All other packageobjects are created automatically from information in the pkgmap file.

c. Creates all hard links.

5. Executes the postinstall script.

Script Processing During Package RemovalWhen a package is being removed, the pkgrm command performs these steps:

1. Executes the preremove script.

2. Removes the package objects, for each class.

Removal also occurs class by class. Removal scripts are processed in the reverseorder of installation, based on the sequence defined in the CLASSESparameter.For more information on how classes are processed during installation, see “HowClasses Are Processed During Installation” on page 62.

a. Removes hard links.

b. Removes regular files.

c. Removes symbolic links, devices, and named pipes.


3. Executes the postremove script.

The request script is not processed at the time of package removal. However, itsoutput (a list of environment variables) is retained in the installed package and madeavailable to removal scripts.

Package Environment Variables Available toScriptsThe following four groups of environment variables are available to all installationscripts. Some of the environment variables can be modified by a request orcheckinstall script.

� The 19 standard parameters that can be defined in the pkginfo file. Of these, therequest or checkinstall script can only modify the CLASSESand theBASEDIRparameters. The standard installation parameters are described in detailin the pkginfo (4) man page.

Note - The BASEDIRparameter can only be modified with the Solaris 2.5 and laterreleases.

� You can define your own installation environment variables by assigning values tothem in the pkginfo file. Such environment variables must be alphanumeric withinitial capital letters. Any of these environment variables can be changed by arequest or checkinstall script.

� Both a request script and a checkinstall script can define new environmentvariables by assigning values to them and putting them in the installationenvironment.

� Table 3–2 lists environment variables that are available to all installation scriptsthrough the environment. None of these can be modified by a script.


TABLE 3–2 Package Environment Variables Available to Scripts

Environment Variable Description

CLIENT_BASEDIR The base directory with respect to the target system. While BASEDIRis the variable to use if you are referring to a specific package objectfrom the install system (most likely a server), CLIENT_BASEDIR is thepath to include in files placed on the client system. CLIENT_BASEDIRexists if BASEDIR exists and is identical to BASEDIR if there is noPKG_INSTALL_ROOT.

INST_DATADIR The directory where the package now being read is located. If thepackage is being read from a tape, this will be the location of atemporary directory where the package has been transferred intodirectory format. In other words, assuming there is no extension to thepackage name (for example, SUNWstuff.d ), the request script forthe current package would be found at $INST_DATADIR/$PKG/install .

PATH The search list used by sh to find commands on script invocation.PATHis usually set to /sbin:/usr/sbin:/usr/bin:/usr/sadm/install/bin

PKGINST The instance identifier of the package being installed. If anotherinstance of the package is not already installed, the value is thepackage abbreviation (for example, SUNWcadap). Otherwise, it is thepackage abbreviation followed by a suffix, such as SUNWcadap.4.

PKGSAV The directory where files can be saved for use by removal scripts orwhere previously saved files can be found. Available only in theSolaris 2.5 and later releases.

PKG_INSTALL_ROOT The root file system on the target system where the package is beinginstalled. It exists only if the pkgadd and pkgrm commands wereinvoked with the −R option. This conditional existence facilitates its usein procedure scripts in the form ${PKG_INSTALL_ROOT}/ somepath.

PKG_NO_UNIFIED Is an environment variable that gets set if the pkgadd and pkgrmcommands were invoked with the −Mand −R options. Thisenvironment variable is passed to any package installation script orpackage command that is part of the package environment.

UPDATE This environment variable does not exist under most installationenvironments. If it does exist (with the value yes ), it means that apackage with the same name, version, and architecture is alreadyinstalled on the system or that this package is overwriting an installedpackage of the same name at the direction of the administrator. Inthese events, the original base directory is always used.


Obtaining Package Information for a ScriptTwo commands can be used from scripts to solicit information about a package:

� The pkginfo command returns information about software packages, such as theinstance identifier and package name.

� The pkgparam command returns values for requested environment variables.

See the pkginfo (1) and pkgparam (1) man pages and Chapter 4 for moreinformation.

Exit Codes for ScriptsEach script must exit with one of the exit codes shown in Table 3–3.

TABLE 3–3 Installation Script Exit Codes

Code Meaning

0 Successful completion of script.

1 Fatal error. Installation process is terminated at this point.

2 Warning or possible error condition. Installation continues. A warning message isdisplayed at the time of completion.

3 The pkgadd command is cleanly halted. Only the checkinstall script returnsthis code,

10 System should be rebooted when installation of all selected packages is completed.(This value should be added to one of the single-digit exit codes described above.)

20 System should be rebooted immediately upon completing installation of thecurrent package. (This value should be added to one of the single-digit exit codesdescribed above.)

See Chapter 5 for examples of exit codes returned by installation scripts.

Note - All installation scripts delivered with your package should have an entry inthe prototype file. The file type should be i (for package installation script).


Writing a request ScriptThe request script is the only way your package can interact directly with theadministrator installing it. It can be used, for example, to ask the administrator ifoptional pieces of a package should be installed.

The output of a request script must be a list of environment variables and theirvalues. This list can include any of the parameters you created in the pkginfo fileand the CLASSESand BASEDIR parameters. The list can also introduce environmentvariables that have not been defined elsewhere (although the pkginfo file shouldalways provide default values, when practical). For more information on packageenvironment variables, see “Package Environment Variables” on page 13.

When your request script assigns values to a environment variable, it must thenmake those values available to the pkgadd command and other package scripts.

request Script Behaviors� The request script cannot modify any files. It only interacts with administrators

installing the package and creates a list of environment variable assignments basedupon that interaction. To enforce this restriction, the request script is executed asthe non-privileged user install if that user exists; otherwise it is executed as thenon-privileged user nobody . The request script does not have superuserauthority.

� The pkgadd command calls the request script with one argument that namesthe script’s response file (the file that stores the administrator’s responses).

� The request script is not executed during package removal. However, theenvironment variables assigned by the script are saved and are available duringremoval.

Design Rules for request Scripts� There can be only one request script per package and it must be named

request .

� The environment variable assignments should be added to the installationenvironment for use by the pkgadd command and other packaging scripts bywriting them to the response file (known to the script as $1).

� System environment variables and standard installation environment variables,except for the CLASSESand BASEDIRparameters, cannot be modified by arequest script. Any of the other environment variables you created can bechanged.

Note - A request script can only modify the BASEDIRparameter as of Solaris 2.5and later releases.


� Every environment variable that the request script may manipulate should beassigned a default value in the pkginfo file.

� The format of the output list should be PARAM=value. For example:

CLASSES=none class1

� The administrator’s terminal is defined as standard input to the request script.

� Do not perform any special analysis of the target system in a request script. It isrisky to test the system for the presence of certain binaries or behaviors, and setenvironment variables based upon that analysis, because there is no guarantee thatthe request script will actually be executed at install time. The administratorinstalling the package may provide a response file that will insert the environmentvariables without ever calling the request script. If the request script is alsoevaluating the target file system, that evaluation may not happen. An analysis ofthe target system for special treatment is best left to the checkinstall script.

Note - If it is possible that the administrators who will be installing your packagewill be using the JumpStartTM product, then the installation of your package must notbe interactive. This implies that either you should not provide a request script withyour package, or you need to communicate to the administrator that they should usethe pkgask command, prior to installation, to store their responses to the requestscript. For more information on the pkgask command, see the pkgask (1M) manpage.

How to Write a request Script1. Make the directory containing your information files the current working

directory.

2. Create a file named request with your favorite text editor.

3. Save your changes and quit the editor when you are done.


� If you want to create additional installation scripts, skip to the next task, “Howto Gather File System Data” on page 58.


� If you have already created your prototype file, edit it and add an entry forthe installation script you just created.





Example—Writing a request ScriptWhen a request script assigns values to environment variables, it must make thosevalues available to the pkgadd command. This example shows a request scriptsegment that performs this task for the four environment variables CLASSES,NCMPBIN, EMACS, and NCMPMAN. (These were defined in an interactive session withthe administrator earlier in the script.)

# make environment variables available to installation# service and any other packaging script we might have

cat >$1 <<!CLASSES=$CLASSESNCMPBIN=$NCMPBIEMACS=$EMACSNCMPMAN=$NCMPMAN!

Gathering Data With the checkinstall ScriptThe checkinstall script is executed shortly after the optional request script. Itruns as the user install , if such a user exists, or the user nobody . Thecheckinstall script does not have the authority to change file system data; it isstrictly a data gatherer. However, based on the information it gathers, it can create ormodify environment variables in order to control the course of the resultinginstallation. It is also capable of cleanly halting the installation process.

The checkinstall script is intended to perform basic checks on a file system thatwould not be normal for the pkgadd command. For example, it can be used to checkahead to determine if any files from the current package are going to overwriteexisting files, or manage general software dependencies (the depend file onlymanages package-level dependencies).

Unlike the request script, the checkinstall script is executed whether or not aresponse file is provided; and, its presence does not brand the package as“interactive.” This means that the checkinstall script can be used in situationswhere a request script is forbidden or administrative interaction is not practical.

Note - The checkinstall script is available with the Solaris 2.5 and later releases.


checkinstall Script Behaviors� The checkinstall script cannot modify any files. It only analyzes the state of

the system and creates a list of environment variable assignments based upon thatinteraction. To enforce this restriction, the checkinstall script is executed as thenon-privileged user install if that user exists; otherwise it is executed as thenon-privileged user nobody . The checkinstall script does not have superuserauthority.

� The pkgadd command calls the checkinstall script with one argument thatnames the script’s response file (the file that stores the administrator’s responses).

� The checkinstall script is not executed during package removal. However, theenvironment variables assigned by the script are saved and are available duringremoval.

Design Rules for checkinstall Scripts� There can be only one checkinstall script per package and it must be named

checkinstall .

� The environment variable assignments should be added to the installationenvironment for use by the pkgadd command and other packaging scripts bywriting them to the response file (known to the script as $1).

� System environment variables and standard installation environment variables,except for the CLASSESand BASEDIRparameters, cannot be modified by acheckinstall script. Any of the other environment variables you created can bechanged.

� Every environment variable that the checkinstall script may manipulateshould be assigned a default value in the pkginfo file.

� The format of the output list should be PARAM=value. For example:

CLASSES=none class1

� Administrator interaction is not permitted during execution of a checkinstallscript. All administrator interaction is restricted to the request script.

How to Gather File System Data1. Make the directory containing your information files the current working

directory.

2. Create a file named checkinstall with your favorite text editor.

3. Save your changes and quit the editor when you are done.



� If you want to create additional installation scripts, skip to the next task, “Howto Write Procedure Scripts” on page 61.


� If you have already created your prototype file, edit it and add an entry forthe installation script you just created.




Example—Writing a checkinstall ScriptThis example checkinstall script checks to see if database software needed by theSUNWcadappackage is installed.

# checkinstall script for SUNWcadap## This confirms the existence of the required specU database

# First find which database package has been installed.pkginfo -q SUNWspcdA # try the older one

if [ $? -ne 0 ]; thenpkginfo -q SUNWspcdB # now the latest

if [ $? -ne 0 ]; then # oopsecho "No database package can be found. Please install the"echo "SpecU database package and try this installation again."exit 3 # Suspend

elseDBBASE="‘pkgparam SUNWsbcdB BASEDIR‘/db" # new DB software

fielse

DBBASE="‘pkgparam SUNWspcdA BASEDIR‘/db" # old DB softwarefi

# Now look for the database file we will need for this installationif [ $DBBASE/specUlatte ]; then

exit 0 # all OKelse

echo "No database file can be found. Please create the database"

(continued)


(Continuation)

echo "using your installed specU software and try this"echo "installation again."exit 3 # Suspend

fi

Writing Procedure ScriptsThe procedure scripts provide a set of instructions to be performed at particularpoints in package installation or removal. The four procedure scripts must be namedone of the predefined names, depending on when the instructions are to be executed,and are executed without arguments.

� The preinstall script

Runs before class installation begins. No files should be installed by this script.

� The postinstall script

Runs after all volumes have been installed.

� The preremove script

Runs before class removal begins. No files should be removed by this script.

� The postremove script

Runs after all classes have been removed.

Procedure Script BehaviorsProcedure scripts are executed as uid=root and gid=other .

Design Rules for Procedure Scripts� Each script should be able to be executed more than once since it is executed once

for each volume in a package. This means that executing a script any number oftimes with the same input produces the same results as executing the script onlyonce.

� Each procedure script that installs a package object not in the pkgmap file mustuse the installf command to notify the package database that it is adding ormodifying a path name. After all additions or modifications are complete, thiscommand should be invoked with the −f option. Only postinstall andpostremove scripts may install package objects in this way. See theinstallf (1M) man page and Chapter 5 for more information.


� Administrator interaction is not permitted during execution of a procedure script.All administrator interaction is restricted to the request script.

� Each procedure script that removes files not installed from the pkgmap file mustuse the removef command to notify the package database that it is removing apath name. After removal is complete, this command should be invoked with the−f option. See the removef (1M) man page and Chapter 5 for details andexamples.

Note - The installf and removef commands must be used because procedurescripts are not automatically associated with any path names listed in the pkgmapfile.

How to Write Procedure Scripts1. Make the directory containing your information files the current working

directory.

2. Create one or more procedure scripts with your favorite text editor.

A procedure script must be named one of the predefined names: preinstall ,postinstall , preremove , or postremove .



� If you want to create class action scripts, skip to the next task, “How to WriteClass Action Scripts” on page 68.


� If you have already created your prototype file, edit it and add an entry foreach installation script you just created.





Writing Class Action Scripts

Defining Object ClassesObject classes allow a series of actions to be performed on a group of package objectsat installation or removal. You assign objects to a class in the prototype file. Allpackage objects must be given a class, although the class of none is used by defaultfor objects that require no special action.

The installation parameter CLASSES, defined in the pkginfo file, is a list of classesto be installed (including the none class).

Note - Objects defined in the pkgmap file that belong to a class not listed in thisparameter in the pkginfo file will not be installed.

The CLASSESlist determines the order of installation. Class none is always installedfirst, if present, and removed last. Since directories are the fundamental supportstructure for all other file system objects, they should all be assigned to the noneclass. Exceptions can be made, but as a general rule, the none class is safest. Thereason for this is to ensure that the directories are created before the objects they willcontain and also to ensure that no attempt is made to delete a directory before it hasbeen emptied.

How Classes Are Processed During InstallationThe following list describes the system actions that occur when a class is installed.The actions are repeated once for each volume of a package as that volume is beinginstalled.

1. The pkgadd command creates a path name list.

The pkgadd command creates a list of path names upon which the action scriptwill operate. Each line of this list contains source and destination path names,separated by a space. The source path name indicates where the object to beinstalled resides on the installation volume and the destination path nameindicates the location on the target system where the object should be installed.The contents of the list are restricted by the following criteria:

� The list contains only path names belonging to the associated class.

� If the attempt to create the package object fails, directories, named pipes,character devices, block devices, and symbolic links are included in the listwith the source path name set to /dev/null . Normally they will beautomatically created by the pkgadd command (if not already in existence) andgiven proper attributes (mode, owner, group) as defined in the pkgmap file.

� Linked files where the file type is l are not included in the list under anycircumstances. Hard links in the given class are created in item 4.


� If a path name already exists on the target system and it is the same as thepath name being installed, it is not included in the list. The path name isjudged the same if size and checksum are identical.

2. If no class action script is provided for installation of a particular class, the pathnames in the generated list are copied from the volume to the appropriate targetlocation.

3. If there is a class action script, the script is executed.

The class action script is invoked with standard input containing the list generatedin item 1. If this is the last volume of the package, or there are no more objects inthis class, the script is executed with the single argument of ENDOFCLASS.

Note - Even if there are no regular files of this class anywhere in the package, theclass action script will be called at least once with an empty list and theENDOFCLASSargument.

4. The pkgadd command performs a content and attribute audit and creates hardlinks.

After successfully executing items 2 or 3, the pkgadd command audits bothcontent and attribute information for the list of path names. The pkgaddcommand creates the links associated with the class automatically. Detectedattribute inconsistencies are corrected for all path names in the generated list.

How Classes Are Processed During RemovalObjects are removed class by class. Classes that exist for a package but that are notlisted in the CLASSESparameter are removed first (for example, an object installedwith the installf command). Classes listed in the CLASSESparameter areremoved in reverse order. The none class is always removed last. The following listdescribes the system actions that occur when a class is removed:

1. The pkgrm command creates a path name list.

The pkgrm command creates a list of installed path names that belong to theindicated class. Path names referenced by another package are excluded from thelist unless their file type is e (meaning the file should be edited upon installationor removal).

If the package being removed modified any files of type e during installation, itshould remove just the lines it added. Do not delete a non-empty editable file; justremove the lines the package added.

2. If there is no class action script, the path names are deleted.

If your package has no removal class action script for the class, all the path namesin the list generated by the pkgrm command are deleted.


Note - Files with a file type of e (editable), which are not assigned to a class and anassociated class action script, will be removed at this point, even if the path nameis shared with other packages.

3. If there is a class action script, the script is executed.

The pkgrm command invokes the class action script with standard input for thescript containing the list generated in item 1.

4. The pkgrm command performs an audit.

After successfully executing the class action script, the pkgrm command removesknowledge of the path names from the package database unless a path name isreferenced by another package.

The Class Action ScriptThe class action script defines a set of actions to be executed during installation orremoval of a package. The actions are performed on a group of path names based ontheir class definition. (See Chapter 5, for examples of class action scripts.)

The name of a class action script is based on the class on which it should operateand whether those operations should occur during package installation or removal.The two name formats are as follows:

Name Format Description

i. class Operates on path names in the indicated class duringpackage installation.

r. class Operates on path names in the indicated class duringpackage removal.

For example, the name of the installation script for a class named manpage would bei.manpage and the removal script would be named r.manpage .

Note - This file name format is not used for files belonging to the sed , awk, orbuild system classes. For more information on these special classes, see “TheSpecial System Classes” on page 65.

Class Action Script Behaviors� Class action scripts are executed as uid=root and gid=other .

� A script is executed for all files in the given class on the current volume (forexample, floppy disk).


� The pkgadd and pkgrm commands create a list of all objects listed in the pkgmapfile that belong to the class. As a result, a class action script can act only upon pathnames defined in the pkgmap that belong to a particular class.

� When a class action script is executed for the last time (that is, no more files arefound belonging to that class), the class action script will be executed once withthe keyword argument ENDOFCLASS.

� Administrator interaction is not permitted during execution of a class action script.

Design Rules for Class Action Scripts� If a package spans more than one volume, the class action script is executed once

for each volume that contains at least one file belonging to a class. Consequently,each script must be able to be executed more than once. This means that executinga script any number of times with the same input must produce the same resultsas executing the script only once.

� When a file is part of a class that has a class action script, the script must installthe file. The pkgadd command does not install files for which a class action scriptexists, although it does verify the installation.

� A class action script should never add, remove, or modify a path name or systemattribute that does not appear in the list generated by the pkgadd command. Formore information on this list, see item 1 in “How Classes Are Processed DuringInstallation” on page 62.

� When your script sees the ENDOFCLASSargument, put post-processing actions(like clean up) into your script.

� All administrator interaction is restricted to the request script. Do not try toobtain information from the administrator using a class action script.

The Special System ClassesThe system provides three special classes in the Solaris 2.5 and later operatingenvironments. They are:

� The sed class

Provides a method for using sed instructions to edit files upon packageinstallation and removal.

� The awk class

Provides a method for using awk instructions to edit files upon packageinstallation and removal.

� The build class

Provides a method to dynamically construct or modify a file using Bourne shellcommands.


If there are several files in a package that require special processing that can be fullydefined through sed , awk, or sh commands, installation will be faster by using thesystem classes rather than multiple classes and their corresponding class actionscripts.

The sed Class ScriptThe sed class provides a method to modify an existing object on the target system.The sed class action script executes automatically at installation if a file belonging toclass sed exists. The name of the sed class action script should be the same as thename of the file on which the instructions will be executed.

A sed class action script delivers sed instructions in the format shown in Figure 3–1.

# comment, which may appear on any line in the file

!install# sed(1) instructions which will be invoked during# installation of the object

[ address [, address]] function [ arguments]

. . .

!remove

# sed(1) instructions to be invoked during the removal process

[ address [, address]] function [ arguments]

Figure 3–1 Format of a sed Class Action Script

Two commands indicate when instructions should be executed. The sed instructionsthat follow the !install command are executed during package installation andthose that follow the !remove command are executed during package removal. Itdoes not matter which order these commands are used in the file.

For more information on sed instructions, see the sed (1) man page. For examplesof sed class action scripts, see Chapter 5.

The awk Class ScriptThe awk class provides a method to modify an existing object on the target system.Modifications are delivered as awk instructions in an awk class action script.

The awk class action script is executed automatically at installation if a file belongingto class awk exists. Such a file contains instructions for the awk class script in theformat shown in Figure 3–2.


# comment, which may appear on any line in the file

!install

# awk(1) program to install changes

. . . (awk program)

!remove

# awk1(1) program to remove changes

. . . (awk program)

Figure 3–2 Format of an awk Class Action Script

Two commands indicate when instructions should be executed. The awk instructionsthat follow the !install command are executed during package installation, andthose that follow the !remove command are executed during package removal. Itdoes not matter in which order these commands are used in the file.

The name of the awk class action script should be the same as the name of the file onwhich the instructions will be executed.

The file to be modified is used as input to awk and the output of the scriptultimately replaces the original object. Environment variables may not be passed tothe awk command with this syntax.

For more information on awk instructions, see the awk(1) man page.

The build Class ScriptThe build class creates or modifies a package object file by executing Bourne shellinstructions. These instructions are delivered as the package object, which runsautomatically at installation if it belongs to the build class.

The name of the build class action script should be the same as the name of the fileon which the instructions will be executed, and must be executable by the shcommand. The script’s output becomes the new version of the file as it is built ormodified.

For example, if a package delivers a default file, /etc/randomtable , and if the filedoes not already exist on the target system, the prototype file entry might be:

e build /etc/randomtable ? ? ?

and the package object, /etc/randomtable , might look like this:


!install# randomtable builderif [ -f $PKG_INSTALL_ROOT/etc/randomtable ]; then

echo "/etc/randomtable is already in place.";else

echo "# /etc/randomtable" > $PKG_INSTALL_ROOT/etc/randomtableecho "1121554 # first random number" >> $PKG_INSTALL_ROOT/etc/randomtable

fi

!remove# randomtable deconstructorif [ -f $PKG_INSTALL_ROOT/etc/randomtable ]; then

# the file can be removed if it’s unchangedif [ egrep "first random number" $PKG_INSTALL_ROOT/etc/

randomtable ]; thenrm $PKG_INSTALL_ROOT/etc/randomtable;

fifi

See Chapter 5, for another example using the build class.

How to Write Class Action Scripts1. Make the directory containing your information files the current working

directory.

2. Assign the package objects in the prototype file the desired class names. Forexample, assigning objects to an application and manpage class would looklike:

f manpage /usr/share/man/manl/myappl.1lf application /usr/bin/myappl

3. Modify the CLASSESparameter in the pkginfo file to contain the class namesyou want to use in your package. For example, entries for the applicationand manpage classes would look like:

CLASSES=manpage application none

Note - The none class is always installed first and removed last, regardless ofwhere it appears in the definition of the CLASSESparameter.


4. If you are a creating class action script for a file belonging to the sed , awk, orbuild class, make the directory containing the package object your currentworking directory.

5. Create the class action scripts or package objects (for files belonging to the sed ,awk, or build class). An installation script for a class named applicationwould be named i.application and a removal script would be namedr.application .

Remember, when a file is part of a class that has a class action script, the scriptmust install the file. The pkgadd command does not install files for which a classaction script exists, although it does verify the installation. And, if you define aclass but do not deliver a class action script, the only action taken for that class isto copy components from the installation medium to the target system (thedefault pkgadd behavior).



� If you have already created your prototype file, edit it and add an entry foreach installation script you just created.



Where to Go Next

After you build the package, install it to confirm that it installs correctly and verifyits integrity. Chapter 4 explains how to do this and provides step-by-step instructionson how to transfer your verified package to a distribution medium.


CHAPTER 4

Verifying and Transferring a Package

This chapter describes how to verify your package’s integrity and transfer it to adistribution medium, such as floppy disk or a CD-ROM.

This is a list of the overview information in this chapter:

� “Task Map: Verifying and Transferring a Package” on page 71

� “Installing Software Packages” on page 72

� “Verifying the Integrity of a Package” on page 76

� “Displaying Additional Information About Installed Packages” on page 79

� “Removing a Package” on page 85

� “Transferring a Package to a Distribution Medium” on page 87

Task Map: Verifying and Transferring aPackageTable 4–1 describes the steps you should follow in order to verify your package’sintegrity and transfer it to a distribution medium.

TABLE 4–1 Task Map: Verifying and Transferring a Package


Build Your Package Build your package ondisk.

Chapter 2

71

TABLE 4–1 Task Map: Verifying and Transferring a Package (continued)


Install YourPackage

Test your package byinstalling it and makingsure that it installswithout errors.

“How to Install a Package on a Standaloneor Server” on page 74 and “How to Add aPackage to a Diskless or AutoClientSystem’s Root File System” on page 75

Verify YourPackage’s Integrity

Use the pkgchkcommand to verify theintegrity of yourpackage.

“How to Verify the Integrity of YourPackage” on page 77

Obtain OtherPackageInformation

Optional. Use thepkginfo andpkgparam commands toperform package-specificverification.

“Displaying Additional Information AboutInstalled Packages” on page 79

Remove theInstalled Package

Use the pkgrmcommand to removeyour installed packagefrom the system.

“How to Remove a Package” on page 85and “How to Remove a Package From aDiskless or AutoClient System” on page 86

Transfer YourPackage to aDistributionMedium

Use the pkgtranscommand to transferyour package (inpackage format) to adistribution medium.

“How to Transfer Your Package to aDistribution Medium” on page 87

Installing Software PackagesSoftware packages are installed using the pkgadd command. This commandtransfers the contents of a software package from the distribution medium ordirectory and installs it onto a system.


This section provides basic installation instructions for installing your package inorder to verify that it installs correctly. For more comprehensive installationexamples, such as installing packages for diskless clients in a heterogeneousenvironment, see Chapter 18 in the System Administration Guide.

The Installation Software DatabaseInformation for all packages installed on a system is kept in the installation softwaredatabase. There is an entry for every object in a package, with information such asthe component name, where it resides, and its type. An entry contains a record of thepackage to which a component belongs; other packages that might reference thecomponent; and information such as path name, where the component resides andthe component type. Entries are added and removed automatically by the pkgaddand pkgrm commands. You can view the information in the database by using thepkgchk and the pkginfo commands.

Two types of information are associated with each package component. The attributeinformation describes the component itself. For example, the component’s accesspermissions, owner ID, and group ID are attribute information. The contentinformation describes the contents of the component, such as file size and time oflast modification.

The installation software database keeps track of the package status. A package canbe either fully installed (it has successfully completed the installation process), orpartially installed (it did not successfully complete the installation process).

When a package is partially installed, portions of a package may have been installedbefore installation was terminated; thus, part of the package is installed, andrecorded in the database, and part is not. When you reinstall the package, you areprompted to start at the point where installation stopped because the pkgaddcommand can access the database and detect which portions have already beeninstalled. You can also remove the portions that have been installed, based on theinformation in the installation software database using the pkgrm command.

Interacting with the pkgadd CommandIf the pkgadd command encounters a problem, it first checks the installationadministration file for instructions. (See the admin (4) man page for moreinformation.) If no instructions exist, or if the relevant parameter in theadministration file is set to ask , the pkgadd displays a message describing theproblem and prompts for a reply. The prompt is usuallyDo you want to continue with this installation? . You should respondwith yes , no , or quit .

Verifying and Transferring a Package 73

If you have specified more than one package, no stops installation of the packagebeing installed but pkgadd continues with installation of the other packages. quitindicates that pkgadd should stop installation of all packages.

Installing Packages on Standalones or Servers in aHomogeneous Environment

How to Install a Package on a Standalone orServer1. Build your package.

See “Building a Package” on page 34, if needed.

2. Log in to the system as superuser.

3. Add the software package to the system.

# pkgadd -d device-name [ pkg-abbrev...]


pkg-abbrev Is the name of one or more packages (separated byspaces) to be added. If omitted, pkgadd installs allavailable packages.

Where to Go NextIf you are ready to go to the next task, see “How to Verify the Integrity of YourPackage” on page 77.

Example—Installing Packages on Standalones and ServersTo install a software package named pkgA from a tape device named /dev/rmt/0 ,you would enter the following command:


# pkgadd -d /dev/rmt/0 pkgA

You can also install multiple packages at the same time, as long as you separatepackage names with a space, as follows:

# pkgadd -d /dev/rmt/0 pkgA pkgB pkgC

If you do not name the device on which the package resides, the command checksthe default spool directory (/var/spool/pkg ). If the package is not there, theinstallation fails.

Installing Packages for Diskless Clients andAutoClient Systems on a ServerThis section describes how to install packages for a client system that places files inthe root (/ ) file system. Note that packages that do not place files in root (/ ) can bemade available to client systems by installing the package on the server with thepkgadd command—these packages are then made available when the file systemsare mounted by the client systems.

Packages that are not part of the Solaris operating environment (unbundled softwarepackages) should be installed into /opt . However, some packages, such as apackage containing a device driver, must be installed into root (/ ) or /usr .

Use the pkgadd command on a server to install software for the use of clientsystems. Software installed for the use of client systems is installed in the clientsystem’s root (/ ) file system, not the server’s root (/ ) file system. A diskless client’sand AutoClient system’s root (/ ) file system is located on the server, in the directory/export/root/ client.

Files installed in the client system’s root (/ ) file system appear in the client system’ssoftware database as installed . Files that the client expects to find in its /usr filesystem are shown as shared in the client system’s database. The shared files must beinstalled on the server with a separate invocation of the pkgadd command.

How to Add a Package to a Diskless orAutoClient System’s Root File System1. Build your package.

See “Building a Package” on page 34, if needed.

2. Log in to the server as superuser.

3. Add a software package to the client system’s root file system.


server# pkgadd -d device-name -R rootpath [ pkg-abbrev...]


−R rootpath Specifies the location of the client system’s root (/ ) filesystem on the server.

pkg-abbrev Is the name of one or more packages (separated byspaces) to be added. If omitted, pkgadd installs allavailable packages.

Where to Go NextIf you are ready to go to the next task, see “How to Verify the Integrity of YourPackage” on page 77.

Example—Installing a Package to a Diskless Client’s Root FileSystemThe following example shows a command to install the SUNWadmr(software tosupport system and network administration) package from a server onto a disklessclient’s root file system. In this case, the diskless client’s root file system is/export/root/client-1 . This example assumes the SUNWadmrpackage isavailable from a mounted SPARC 2.x Solaris CD(/cdrom/cdrom0/s0/Solaris_2.6 ).

server# pkgadd -d /cdrom/cdrom0/s0/Solaris_2.6 -R /export/root/client-1 SUNWadmr...

Installation of <SUNWadmr> complete.server#

Verifying the Integrity of a PackageThe pkgchk command enables you to check the integrity of packages, whether theyare installed on a system or in package format (ready to be installed with the


pkgadd command). It confirms package structure or the installed files anddirectories, or displays information about package objects. The pkgchk commandcan list or check the following:

� The package installation scripts.

� The contents or attributes, or both, of objects currently installed on the system.

� The contents of a spooled, uninstalled package.

� The contents or attributes, or both, of objects described in the specified pkgmapfile.

For more information about this command, refer to the pkgchk (1M) man page.

The pkgchk command performs two kinds of checks. It checks file attributes (thepermissions and ownership of a file and major/minor numbers for block or characterspecial devices) and the file contents (the size, checksum, and modification date). Bydefault, the command checks both the file attributes and the file contents.

The pkgchk command also compares the file attributes and contents of the installedpackage against the installation software database. The entries concerning a packagemay have been changed since the time of installation; for example, another packagemay have changed a package component. The database reflects that change.

How to Verify the Integrity of Your Package1. Install your package.

See “How to Install a Package on a Standalone or Server” on page 74 or “How toAdd a Package to a Diskless or AutoClient System’s Root File System” on page75, if needed.

2. Verify the integrity of your package.

# pkgchk [ -v ] [ -R root-path] [ pkg-abbrev...]

−vLists files as they are processed.

−R root-path Specifies the location of the client system’s root file system.

pkg-abbrev Is the name of one or more packages (separated byspaces) to be checked. If omitted, pkgchk checks allavailable packages.


Where to Go NextIf you are ready to go to the next task, see “How to Obtain Information With thepkginfo Command” on page 84.

Example—Verifying the Integrity of a PackageThis example shows the command you should use to verify the integrity of aninstalled package.

$ pkgchk pkg-abbrev$

If there are errors, the pkgchk command prints them. Otherwise, it does not printanything and returns an exit code of 0. If you do not supply a package abbreviation,then it will check all of the packages on the system.

Alternately, you could use the −v option, which will print a list of files in thepackage if there are no errors. For example,

$ pkgchk -v SUNWcadap/opt/SUNWcadap/opt/SUNWcadap/demo/opt/SUNWcadap/demo/file1/opt/SUNWcadap/lib/opt/SUNWcadap/lib/file2/opt/SUNWcadap/man/opt/SUNWcadap/man/man1/opt/SUNWcadap/man/man1/file3.1/opt/SUNWcadap/man/man1/file4.1/opt/SUNWcadap/man/windex/opt/SUNWcadap/srcfiles/opt/SUNWcadap/srcfiles/file5/opt/SUNWcadap/srcfiles/file6$

If you need to verify a package that is installed on a client system’s root file system,use this command:

$ pkgchk -v -R root-path pkg-abbrev


Displaying Additional InformationAbout Installed PackagesYou can use two other commands to display information about installed packages:

� The pkgparam command displays parameter values.

� The pkginfo command displays information from the installation softwaredatabase.

The pkgparam CommandThe pkgparam command enables you to display the values associated with theparameters you specified on the command line. The values are retrieved from eitherthe pkginfo file for a specific package, or from the file you name. One parametervalue is shown per line. You can display the values only or the parameters and theirvalues.

How to Obtain Information With the pkgparamCommand1. Install your package.


2. Display additional information about your package.

# pkgparam [ -v ] pkg-abbrev [ param...]

−vDisplays the name of the parameter and its value.

pkg-abbrev Is the name of a specific package.

param Specifies one or more parameters whose value isdisplayed.


Where to Go NextIf you are ready to go to the next task, see “How to Remove a Package” on page 85or “How to Remove a Package From a Diskless or AutoClient System” on page 86.

Example—Obtaining Information With the pkgparamCommandFor example, to display values only, use this command.

$ pkgparam SUNWcadapnone/optUS/Mountain/sbin:/usr/sbin:/usr/bin:/usr/sadm/install/bin/usr/sadm/sysadmSUNWcadapChip designers need CAD application software to design abcchips. Runs only on xyz hardware and is installed in the usrpartition.systemrelease 1.0SPARCupnaway960717083849SUNWcadap/var/sadm/pkg/SUNWcadap/saveJul 29 1996 15:24$

To display parameters and their values, use the following command.

$ pkgparam -v SUNWcadappkgparam -v SUNWcadapCLASSES=’none’BASEDIR=’/opt’TZ=’US/Mountain’PATH=’/sbin:/usr/sbin:/usr/bin:/usr/sadm/install/bin’OAMBASE=’/usr/sadm/sysadm’PKG=’SUNWcadap’NAME=’Chip designers need CAD application software to design abc chips.Runs only on xyz hardware and is installed in the usr partition.’CATEGORY=’system’VERSION=’release 1.0’ARCH=’SPARC’PSTAMP=’upnaway960717083849’PKGINST=’SUNWcadap’PKGSAV=’/var/sadm/pkg/SUNWcadap/save’INSTDATE=’Jul 29 1996 15:24’$

Or, if you want to display the value of a specific parameter, use this format:


$ pkgparam SUNWcadap BASEDIR/opt$

For more information, refer to the pkgparam (1) man page.

The pkginfo CommandYou can display information about installed packages with the pkginfo command.This command has several options that enable you to customize both the format andthe contents of the display.

You can request information about any number of package instances.

The Default pkginfo DisplayWhen the pkginfo command is executed without options, it displays the category,package instance, and package name of all packages that have been completelyinstalled on your system. The display is organized by categories as shown in thefollowing example.

$ pkginfo...system SUNWinst Install Softwaresystem SUNWipc Interprocess Communicationssystem SUNWisolc XSH4 conversion for ISO Latin character setsapplication SUNWkcspf KCMS Optional Profilesapplication SUNWkcspg KCMS Programmers Environmentapplication SUNWkcsrt KCMS Runtime Environment...$

Customizing the Format of the pkginfo DisplayYou can get a pkginfo display in any of three formats: short, extracted, and long.

The short format is the default. It shows only the category, package abbreviation, andfull package name, as shown in “The Default pkginfo Display” on page 81.

The extracted format shows the package abbreviation, package name, packagearchitecture (if available), and package version (if available). Use the −x option torequest the extracted format as shown in the next example.


$ pkginfo -x...SUNWipc Interprocess Communications

(sparc) 11.5.1,REV=95.10.27.15.23SUNWisolc XSH4 conversion for ISO Latin character sets

(sparc) 1.0,REV=5.0SUNWkcspf KCMS Optional Profiles

(sparc) 1.0,REV=1.0.14SUNWkcspg KCMS Programmers Environment

(sparc) 1.0,REV=1.0.1...$

Using the −l option produces a display in the long format showing all of theavailable information about a package, as in the following example.

$ pkginfo -l SUNWcadapPKGINST: SUNWcadap

NAME: Chip designers need CAD application software todesign abc chips. Runs only on xyz hardware and is installedin the usr partition.

CATEGORY: systemARCH: SPARC

VERSION: release 1.0BASEDIR: /opt

PSTAMP: system960717083849INSTDATE: Jul 29 1996 15:24

STATUS: completely installedFILES: 13 installed pathnames

6 directories3 executables

3121 blocks used (approx)$

Parameter Descriptions for the pkginfo Long FormatTable 4–2describes the package parameters that can be displayed for each package. Aparameter and its value are displayed only when the parameter has a value assignedto it.


TABLE 4–2 Package Parameters

Parameter Description

ARCH The architecture supported by this package.

BASEDIR The base directory in which the software package resides (shown if thepackage is relocatable).

CATEGORY The software category, or categories, of which this package is a member(for example, system or application ).

CLASSES A list of classes defined for a package. The order of the list determinesthe order in which the classes are installed. Classes listed first will beinstalled first (on a media by media basis). This parameter may bemodified by the request script.

DESC Text that describes the package.

EMAIL The electronic mail address for user inquiries.

HOTLINE Information on how to receive hotline help about this package.

INTONLY Indicates that the package should only be installed interactively when setto any non-NULL value.

ISTATES A list of allowable run states for package installation (for example, S s 1).

MAXINST The maximum number of package instances that should be allowed on amachine at the same time. By default, only one instance of a package isallowed.

NAME The package name, generally text describing the package abbreviation.

ORDER A list of classes defining the order in which they should be put on themedium. Used by the pkgmk command in creating the package. Classesnot defined in this parameter are placed on the medium using thestandard ordering procedures.

PKGINST Abbreviation for the package being installed.

PSTAMP The production stamp for this package

RSTATES A list of allowable run states for package removal (for example, S s 1).


TABLE 4–2 Package Parameters (continued)

ULIMIT If set, this parameter is passed as an argument to the ulimit command,which establishes the maximum size of a file during installation. Thisapplies only to files created by procedure scripts.

VENDOR The name of the vendor who supplied the software package.

VERSION The version of this package.

VSTOCK The vendor-supplied stock number.

For detailed information about the pkginfo command, refer to the pkginfo (1)man page.

How to Obtain Information With the pkginfoCommand1. Install your package.


2. Display additional information about your package.

# pkginfo [ -x | -l ] [ pkg-abbrev]

−xDisplays package information in extracted format.

−lDisplays package information in long format.

pkg-abbrev Is the name of a specific package. If omitted, the pkginfocommand displays information about all installedpackages, in the default format.


Where to Go NextIf you are ready to go to the next task, see “How to Remove a Package” on page 85or “How to Remove a Package From a Diskless or AutoClient System” on page 86.

Removing a PackageBecause the pkgrm command updates information in the software products database,it is important when you remove a package to use the pkgrm command—eventhough you might be tempted to use the rm command instead. For example, youcould use the rm command to remove a binary executable file, but that is not thesame as using pkgrm to remove the software package that includes that binaryexecutable. Using the rm command to remove a package’s files will corrupt thesoftware products database. (If you really only want to remove one file, you can usethe removef command, which will update the software product database correctly.See the removef (1) man page for more information.)

How to Remove a Package1. Log in to the system as superuser.

2. Remove an installed package.

# pkgrm pkg-abbrev...

pkg-abbrev Is the name of one or more packages (separated byspaces). If omitted, pkgrm removes all available packages.

3. Verify that the package has successfully been removed, use the pkginfocommand.

$ pkginfo | egrep pkg-abbrev

If pkg-abbrev is installed, the pkginfo command returns a line of informationabout it. Otherwise, pkginfo returns the system prompt.


How to Remove a Package From a Diskless orAutoClient System1. Log in to the server and become superuser.

2. Remove a software package from a client system’s server with the pkgrm -Rcommand.

server# pkgrm -R rootpath pkg-abbrev...

−R rootpath Specifies the mount point of the client’s root file system.

pkg-abbrev Is the name of one or more packages (separated byspaces) to be removed. If omitted, pkgrm removes allavailable packages.

Files in the client system’s package database that are marked shared are notremoved from the server, but are removed from the client system’s database. If allclient systems have removed the package, you can remove the shared files fromthe server using a separate invocation of pkgrm on the server.

3. Verify that the package has successfully been removed, use the pkginfocommand.

server$ pkginfo -R rootpath | egrep pkg-abbrev

If pkg-abbrev is installed, the pkginfo command returns a line of informationabout it. Otherwise, pkginfo returns the system prompt.

Where to Go NextIf you are ready to go to the next task, see “How to Transfer Your Package to aDistribution Medium” on page 87.

Example—Removing a Diskless Client’s PackageIn the following example, assume the client system’s root file system is shared. Also,assume these commands are executed on the client system’s server.

server# pkgrm -R /export/root/client-1 SUNWaudioThe following package is currently installed.SUNWaudio

(continued)


(Continuation)

Do you want to remove this package? y/n/q?

y...

server#

Transferring a Package to a DistributionMediumThe pkgtrans command moves packages and performs package formattranslations. You can use the pkgtrans command to perform the followingtranslations for an installable package:

� File system format to datastream format

� Datastream format to file system format

� One file system format to another file system format

How to Transfer Your Package to a DistributionMedium1. Build your package, creating a directory format package, if you have not

already done so.

For more information, see “How to Build a Package” on page 35.

2. Install your package to verify that it installs correctly.


3. Verify your package’s integrity.

See “How to Verify the Integrity of Your Package” on page 77, “How to ObtainInformation With the pkgparam Command” on page 79, and “How to ObtainInformation With the pkginfo Command” on page 84, if needed.

4. Remove the installed package from the system.


See “How to Remove a Package” on page 85 or “How to Remove a Package Froma Diskless or AutoClient System” on page 86, if needed.

5. Transfer the package (in package format) to a distribution medium.

To perform a basic translation, execute the following command:

$ pkgtrans device1 device2 [ pkg-abbrev...]

device1 Is the name of the device where the package currently resides.

device2 Is the name of the device onto which the translated package willbe written.

[pkg-abbrev] Is one or more package abbreviations.

If no package names are given, all packages residing in device1 are translated andwritten to device2.

Note - If more than one instance of a package resides on device1, you must usean instance identifier for the package. For a description of a package identifier,see “Defining a Package Instance” on page 15. When an instance of the packagebeing translated already exists on device2, the pkgtrans command does notperform the translation. You can use the −o option to tell the pkgtranscommand to overwrite any existing instances on the destination device and the−n option to tell it to create a new instance if one already exists. Note that thischeck does not apply when device2 supports a datastream format.

Where to Go NextAt this point you have completed the steps necessary to design, build, verify, andtransfer your package. If you are interested in looking at some case studies, seeChapter 5. If you are interested in advanced package design ideas, see Chapter 6.


CHAPTER 5

Package Creation Case Studies

This chapter provides case studies to show packaging scenarios such as installingobjects conditionally, determining at run time how many files to create, andmodifying an existing data file during package installation and removal.

Each case study begins with a description, followed by a list of the packagingtechniques used, a narrative description of the approach taken when using thosetechniques, and sample files and scripts associated with the case study.

This is a list of the case studies in this chapter:

� “Soliciting Input From the Administrator” on page 89

� “Creating a File at Installation and Saving It During Removal” on page 93

� “Defining Package Compatibilities and Dependencies” on page 97

� “Modifying a File Using Standard Classes and Class Action Scripts” on page 99

� “Modifying a File Using the sed Class and a postinstall Script” on page 103

� “Modifying a File Using the build Class” on page 105

� “Modifying crontab Files During Installation” on page 108

� “Installing and Removing a Driver With Procedure Scripts” on page 111

� “Installing a Driver Using the sed Class and Procedure Scripts” on page 114

Soliciting Input From the AdministratorThe package in this case study has three types of objects. The administrator maychoose which of the three types to install and where to locate the objects on theinstallation machine.

89

TechniquesThis case study demonstrates the following techniques:

� Using parametric path names (variables in object path names) that are used toestablish multiple base directories

For information on parametric path names, see “Parametric Path Names” on page23.

� Using a request script to solicit input from the administrator

For information on request scripts, see “Writing a request Script” on page 55.

� Setting conditional values for an installation parameter

ApproachTo set up the selective installation in this case study, you must complete thefollowing tasks:

� Define a class for each type of object that can be installed.

In this case study, the three object types are the package executables, the manpages, and the emacs executables. Each type has its own class: bin , man, andemacs, respectively. Notice that in the prototype file all the object files belong toone of these three classes.

� Initialize the CLASSESparameter in the pkginfo file to null.

Normally when you define a class, you should list that class in the CLASSESparameter in the pkginfo file. Otherwise, no objects in that class are installed. Forthis case study, the parameter is initially set to null, which means no objects willget installed. The CLASSESparameter will be changed by the request script,based on the choices of the administrator. This way, the CLASSESparameter is setto only those object types that the administrator wants installed.

Note - Usually it is a good idea to set parameters to a default value. If this packagehad components common to all three object types, you could assign them to thenone class, and then set the CLASSESparameter equal to none .

� Insert parametric path names into the prototype file.

The request script sets these environment variables to the value that theadministrator provides. Then, the pkgadd command resolves these environmentvariables at installation time and knows where to install the package.

The three environment variables used in this example are set to their default in thepkginfo file and serve the following purposes:

� $NCMPBINdefines the location for object executables


� $NCMPMANdefines the location for man pages

� $EMACSdefines the location for emacs executables

The example prototype file shows how to define the object path names withvariables.

� Create a request script to ask the administrator which parts of the packageshould be installed and where they should be placed.

The request script for this package asks the administrator two questions:

� Should this part of the package be installed?

When the answer is yes, the appropriate class name is added to the CLASSESparameter. For example, when the administrator chooses to install the manpages associated with this package, the class man is added to the CLASSESparameter.

� If so, where should this part of the package be placed?

The appropriate environment variable is set to the response to this question. Inthe man page example, the variable $NCMPMANis set to the response value.

These two questions are repeated for each of the three object types.

At the end of the request script, the parameters are made available to theinstallation environment for the pkgadd command and any other packagingscripts. The request script does this by writing these definitions to the fileprovided by the calling utility. For this case study, no other scripts are provided.

When looking at the request script for this case study, notice that the questionsare generated by the data validation tools ckyorn and ckpath . For moreinformation on these tools see the ckyorn (1) and ckpath (1) man pages.

Case Study Files

The pkginfo File

PKG=ncmpNAME=NCMP UtilitiesCATEGORY=application, toolsBASEDIR=/ARCH=SPARCVERSION=RELEASE 1.0, Issue 1.0

(continued)

Package Creation Case Studies 91

(Continuation)

CLASSES=""NCMPBIN=/binNCMPMAN=/usr/manEMACS=/usr/emacs

The prototype File

i pkginfoi requestx bin $NCMPBIN 0755 root otherf bin $NCMPBIN/dired=/usr/ncmp/bin/dired 0755 root otherf bin $NCMPBIN/less=/usr/ncmp/bin/less 0755 root otherf bin $NCMPBIN/ttype=/usr/ncmp/bin/ttype 0755 root otherf emacs $NCMPBIN/emacs=/usr/ncmp/bin/emacs 0755 root otherx emacs $EMACS 0755 root otherf emacs $EMACS/ansii=/usr/ncmp/lib/emacs/macros/ansii 0644 root otherf emacs $EMACS/box=/usr/ncmp/lib/emacs/macros/box 0644 root otherf emacs $EMACS/crypt=/usr/ncmp/lib/emacs/macros/crypt 0644 root otherf emacs $EMACS/draw=/usr/ncmp/lib/emacs/macros/draw 0644 root otherf emacs $EMACS/mail=/usr/ncmp/lib/emacs/macros/mail 0644 root otherf emacs $NCMPMAN/man1/emacs.1=/usr/ncmp/man/man1/emacs.1 0644 root otherd man $NCMPMAN 0755 root otherd man $NCMPMAN/man1 0755 root otherf man $NCMPMAN/man1/dired.1=/usr/ncmp/man/man1/dired.1 0644 root otherf man $NCMPMAN/man1/ttype.1=/usr/ncmp/man/man1/ttype.1 0644 root otherf man $NCMPMAN/man1/less.1=/usr/ncmp/man/man1/less.1 0644 inixmr other

The request Script

trap ’exit 3’ 15# determine if and where general executables should be placedans=‘ckyorn -d y \-p "Should executables included in this package be installed"‘ || exit $?if [ "$ans" = y ]then

CLASSES="$CLASSES bin"NCMPBIN=‘ckpath -d /usr/ncmp/bin -aoy \-p "Where should executables be installed"‘ || exit $?

fi# determine if emacs editor should be installed, and if it should# where should the associated macros be placed

(continued)


(Continuation)

ans=‘ckyorn -d y \-p "Should emacs editor included in this package be installed"‘ || exit $?if [ "$ans" = y ]then

CLASSES="$CLASSES emacs"EMACS=‘ckpath -d /usr/ncmp/lib/emacs -aoy \-p "Where should emacs macros be installed"‘ || exit $?

fi

Note that a request script can exit without leaving any files on the file system. Forinstallations on Solaris versions prior to 2.5 (where no checkinstall script may beused) the request script is the correct place to test the file system in any mannernecessary to ensure that the installation will succeed. When the request script exitswith code 1, the installation will quit cleanly.

These example files show the use of parametric paths to establish multiple basedirectories. However, the preferred method involves use of the BASEDIR parameterwhich is managed and validated by the pkgadd command. Whenever multiple basedirectories are used, take special care to provide for installation of multiple versionsand architectures on the same platform.

Creating a File at Installation andSaving It During RemovalThis case study creates a database file at installation time and saves a copy of thedatabase when the package is removed.


� Using classes and class action scripts to perform special actions on different sets ofobjects

For more information, see “Writing Class Action Scripts” on page 62.


� Using the space file to inform the pkgadd command that extra space is requiredto install this package properly

For more information on the space file, see “Reserving Additional Space on aTarget System” on page 48.

� Using the installf command to install a file not defined in the prototype andpkgmap files

ApproachTo create a database file at installation and save a copy on removal for this casestudy, you must complete the following tasks:

� Define three classes.

The package in this case study requires the following three classes be defined inthe CLASSESparameter:

� The standard class of none , which contains a set of processes belonging in thesubdirectory bin .

� The admin class, which contains an executable file config and a directorycontaining data files.

� The cfgdata class, which contains a directory.

� Make the package collectively relocatable.

Notice in the prototype file that none of the path names begins with a slash oran environment variable. This indicates that they are collectively relocatable.

� Calculate the amount of space the database file requires and create a space file todeliver with the package. This file notifies the pkgadd command that the packagerequires extra space and specifies how much.

� Create a class action script for the admin class (i.admin ).

The sample script initializes a database using the data files belonging to the adminclass. To perform this task, it does the following:

� Copies the source data file to its proper destination

� Creates an empty file named config.data and assigns it to a class ofcfgdata

� Executes the bin/config command (delivered with the package and alreadyinstalled) to populate the database file config.data using the data filesbelonging to the admin class


� Executes the installf -f command to finalize installation of config.data

No special action is required for the admin class at removal time so no removalclass action script is created. This means that all files and directories in the adminclass are removed from the system.

� Create a removal class action script for the cfgdata class (r.cfgdata ).

The removal script makes a copy of the database file before it is deleted. Nospecial action is required for this class at installation time, so no installation classaction script is needed.

Remember that the input to a removal script is a list of path names to remove.Path names always appear in reverse alphabetical order. This removal script copiesfiles to the directory named $PKGSAV. When all the path names have beenprocessed, the script then goes back and removes all directories and filesassociated with the cfgdata class.

The outcome of this removal script is to copy config.data to $PKGSAVand thenremove the config.data file and the data directory.

Case Study Files

The pkginfo File

PKG=krazyNAME=KrAzY ApplicationsCATEGORY=applicationsBASEDIR=/optARCH=SPARCVERSION=Version 1CLASSES=none cfgdata admin

The prototype File

i pkginfoi requesti i.admini r.cfgdatad none bin 555 root sysf none bin/process1 555 root otherf none bin/process2 555 root otherf none bin/process3 555 root other

(continued)


(Continuation)

f admin bin/config 500 root sysd admin cfg 555 root sysf admin cfg/datafile1 444 root sysf admin cfg/datafile2 444 root sysf admin cfg/datafile3 444 root sysf admin cfg/datafile4 444 root sysd cfgdata data 555 root sys

The space File

# extra space required by config data which is# dynamically loaded onto the systemdata 500 1

The i.admin Class Action Script

# PKGINST parameter provided by installation service# BASEDIR parameter provided by installation servicewhile read src destdo

cp $src $dest || exit 2done# if this is the last time this script will be executed# during the installation, do additional processing here.if [ "$1" = ENDOFCLASS ]then# our config process will create a data file based on any changes# made by installing files in this class; make sure the data file# is in class ‘cfgdata’ so special rules can apply to it during# package removal.

installf -c cfgdata $PKGINST $BASEDIR/data/config.data f 444 rootsys || exit 2$BASEDIR/bin/config > $BASEDIR/data/config.data || exit 2installf -f -c cfgdata $PKGINST || exit 2

fiexit 0

This illustrates a rare instance in which installf is appropriate in a class actionscript. Because a space file has been used to reserve room on a specific file system,this new file may be safely added even though it is not included in the pkgmap file.


The r.cfgdata Removal Script

# the product manager for this package has suggested that# the configuration data is so valuable that it should be# backed up to $PKGSAV before it is removed!while read pathdo# path names appear in reverse lexical order.

mv $path $PKGSAV || exit 2rm -f $path || exit 2

doneexit 0

Defining Package Compatibilities andDependenciesThe package in this case study uses optional information files to define packagecompatibilities and dependencies, and to present a copyright message duringinstallation.


� Using the copyright file

� Using the compver file

� Using the depend file

For more information on these files, see “Creating Information Files” on page 43.

ApproachTo meet the requirements in the description, you must:

� Create a copyright file.

A copyright file contains the ASCII text of a copyright message. The messageshown in the sample file is displayed on the screen during package installation.


� Create a compver file.

The pkginfo file shown in the next figure defines this package version as version3.0. The compver file defines version 3.0 as being compatible with versions 2.3,2.2, 2.1, 2.1.1, 2.1.3 and 1.7.

� Create a depend file.

Files listed in a depend file must already be installed on the system when apackage is installed. The example file has 11 packages which must already be onthe system at installation time.

Case Study Files

The pkginfo File

PKG=case3NAME=Case Study #3CATEGORY=applicationBASEDIR=/optARCH=SPARCVERSION=Version 3.0CLASSES=none

The copyright File

Copyright (c) 1996 company_nameAll Rights Reserved.THIS PACKAGE CONTAINS UNPUBLISHED PROPRIETARY SOURCE CODE OFcompany_name.The copyright notice above does not evidence anyactual or intended publication of such source code


The compver File

Version 3.0Version 2.3Version 2.2Version 2.1Version 2.1.1Version 2.1.3Version 1.7

The depend File

P acu Advanced C UtilitiesIssue 4 Version 1P cc C Programming LanguageIssue 4 Version 1P dfm Directory and File Management UtilitiesP ed Editing UtilitiesP esg Extended Software Generation UtilitiesIssue 4 Version 1P graph Graphics UtilitiesP rfs Remote File Sharing UtilitiesIssue 1 Version 1P rx Remote Execution UtilitiesP sgs Software Generation UtilitiesIssue 4 Version 1P shell Shell Programming UtilitiesP sys System Header FilesRelease 3.1

Modifying a File Using StandardClasses and Class Action ScriptsThis case study modifies an existing file during package installation using standardclasses and class action scripts. It uses one of three modification methods. The othertwo methods are described in “Modifying a File Using the sed Class and apostinstall Script” on page 103 and “Modifying a File Using the build Class”on page 105. The file modified is /sbin/inittab .


TechniquesThis case study demonstrates how to use installation and removal class actionscripts. For more information, see “Writing Class Action Scripts” on page 62.

ApproachTo modify /sbin/inittab during installation, using classes and class actionscripts, you must complete the following tasks:

� Create a class.

Create a class called inittab . You must provide an installation and a removalclass action script for this class. Define the inittab class in the CLASSESparameter in the pkginfo file.

� Create an inittab file.

This file contains the information for the entry that you will add to/sbin/inittab . Notice in the prototype file figure that inittab is a memberof the inittab class and has a file type of e for editable.

� Create an installation class action script (i.inittab ).

Remember that class action scripts must produce the same results each time theyare executed. The class action script performs the following procedures:

� Checks if this entry has been added before

� If it has, removes any previous versions of the entry

� Edits the inittab file and adds the comment lines so you know where theentry is from

� Moves the temporary file back into /sbin/inittab

� Executes the init q command when it receives the ENDOFCLASSindicator

Note that the init q command can be performed by this installation script. Aone-line postinstall script is not needed by this approach.

� Create a removal class action script (r.inittab ).

The removal script is very similar to the installation script. The information addedby the installation script is removed and the init q command is executed.

This case study is more complicated than the next one; see “Modifying a File Usingthe sed Class and a postinstall Script” on page 103. Instead of providing twofiles, three are needed and the delivered /sbin/inittab file is actually just a placeholder containing a fragment of the entry to be inserted. This could have been placedinto the i.inittab file except that the pkgadd command must have a file to pass


to the i.inittab file. Also, the removal procedure must be placed into a separatefile (r.inittab ). While this method works fine, it is best reserved for casesinvolving very complicated installations of multiple files. See “Modifying crontabFiles During Installation” on page 108.

The sed program used in “Modifying a File Using the sed Class and apostinstall Script” on page 103 supports multiple package instances since thecomment at the end of the inittab entry is based on package instance. The casestudy in “Modifying a File Using the build Class” on page 105 shows a morestreamlined approach to editing /sbin/inittab during installation.

Case Study Files

The pkginfo File

PKG=case5NAME=Case Study #5CATEGORY=applicationsBASEDIR=/optARCH=SPARCVERSION=Version 1d05CLASSES=inittab

The prototype File

i pkginfoi i.inittabi r.inittabe inittab /sbin/inittab ? ? ?

The i.inittab Installation Class Action Script

# PKGINST parameter provided by installation servicewhile read src destdo# remove all entries from the table that# associated with this PKGINSTsed -e "/^[^:]*:[^:]*:[^:]*:[^#]*#$PKGINST$/d" $dest >/tmp/$$itab ||exit 2sed -e "s/$/#$PKGINST" $src >> /tmp/$$itab ||


(Continuation)

exit 2mv /tmp/$$itab $dest ||exit 2doneif [ "$1" = ENDOFCLASS ]then/sbin/init q ||exit 2fiexit 0

The r.inittab Removal Class Action Script

# PKGINST parameter provided by installation servicewhile read src destdo# remove all entries from the table that# are associated with this PKGINSTsed -e "/^[^:]*:[^:]*:[^:]*:[^#]*#$PKGINST$/d" $dest >/tmp/$$itab ||exit 2mv /tmp/$$itab $dest ||exit 2done/sbin/init q ||exit 2exit 0

The inittab File

rb:023456:wait:/usr/robot/bin/setup


Modifying a File Using the sed Classand a postinstall ScriptThis case study modifies a file which exists on the installation machine duringpackage installation. It uses one of three modification methods. The other twomethods are described in “Modifying a File Using Standard Classes and Class ActionScripts” on page 99 and “Modifying a File Using the build Class” on page 105. Thefile modified is /sbin/inittab .


� Using the sed class

For more information on the sed class, see “The sed Class Script ” on page 66.

� Using a postinstall script

For more information on this script, see “Writing Procedure Scripts” on page 60.

ApproachTo modify /sbin/inittab at the time of installation, using the sed class, you mustcomplete the following tasks:

� Add the sed class script to the prototype file.

The name of a script must be the name of the file that will be edited. In this case,the file to be edited is /sbin/inittab and so the sed script is named/sbin/inittab . There are no requirements for the mode, owner, and group of ased script (represented in the sample prototype by question marks). The filetype of the sed script must be e (indicating that it is editable).

� Set the CLASSESparameter to include the sed class.

As shown in the example file, sed is the only class being installed. However, itcould be one of any number of classes.

� Create a sed class action script.

Your package cannot deliver a copy of /sbin/inittab that looks the way youneed it to, since /sbin/inittab is a dynamic file and you have no way ofknowing how it will look at the time of package installation. However, using ased script allows you to modify the /sbin/inittab file during packageinstallation.


� Create a postinstall script.

You need to execute the init q command to inform the system that/sbin/inittab has been modified. The only place you can perform that actionin this example is in a postinstall script. Looking at the examplepostinstall script, you will see that its only purpose is to execute the init qcommand.

This approach to editing /sbin/inittab during installation has one drawback; youhave to deliver a full script (the postinstall script) simply to perform the init qcommand.

Case Study Files

The pkginfo File

PKG=case4NAME=Case Study #4CATEGORY=applicationsBASEDIR=/optARCH=SPARCVERSION=Version 1d05CLASSES=sed

The prototype File

i pkginfoi postinstalle sed /sbin/inittab ? ? ?

The sed Class Action Script (/sbin/inittab )

!remove# remove all entries from the table that are associated# with this package, though not necessarily just# with this package instance/^[^:]*:[^:]*:[^:]*:[^#]*#ROBOT$/d!install# remove any previous entry added to the table# for this particular change/^[^:]*:[^:]*:[^:]*:[^#]*#ROBOT$/d# add the needed entry at the end of the table;


(Continuation)

# sed(1) does not properly interpret the ’$a’# construct if you previously deleted the last# line, so the command# $a\# rb:023456:wait:/usr/robot/bin/setup #ROBOT# will not work here if the file already contained# the modification. Instead, you will settle for# inserting the entry before the last line!$i\rb:023456:wait:/usr/robot/bin/setup #ROBOT

The postinstall Script

# make init re-read inittab/sbin/init q ||exit 2exit 0

Modifying a File Using the build ClassThis case study modifies a file which exists on the installation machine duringpackage installation. It uses one of three modification methods. The other twomethods are described in “Modifying a File Using Standard Classes and Class ActionScripts” on page 99 and “Modifying a File Using the sed Class and a postinstallScript” on page 103. The file modified is /sbin/inittab .

TechniquesThis case study demonstrates how to use the build class. For more information onthe build class, see “The build Class Script ” on page 67.


ApproachThis approach to modifying /sbin/inittab uses the build class. A build classscript is executed as a shell script and its output becomes the new version of the filebeing executed. In other words, the data file /sbin/inittab that is delivered withthis package will be executed and the output of that execution will become/sbin/inittab .

The build class script is executed during package installation and package removal.The argument install is passed to the file if it is being executed at installationtime. Notice in the sample build class script that installation actions are defined bytesting for this argument.

To edit /sbin/inittab using the build class, you must complete the followingtasks:

� Define the build file in the prototype file.

The entry for the build file in the prototype file should place it in the buildclass and define its file type as e. Be certain that the CLASSESparameter in thepkginfo file is defined as build .

� Create the build class script.

The sample build class script performs the following procedures:

� Edits the /sbin/inittab file to remove any existing changes for thispackage. Notice that the file name /sbin/inittab is hardcoded into the sedcommand.

� If the package is being installed, adds the new line to the end of/sbin/inittab . A comment tag is included in this new entry to describewhere that entry came from.

� Executes the init q command.

This solution addresses the drawbacks described in the case studies in “Modifying aFile Using Standard Classes and Class Action Scripts” on page 99 and “Modifying aFile Using the sed Class and a postinstall Script” on page 103. Only one shortfile is needed (beyond the pkginfo and prototype files). The file works withmultiple instances of a package since the PKGINST parameter is used, and nopostinstall script is required since the init q command can be executed fromthe build class script.


Case Study Files

The pkginfo File

PKG=case6NAME=Case Study #6CATEGORY=applicationsBASEDIR=/optARCH=SPARCVERSION=Version 1d05CLASSES=build

The prototype File

i pkginfoe build /sbin/inittab ? ? ?

The Build File

# PKGINST parameter provided by installation service# remove all entries from the existing table that# are associated with this PKGINSTsed -e "/^[^:]*:[^:]*:[^:]*:[^#]*#$PKGINST$/d" /sbin/inittab ||exit 2if [ "$1" = install ]then# add the following entry to the tableecho "rb:023456:wait:/usr/robot/bin/setup #$PKGINST" ||exit 2fi/sbin/init q ||exit 2exit 0


Modifying crontab Files DuringInstallationThis case study modifies crontab files during package installation.


� Using classes and class action scripts

For more information, see “Writing Class Action Scripts” on page 62.

� Using the crontab command within a class action script

ApproachThe most efficient way to edit more than one file during installation is to define aclass and provide a class action script. If you used the build class approach, youwould need to deliver one build class script for each crontab file edited. Defininga cron class provides a more general approach. To edit crontab files with thisapproach, you must:

� Define the crontab files that are to be edited in the prototype file.

Create an entry in the prototype file for each crontab file that will be edited.Define the class as cron and the file type as e for each file. Use the actual name ofthe file to be edited.

� Create the crontab files for the package.

These files contain the information you want added to the existing crontab filesof the same name.

� Create an installation class action script for the cron class.

The sample i.cron script performs the following procedures:

� Determines the user ID (UID).

The i.cron script sets the variable user to the base name of the cron classscript being processed. That name is the UID. For example, the base name of/var/spool/cron/crontabs/root is root, which is also the UID.

� Executes crontab using the UID and the −l option.


Using the −l option tells crontab to send the contents of the crontab file forthe defined user to the standard output.

� Pipes the output of the crontab command to a sed script that removes anyprevious entries added with this installation technique.

� Puts the edited output into a temporary file.

� Adds the data file for the root UID (that was delivered with the package) to thetemporary file and adds a tag so you will know where these entries came from.

� Executes crontab with the same UID and gives it the temporary file as input.

� Create a removal class action script for the cron class.

The r.cron script is the same as the installation script except there is noprocedure to add information to the crontab file.

These procedures are performed for every file in the cron class.

Case Study Files

The pkginfo Command

PKG=case7NAME=Case Study #7CATEGORY=applicationBASEDIR=/optARCH=SPARCVERSION=Version 1.0CLASSES=cron

The prototype File

i pkginfoi i.croni r.crone cron /var/spool/cron/crontabs/root ? ? ?e cron /var/spool/cron/crontabs/sys ? ? ?


The i.cron Installation Class Action Script

# PKGINST parameter provided by installation servicewhile read src destdouser=‘basename $dest‘ ||exit 2(crontab -l $user |sed -e "/#$PKGINST$/d" > /tmp/$$crontab) ||exit 2sed -e "s/$/#$PKGINST/" $src >> /tmp/$$crontab ||exit 2crontab $user < /tmp/$$crontab ||exit 2rm -f /tmp/$$crontabdoneexit 0

The r.cron Removal Class Action Script

# PKGINST parameter provided by installation servicewhile read pathdouser=‘basename $path‘ ||exit 2(crontab -l $user |sed -e "/#$PKGINST$/d" > /tmp/$$crontab) ||exit 2crontab $user < /tmp/$$crontab ||exit 2rm -f /tmp/$$crontabdoneexit

crontab File #1

41,1,21 * * * * /usr/lib/uucp/uudemon.hour > /dev/null45 23 * * * ulimit 5000; /usr/bin/su uucp -c"/usr/lib/uucp/uudemon.cleanup" >/dev/null 2>&111,31,51 * * * * /usr/lib/uucp/uudemon.poll > /dev/null


crontab File #2

0 * * * 0-6 /usr/lib/sa/sa120,40 8-17 * * 1-5 /usr/lib/sa/sa15 18 * * 1-5 /usr/lib/sa/sa2 -s 8:00 -e 18:01 -i 1200 -A

Note - If editing of a group of files will increase total file size by more than 10K,supply a space file so the pkgadd command can allow for this increase. For moreinformation on the space file, see “Reserving Additional Space on a Target System”on page 48.

Installing and Removing a Driver WithProcedure ScriptsThis package installs a driver.


� Installing and loading a driver with a postinstall script

� Unloading a driver with a preremove script

For more information on these scripts, see “Writing Procedure Scripts” on page 60.

Approach� Create a request script.

The request script determines where the administrator wants the driver objectsto be installed, by questioning the administrator and assigning the answer to the$KERNDIRparameter.

The script ends with a routine to make the two parameters CLASSESandKERNDIRavailable to the installation environment and the postinstall script.



The postinstall script actually performs the driver installation. It is executedafter the two files buffer and buffer.conf have been installed. Thepostinstall file shown for this example performs the following actions:

� Uses the add_drv command to load the driver into the system

� Creates a link for the device using the installf command

� Finalizes the installation using the installf -f command

� Create a preremove script.

The preremove script uses the rem_drv command to unload the driver from thesystem, and then removes the link /dev/buffer0 .

Case Study Files

The pkginfo File

PKG=bufdevNAME=Buffer DeviceCATEGORY=systemBASEDIR=/ARCH=INTELVERSION=Software Issue #19CLASSES=none

The prototype FileTo install a driver at the time of installation, you must include the object andconfiguration files for the driver in the prototype file.

In this example, the executable module for the driver is named buffer ; theadd_drv command operates on this file. The kernel uses the configuration file,buffer.conf , to help configure the driver.

i pkginfoi requesti postinstalli preremovef none $KERNDIR/buffer 444 root rootf none $KERNDIR/buffer.conf 444 root root

(continued)


(Continuation)

Looking at the prototype file for this example, notice the following:

� Since no special treatment is required for the package objects, you can put theminto the standard none class. The CLASSESparameter is set to none in thepkginfo file.

� The path names for buffer and buffer.conf begin with the variable$KERNDIR. This variable is set in the request script and allows the administratorto decide where the driver files should be installed. The default directory is/kernel/drv .

� There is an entry for the postinstall script (the script that will perform thedriver installation).

� Note that a BASEDIR is specified even though this is an absolute package. This isbecause the pkgadd command does not know that $KERNDIRis going to resolveto an absolute path until after the BASEDIRhas been evaluated.

The request Script

trap ’exit 3’ 15# determine where driver object should be placed; location# must be an absolute path name that is an existing directoryKERNDIR=‘ckpath -aoy -d /kernel/drv -p \‘‘Where do you want the driver object installed’’‘ || exit $?

# make parameters available to installation service, and# so to any other packaging scriptscat >$1 <<!

CLASSES=’$CLASSES’KERNDIR=’$KERNDIR’!exit 0


The postinstall Script

# KERNDIR parameter provided by ‘request’ scripterr_code=1 # an error is considered fatal# Load the module into the systemcd $KERNDIRadd_drv -m ’* 0666 root sys’ buffer || exit $err_code# Create a /dev entry for the character node

installf $PKGINST /dev/buffer0=/devices/eisa/buffer*:0 sinstallf -f $PKGINST

The preremove Script

err_code=1 # an error is considered fatal# Unload the driverrem_drv buffer || exit $err_code# remove /dev fileremovef $PKGINST /dev/buffer0 ; rm /dev/buffer0removef -f $PKGINST

Installing a Driver Using the sed Classand Procedure ScriptsThis case study describes how to install a driver using the sed class and procedurescripts. It is also different from the previous case study (see “Installing andRemoving a Driver With Procedure Scripts” on page 111) because this package ismade up of both absolute and relocatable objects.


� Building a prototype file with both absolute and relocatable objects

For more information on building a prototype file, see “Creating a prototypeFile” on page 20.

� Using the sed class


For more information on the sed class, see “The sed Class Script ” on page 66.

� Using a postinstall script


� Using a preremove script


� Using a copyright file

For more information on this file, see “Writing a Copyright Message ” on page 47.

Approach

� Create a prototype file containing both absolute and relocatable package objects.

This is discussed in detail in “The prototype File” on page 116.

� Add the sed class script to the prototype file.

The name of a script must be the name of the file that will be edited. In this case,the file to be edited is /etc/devlink.tab and so the sed script is named/etc/devlink.tab . There are no requirements for the mode, owner, and groupof a sed script (represented in the sample prototype by question marks). Thefile type of the sed script must be e (indicating that it is editable).

� Set the CLASSESparameter to include the sed class.

� Create a sed class action script (/etc/devlink.tab ).


The postinstall script needs to execute the add_drv command to add thedevice driver to the system.

� Create a preremove script.

The preremove script needs to execute the rem_drv command to remove thedevice driver from the system, prior to the package being removed.

� Create a copyright file.

A copyright file contains the ASCII text of a copyright message. The messageshown in the sample file is displayed on the screen during package installation.


Case Study Files

The pkginfo FilePKG=SUNWsstNAME=Simple SCSI Target DriverVERSION=1CATEGORY=systemARCH=sparcVENDOR=Sun MicrosystemsBASEDIR=/optCLASSES=sed

The prototype FileFor example, this case study uses the hierarchical layout of the package objectsshown in Figure 5–1.

pkg

kernel

SUNWsst

drv

sst.conf

sstest.c

usr

include

sys

scsi

targets

sst_def.h

pkginfopostinstallpreremovecopyright

sst

etc

devlink.tab

Figure 5–1 Hierarchical Package Directory Structure

The package objects are installed in the same places as they are in the pkg directoryabove. The driver modules (sst and sst.conf ) are installed into/usr/kernel/drv and the include file is installed into/usr/include/sys/scsi/targets . The sst , sst.conf , and sst_def.h filesare absolute objects. The test program, sstest.c , and its directory SUNWsst arerelocatable; their installation location is set by the BASEDIR parameter.

The remaining components of the package (all the control files) go in the topdirectory of the package on the development machine, except the sed class script.This is called devlink.tab after the file it modifies, and goes into etc , thedirectory containing the real devlink.tab file.


From the pkg directory, run the pkgproto command as follows:

find usr SUNWsst -print | pkgproto > prototype

The output from the above command looks like this:

d none usr 0775 pms mtsd none usr/include 0775 pms mtsd none usr/include/sys 0775 pms mtsd none usr/include/sys/scsi 0775 pms mtsd none usr/include/sys/scsi/targets 0775 pms mtsf none usr/include/sys/scsi/targets/sst_def.h 0444 pms mtsd none usr/kernel 0775 pms mtsd none usr/kernel/drv 0775 pms mtsf none usr/kernel/drv/sst 0664 pms mtsf none usr/kernel/drv/sst.conf 0444 pms mtsd none SUNWsst 0775 pms mtsf none SUNWsst/sstest.c 0664 pms mts

This prototype file is not yet complete. To complete this file, you need to make thefollowing modifications:

� Insert the entries for the control files (file type i ), because they have a differentformat than the other package objects.

� Remove entries for directories that already exist on the target system.

� Change the access permission and ownership for each entry.

� Prepend a slash to the absolute package objects.

This is the final prototype file:

i pkginfoi postinstalli preremovei copyrighte sed /etc/devlink.tab ? ? ?f none /usr/include/sys/scsi/targets/sst_def.h 0644 bin binf none /usr/kernel/drv/sst 0755 root sysf none /usr/kernel/drv/sst.conf 0644 root sysd none SUNWsst 0775 root sysf none SUNWsst/sstest.c 0664 root sys

The questions marks in the entry for the sed script indicate that the accesspermissions and ownership of the existing file on the installation machine should notbe changed.


The sed Class Action Script (/etc/devlink.tab )In the driver example, a sed class script is used to add an entry for the driver to thefile /etc/devlink.tab . This file is used by the devlinks command to createsymbolic links from /dev into /devices . This is the sed script:

# sed class script to modify /etc/devlink.tab!install/name=sst;/d$i\type=ddi_pseudo;name=sst;minor=character rsst\\A1

!remove/name=sst;/d

The pkgrm command does not run the removal part of the script. You may need toadd a line to the preremove script to run sed directly to remove the entry from/etc/devlink.tab .

The postinstall Installation ScriptIn this example, all the script needs to do is run the add_drv command.

# Postinstallation script for SUNWsst# This does not apply to a client.if [$PKG_INSTALL_ROOT = "/" -o -z $PKG_INSTALL_ROOT]; then

SAVEBASE=$BASEDIRBASEDIR=’’’’; export BASEDIR/usr/sbin/add_drv sstSTATUS=$?BASEDIR=$SAVEBASE; export BASEDIRif [ $STATUS -eq 0 ]then

exit 20else

exit 2fi

elseecho "This cannot be installed onto a client."exit 2

fi


Note - This example will probably not work correctly if you install it onto a disklessclient from a server, since there is no reliable way to run the add_drv and rem_drvcommands on that client from the pkgadd command executing on the server. Youmay be better off splitting the package on the root (/ ) and /usr boundaries.

The add_drv command uses the BASEDIRparameter, so the script has to unsetBASEDIR before running the command, and restore it afterwards.

One of the actions of the add_drv command is to run devlinks , which uses theentry placed in /etc/devlink.tab by the sed class script to create the /deventries for the driver.

The exit code from the postinstall script is significant. The exit code 20 tells thepkgadd command to tell the user to reboot the system (necessary after installing adriver), and the exit code 2 tells the pkgadd command to tell the user that theinstallation partially failed.

The preremove Removal ScriptIn the case of this driver example, it removes the links in /dev and runs therem_drv command on the driver.

# Pre removal script for the sst driverecho ‘‘Removing /dev entries’’/usr/bin/rm -f /dev/rsst*

echo ‘‘Deinstalling driver from the kernel’’SAVEBASE=$BASEDIRBASEDIR=’’’’; export BASEDIR/usr/sbin/rem_drv sstBASEDIR=$SAVEBASE; export BASEDIR

exit

The script removes the /dev entries itself; the /devices entries are removed by therem_drv command.

The copyright FileThis is a simple ASCII file containing the text of a copyright notice. The notice isdisplayed at the beginning of package installation exactly as it appears in the file.


Copyright (c) 1996 Drivers-R-Us, Inc.10 Device Drive, Thebus, IO 80586

All rights reserved. This product and related documentation isprotected by copyright and distributed under licensesrestricting its use, copying, distribution and decompilation.No part of this product or related documentation may bereproduced in any form by any means without prior writtenauthorization of Drivers-R-Us and its licensors, if any.


CHAPTER 6

Advanced Package Creation Techniques

The full capabilities of System V packaging as implemented in the Solaris operatingenvironment provide a powerful tool for the installation of software products. As apackage designer, you can take advantage of these capabilities. Packages that are notpart of the Solaris operating environment (unbundled packages) may use the classmechanism to customize server/client installations. Relocatable packages can bedesigned to accommodate the desires of the administrator. A complex product can bedelivered as a set of composite packages that automatically resolve packagedependencies. Upgrading and patching may be customized by the package designer.Patched packages can be delivered in the same way as unpatched packages, and thebackout archives can also be included in the product.


� “Specifying the Base Directory” on page 121

� “Accommodating Relocation” on page 126

� “Supporting Relocation in a Heterogeneous Environment” on page 135

� “Making Packages Installable Remotely” on page 146

� “Patching Packages” on page 148

� “Upgrading Packages” on page 171

Specifying the Base DirectoryYou can use several methods to specify where a package will be installed, and it isimportant to be able to change the installation base dynamically at install time. If thisis accomplished correctly, an administrator can install multiple versions and multiplearchitectures without complications.

121

This section discusses common methods first, followed by approaches that enhanceinstallations to heterogeneous systems.

The Administrative Defaults FileAdministrators responsible for installing packages can use administration files tocontrol package installation. However, as a package designer, you need to knowabout administration files and how an administrator can alter your intended packageinstallation.

An administration file tells the pkgadd command whether to perform any of thechecks or prompts that it normally does. Consequently, administrators should fullyunderstand a package’s installation process and the scripts involved before usingadministration files.

A basic administrative defaults file is shipped with the SunOS operating system in/var/sadm/install/admin/default . This is the file that establishes the mostbasic level of administrative policy as regards the installation of software products.The file looks like this as shipped:

#ident "@(#)default1.4 92/12/23 SMI" /* SVr4.0 1.5.2.1 */mail=instance=uniquepartial=askrunlevel=askidepend=askrdepend=askspace=asksetuid=askconflict=askaction=askbasedir=default

The administrator may edit this file to establish new default behaviors, or create adifferent administration file and specify its existence by using the −a option to thepkgadd command.

Eleven parameters can be defined in an administration file, but not all need to bedefined. For more information, see the admin (4) man page.

The basedir parameter specifies how the base directory will be derived when apackage is installed. Most administrators leave this as default , but basedir can beset to one of the following:

� ask , which means always ask the administrator for a base directory

� An absolute path name


� An absolute path name containing the $PKGINST construction, which meansalways install to a base directory derived from the package instance

Note - If the pkgadd command is called with the argument −a none , it always asksthe administrator for a base directory. Unfortunately, this also sets all parameters inthe file to the default value of quit , which can result in additional problems.

Becoming Comfortable With UncertaintyAn administrator has control over all packages being installed on a system by usingan administration file. Unfortunately, an alternate administrative defaults file is oftenprovided by the package designer, bypassing the wishes of the administrator.

Package designers sometimes include an alternate administration file so that they,not the administrator, control a package’s installation. Because the basedir entry inthe administrative defaults file overrides all other base directories, it provides asimple method for selecting the appropriate base directory at install time. In allversions of the Solaris operating environment prior to release 2.5, this wasconsidered the simplest method for controlling the base directory.

However, it is necessary for you to accept the administrator’s desires regarding theinstallation of the product. Providing a temporary administrative defaults file for thepurpose of controlling the installation leads to mistrust on the part of administrators.You should use a request script and checkinstall script to control theseinstallations under the supervision of the administrator. If the request scriptfaithfully involves the administrator in the process, System V packaging will serveboth administrators and package designers.

Using the BASEDIR ParameterThe pkginfo file for any relocatable package must include a default base directoryin the form of an entry like this:

BASEDIR=absolute_path

This is only the default base directory; it can be changed by the administrator duringinstallation.

While some packages require more than one base directory, the advantage to usingthis parameter to position the package is because the base directory is guaranteed tobe in place and writable as a valid directory by the time installation begins. Thecorrect path to the base directory for the server and client is available to allprocedure scripts in the form of reserved environment variables, and thepkginfo -r SUNWstuf command displays the current installation base for thepackage.

Advanced Package Creation Techniques 123

In the checkinstall script, BASEDIR is the parameter exactly as defined in thepkginfo file (it has not been conditioned yet). In order to inspect the target basedirectory, the ${PKG_INSTALL_ROOT}$BASEDIR construction is required. Thismeans that the request or checkinstall script can change the value of BASEDIRin the installation environment with predictable results. By the time the preinstallscript is called, the BASEDIR parameter is the fully conditioned pointer to the actualbase directory on the target system, even if the system is a client.

Note - The request script utilizes the BASEDIR parameter differently for differentreleases of the SunOS operating system. In order to test a BASEDIR parameter in arequest script, the following code should be used to determine the actual basedirectory in use.

# request scriptconstructs base directoryif [ ${CLIENT_BASEDIR} ]; then

LOCAL_BASE=$BASEDIRelse

LOCAL_BASE=${PKG_INSTALL_ROOT}$BASEDIRfi

Using Parametric Base DirectoriesIf a package requires multiple base directories, you can establish them withparametric path names. This method has become quite popular, although it has thefollowing drawbacks.

� A package with parametric path names usually behaves like an absolute packagebut is treated by the pkgadd command like a relocatable package. The BASEDIRparameter must be defined even if it is not used.

� The administrator cannot ascertain the installation base for the package using theSystem V utilities (the pkginfo -r command will not work).

� The administrator cannot use the established method to relocate the package (it iscalled relocatable but it acts absolute).

� Multiple architecture or multiple version installations require contingencyplanning for each of the target base directories which often means multiplecomplex class action scripts.

While the parameters that determine the base directories are defined in the pkginfofile, they may be modified by the request script. That is one of the primary reasons


for the popularity of this approach. The drawbacks, however are chronic and youshould consider this configuration a last resort.

Example—Using Parametric Base Directories

The pkginfo File

# pkginfo filePKG=SUNWstufNAME=software stuffARCH=sparcVERSION=1.0.0,REV=1.0.4CATEGORY=applicationDESC=a set of utilities that do stuffBASEDIR=/EZDIR=/usr/stuf/EZstufHRDDIR=/opt/SUNWstuf/HRDstufVENDOR=Sun Microsystems, Inc.HOTLINE=Please contact your local service providerEMAIL=MAXINST=1000CLASSES=nonePSTAMP=hubert930603141632

The pkgmap File

: 1 17581 d none $EZDIR 0775 root bin1 f none $EZDIR/dirdel 0555 bin bin 40 773 7513102291 f none $EZDIR/usrdel 0555 bin bin 40 773 7513102291 f none $EZDIR/filedel 0555 bin bin 40 773 7513102291 d none $HRDDIR 0775 root bin1 f none $HRDDIR/mksmart 0555 bin bin 40 773 7513102291 f none $HRDDIR/mktall 0555 bin bin 40 773 7513102291 f none $HRDDIR/mkcute 0555 bin bin 40 773 7513102291 f none $HRDDIR/mkeasy 0555 bin bin 40 773 7513102291 d none /etc ? ? ?1 d none /etc/rc2.d ? ? ?1 f none /etc/rc2.d/S70dostuf 0744 root sys 450 2234431 i pkginfo 348 28411 7607401631 i postinstall 323 26475 7513099081 i postremove 402 33179 7513099451 i preinstall 321 26254 7513100191 i preremove 320 26114 751309865

(continued)


(Continuation)

Managing the Base DirectoryAny package that is available in multiple versions or for multiple architecturesshould be designed to walk the base directory, if needed. Walking a base directorymeans that if a previous version or a different architecture of the package beinginstalled already exists in the base directory, the package being installed resolves thisissue, perhaps by creating a new base directory with a slightly different name. Therequest and checkinstall scripts in the Solaris 2.5 and later releases have theability to modify the BASEDIR environment variable. This is not true for any priorversion of the Solaris operating environment.

Even in older versions of the Solaris operating environment, the request script hadthe authority to redefine directories within the installation base. The request scriptcan do this in a way that still supports most administrative preferences.

Accommodating RelocationWhile you can select base directories for various packages that are guaranteed uniqueto an architecture and version, this leads to unnecessary levels of directory hierarchy.For example, for a product designed for SPARC and x86–based processors, you couldorganize the base directories by processor and version as shown in Table 6–1.

TABLE 6–1

Base Directory Version and Processor

/opt/SUNWstuf/sparc/1.0 Version 1.0, SPARC

/opt/SUNWstuf/sparc/1.2 Version 1.2, SPARC

/opt/SUNWstuf/x86/1.0 Version 1.0, x86


This is okay and it does work, but you are treating names and numbers as thoughthey mean something to the administrator. A better approach is to do thisautomatically after explaining it to the administrator and obtaining permission.

This means that you can do the whole job in the package without requiring theadministrator to do it manually. You can assign the base directory arbitrarily andthen transparently establish the appropriate client links in a postinstall script.You can also use the pkgadd command to install all or part of the package to theclients in the postinstall script. You can even ask the administrator which usersor clients need to know about this package and automatically update PATHenvironment variables and /etc files. This is completely acceptable as long aswhatever the package does upon installation, it undoes upon removal.

Walking Base DirectoriesYou can take advantage of two methods for controlling the base directory at installtime. The first is best for new packages that will install only to Solaris 2.5 and laterreleases; it provides very useful data for the administrator and supports multipleinstalled versions and architectures and requires minimal special work. The secondmethod can be used by any package and makes use of the request script’s inherentcontrol over build parameters to ensure successful installations.

Using the BASEDIRParameterThe checkinstall script can select the appropriate base directory at install time,which means that the base directory can be placed very low in the directory tree.This example increments the base directory sequentially, leading to directories of theform /opt/SUNWstuf , /opt/SUNWstuf.1 , and /opt/SUNWstuf.2 . Theadministrator can use the pkginfo command to determine which architecture andversion are installed in each base directory.

If the SUNWstuf package (containing a set of utilities that do stuff) uses this method,its pkginfo and pkgmap files would look like this.

The pkginfo File

# pkginfo filePKG=SUNWstufNAME=software stuffARCH=sparcVERSION=1.0.0,REV=1.0.4CATEGORY=applicationDESC=a set of utilities that do stuffBASEDIR=/opt/SUNWstuf

(continued)


(Continuation)

VENDOR=Sun Microsystems, Inc.HOTLINE=Please contact your local service providerEMAIL=MAXINST=1000CLASSES=none daemonPSTAMP=hubert930603141632

The pkgmap File

: 1 17581 d none EZstuf 0775 root bin1 f none EZstuf/dirdel 0555 bin bin 40 773 7513102291 f none EZstuf/usrdel 0555 bin bin 40 773 7513102291 f none EZstuf/filedel 0555 bin bin 40 773 7513102291 d none HRDstuf 0775 root bin1 f none HRDstuf/mksmart 0555 bin bin 40 773 7513102291 f none HRDstuf/mktall 0555 bin bin 40 773 7513102291 f none HRDstuf/mkcute 0555 bin bin 40 773 7513102291 f none HRDstuf/mkeasy 0555 bin bin 40 773 7513102291 d none /etc ? ? ?1 d none /etc/rc2.d ? ? ?1 f daemon /etc/rc2.d/S70dostuf 0744 root sys 450 2234431 i pkginfo 348 28411 7607401631 i postinstall 323 26475 7513099081 i postremove 402 33179 7513099451 i preinstall 321 26254 7513100191 i preremove 320 26114 7513098651 i i.daemon 509 39560 7529781031 i r.daemon 320 24573 742152591

Example—Analysis Scripts That Walk a BASEDIR

Assume that the x86 version of SUNWstuf is already installed on the server in/opt/SUNWstuf . When the administrator uses the pkgadd command to install theSPARC version, the request script needs to detect the existence of the x86 versionand interact with the administrator regarding the installation.

Note - The base directory could be walked without administrator interaction in acheckinstall script, but if arbitrary operations like this happen too often,administrators lose confidence in the process.


The request script and checkinstall script for a package that handle thissituation might look like this.

The request Script

# request scriptfor SUNWstuf to walk the BASEDIR parameter.

PATH=/usr/sadm/bin:${PATH} # use admin utilities

GENMSG="The base directory $LOCAL_BASE already contains a \different architecture or version of $PKG."

OLDMSG="If the option \"-a none\" was used, press the \key and enter an unused base directory when it is requested."

OLDPROMPT="Do you want to overwrite this version? "

OLDHELP="\"y\" will replace the installed package, \"n\" will \stop the installation."

SUSPEND="Suspending installation at user request using error \code 1."

MSG="This package could be installed at the unused base directory $WRKNG_BASE."

PROMPT="Do you want to use to the proposed base directory? "

HELP="A response of \"y\" will install to the proposed directory and continue,\"n\" will request a different directory. If the option \"-a none\" was used,press the key and enter an unused base directory when it is requested."

DIRPROMPT="Select a preferred base directory ($WRKNG_BASE) "

DIRHELP="The package $PKG will be installed at the location entered."

NUBD_MSG="The base directory has changed. Be sure to update \any applicable search paths with the actual location of the \binaries which are at $WRKNG_BASE/EZstuf and $WRKNG_BASE/HRDstuf."

OldSolaris=""Changed=""Suffix="0"

## Determine if this product is actually installed in the working# base directory.#Product_is_present () {

if [ -d $WRKNG_BASE/EZstuf -o -d $WRKNG_BASE/HRDstuf ]; thenreturn 1

elsereturn 0

fi

(continued)


(Continuation)

}

if [ ${BASEDIR} ]; then# This may be an old version of Solaris. In the latest Solaris# CLIENT_BASEDIR won’t be defined yet. In older version it is.if [ ${CLIENT_BASEDIR} ]; then

LOCAL_BASE=$BASEDIROldSolaris="true"

else # The base directory hasn’t been processed yetLOCAL_BASE=${PKG_INSTALL_ROOT}$BASEDIR

fi

WRKNG_BASE=$LOCAL_BASE

# See if the base directory is already in place and walk it if# possible

while [ -d ${WRKNG_BASE} -a Product_is_present ]; do# There is a conflict# Is this an update of the same arch & version?if [ ${UPDATE} ]; then

exit 0 # It’s out of our hands.else

# So this is a different architecture or# version than what is already there.# Walk the base directorySuffix=‘expr $Suffix + 1‘WRKNG_BASE=$LOCAL_BASE.$SuffixChanged="true"

fidone

# So now we can propose a base directory that isn’t claimed by# any of our other versions.

if [ $Changed ]; thenputtext "$GENMSG"if [ $OldSolaris ]; then

puttext "$OLDMSG"result=‘ckyorn -Q -d "a" -h "$OLDHELP" -p "$OLDPROMPT"‘if [ $result="n" ]; then

puttext "$SUSPEND"exit 1 # suspend installation

elseexit 0

fielse # The latest functionality is available

puttext "$MSG"result=‘ckyorn -Q -d "a" -h "$HELP" -p "$PROMPT"‘if [ $? -eq 3]; then

echo quitinstall >> $1exit 0

fi

if [ $result="n" ]; thenWRKNG_BASE=‘ckpath -ayw -d "$WRKNG_BASE" \

(continued)


(Continuation)

-h "$DIRHELP" -p "$DIRPROMPT"‘else if [ $result="a" ]

exit 0fifiecho "BASEDIR=$WRKNG_BASE" >> $1puttext "$NUBD_MSG"

fifiexit 0

The checkinstall Script

# checkinstallscript for SUNWstuf to politely suspend

grep quitinstall $1if [ $? -eq 0 ]; then

exit 3 # politely suspend installationfi

exit 0

This approach would not work very well if the base directory was simply /opt . Thispackage has to call out the BASEDIR more precisely since /opt would be difficult towalk. In fact, depending on the mount scheme, it may not be possible. The examplewalks the base directory by creating a new directory under /opt , which does notintroduce any problems.

This example uses a request script and a checkinstall script even thoughversions of Solaris prior to the 2.5 release cannot run a checkinstall script. Thecheckinstall script in this example is used for the purpose of politely halting theinstallation in response to a private message in the form of the string “quitinstall.” Ifthis script executes under the Solaris 2.3 release, the checkinstall script is ignoredand the request script halts the installation with an error message.

Remember that prior to the Solaris 2.5 release, the BASEDIRparameter is a read-onlyparameter and cannot be changed by the request script. For this reason, if an oldversion of the SunOS operating system is detected (by testing for a conditionedCLIENT_BASEDIR environment variable), the request script has only twooptions—continue or quit.


Using Relative Parametric PathsIf your software product might be installed on older versions of the SunOS operatingsystem, the request script needs to do all the necessary work. This approach canalso be used to manipulate multiple directories. If additional directories are required,they still need to be included under a single base directory in order to provide aneasily administrable product. While the BASEDIRparameter does not provide thelevel of granularity available in the latest Solaris release, your package can still walkthe base directory by using the request script to manipulate parametric paths. Thisis how the pkginfo and pkgmap files might look.

The pkginfo File

# pkginfo filePKG=SUNWstufNAME=software stuffARCH=sparcVERSION=1.0.0,REV=1.0.4CATEGORY=applicationDESC=a set of utilities that do stuffBASEDIR=/optSUBBASE=SUNWstufVENDOR=Sun Microsystems, Inc.HOTLINE=Please contact your local service providerEMAIL=MAXINST=1000CLASSES=none daemonPSTAMP=hubert930603141632

The pkgmap File

: 1 17581 d none $SUBBASE/EZstuf 0775 root bin1 f none $SUBBASE/EZstuf/dirdel 0555 bin bin 40 773 7513102291 f none $SUBBASE/EZstuf/usrdel 0555 bin bin 40 773 7513102291 f none $SUBBASE/EZstuf/filedel 0555 bin bin 40 773 7513102291 d none $SUBBASE/HRDstuf 0775 root bin1 f none $SUBBASE/HRDstuf/mksmart 0555 bin bin 40 773 7513102291 f none $SUBBASE/HRDstuf/mktall 0555 bin bin 40 773 7513102291 f none $SUBBASE/HRDstuf/mkcute 0555 bin bin 40 773 7513102291 f none $SUBBASE/HRDstuf/mkeasy 0555 bin bin 40 773 7513102291 d none /etc ? ? ?1 d none /etc/rc2.d ? ? ?1 f daemon /etc/rc2.d/S70dostuf 0744 root sys 450 2234431 i pkginfo 348 28411 7607401631 i postinstall 323 26475 751309908

(continued)


(Continuation)

1 i postremove 402 33179 7513099451 i preinstall 321 26254 7513100191 i preremove 320 26114 7513098651 i i.daemon 509 39560 7529781031 i r.daemon 320 24573 742152591

This example is not perfect. A pkginfo -r command returns /opt for theinstallation base, which is pretty ambiguous. Many packages are in /opt , but at leastit is a meaningful directory. Just like the previous example, this next example fullysupports multiple architectures and versions. The request script can be tailored tothe needs of the specific package and resolve whatever dependencies are applicable.

Example—A request Script That Walks a RelativeParametric Path

# request scriptfor SUNWstuf to walk a parametric path

PATH=/usr/sadm/bin:${PATH} # use admin utilities

MSG="The target directory $LOCAL_BASE already contains \different architecture or version of $PKG. This package \could be installed at the unused target directory $WRKNG_BASE."

PROMPT="Do you want to use to the proposed directory? "

HELP="A response of \"y\" will install to the proposed directory \and continue, \"n\" will request a different directory. If \the option \"-a none\" was used, press the <RETURN> key and \enter an unused base directory when it is requested."

DIRPROMPT="Select a relative target directory under $BASEDIR/"

DIRHELP="The package $PKG will be installed at the location entered."

SUSPEND="Suspending installation at user request using error \code 1."

NUBD_MSG="The location of this package is not the default. Be \sure to update any applicable search paths with the actual \location of the binaries which are at $WRKNG_BASE/EZstuf \and $WRKNG_BASE/HRDstuf."

(continued)


(Continuation)

Changed=""Suffix="0"

## Determine if this product is actually installed in the working# base directory.#Product_is_present () {

if [ -d $WRKNG_BASE/EZstuf -o -d $WRKNG_BASE/HRDstuf ]; thenreturn 1

elsereturn 0

fi}

if [ ${BASEDIR} ]; then# This may be an old version of Solaris. In the latest Solaris# CLIENT_BASEDIR won’t be defined yet. In older versions it is.if [ ${CLIENT_BASEDIR} ]; then

LOCAL_BASE=$BASEDIR/$SUBBASEelse # The base directory hasn’t been processed yet

LOCAL_BASE=${PKG_INSTALL_ROOT}$BASEDIR/$SUBBASEfi

WRKNG_BASE=$LOCAL_BASE

# See if the base directory is already in place and walk it if# possiblewhile [ -d ${WRKNG_BASE} -a Product_is_present ]; do

# There is a conflict# Is this an update of the same arch & version?if [ ${UPDATE} ]; then

exit 0 # It’s out of our hands.else

# So this is a different architecture or# version than what is already there.# Walk the base directorySuffix=‘expr $Suffix + 1‘WRKNG_BASE=$LOCAL_BASE.$SuffixChanged="true"

fidone

# So now we can propose a base directory that isn’t claimed by# any of our other versions.if [ $Changed ]; then

puttext "$MSG"result=‘ckyorn -Q -d "a" -h "$HELP" -p "$PROMPT"‘if [ $? -eq 3 ]; then

puttext "$SUSPEND"exit 1

fi

(continued)


(Continuation)

if [ $result="n" ]; thenWRKNG_BASE=‘ckpath -lyw -d "$WRKNG_BASE" -h "$DIRHELP" \-p "$DIRPROMPT"‘

elif [ $result="a" ]; thenexit 0

elseexit 1

fiecho SUBBASE=$SUBBASE.$Suffix >> $1puttext "$NUBD_MSG"

fifiexit 0

Supporting Relocation in aHeterogeneous EnvironmentThe original concept behind System V packaging assumed one architecture persystem. The concept of a server did not play a role in the design. Now, of course, asingle server may provide support for several architectures, which means there maybe several copies of the same software on a server, each for a different architecture.While Solaris packages are sequestered within recommended file system boundaries(for example, / and /usr ), with product databases on the server as well as eachclient, not all installations necessarily support this division. Certain implementationssupport an entirely different structure and imply a common product database. Whilepointing the clients to different versions is straightforward, actually installing SystemV packages to different base directories can introduce complications for theadministrator.

When you design your package, you should also consider the common methodsadministrators use for introducing new software versions. Administrators often seekto install and test the latest version side-by-side with the currently installed version.The procedure involves installing the new version to a different base directory thanthe current version and directing a handful of non-critical clients to the new versionas a test. As confidence builds, the administrator redirects more and more clients to


the new version. Eventually, the administrator retains the old version only foremergencies and then finally deletes it.

What this means is that packages destined for modern heterogeneous systems mustsupport true relocation in the sense that the administrator may put them anyreasonable place on the file system and still see full functionality. The Solaris 2.5 andlater releases provide a number of useful tools which allow multiple architecturesand versions to install cleanly to the same system. Older versions of the SunOSoperating system also support true relocation but accomplishing the task is not quiteas obvious.

Traditional Approach

Relocatable PackagesThe System V ABI implies that the original intention behind the relocatable packagewas to make installing the package more convenient for the administrator. Now theneed for relocatable packages goes much further. Convenience is not the only issue,rather it is quite possible that during the installation an active software product isalready installed in the default directory. A package that is not designed to deal withthis situation either overwrites the existing product or fails to install. However, apackage designed handle multiple architectures and multiple versions can installsmoothly and offer the administrator a wide range of options that are fullycompatible with existing administrative traditions.

In some ways the problem of multiple architectures and the problem of multipleversions is the same. It must be possible to install a variant of the existing packageside by side with other variants, and direct clients or standalone consumers ofexported file systems to any one of those variants, without degraded functionality.While Sun has established methods for dealing with multiple architectures on aserver, the administrator may not adhere to those recommendations. All packagesneed to be capable of complying with the administrators’ reasonable wishesregarding installation.

Example-A Traditional Relocatable PackageThis example shows what a traditional relocatable package may look like. Thepackage is to be located in /opt/SUNWstuf , and its pkginfo file and pkgmap filemight look like this.


The pkginfo File

# pkginfo filePKG=SUNWstufNAME=software stuffARCH=sparcVERSION=1.0.0,REV=1.0.4CATEGORY=applicationDESC=a set of utilities that do stuffBASEDIR=/optVENDOR=Sun Microsystems, Inc.HOTLINE=Please contact your local service providerEMAIL=MAXINST=1000CLASSES=nonePSTAMP=hubert930603141632

The pkgmap File

: 1 17581 d none SUNWstuf 0775 root bin1 d none SUNWstuf/EZstuf 0775 root bin1 f none SUNWstuf/EZstuf/dirdel 0555 bin bin 40 773 7513102291 f none SUNWstuf/EZstuf/usrdel 0555 bin bin 40 773 7513102291 f none SUNWstuf/EZstuf/filedel 0555 bin bin 40 773 7513102291 d none SUNWstuf/HRDstuf 0775 root bin1 f none SUNWstuf/HRDstuf/mksmart 0555 bin bin 40 773 7513102291 f none SUNWstuf/HRDstuf/mktall 0555 bin bin 40 773 7513102291 f none SUNWstuf/HRDstuf/mkcute 0555 bin bin 40 773 7513102291 f none SUNWstuf/HRDstuf/mkeasy 0555 bin bin 40 773 7513102291 i pkginfo 348 28411 7607401631 i postinstall 323 26475 7513099081 i postremove 402 33179 7513099451 i preinstall 321 26254 7513100191 i preremove 320 26114 751309865

This is referred to as the traditional method because every package object is installedto the base directory defined by the BASEDIR parameter from the pkginfo file. Forexample, the first object in the pkgmap file is installed as the directory/opt/SUNWstuf .

Absolute Packages

An absolute package is one that installs to a particular root (/ ) file system. Thesepackages are difficult to deal with from the standpoint of multiple versions and


architectures. As a general rule, all packages should be relocatable. There are,however very good reasons to include absolute elements in a relocatable package.

Example-A Traditional Absolute PackageIf the SUNWstuf package was an absolute package, the BASEDIR parameter shouldnot be defined in the pkginfo file, and the pkgmap file would look like this.

The pkgmap File

: 1 17581 d none /opt ? ? ?1 d none /opt/SUNWstuf 0775 root bin1 d none /opt/SUNWstuf/EZstuf 0775 root bin1 f none /opt/SUNWstuf/EZstuf/dirdel 0555 bin bin 40 773 7513102291 f none /opt/SUNWstuf/EZstuf/usrdel 0555 bin bin 40 773 7513102291 f none /opt/SUNWstuf/EZstuf/filedel 0555 bin bin 40 773 7513102291 d none /opt/SUNWstuf/HRDstuf 0775 root bin1 f none /opt/SUNWstuf/HRDstuf/mksmart 0555 bin bin 40 773 7513102291 f none /opt/SUNWstuf/HRDstuf/mktall 0555 bin bin 40 773 7513102291 f none /opt/SUNWstuf/HRDstuf/mkcute 0555 bin bin 40 773 7513102291 f none /opt/SUNWstuf/HRDstuf/mkeasy 0555 bin bin 40 773 7513102291 i pkginfo 348 28411 7607401631 i postinstall 323 26475 7513099081 i postremove 402 33179 7513099451 i preinstall 321 26254 7513100191 i preremove 320 26114 751309865

In this example, if the administrator specified an alternate base directory duringinstallation, it would be ignored by the pkgadd command. This package alwaysinstalls to /opt/SUNWstuf of the target system.

The −R argument to the pkgadd command works as expected. For example,

pkgadd -d . -R /export/opt/client3 SUNWstuf

installs the objects in /export/opt/client3/opt/SUNWstuf ; but that is theclosest this package comes to being relocatable.

Notice the use of the question mark (?) for the /opt directory in the pkgmap file.This indicates that the existing attributes should not be changed. It does not mean“create the directory with default attributes,” although under certain circumstancesthat may happen. Any directory that is specific to the new package must specify allattributes explicitly.


Composite PackagesAny package containing relocatable objects is referred to as a relocatable package.This can be misleading because a relocatable package may contain absolute paths inits pkgmap file. Using a root (/ ) entry in a pkgmap file can enhance the relocatableaspects of the package. Packages that have both relocatable and root entries arecalled composite packages.

Example-A Traditional SolutionAssume that one object in the SUNWstuf package is a startup script executed at runlevel 2. The file /etc/rc2.d/S70dostuf needs to be installed as a part of thepackage, but it cannot be placed into the base directory. Assuming that a relocatablepackage is the only solution, the pkginfo and a pkgmap might look like this.

The pkginfo File

# pkginfo filePKG=SUNWstufNAME=software stuffARCH=sparcVERSION=1.0.0,REV=1.0.4CATEGORY=applicationDESC=a set of utilities that do stuffBASEDIR=/VENDOR=Sun Microsystems, Inc.HOTLINE=Please contact your local service providerEMAIL=MAXINST=1000CLASSES=nonePSTAMP=hubert930603141632

The pkgmap File

: 1 17581 d none opt/SUNWstuf/EZstuf 0775 root bin1 f none opt/SUNWstuf/EZstuf/dirdel 0555 bin bin 40 773 7513102291 f none opt/SUNWstuf/EZstuf/usrdel 0555 bin bin 40 773 7513102291 f none opt/SUNWstuf/EZstuf/filedel 0555 bin bin 40 773 7513102291 d none opt/SUNWstuf/HRDstuf 0775 root bin1 f none opt/SUNWstuf/HRDstuf/mksmart 0555 bin bin 40 773 7513102291 f none opt/SUNWstuf/HRDstuf/mktall 0555 bin bin 40 773 7513102291 f none opt/SUNWstuf/HRDstuf/mkcute 0555 bin bin 40 773 7513102291 f none opt/SUNWstuf/HRDstuf/mkeasy 0555 bin bin 40 773 751310229

(continued)


(Continuation)

1 d none etc ? ? ?1 d none etc/rc2.d ? ? ?1 f none etc/rc2.d/S70dostuf 0744 root sys 450 2234431 i pkginfo 348 28411 7607401631 i postinstall 323 26475 7513099081 i postremove 402 33179 7513099451 i preinstall 321 26254 7513100191 i preremove 320 26114 751309865

There is not much difference between this approach and that of the absolute package.In fact, this would be better off as an absolute package—if the administratorprovided an alternate base directory for this package, it would not work!

In fact, only one file in this package needs to be root-relative, the rest could bemoved anywhere. How to solve this problem through the use of a compositepackage is discussed throughout the remainder of this section.

Beyond TraditionThe approach described in this section does not apply to all packages, but it doesresult in improved performance during installation to an heterogeneousenvironment. Very little of this applies to packages that are delivered as part of theSolaris operating environment (bundled packages); however, unbundled packagescan practice non-traditional packaging.

The reason behind encouraging relocatable packages is to support this requirement:

When a package is added or removed, the existing desirable behaviors of installed softwareproducts will be unchanged.

Unbundled packages should reside under /opt so as to assure that the new packagedoes not interfere with existing products.

Another Look at Composite PackagesThere are two rules to follow when constructing a functional composite package:

� Establish the base directory based upon where the vast majority of the packageobjects go.

� If a package object goes into a common directory that is not the base directory (forexample, /etc ), specify it as an absolute path name in the prototype file.


In other words, since “relocatable” means the object can be installed anywhere andstill work, no startup script run by init at boot time can be considered relocatable!While there is nothing wrong with specifying /etc/passwd as a relative path in thedelivered package, there is only one place it can go.

Making Absolute Path Names Look RelocatableIf you are going to construct a composite package, the absolute paths must operatein a manner which does not interfere with existing installed software. A package thatcan be entirely contained in /opt gets around this problem since there are noexisting files in the way. When a file in /etc is included in the package, you mustensure that the absolute path names behave in the same way that is expected fromrelative path names. Consider the following two examples.

Example—Modifying a File

DescriptionAn entry is being added to a table, or the object is a new table which is likely to bemodified by other programs or packages.

ImplementationDefine the object as file type e and belonging to the build , awk, or sed class. Thescript that performs this task must remove itself as effectively as it adds itself.

ExampleAn entry needs to be added to /etc/vfstab in support of the new solid state harddisk.

The entry in the pkgmap file might be

1 e sed /etc/vfstab ? ? ?

The request script asks the operator if /etc/vfstab should be modified by thepackage. If the operator answers “no” then the request script will print instructionson how to do the job manually and will execute

echo "CLASSES=none" >> $1

If the operator answers “yes” then it executes

echo "CLASSES=none sed" >> $1


which activates the class action script that will make the necessary modifications.The sed class means that the package file /etc/vfstab is a sed program whichcontains both the install and remove operations for the same-named file on the targetsystem.

Example—Creating a New File

DescriptionThe object is an entirely new file that is unlikely to be edited at a later time or, it isreplacing a file owned by another package.

ImplementationDefine the package object as file type f and install it using a class action scriptcapable of undoing the change.

ExampleA brand new file is required in /etc to provide the necessary information tosupport the solid state hard disk, named /etc/shdisk.conf . The entry in thepkgmap file might look like this:

.

.

.1 f newetc /etc/shdisk.conf...

The class action script i.newetc is responsible for installing this and any other filesthat need to go into /etc . It checks to make sure there is not another file there. Ifthere is not, it will simply copy the new file into place. If there is already a file inplace, it will back it up before installing the new file. The script r.newetc removesthese files and restores the originals, if required. Here is the key fragment of theinstall script.


# i.newetcwhile read src dst; do

if [ -f $dst ]; thendstfile=‘basename $dst‘cp $dst $PKGSAV/$dstfile

ficp $src $dst

done

if [ "${1}" = "ENDOFCLASS" ]; thencd $PKGSAVtar cf SAVE.newetc .$INST_DATADIR/$PKG/install/squish SAVE.newetc

fi

Notice that this script uses the PKGSAVenvironment variable to store a backup of thefile to be replaced. When the argument ENDOFCLASSis passed to the script, that isthe pkgadd command informing the script that these are the last entries in this class,at which point the script archives and compresses the files that were saved using aprivate compression program stored in the install directory of the package.

While the use of the PKGSAVenvironment variable is not reliable during a packageupdate; if the package is not updated (through a patch, for instance) the backup fileis secure. The following remove script includes code to deal with the otherissue—the fact that older versions of the pkgrm command do not pass the scripts thecorrect path to the PKGSAVenvironment variable.

The removal script might look like this.

# r.newetc

# make sure we have the correct PKGSAVif [ -d $PKG_INSTALL_ROOT$PKGSAV ]; then

PKGSAV="$PKG_INSTALL_ROOT$PKGSAV"fi

# find the unsquish programUNSQUISH_CMD=‘dirname $0‘/unsquish

while read file; dorm $file

done

if [ "${1}" = ENDOFCLASS ]; thenif [ -f $PKGSAV/SAVE.newetc.sq ]; then

$UNSQUISH_CMD $PKGSAV/SAVE.newetcfi

(continued)


(Continuation)

if [ -f $PKGSAV/SAVE.newetc ]; thentargetdir=dirname $file # get the right directorycd $targetdirtar xf $PKGSAV/SAVE.newetcrm $PKGSAV/SAVE.newetc

fifi

This script uses a private uninstalled algorithm (unsquish ) which is in the installdirectory of the package database. This is done automatically by the pkgaddcommand at install time. All scripts not specifically recognized as install-only by thepkgadd command are left in this directory for use by the pkgrm command. Youcannot count on where that directory is, but you can depend on the directory beingflat and containing all appropriate information files and installation scripts for thepackage. This script finds the directory by virtue of the fact that the class actionscript is guaranteed to be executing from the directory that contains the unsquishprogram.

Notice, also, that this script does not just assume the target directory is /etc . It mayactually be /export/root/client2/etc . The correct directory could beconstructed in one of two ways.

� Use the ${PKG_INSTALL_ROOT}/etc construction, or

� Take the directory name of a file passed by the pkgadd command (which is whatthis script does).

By using this approach for each absolute object in the package, you can be sure thatthe current desirable behavior is unchanged or at least recoverable.

Example—A Composite PackageThis is an example of the pkginfo and pkgmap files for a composite package.

The pkginfo File

PKG=SUNWstufNAME=software stuffARCH=sparcVERSION=1.0.0,REV=1.0.4CATEGORY=applicationDESC=a set of utilities that do stuff


(Continuation)

BASEDIR=/optVENDOR=Sun Microsystems, Inc.HOTLINE=Please contact your local service providerEMAIL=MAXINST=1000CLASSES=none daemonPSTAMP=hubert930603141632

The pkgmap File

: 1 17581 d none SUNWstuf/EZstuf 0775 root bin1 f none SUNWstuf/EZstuf/dirdel 0555 bin bin 40 773 7513102291 f none SUNWstuf/EZstuf/usrdel 0555 bin bin 40 773 7513102291 f none SUNWstuf/EZstuf/filedel 0555 bin bin 40 773 7513102291 d none SUNWstuf/HRDstuf 0775 root bin1 f none SUNWstuf/HRDstuf/mksmart 0555 bin bin 40 773 7513102291 f none SUNWstuf/HRDstuf/mktall 0555 bin bin 40 773 7513102291 f none SUNWstuf/HRDstuf/mkcute 0555 bin bin 40 773 7513102291 f none SUNWstuf/HRDstuf/mkeasy 0555 bin bin 40 773 7513102291 d none /etc ? ? ?1 d none /etc/rc2.d ? ? ?1 e daemon /etc/rc2.d/S70dostuf 0744 root sys 450 2234431 i i.daemon 509 39560 7529781031 i pkginfo 348 28411 7607401631 i postinstall 323 26475 7513099081 i postremove 402 33179 7513099451 i preinstall 321 26254 7513100191 i preremove 320 26114 7513098651 i r.daemon 320 24573 742152591

While S70dostuf belongs to the daemon class, the directories that lead up to it(which are already in place at install time) belong to the none class. Even if thedirectories were unique to this package, you should leave them in the none class.The reason for this is that the directories need to be created first and deleted last, andthis is always true for the none class. The pkgadd command creates directories; theyare not copied from the package and they are not passed to a class action script to becreated. Instead, they are created by the pkgadd command before it calls the installclass action script, and the pkgrm command deletes directories after completion ofthe removal class action script.


This means that if a directory in a special class contains objects in the class none ,when the pkgrm command attempts to remove the directory, it fails because thedirectory will not be empty in time. If an object of class none is to be inserted into adirectory of some special class, that directory will not exist in time to accept theobject. The pkgadd command will create the directory on-the-fly during installationof the object and may not be able to synchronize the attributes of that directory whenit finally sees the pkgmap definition.

Note - When assigning a directory to a class, always remember the order of creationand deletion.

Making Packages Installable RemotelyAll packages must be installable remotely. Installable remotely means you do notassume the administrator installing your package is installing to the root (/ ) filesystem of the system running the pkgadd command. If, in one of your procedurescripts, you need to get to the /etc/vfstab file of the target system, you need touse the PKG_INSTALL_ROOTenvironment variable. In other words, the path name/etc/vfstab will get you to the /etc/vfstab file of the system running thepkgadd command, but the administrator may be installing to a client at/export/root/client3 . The path ${PKG_INSTALL_ROOT}/etc/vfstab isguaranteed to get you to the target file system.

Example—Installing to a ClientIn this example, the SUNWstuf package is installed to client3 , which is configuredwith /opt in its root (/ ) file system. One other version of this package is alreadyinstalled on client3 , and the base directory is set to basedir=/opt/$PKGINSTfrom an administration file, thisadmin . (For more information on administrationfiles, see “The Administrative Defaults File” on page 122.) The pkgadd commandexecuted on the server is:

pkgadd -a thisadmin -R /export/root/client3 SUNWstuf

Table 6–2 lists the environment variables and their values that are passed to theprocedure scripts.


TABLE 6–2 Values Passed to Procedure Scripts

Environment Variable Value

PKGINST SUNWstuf.2

PKG_INSTALL_ROOT /export/root/client3

CLIENT_BASEDIR /opt/SUNWstuf.2

BASEDIR /export/root/client3/opt/SUNWstuf.2

Example—Installing to a Server or StandaloneTo install to the server or a standalone system under the same circumstances as theprevious example, the command is:

pkgadd -a thisadmin SUNWstuf

Table 6–3 lists the environment variables and their values that are passed to theprocedure scripts.

TABLE 6–3 Values Passed to Procedure Scripts

Environment Variable Value

PKGINST SUNWstuf.2

PKG_INSTALL_ROOT Not defined.

CLIENT_BASEDIR /opt/SUNWstuf.2

BASEDIR /opt/SUNWstuf.2


Example—Mounting Shared File SystemsAssume that the SUNWstuf package creates and shares a file system on the server at/export/SUNWstuf/share . When the package is installed to the clients, their/etc/vfstab files need to be updated to mount this shared file system. This is asituation where you can use the CLIENT_BASEDIR variable.

The entry on the client needs to present the mount point with reference to the client’sfile system. This line should be constructed correctly whether the installation is fromthe server or from the client. Assume that the server’s system name is $SERVER. Youcan go to $PKG_INSTALL_ROOT/etc/vfstab and, using the sed or awkcommands, construct the following line for the client’s /etc/vfstab file.

$SERVER:/export/SUNWstuf/share - $CLIENT_BASEDIR/usr nfs - yes ro

For example, for the server universe and the client system client9 , the line in theclient system’s /etc/vfstab file would look like:

universe:/export/SUNWstuf/share - /opt/SUNWstuf.2/usr nfs - yes ro

Using these parameters correctly, the entry always mounts the client’s file system,whether it is being constructed locally or from the server.

Patching PackagesA patch to a package is just a sparse package designed to overwrite certain files inthe original. There is no real reason for shipping a sparse package except to savespace on the delivery medium. You could also ship the entire original package with afew files changed, or provide access to the modified package over a network. Aslong as only those new files are actually different (the other files were notrecompiled), the pkgadd command installs the differences. Review the followingguidelines regarding patching packages.

� A patch must not change the intended delivered behavior of the package—it is nota mechanism for installing new features. A patch is used to repair objects installedon the system.

� If the system is complex enough, it is wise to establish a patch identificationsystem which assures that no two patches replace the same file in an attempt to


correct different aberrant behaviors. For instance, Sun patch base numbers areassigned mutually exclusive sets of files for which they are responsible.

� It is necessary to be able to back out a patch.

It is crucial that the version number of the patch package be the same as that of theoriginal package. This is true because a patch must not add functionality. You shouldkeep track of the patch status of the package using a separate pkginfo file entry ofthe form

PATCH=patch_number

If the package version is changed for a patch, you create another instance of thepackage and it becomes extremely difficult to manage the patched product. Thismethod of progressive instance patching carried certain advantages in the earlyreleases of the Solaris operating environment, but makes management of morecomplicated systems tedious.

As far as the packages that make up the Solaris operating environment areconcerned, there should be only one copy of the package in the package database,although there may be multiple patched instances. In order to remove an object froman installed package (using the removef command) you need to figure out whatinstances own that file.

However, if your package (that is not part of the Solaris operating environment)needs to determine the patch level of a particular package that is part of the Solarisoperating environment, this becomes a problem to be resolved here. The installationscripts can be quite large without significant impact since they are not stored on thetarget file system. Using class action scripts and various other procedure scripts, youcan save changed files using the PKGSAVenvironment variable (or to some other,more permanent directory) in order to allow backing out installed patches. You canalso monitor patch history by setting appropriate environment variables through therequest scripts. The scripts in the next sections assume that there may be multiplepatches whose numbering scheme carries some meaning when applied to a singlepackage. In this case, individual patch numbers represent a subset of functionallyrelated files within the package. Two different patch numbers cannot change thesame file.

In order to make a regular sparse package into a patch package, the scripts describedin the following sections can simply be folded into the package. All of them arerecognizable as standard package components with the exception of the last twowhich are named patch_checkinstall and patch_postinstall . Those twoscripts can be incorporated into the backout package, if you want to include theability to back out the patch. The scripts are fairly simple and their various tasks arestraightforward.

Note - This method of patching can be used to patch client systems, but client rootdirectories on the server must have the correct permissions to allow reading by theuser install or nobody .


The checkinstall ScriptThe checkinstall script verifies that the patch is appropriate for this particularpackage. Once that is confirmed, it constructs the patch list and the patch info list, andthen inserts them into the response file for incorporation into the package database.

A patch list is the list of patches that have affected the current package. This list ofpatches is recorded in the installed package in the pkginfo file with a line thatmight look like this:

PATCHLIST=patch_id patch_id ...

A patch info list is the list of patches on which the current patch is dependent. Thislist of patches is also recorded in the pkginfo file with a line that might look likethis.

PATCH_INFO_103203-01=Installed... Obsoletes:103201-01 Requires: \Incompatibles: 120134-01

Note - These lines (and their format) are declared as a public interface. Anycompany that ships patches for Solaris packages should update this listappropriately. When a patch is delivered, each package within the patch contains acheckinstall script that performs this task. That same checkinstall script alsoupdates some other patch-specific parameters. This is the new patch architecture,which is called Direct Instance Patching.

In this example, both the original packages and their patches exist in the samedirectory. The two original packages are named SUNWstuf.v1 and SUNWstuf.v2 ,and their patches are named SUNWstuf.p1 and SUNWstuf.p2 . What this means isthat it could be very difficult for a procedure script to figure out what directory thesefiles came from, since everything in the package name after the dot (“.”) is strippedfor the PKGparameter, and the PKGINST environment variable refers to the installedinstance not the source instance. So the procedure scripts can find the sourcedirectory, the checkinstall script (which is always executed from the sourcedirectory) makes the inquiry and passes the location on as the variableSCRIPTS_DIR. If there had been only one package in the source directory calledSUNWstuf , then the procedure scripts could have found it using $INSTDIR/$PKG .

# checkinstall script to control a patch installation.# directory format options.## @(#)checkinstall 1.6 96/09/27 SMI## Copyright (c) 1995 by Sun Microsystems, Inc.


(Continuation)

# All rights reserved#

PATH=/usr/sadm/bin:$PATH

INFO_DIR=‘dirname $0‘INFO_DIR=‘dirname $INFO_DIR‘ # one level up

NOVERS_MSG="PaTcH_MsG 8 Version $VERSION of $PKG is not installed on this system."ALRDY_MSG="PaTcH_MsG 2 Patch number $Patch_label is already applied."TEMP_MSG="PaTcH_MsG 23 Patch number $Patch_label cannot be applied until all \restricted patches are backed out."

# Read the provided environment from what may have been a request script. $1

# Old systems can’t deal with checkinstall scripts anywayif [ "$PATCH_PROGRESSIVE" = "true" ]; then

exit 0fi

## Confirm that the intended version is installed on the system.#if [ "${UPDATE}" != "yes" ]; then

echo "$NOVERS_MSG"exit 3

fi

## Confirm that this patch hasn’t already been applied and# that no other mix-ups have occurred involving patch versions and# the like.#Skip=0active_base=‘echo $Patch_label | nawk ’

{ print substr($0, 1, match($0, "Patchvers_pfx")-1) } ’‘active_inst=‘echo $Patch_label | nawk ’

{ print substr($0, match($0, "Patchvers_pfx")+Patchvers_pfx_lnth) } ’‘

# Is this a restricted patch?if echo $active_base | egrep -s "Patchstrict_str"; then

is_restricted="true"# All restricted patches are backoutableecho "PATCH_NO_UNDO=" >> $1

elseis_restricted="false"

fi

for patchappl in ${PATCHLIST}; do# Is this an ordinary patch applying over a restricted patch?if [ $is_restricted = "false" ]; then

if echo $patchappl | egrep -s "Patchstrict_str"; thenecho "$TEMP_MSG"

(continued)


(Continuation)

exit 3;fi

fi

# Is there a newer version of this patch?appl_base=‘echo $patchappl | nawk ’

{ print substr($0, 1, match($0, "Patchvers_pfx")-1) } ’‘if [ $appl_base = $active_base ]; then

appl_inst=‘echo $patchappl | nawk ’{ print substr($0, match($0, "Patchvers_pfx")\

+Patchvers_pfx_lnth) } ’‘result=‘expr $appl_inst \> $active_inst‘if [ $result -eq 1 ]; then

echo "PaTcH_MsG 1 Patch number $Patch_label is \superceded by the already applied $patchappl."

exit 3elif [ $appl_inst = $active_inst ]; then

# Not newer, it’s the sameif [ "$PATCH_UNCONDITIONAL" = "true" ]; then

if [ -d $PKGSAV/$Patch_label ]; thenecho "PATCH_NO_UNDO=true" >> $1

fielse

echo "$ALRDY_MSG"exit 3;

fifi

fidone

# Construct a list of applied patches in orderecho "PATCHLIST=${PATCHLIST} $Patch_label" >> $1

## Construct the complete list of patches this one obsoletes#ACTIVE_OBSOLETES=$Obsoletes_label

if [ -n "$Obsoletes_label" ]; then# Merge the two listsecho $Obsoletes_label | sed ’y/\ /\n/’ | \nawk -v PatchObsList="$PATCH_OBSOLETES" ’BEGIN {

printf("PATCH_OBSOLETES=");PatchCount=split(PatchObsList, PatchObsComp, " ");

for(PatchIndex in PatchObsComp) {Atisat=match(PatchObsComp[PatchIndex], "@");PatchObs[PatchIndex]=substr(PatchObsComp[PatchIndex], \

0, Atisat-1);PatchObsCnt[PatchIndex]=substr(PatchObsComp\

[PatchIndex], Atisat+1);}

}

(continued)


(Continuation)

{Inserted=0;for(PatchIndex in PatchObs) {

if (PatchObs[PatchIndex] == $0) {if (Inserted == 0) {

PatchObsCnt[PatchIndex]=PatchObsCnt\[PatchIndex]+1;

Inserted=1;} else {

PatchObsCnt[PatchIndex]=0;}

}}if (Inserted == 0) {

printf ("%s@1 ", $0);}next;

}END {

for(PatchIndex in PatchObs) {if ( PatchObsCnt[PatchIndex] != 0) {

printf("%s@%d ", PatchObs[PatchIndex], \PatchObsCnt[PatchIndex]);

}}printf("\n");

} ’ >> $1# Clear the parameter since it has already been used.echo "Obsoletes_label=" >> $1

# Pass it’s value on to the preinstall under another nameecho "ACTIVE_OBSOLETES=$ACTIVE_OBSOLETES" >> $1

fi

## Construct PATCH_INFO line for this package.#

tmpRequire=‘nawk -F= ’ $1 ~ /REQUIR/ { print $2 } ’ $INFO_DIR/pkginfo ‘tmpIncompat=‘nawk -F= ’ $1 ~ /INCOMPAT/ { print $2 } ’ $INFO_DIR/pkginfo ‘

if [ -n "$tmpRequire" ] && [ -n "$tmpIncompat" ]then

echo "PATCH_INFO_$Patch_label=Installed: ‘date‘ From: ‘uname -n‘ \Obsoletes: $ACTIVE_OBSOLETES Requires: $tmpRequire \Incompatibles: $tmpIncompat" >> $1

elif [ -n "$tmpRequire" ]then

echo "PATCH_INFO_$Patch_label=Installed: ‘date‘ From: ‘uname -n‘ \Obsoletes: $ACTIVE_OBSOLETES Requires: $tmpRequire \

Incompatibles: " >> $1elif [ -n "$tmpIncompat" ]then

echo "PATCH_INFO_$Patch_label=Installed: ‘date‘ From: ‘uname -n‘ \

(continued)


(Continuation)

Obsoletes: $ACTIVE_OBSOLETES Requires: Incompatibles: \$tmpIncompat" >> $1else

echo "PATCH_INFO_$Patch_label=Installed: ‘date‘ From: ‘uname -n‘ \Obsoletes: $ACTIVE_OBSOLETES Requires: Incompatibles: " >> $1

fi

## Since this script is called from the delivery medium and we may be using# dot extensions to distinguish the different patch packages, this is the# only place we can, with certainty, trace that source for our backout# scripts. (Usually $INST_DATADIR would get us there).#echo "SCRIPTS_DIR=‘dirname $0‘" >> $1

# If additional operations are required for this package, place# those package-specific commands here.

#XXXSpecial_CommandsXXX#

exit 0

The preinstall ScriptThe preinstall script initializes the prototype file, information files, andinstallation scripts for the backout package to be constructed. This script is verysimple and the remaining scripts in this example only allow a backout package todescribe regular files.

If you wanted to restore symbolic links, hard links, devices, and named pipes in abackout package, you could modify the preinstall script to use the pkgprotocommand to compare the delivered pkgmap file with the installed files, and thencreate a prototype file entry for each non-file to be changed in the backout package.The method you should use is similar to the method in the class action script.

The scripts patch_checkinstall and patch_postinstall are inserted into thepackage source tree from the preinstall script. These two scripts undo what thepatch does.

# This script initializes the backout data for a patch package# directory format options.## @(#)preinstall 1.5 96/05/10 SMI## Copyright (c) 1995 by Sun Microsystems, Inc.

(continued)


(Continuation)

# All rights reserved#

PATH=/usr/sadm/bin:$PATHrecovery="no"

if [ "$PKG_INSTALL_ROOT" = "/" ]; thenPKG_INSTALL_ROOT=""

fi

# Check to see if this is a patch installation retry.if [ "$INTERRUPTION" = "yes" ]; then

if [ -d "$PKG_INSTALL_ROOT/var/tmp/$Patch_label.$PKGINST" ] || [ -d \"$PATCH_BUILD_DIR/$Patch_label.$PKGINST" ]; then

recovery="yes"fi

fi

if [ -n "$PATCH_BUILD_DIR" -a -d "$PATCH_BUILD_DIR" ]; thenBUILD_DIR="$PATCH_BUILD_DIR/$Patch_label.$PKGINST"

elseBUILD_DIR="$PKG_INSTALL_ROOT/var/tmp/$Patch_label.$PKGINST"

fi

FILE_DIR=$BUILD_DIR/filesRELOC_DIR=$BUILD_DIR/files/relocROOT_DIR=$BUILD_DIR/files/rootPROTO_FILE=$BUILD_DIR/prototypePKGINFO_FILE=$BUILD_DIR/pkginfoTHIS_DIR=‘dirname $0‘

if [ "$PATCH_PROGRESSIVE" = "true" ]; then# If this is being used in an old-style patch, insert# the old-style script commands here.

#XXXOld_CommandsXXX#

exit 0fi

## Unless specifically denied, initialize the backout patch data by# creating the build directory and copying over the original pkginfo# which pkgadd saved in case it had to be restored.#if [ "$PATCH_NO_UNDO" != "true" ] && [ "$recovery" = "no" ]; then

if [ -d $BUILD_DIR ]; thenrm -r $BUILD_DIR

fi

# If this is a retry of the same patch then recovery is set to# yes. Which means there is a build directory already in# place with the correct backout data.

(continued)


(Continuation)

if [ "$recovery" = "no" ]; thenmkdir $BUILD_DIRmkdir -p $RELOC_DIRmkdir $ROOT_DIR

fi

## Here we initialize the backout pkginfo file by first# copying over the old pkginfo file and themn adding the# ACTIVE_PATCH parameter so the backout will know what patch# it’s backing out.## NOTE : Within the installation, pkgparam returns the# original data.#pkgparam -v $PKGINST | nawk ’

$1 ~ /PATCHLIST/ { next; }$1 ~ /PATCH_OBSOLETES/ { next; }$1 ~ /ACTIVE_OBSOLETES/ { next; }$1 ~ /Obsoletes_label/ { next; }$1 ~ /ACTIVE_PATCH/ { next; }$1 ~ /Patch_label/ { next; }$1 ~ /UPDATE/ { next; }$1 ~ /SCRIPTS_DIR/ { next; }$1 ~ /PATCH_NO_UNDO/ { next; }$1 ~ /INSTDATE/ { next; }$1 ~ /PKGINST/ { next; }$1 ~ /OAMBASE/ { next; }$1 ~ /PATH/ { next; }{ print; } ’ > $PKGINFO_FILE

echo "ACTIVE_PATCH=$Patch_label" >> $PKGINFO_FILEecho "ACTIVE_OBSOLETES=$ACTIVE_OBSOLETES" >> $PKGINFO_FILE

# And now initialize the backout prototype file with the# pkginfo file just formulated.echo "i pkginfo" > $PROTO_FILE

# Copy over the backout scripts including the undo class# action scriptsfor script in $SCRIPTS_DIR/*; do

srcscript=‘basename $script‘targscript=‘echo $srcscript | nawk ’

{ script=$0; }/u\./ {

sub("u.", "i.", script);print script;next;

}/patch_/ {

sub("patch_", "", script);print script;next;

}{ print "dont_use" } ’‘

(continued)


(Continuation)

if [ "$targscript" = "dont_use" ]; thencontinue

fi

echo "i $targscript=$FILE_DIR/$targscript" >> $PROTO_FILEcp $SCRIPTS_DIR/$srcscript $FILE_DIR/$targscript

done#

# Now add entries to the prototype file that won’t be passed to# class action scripts. If the entry is brand new, add it to the# deletes file for the backout package.#Our_Pkgmap=‘dirname $SCRIPTS_DIR‘/pkgmapBO_Deletes=$FILE_DIR/deletes

nawk -v basedir=${BASEDIR:-/} ’BEGIN { count=0; }{

token = $2;ftype = $1;

}$1 ~ /[#\!:]/ { next; }$1 ~ /[0123456789]/ {

if ( NF >= 3) {token = $3;ftype = $2;

} else {next;

}}{ if (ftype == "i" || ftype == "e" || ftype == "f" || ftype == \

"v" || ftype == "d") { next; } }{

equals=match($4, "=")-1;if ( equals == -1 ) { print $3, $4; }else { print $3, substr($4, 0, equals); }

}’ < $Our_Pkgmap | while read class path; do

## NOTE: If pkgproto is passed a file that is# actually a hard link to another file, it# will return ftype "f" because the first link# in the list (consisting of only one file) is# viewed by pkgproto as the source and always# gets ftype "f".## If this isn’t replacing something, then it# just goes to the deletes list.#if valpath -l $path; then

Chk_Path="$BASEDIR/$path"Build_Path="$RELOC_DIR/$path"Proto_From="$BASEDIR"

else # It’s an absolute path

(continued)


(Continuation)

Chk_Path="$PKG_INSTALL_ROOT$path"Build_Path="$ROOT_DIR$path"Proto_From="$PKG_INSTALL_ROOT"

fi#

# Hard links have to be restored as regular files.# Unlike the others in this group, an actual# object will be required for the pkgmk.#if [ -f "$Chk_Path" ]; then

mkdir -p ‘dirname $Build_Path‘cp $Chk_Path $Build_Pathcd $Proto_Frompkgproto -c $class "$Build_Path=$path" 1>> \

$PROTO_FILE 2> /dev/nullcd $THIS_DIR

elif [ -h "$Chk_Path" -o \-c "$Chk_Path" -o \-b "$Chk_Path" -o \-p "$Chk_Path" ]; then

pkgproto -c $class "$Chk_Path=$path" 1>> \$PROTO_FILE 2> /dev/null

elseecho $path >> $BO_Deletes

fidone

fi



exit 0

The Class Action ScriptThe class action script creates a copy of each file that replaces an existing file andadds a corresponding line to the prototype file for the backout package. This is alldone with fairly simple nawk scripts. The class action script receives a list of source/destination pairs consisting of ordinary files that do not match the correspondinginstalled files. Symbolic links and other non-files must be dealt with in thepreinstall script.


# This class action script copies the files being replaced# into a package being constructed in $BUILD_DIR. This class

# action script is only appropriate for regular files that# are installed by simply copying them into place.#

# For special package objects such as edittable files, the patch# producer must supply appropriate class action scripts.## directory format options.## @(#)i.script 1.6 96/05/10 SMI## Copyright (c) 1995 by Sun Microsystems, Inc.# All rights reserved#


ECHO="/usr/bin/echo"SED="/usr/bin/sed"PKGPROTO="/usr/bin/pkgproto"EXPR="/usr/bin/expr" # used by dirnameMKDIR="/usr/bin/mkdir"CP="/usr/bin/cp"RM="/usr/bin/rm"MV="/usr/bin/mv"

recovery="no"Pn=$$procIdCtr=0

CMDS_USED="$ECHO $SED $PKGPROTO $EXPR $MKDIR $CP $RM $MV"LIBS_USED=""


fi

# Check to see if this is a patch installation retry.if [ "$INTERRUPTION" = "yes" ]; then

if [ -d "$PKG_INSTALL_ROOT/var/tmp/$Patch_label.$PKGINST" ] ||\[ -d "$PATCH_BUILD_DIR/$Patch_label.$PKGINST" ]; then

recovery="yes"fi

fi



fi

FILE_DIR=$BUILD_DIR/filesRELOC_DIR=$FILE_DIR/relocROOT_DIR=$FILE_DIR/rootBO_Deletes=$FILE_DIR/deletes

(continued)


(Continuation)

PROGNAME=‘basename $0‘

if [ "$PATCH_PROGRESSIVE" = "true" ]; thenPATCH_NO_UNDO="true"

fi

# Since this is generic, figure out the class.Class=‘echo $PROGNAME | nawk ’ { print substr($0, 3) }’‘

# Since this is an update, $BASEDIR is guaranteed to be correctBD=${BASEDIR:-/}

cd $BD

## First, figure out the dynamic libraries that can trip us up.#if [ -z "$PKG_INSTALL_ROOT" ]; then

if [ -x /usr/bin/ldd ]; thenLIB_LIST=‘/usr/bin/ldd $CMDS_USED | sort -u | nawk ’

$1 ~ /\// { continue; }{ printf "%s ", $3 } ’‘

elseLIB_LIST="/usr/lib/libc.so.1 /usr/lib/libdl.so.1

\/usr/lib/libw.so.1 /usr/lib/libintl.so.1 /usr/lib/libadm.so.1 \/usr/lib/libelf.so.1"

fifi

## Now read the list of files in this class to be replaced. If the file# is already in place, then this is a change and we need to copy it# over to the build directory if undo is allowed. If it’s a new entry# (No $dst), then it goes in the deletes file for the backout package.#procIdCtr=0while read src dst; do

if [ -z "$PKG_INSTALL_ROOT" ]; thenChk_Path=$dstfor library in $LIB_LIST; do

if [ $Chk_Path = $library ]; then$CP $dst $dst.$PnLIBS_USED="$LIBS_USED $dst.$Pn"LD_PRELOAD="$LIBS_USED"export LD_PRELOAD

fidone

fi

if [ "$PATCH_PROGRESSIVE" = "true" ]; then# If this is being used in an old-style patch, insert# the old-style script commands here.

(continued)


(Continuation)

#XXXOld_CommandsXXX#echo >/dev/null # dummy

fi

if [ "${PATCH_NO_UNDO}" != "true" ]; then## Here we construct the path to the appropriate source# tree for the build. First we try to strip BASEDIR. If# there’s no BASEDIR in the path, we presume that it is# absolute and construct the target as an absolute path# by stripping PKG_INSTALL_ROOT. FS_Path is the path to# the file on the file system (for deletion purposes).# Build_Path is the path to the object in the build# environment.#if [ "$BD" = "/" ]; then

FS_Path=‘$ECHO $dst | $SED s@"$BD"@@‘else

FS_Path=‘$ECHO $dst | $SED s@"$BD/"@@‘fi

# If it’s an absolute path the attempt to strip the# BASEDIR will have failed.if [ $dst = $FS_Path ]; then

if [ -z "$PKG_INSTALL_ROOT" ]; thenFS_Path=$dstBuild_Path="$ROOT_DIR$dst"

elseBuild_Path="$ROOT_DIR‘echo $dst | \

sed s@"$PKG_INSTALL_ROOT"@@‘"FS_Path=‘echo $dst | \

sed s@"$PKG_INSTALL_ROOT"@@‘fi

elseBuild_Path="$RELOC_DIR/$FS_Path"

fi

if [ -f $dst ]; then # If this is replacing somethingcd $FILE_DIR## Construct the prototype file entry. We replace# the pointer to the filesystem object with the# build directory object.#$PKGPROTO -c $Class $dst=$FS_Path | \

$SED -e s@=$dst@=$Build_Path@ >> \$BUILD_DIR/prototype

# Now copy over the fileif [ "$recovery" = "no" ]; then

DirName=‘dirname $Build_Path‘$MKDIR -p $DirName$CP -p $dst $Build_Path

else

(continued)


(Continuation)

# If this file is already in the build area skip itif [ -f "$Build_Path" ]; then

cd $BDcontinue

elseDirName=‘dirname $Build_Path‘if [ ! -d "$DirName" ]; then

$MKDIR -p $DirNamefi$CP -p $dst $Build_Path

fifi

cd $BDelse # It’s brand new

$ECHO $FS_Path >> $BO_Deletesfi

fi

# If special processing is required for each src/dst pair,# add that here.##XXXSpecial_CommandsXXX##

$CP $src $dst.$$$procIdCtrif [ $? -ne 0 ]; then

$RM $dst.$$$procIdCtr 1>/dev/null 2>&1else

$MV -f $dst.$$$procIdCtr $dstfor library in $LIB_LIST; do

if [ "$library" = "$dst" ]; thenLD_PRELOAD="$dst"export LD_PRELOAD

fidone

fiprocIdCtr=‘expr $procIdCtr + 1‘

done



## Release the dynamic libraries#for library in $LIBS_USED; do

$RM -f $librarydone

(continued)


(Continuation)

exit 0

The postinstall ScriptThe postinstall script creates the backout package using the informationprovided by the other scripts. Since the pkgmk and pkgtrans commands do notrequire the package database, they can be executed within a package installation.

In the example, undoing the patch is permitted by constructing a stream formatpackage in the save directory (using the PKGSAVenvironment variable). It is notobvious, but this package must be in stream format, because the save directory getsmoved around during a pkgadd operation. If the pkgadd command is applied to apackage in its own save directory, assumptions about where the package source is atany given time become very unreliable. A stream format package is unpacked into atemporary directory and installed from there. (A directory format package wouldbegin installing from the save directory and find itself suddenly relocated during apkgadd fail-safe operation.)

To determine which patches are applied to a package, use this command:

pkgparam SUNWstuf PATCHLIST

With the exception of PATCHLIST, which is a Sun public interface, there is nothingsignificant in the parameter names in this example. Instead of PATCHyou could usethe traditional SUNW_PATCHIDand the various other lists such as PATCH_EXCLandPATCH_REQDcould be renamed accordingly.

If certain patch packages depend upon other patch packages which are availablefrom the same medium, the checkinstall script could determine this and create ascript to be executed by the postinstall script in the same way that the upgradeexample (see “Upgrading Packages” on page 171) does.

# This script creates the backout package for a patch package## directory format options.## @(#) postinstall 1.6 96/01/29 SMI## Copyright (c) 1995 by Sun Microsystems, Inc.# All rights reserved#

# Description:

(continued)


(Continuation)

# Set the TYPE parameter for the remote file## Parameters:# none## Globals set:# TYPE

set_TYPE_parameter () {if [ ${PATCH_UNDO_ARCHIVE:?????} = "/dev" ]; then

# handle device specific stuffTYPE="removable"

elseTYPE="filesystem"

fi}

## Description:# Build the remote file that points to the backout data## Parameters:# $1: the un/compressed undo archive## Globals set:# UNDO, STATE

build_remote_file () {remote_path=$PKGSAV/$Patch_label/remoteset_TYPE_parameterSTATE="active"

if [ $1 = "undo" ]; thenUNDO="undo"

elseUNDO="undo.Z"

fi

cat > $remote_path << EOF# Backout data stored remotelyTYPE=$TYPEFIND_AT=$ARCHIVE_DIR/$UNDOSTATE=$STATEEOF}



fi


(continued)


(Continuation)


fi

if [ ! -n "$PATCH_UNDO_ARCHIVE" ]; thenPATCH_UNDO_ARCHIVE="none"

fi

FILE_DIR=$BUILD_DIR/filesRELOC_DIR=$FILE_DIR/relocROOT_DIR=$FILE_DIR/rootBO_Deletes=$FILE_DIR/deletesTHIS_DIR=‘dirname $0‘PROTO_FILE=$BUILD_DIR/prototypeTEMP_REMOTE=$PKGSAV/$Patch_label/temp

if [ "$PATCH_PROGRESSIVE" = "true" ]; then# remove the scripts that are left behindinstall_scripts=‘dirname $0‘rm $install_scripts/checkinstall \

$install_scripts/patch_checkinstall $install_scripts/patch_postinstall

# If this is being used in an old-style patch, insert# the old-style script commands here.

#XXXOld_CommandsXXX#

exit 0fi## At this point we either have a deletes file or we don’t. If we do,# we create a prototype entry.#if [ -f $BO_Deletes ]; then

echo "i deletes=$BO_Deletes" >> $BUILD_DIR/prototypefi

## Now delete everything in the deletes list after transferring# the file to the backout package and the entry to the prototype# file. Remember that the pkgmap will get the CLIENT_BASEDIR path# but we have to actually get at it using the BASEDIR path. Also# remember that removef will import our PKG_INSTALL_ROOT#Our_Deletes=$THIS_DIR/deletesif [ -f $Our_Deletes ]; then

cd $BASEDIR

cat $Our_Deletes | while read path; doReg_File=0

if valpath -l $path; thenClient_Path="$CLIENT_BASEDIR/$path"Build_Path="$RELOC_DIR/$path"

(continued)


(Continuation)

Proto_Path=$BASEDIR/$pathelse # It’s an absolute path

Client_Path=$pathBuild_Path="$ROOT_DIR$path"Proto_Path=$PKG_INSTALL_ROOT$path

fi

# Note: If the file isn’t really there, pkgproto# doesn’t write anything.LINE=‘pkgproto $Proto_Path=$path‘ftype=‘echo $LINE | nawk ’{ print $1 }’‘if [ $ftype = "f" ]; then

Reg_File=1fi

if [ $Reg_File = 1 ]; then# Add source file to the prototype entryif [ "$Proto_Path" = "$path" ]; then

LINE=‘echo $LINE | sed -e s@$Proto_Path@$Build_Path@2‘else

LINE=‘echo $LINE | sed -e s@$Proto_Path@$Build_Path@‘fi

DirName=‘dirname $Build_Path‘# make room in the build treemkdir -p $DirNamecp -p $Proto_Path $Build_Path

fi

# Insert it into the prototype fileecho $LINE 1>>$PROTO_FILE 2>/dev/null

# Remove the file only if it’s OK’d by removefrm ‘removef $PKGINST $Client_Path‘ 1>/dev/null 2>&1

doneremovef -f $PKGINST

rm $Our_Deletesfi

## Unless specifically denied, make the backout package.#if [ "$PATCH_NO_UNDO" != "true" ]; then

cd $BUILD_DIR # We have to build from here.

if [ "$PATCH_UNDO_ARCHIVE" != "none" ]; thenSTAGE_DIR="$PATCH_UNDO_ARCHIVE"ARCHIVE_DIR="$PATCH_UNDO_ARCHIVE/$Patch_label/$PKGINST"mkdir -p $ARCHIVE_DIRmkdir -p $PKGSAV/$Patch_label

elseif [ -d $PKGSAV/$Patch_label ]; then

rm -r $PKGSAV/$Patch_label

(continued)


(Continuation)

fiSTAGE_DIR=$PKGSAVARCHIVE_DIR=$PKGSAV/$Patch_labelmkdir $ARCHIVE_DIR

fi

pkgmk -o -d $STAGE_DIR 1>/dev/null 2>&1pkgtrans -s $STAGE_DIR $ARCHIVE_DIR/undo $PKG 1>/dev/null 2>&1compress $ARCHIVE_DIR/undoretcode=$?if [ "$PATCH_UNDO_ARCHIVE" != "none" ]; then

if [ $retcode != 0 ]; thenbuild_remote_file "undo"

elsebuild_remote_file "undo.Z"

fifirm -r $STAGE_DIR/$PKG

cd ..rm -r $BUILD_DIR# remove the scripts that are left behindinstall_scripts=‘dirname $0‘rm $install_scripts/checkinstall $install_scripts/patch_\

checkinstall $install_scripts/patch_postinstallfi

## Since this apparently worked, we’ll mark as obsoleted the prior# versions of this patch - installpatch deals with explicit obsoletions.#cd ${PKG_INSTALL_ROOT:-/}cd var/sadm/pkg

active_base=‘echo $Patch_label | nawk ’{ print substr($0, 1, match($0, "Patchvers_pfx")-1) } ’‘

List=‘ls -d $PKGINST/save/${active_base}*‘if [ $? -ne 0 ]; then

List=""fi

for savedir in $List; dopatch=‘basename $savedir‘if [ $patch = $Patch_label ]; then

breakfi

# If we get here then the previous patch gets deletedif [ -f $savedir/undo ]; then

mv $savedir/undo $savedir/obsoleteecho $Patch_label >> $savedir/obsoleted_by

elif [ -f $savedir/undo.Z ]; thenmv $savedir/undo.Z $savedir/obsolete.Z

(continued)


(Continuation)

echo $Patch_label >> $savedir/obsoleted_byelif [ -f $savedir/remote ]; then

‘grep . $PKGSAV/$patch/remote | sed ’s/STATE=.*/STATE=obsolete/’ > $TEMP_REMOTE‘

rm -f $PKGSAV/$patch/remotemv $TEMP_REMOTE $PKGSAV/$patch/remoterm -f $TEMP_REMOTEecho $Patch_label >> $savedir/obsoleted_by

elif [ -f $savedir/obsolete -o -f $savedir/obsolete.Z ]; thenecho $Patch_label >> $savedir/obsoleted_by

fidone



exit 0

The patch_checkinstallScript

# checkinstall script to validate backing out a patch.# directory format option.## @(#)patch_checkinstall 1.2 95/10/10 SMI## Copyright (c) 1995 by Sun Microsystems, Inc.# All rights reserved#


LATER_MSG="PaTcH_MsG 6 ERROR: A later version of this patch is applied."NOPATCH_MSG="PaTcH_MsG 2 ERROR: Patch number $ACTIVE_PATCH is not installed"NEW_LIST=""

# Get OLDLIST. $1

## Confirm that the patch that got us here is the latest one installed on# the system and remove it from PATCHLIST.#

(continued)


(Continuation)

Is_Inst=0Skip=0active_base=‘echo $ACTIVE_PATCH | nawk ’

{ print substr($0, 1, match($0, "Patchvers_pfx")-1) } ’‘active_inst=‘echo $ACTIVE_PATCH | nawk ’

{ print substr($0, match($0, "Patchvers_pfx")+1) } ’‘for patchappl in ${OLDLIST}; do

appl_base=‘echo $patchappl | nawk ’{ print substr($0, 1, match($0, "Patchvers_pfx")-1) } ’‘

if [ $appl_base = $active_base ]; thenappl_inst=‘echo $patchappl | nawk ’

{ print substr($0, match($0, "Patchvers_pfx")+1) } ’‘result=‘expr $appl_inst \> $active_inst‘if [ $result -eq 1 ]; then

puttext "$LATER_MSG"exit 3

elif [ $appl_inst = $active_inst ]; thenIs_Inst=1Skip=1

fifiif [ $Skip = 1 ]; then

Skip=0else

NEW_LIST="${NEW_LIST} $patchappl"fi

done

if [ $Is_Inst = 0 ]; thenputtext "$NOPATCH_MSG"exit 3

fi

## OK, all’s well. Now condition the key variables.#echo "PATCHLIST=${NEW_LIST}" >> $1echo "Patch_label=" >> $1echo "PATCH_INFO_$ACTIVE_PATCH=backed out" >> $1

# Get the current PATCH_OBSOLETES and condition itOld_Obsoletes=$PATCH_OBSOLETES

echo $ACTIVE_OBSOLETES | sed ’y/\ /\n/’ | \nawk -v PatchObsList="$Old_Obsoletes" ’

BEGIN {printf("PATCH_OBSOLETES=");PatchCount=split(PatchObsList, PatchObsComp, " ");

for(PatchIndex in PatchObsComp) {Atisat=match(PatchObsComp[PatchIndex], "@");PatchObs[PatchIndex]=substr(PatchObsComp[PatchIndex], \

0, Atisat-1);PatchObsCnt[PatchIndex]=substr(PatchObsComp\

(continued)


(Continuation)

[PatchIndex], Atisat+1);}

}{

for(PatchIndex in PatchObs) {if (PatchObs[PatchIndex] == $0) {

PatchObsCnt[PatchIndex]=PatchObsCnt[PatchIndex]-1;}

}next;

}END {

for(PatchIndex in PatchObs) {if ( PatchObsCnt[PatchIndex] > 0 ) {

printf("%s@%d ", PatchObs[PatchIndex], PatchObsCnt\[PatchIndex]);

}}printf("\n");

} ’ >> $1

# remove the used parametersecho "ACTIVE_OBSOLETES=" >> $1echo "Obsoletes_label=" >> $1

exit 0

The patch_postinstallScript

# This script deletes the used backout data for a patch package# and removes the deletes file entries.## directory format options.## @(#)patch_postinstall 1.2 96/01/29 SMI## Copyright (c) 1995 by Sun Microsystems, Inc.# All rights reserved#PATH=/usr/sadm/bin:$PATHTHIS_DIR=‘dirname $0‘

Our_Deletes=$THIS_DIR/deletes

#

(continued)


(Continuation)

# Delete the used backout data#if [ -f $Our_Deletes ]; then

cat $Our_Deletes | while read path; doif valpath -l $path; then

Client_Path=‘echo "$CLIENT_BASEDIR/$path" | sed s@//@/@‘else # It’s an absolute path

Client_Path=$pathfirm ‘removef $PKGINST $Client_Path‘

doneremovef -f $PKGINST

rm $Our_Deletesfi

## Remove the deletes file, checkinstall and the postinstall#rm -r $PKGSAV/$ACTIVE_PATCHrm -f $THIS_DIR/checkinstall $THIS_DIR/postinstall

exit 0

Upgrading PackagesThe process of upgrading a package is very different from that of overwriting apackage. While there are special tools to support the upgrade of standard packagesdelivered as part of the Solaris operating environment, an unbundled package can bedesigned to support its own upgrade—several previous examples describedpackages that look ahead and control the precise method of installation under thedirection of the administrator. You can design the request script to support directupgrade of a package as well. If the administrator chooses to have one packageinstall so as to completely replace another, leaving no residual obsolete files, thepackage scripts can do this.

The request script and postinstall script in this example provide a simpleupgradable package. The request script communicates with the administrator andthen sets up a simple file in the /tmp directory to remove the old package instance.(Although the request script creates a file (which is forbidden), it is okay becauseeveryone has access to /tmp ).


The postinstall script then executes the shell script in /tmp , which executes thenecessary pkgrm command against the old package and then deletes itself.

This example illustrates a basic upgrade. It is less than fifty lines of code includingsome fairly long messages. It could be expanded to backout the upgrade or makeother major transformations to the package as required by the designer.

The design of the user interface for an upgrade option must be absolutely sure thatthe administrator is fully aware of the process and has actively requested upgraderather than parallel installation. There is nothing wrong with performing a wellunderstood complex operation like upgrade as long as the user interface makes theoperation clear.

The requestScript

# request scriptcontrol an upgrade installation

PATH=/usr/sadm/bin:$PATHUPGR_SCRIPT=/tmp/upgr.$PKGINST

UPGRADE_MSG="Do you want to upgrade the installed version ?"

UPGRADE_HLP="If upgrade is desired, the existing version of the \package will be replaced by this version. If it is not \desired, this new version will be installed into a different \base directory and both versions will be useable."

UPGRADE_NOTICE="Conflict approval questions may be displayed. The \listed files are the ones that will be upgraded. Please \answer \"y\" to these questions if they are presented."

pkginfo -v 1.0 -q SUNWstuf.\*

if [ $? -eq 0 ]; then# See if upgrade is desired hereresponse=‘ckyorn -p "$UPGRADE_MSG" -h "$UPGRADE_HLP"‘if [ $response = "y" ]; then

OldPkg=‘pkginfo -v 1.0 -x SUNWstuf.\* | nawk ’ \/SUNW/{print $1} ’‘# Initiate upgradeecho "PATH=/usr/sadm/bin:$PATH" > $UPGR_SCRIPTecho "sleep 3" >> $UPGR_SCRIPTecho "echo Now removing old instance of $PKG" >> \$UPGR_SCRIPTif [ ${PKG_INSTALL_ROOT} ]; then

echo "pkgrm -n -R $PKG_INSTALL_ROOT $OldPkg" >> \$UPGR_SCRIPT

else

(continued)


(Continuation)

echo "pkgrm -n $OldPkg" >> $UPGR_SCRIPTfiecho "rm $UPGR_SCRIPT" >> $UPGR_SCRIPTecho "exit $?" >> $UPGR_SCRIPT

# Get the original package’s base directoryOldBD=‘pkgparam $OldPkg BASEDIR‘echo "BASEDIR=$OldBD" > $1puttext -l 5 "$UPGRADE_NOTICE"

elseif [ -f $UPGR_SCRIPT ]; then

rm -r $UPGR_SCRIPTfi

fifi

exit 0

The postinstallScript

# postinstallto execute a simple upgrade

PATH=/usr/sadm/bin:$PATHUPGR_SCRIPT=/tmp/upgr.$PKGINST

if [ -f $UPGR_SCRIPT ]; thensh $UPGR_SCRIPT &

fi

exit 0


Glossary

application binaryinterface

Definition of the binary system interface between compiledapplications and the operating system on which they run.

ABI See application binary interface (ABI).

base directory The location where relocatable objects will be installed. It is definedin the pkginfo file, using the BASEDIR parameter.

build time The time during which a package is being built with the pkgmkcommand.

build variable A variable that begins with a lowercase letter and is evaluated atbuild time.

class A name that is used to group package objects. See also class actionscript.

class action script A file that defines a set of actions to be performed on a group ofpackage objects.

collectivelyrelocatable object

A package object that is located relative to a common installationbase. See also base directory.

composite package A package that contains both relocatable and absolute path names.

compver file A method of specifying package backward-compatibility.

control file File that controls how, where, and if a package is to be installed. Seeinformation file and installation script.

copyright The right to own and sell intellectual property, such as software,source code, or documentation. Ownership must be stated on the

Glossary-175

CD-ROM and insert text, whether the copyright is owned bySunSoft, or by another party. Copyright ownership is alsoacknowledged in SunSoft documentation.

depend file A method of resolving basic package dependencies. See alsocompver file.

incompatiblepackage

A package that is incompatible with the named package. See alsodepend file.

individuallyrelocatable object

A package object that is not restricted to the same directory locationas a collectively relocatable object. It is defined using an installvariable in the path field in the prototype file, and the installationlocation is determined via a request script or a checkinstallscript.

information file A file that can define package dependencies, provide a copyrightmessage, or reserve space on a target system.

installation script A script that enables you to provide customized installationprocedures for a package.

install time The time during which a package is being installed with thepkgadd command.

install variable A variable that begins with an uppercase letter and is evaluated atinstall time.

package A collection of files and directories required for a softwareapplication.

packageabbreviation

A short name for a package that is defined via the PKGparameter inthe pkginfo file.

package identifier A numerical suffix added to a package abbreviation by the pkgaddcommand.

package instance A variation of a package, which is determined by combining thedefinitions of the PKG, ARCH, and VERSIONparameters in thepkginfo file for the package.

package object Another name for an application file that is contained in a packageto be installed on a target system.

parametric pathname

A path name that includes a variable specification.

Glossary-176 Application Packaging Developer’s Guide ♦ August, 1997

patch list A list of patches that affect the current package. This list of patchesis recorded in the installed package in the pkginfo file.

prerequisite package A package that depends on the existence of another package. Seealso depend file.

procedure script A script that defines actions that occur at a particular point duringpackage installation and package removal.

relocatable A package object defined in a prototype file with a relative pathname.

relocatable object A package object that does not need an absolute path location on atarget system. Instead, its location is determined during theinstallation process. See also collectively relocatable object andindividually relocatable object.

reverse dependency A condition when another package depends on the existence ofyour package. See also depend file.

segmented A package that does not fit on a single volume, such as a floppydisk.

tar Tape archive retrieval. Solaris command for adding or extractingfiles from a media.

Glossary-177

Glossary-178 Application Packaging Developer’s Guide ♦ August, 1997

Index

Aabsolute package, 137

traditional example, 138administrative defaults file, 122awk class, 65

script, 66

Bbase directory, 22, 121

in the administrative defaults file, 122using parametric path names, 124using the BASEDIR parameter, 123walking the, 126, 127

example, 129, 133build class, 65

in a case study, 107script, 67

in a case study, 107build time, 13build variable

description, 13building a package, 34

the process, 11bundled packages, 140

CCD-ROM drives

software installation andfrom mounted CD to diskless

client, 76checking package installation, 76

the process, 71

checkinstall script, 5, 44, 50, 51, 123, 126, 127,131, 150

and environment variables, 52design rules, 58how to write a, 58writing a, 57

class action script, 5, 50, 51, 64, 158behaviors, 64design rules, 65how to write a, 68in a case study, 96, 97, 101, 102, 110naming conventions, 64

classes, see object classes,clients

installing packages to, 75collectively relocatable object, 22composite, 139composite package

example, 141, 142, 144rules for constructing, 140traditional example, 139

compver file, 4description, 44example, 46how to write, 44in a case study, 99

control filesSee also information files and installation

scripts,copyright file, 4

example, 48how to write, 47in a case study, 98, 119

Index-179

writing a, 47

Ddepend file, 4

description, 44example, 46how to write, 44in a case study, 99

Eexit codes for scripts, 54

Gguidelines, packaging, 5

Iincompatible package, 44individually relocatable object, 22, 23install time, 13install variable

description, 13installation environment variables, 52installation scripts

and environment variables, 52characteristics, 5creating, 50exit codes, 54obtaining package information, 54processing of, 51requirements for, 50types of, 5, 50

installation software database, 73installf command, 60, 63

in a case study, 96, 114installing classes, 62installing packages on a standalone or server

example, 147installing packages to clients, 75

example, 146

Llinks

defining in a prototype file, 25, 30

Mmounting shared file systems

example, 148

Oobject classes, 22, 62

installing, 51, 62removing, 51, 63system, 50, 65

awk, 65build, 65sed, 65

Ppackage

See also object classesclasses,

absolute, 138base directory, 22checking installation, 76

the process, 71commands, 7components, 2composite, 139control files

information files, 2installation scripts, 2

defining dependencies, 44description, 2design criteria, 5environment variables, 13, 52how to build, 35how to install, 74how to organize, 18information files, 9installation scripts, 9installing to clients, 75object, 3

classes, 62path names, 22, 24relocatable, 22

optional components, 4organization, 18patching, 148relocatable, 136

Index-180 Application Packaging Developer’s Guide ♦ August, 1997

required components, 3status, 73transferring to media, 87upgrading, 171

package abbreviationdescription, 16requirements, 16

package components, 2optional, 4required, 3

package dependencieshow to define, 44

package identifierdescription, 15

package instancedescription, 15

packaging guidelines, 5parametric path name, 90, 124, 132

description, 23example, 125in a case study, 91

patch list, 150patching packages, 148pkgadd command, 62, 72

and class installation, 62and directories, 145and disk space, 48and installation problems, 73and installation scripts, 50and package identifiers, 15and patching packages, 148and request scripts, 55and script processing, 51and the administrative defaults file, 122and the installation software database, 73standalone systems and, 85

pkgask command, 56pkgchk command, 37, 73, 76pkginfo command, 54, 73, 81

and package parameters, 82customizing the output, 81

pkginfo file, 2, 125, 127, 132, 137, 139, 144creating a, 15description, 4, 15determining the base directory, 123example, 18how to create, 17

in a case study, 91, 95, 98, 101, 104, 107,109, 112, 116

required parameters, 15using environment variables in, 13

pkgmap file, 34, 48, 51, 60, 62, 65, 77, 94, 125,128, 132, 137 to 139, 145

pkgmk command, 2, 13, 22, 28, 30 to 32, 82,163

building a package, 34pkgparam command, 54, 79, 163pkgproto command, 38, 154

creating a prototype file, 20in a case study, 117

pkgrm command, 118, 143, 172and class removal, 63and directories, 146and script processing, 51and the installation software database, 73basic procedure, 85rR option (diskless and AutoClient

systems), 86rm command vs., 85

pkgtrans command, 87, 163postinstall script, 51, 60, 163, 171, 173

in a case study, 105, 114, 118installing package objects, 60

postremove script, 52, 60removing package objects, 60

preinstall script, 51, 60, 154preremove script, 51, 60

in a case study, 114, 119prerequisite package, 44procedure scripts, 5, 50

behaviors, 60design rules, 60how to write, 61predefined names of, 5, 50, 60writing, 60

prototype file, 2

Index-181

adding functionality to, 29creating links at install time, 30creating objects at install time, 30distributing packages over multiple

volumes, 30nesting prototype files, 31setting default values, 31setting environment variables, 32specifying a search path, 31

creating, 20creating a

from scratch, 26with the pkgproto command, 26

description, 4, 20fine-tuning a, 27

example, 29format of, 20how to create, 32in a case study, 92, 95, 101, 104, 107, 109,

112, 116using environment variables in, 13valid file types, 21

Rrelocatable object, 22relocatable package, 136

traditional example, 136relocation

supporting in a heterogeneousenvironment, 135

removef command, 61, 85, 149in a case study, 114

removing classes, 63request script, 5, 44, 50, 51, 89, 126 to 129, 149,

171, 172and environment variables, 52and package removal, 52

behaviors, 55, 58design rules, 55example, 57, 59how to write a, 56in a case study, 92, 113writing a, 55

reserving additional space on a targetsystem, 48

reverse dependency, 44

Sscripts, see installation scripts,sed class

script, 66in a case study, 104, 118

software package, see package,space file, 4, 48

example, 49how to create a, 48in a case study, 96

system object classes, 65

Ttransferring a package to a distribution

medium, 87

Uunbundled packages, 75, 140upgrading packages, 171

Vverifying package installation, 76

the process, 71

Index-182 Application Packaging Developer’s Guide ♦ August, 1997