Packaging your software applications

Quick steps to packaging

This section shows you how to create a minimal package image for installation on a UnixWare 7 system.

The procedure takes some short cuts and omits optional package components in a tradeoff between ease of prototyping and functionality. It also provides pointers to further information where such short cuts and omissions are made.

The outcome of the procedure is a package image that can be added to a UnixWare 7 system using the pkgadd(1M) or pkginstall(1M) commands, or the scoadmin(1M) application installer.

Create a package staging area on a development machine.
This is where you will collect all the files you want to install on the target system, the package control scripts required by pkgadd(1M), and the information files used as input to the pkgmk(1) command. It can be located anywhere you have permission to create a directory, including your home directory.
Let's assume for this procedure that we have the following files that we want to package for installation on a target system under the /usr/local directory:
- two user-level binaries, cmd1 and cmd2
- manual pages for each of the binaries
For this procedure, assume we'll use the directory /home/user1/pkgarea as our packaging area, and that it looks like this:
```
   /home/user1/pkgarea/
   			pkginfo
   			prototype
   			other information files
   			control scripts
   			/src
   				files to be packaged
```
This is only one possible, and very simple, arrangement. Files can, in fact, be gathered from anywhere on your development system, but in many cases using a packaging area such as the one suggested above simplifies the process of creating a package image and maintaining a backup of what was packaged for future reference.
Copy your source files to /home/user1/pkgarea/src, re-creating the target directory structure; make sure the permissions, owners, and groups are as you want them to be on the target system.
For the purpose of this procedure, we'll assume this structure under /home/user1/pkgarea/src:
```
   /home/user1/pkgarea/src
   			/bin
   				cmd1
   				cmd2
   			/man
   				/man1
   					cmd1.1
   					cmd2.1
```
This directory structure mimics the directory structure that we want under the target install directory (/usr/local).
This step is not required, and might be impractical for a large number of files or even a small set of very large files. However, if all your files will be installed under a common target directory, copying them to the staging area can simplify the creation of the prototype file later in the procedure.
It is possible to gather source files during the build process from multiple locations on the system. To do this, you need to provide a custom prototype file and use appropriate arguments to the pkgproto and pkgmk commands, as we will discuss later in this procedure.
Create package control scripts and information files in (or copy them to) the packaging area.
The files required to create a package are the prototype(4) and pkginfo(4) information files.
We'll create the prototype file in the next step.
The pkginfo file tells the system about your package, and must contain values for the five required installation parameters, as in this example:
```
   PKG=testpkg
   NAME='Test Package'
   ARCH='i386'
   VERSION='Release 1.1'
   CATEGORY='application'
```
The most important of these is PKG, which must be a unique identifier for your package (the PKG variable's value is displayed by the pkginfo(1) command as the package name). It is recommended that you define a PKG value between 3 and 9 characters, using alphanumeric characters (a-z, A-Z, 0-9) and the special characters dot (.), hyphen (-), and underscore (_) only. See pkginfo(4) for a description of these and other parameters that you can define in the pkginfo file; application-specific parameters may also be included.
No other files are required by pkgmk(1), but the particular needs of your installation may require them. [See ``Script processing'' for the sequence of script processing during software installation and removal.]
For example, if your application requires an interactive install, you'll probably need a request script to interact with the user, and a preinstall script to do any work necessary before the installation of the application's files. If any configuration needs to be done once your source files have been copied to the target system, then you'll need to provide a postinstall script that performs the configuration.
The best way to determine which files you need is to:
- Read the descriptions of the various information files later in this chapter under ``The installation scripts''.
- Look in the /var/sadm/pkg directory, which contains one directory for each installed package on your system. The directory names correspond to the PKG variable of the package, as reported by pkginfo(1). Each of these directories contains copies of the package information files and the control scripts used during package installation (the control scripts are located in a subdirectory named install). Use the pkginfo command to locate a similar application on your system, and use that package's files as examples.
In packaging area, execute the pkgproto(1) command to create an initial prototype file.
If we assume:
- we've populated the src directory in our packaging area with all the directories and files we need into install on the target
- all the files will be installed under /usr/local
We can use a rather simple pkgproto command:
```
   pkgproto src=/usr/local > prototype
```
If you need to package files from outside the packaging area (rather than having copied them into the src directory, or if you want to install files to various places on the target machine, you'll need a more complex pkgproto command.
For example, let's assume there's a very large binary that we want to put in the package and it's located on the development system at /build/build39/cmd2bld/cmd2. To include this file in the prototype file without copying it to the packaging area, we could use a pkgproto command like this:
```
   pkgproto /build/build39/cmd2bld=/usr/local/bin src=/var/opt > prototype
```
Note that you can create the prototype file with any editor, you do not have to use pkgproto. See prototype(4).
Edit the prototype file and add a line for each of the package information and control scripts that your package needs.
For example, if our installation required postinstall and postremove scripts, and we placed these files at the top of our packaging area (where we'll execute the pkgmk command), then the following entries in the prototype file would be required to include them in the package:
```
   i pkginfo=pkginfo
   i postinstall=postinstall
   i postremove=postremove
```
For testpkg, we're using only the required pkginfo file.
Check the permissions on each line of the prototype file and change them, if necessary, to reflect the permissions, owner, and group that you want on the files once they are installed on the target system.
At this point, you may also want to add installation classes (to selectively install groups of files based on system conditions or user input from a request script) or make certain files relocatable on installation. These subjects are covered in detail in this chapter, in these sections:

``3. Placing objects into classes''

``The class action script''

``The special system classes''

``1. Selective installation''

``4. Making package objects relocatable''
At the top level of the packaging area, execute pkgmk:
```
   cd /home/user1/pkgarea
   pkgmk [-o] -d path testpkg
```
This places a file system format package image in the directory named by path. Use the -o option to overwrite a previously created package image, if necessary.
Convert the package to datastream format, if desired.
If you plan to make the package image available for download or transfer to another system, you may want to use the pkgtrans command to convert the file system image you just created to a datastream image. A datastream image is an identical, single-file, ASCII-format version of the file system image, and so is typically easier to transfer than a file system image (which might contain many files and directories).
The example command below places a datastream image of the package in /var/spool/pkg/testpkg.ds:
```
   pkgtrans -s path /var/spool/pkg/testpkg.ds
```
If you wanted to perform the reverse operation, creating a file system image from a datastream image, use a command like this example:
```
   pkgtrans /var/spool/pkg/testpkg.ds existing_dir testpkg
```
The above command places a file system format image of the package under existing_dir/testpkg.
Install the package on a target system for installation testing.
To install the ``file system image'' we created above, enter:
```
   pkgadd -d path testpkg
```
To install the ``datastream image'' we created above, enter:
```
   pkgadd -d /var/spool/pkg/testpkg.ds testpkg
```
[Note that when using datastreams, the name of the file containing the datastream image (testpkg.ds) is considered part of the device name. This is necessary because a datastream image can contain any number of packages or sets. A file system format image can contain only one package or set.]
Verify that the package was successfully installed. Use the pkginfo command on the target system:
```
   pkginfo -l testpkg
```
Which should return the contents of the package's pkginfo file, as well as the date and time the package was installed on the target, and other information.
Check the list of files and their attributes as actually installed on the target system.
To list the pathnames of all files installed by a package, one per line, use the pkgchk(1M) command:
```
   pkgchk -v testpkg
```
To get a detailed listing of installed files and directories, including their contents and attributes, use:
```
   pkgchk -l testpkg | pg
```
The output can reveal problems with the package information files and control scripts, such as incorrectly specified entries in the prototype file.
Remove the package to test package removal. Use the pkgrm(1M) command:
```
   pkgrm testpkg
```
The pkginfo command should now return no information for the package:
```
   # pkginfo testpkg
   UX:pkginfo: ERROR: information for "testpkg" was not found
```

See ``Quick steps to network installation'' for how to set up a network install server to offer your package for installation on remote UnixWare 7 systems.