12.2. Packaging applications using mkinstallp
Beginning with AIX 5L Version 5.2 plus 5200-01 Recommended Maintenance Level, AIX provides a command, /usr/sbin/mkinstallp, to allow users to create their own software packages for AIX. Packages created with mkinstallp are in the AIX standard packaging format and can be installed or removed with SMIT or the installp command.
12.2.1. mkinstallp
A new fileset, bos.adt.insttools, includes the following files:
| /usr/sbin/mkinstallp | Front-end command |
| /usr/sbin/makebff.pl | Back-end command |
| /usr/lpp/bos/README.MKINSTALLP | Documentation |
Note
The makebff.pl Perl script was originally written in the development phase of the IBM Redbook Managing AIX Server Farms, SG24-6606. Therefore, it is possible to package your applications on previous versions of AIX; however, the script provided in the redbook, which is downloadable, might be obsolete and is not supported by IBM.
Files to be packaged by mkinstallp must be in a directory structure so that the location of the file relative to the root build directory is the same as the destination of the file after installation.
For example, if /usr/your_app/bin/commandl is to be installed from a package, commandl must be in the <build_root>/usr/your_app/bin directory when mkinstallp is invoked as shown in Figure 12-5 on page 419.
Figure 12-5. Directory structure for packaging
Once the contents of a package are in the correct directory structure, mkinstallp prompts for basic package data from the command line interface. This data includes the package name, requisites, descriptions of files to be packaged, and so on. The mkinstallp command will then generate a template file based on responses given by the user. Template files can be created or edited directly by the user and passed to the mkinstallp command with the -T flag to prevent command line prompting.
The mkinstallp command has the following command syntax:
mkinstallp [ -d build_root_dir ] [ -T template_file ]
Where:
| -d build_root_dir | Specifies the build root directory containing the files to be packaged. If omitted, the current working directory is used. |
| -T template_file | Specifies the full path name of the template file to be passed to mkinstallp. If omitted, mkinstallp will prompt for package information and create a new template file based on user responses. |
12.2.2. Packaging examples
We demonstrate how to use the mkinstallp command in order to package a sample program whose path name is /usr/redbooks/bin/vmgetinfo in this section. Our vmgetinfo command is an executable file compiled from the C source file shown in Example 3-17 on page 149.
The sample application, vmgetinfo, would fail with errno 109 (ENOSYS), as shown in the following example, if it is executed on AIX 5L Version 5.1, because it calls the vmgetinfo() system call, which is supported from Version 5.2:
$ oslevel -r 5100-03 $ vmgetinfo vmgetinfo() at 16 in my_application.c failed with errno = 109: Function not implemented
Assuming that the build root directory is /tmp/packages, we have prepared the install target files (the command itself and its source file), as shown in the following directory structure:
# pwd /tmp/packages # ls -lFR . total 8 drwxr-xr-x 3 root system 512 Feb 24 14:37 usr/ ./usr: total 8 drwxr-xr-x 4 root system 512 Feb 24 14:37 redbooks/ ./usr/redbooks: total 16 drwxr-xr-x 2 root system 512 Feb 24 14:39 bin/ drwxr-xr-x 2 root system 512 Feb 24 14:39 src/ ./usr/redbooks/bin: total 16 -r-xr-xr-x 1 root system 5898 Feb 24 14:39 vmgetinfo* ./usr/redbooks/src: total 8 -rw-r--r-- 1 root system 922 Feb 24 14:39 vmgetinfo.c
Note
The owner, group, and permission modes must be carefully verified before actually creating your packages.
Preparing a template file
We have prepared the template file shown in Example 12-9 on page 421 in order to create a package, called vmgetinfo. In this example, the vmgetinfo package consists of two filesets: vmgetinfo.rte and vmgetinfo.src.
As shown in the high-lighted lines in Example 12-9 on page 421, vmgetinfo.rte requires the bos.rte.libc fileset to be installed with level 5.2.0.0 or higher. This requisite condition would prevent users from installing this fileset on AIX 5L Version 5.1 and earlier. Also, vmgetinfo.src requires that vmgetinfo.rte be installed. Therefore, even if a user selects vmgetinfo.src only, vmgetinfo.rte will be installed automatically.
For the complete definition of requisite condition keywords, refer to the “Packaging Software for Installation” section in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.
Example 12-9. A template file (redbook.tmplt)
Package Name: vmgetinfo Package VRMF: 1.0.0.1 Update: N Fileset Fileset Name: vmgetinfo.rte Fileset VRMF: 1.0.0.1 Fileset Description: vmgetinfo runtime Bosboot required: N License agreement acceptance required: N Name of license agreement: Include license files in this package: N License file path: Requisites: *prereq bos.rte.libc 5.2.0.0 Files /usr/redbooks /usr/redbooks/bin /usr/redbooks/bin/vmgetinfo EOFiles EOFileset Fileset Fileset Name: vmgetinfo.src Fileset VRMF: 1.0.0.0 Fileset Description: vmgetinfo source Bosboot required: N License agreement acceptance required: N Name of license agreement: Include license files in this package: N License file path: Requisites: *coreq vmgetinfo.rte 1.0.0.1 Files /usr/redbooks/src /usr/redbooks/src/vmgetinfo.c EOFiles EOFileset |
The supported keywords in template files are shown in Table 12-4 on page 422.
| Keyword | Description |
|---|---|
| Package Name* | Name of the package. |
| Package VRMF* | Version, Release, Modification, and Fix level of the package. |
| Update* | Is this an update package? |
| Fileset* | Start of a new fileset. |
| Fileset Name* | Name of the fileset. |
| Fileset VRMF* | VRMF of the fileset. |
| Fileset Description | Description of the fileset. |
| Bosboot required* | Is a bosboot required when installing this fileset? |
| License agreement acceptance required | Is license agreement acceptance required for this fileset? |
| Name of license agreement | Name of the license agreement.[a] |
| Include license files in this package | Are the license files included in this package? |
| License file path | Path of the license file(s).[b] |
| Requisites | Requisite conditions (coreq, ifreq, instreq, or prereq) for the fileset.[c] |
| Files* | Start of the files section. |
| /path/to/file | File path.[d] |
| EOFiles* | End of the files section. |
| EOFileset* | End of the fileset. |
[a] The Name of the license agreement is defined as LAR/path/to/license/agreement. The %L tag can be used in place of a hardcoded path to represent the locale of the machine that the package will be installed on. For example, if a package is installed in the en_US locale, %L will be converted to en_US.
[b] The License file path is defined as LAF/path/to/license/file. Multiple license files are separated by semicolons.
[c] Requisites are defined as *Type_keyword Name VRMF; Type_keyword is either coreq, ifreq, instreq, or prereq. Multiple requisites are separated by semicolons.
[d] The full path name for each file in the fileset must be listed in the Files section. Any custom directories should also be listed in this section. For example, to package the /usr/xyz/foo file, list both the /usr/xyz directory and the /usr/xyz/foo file in the Files section. Each entity in the final package will have the same attributes (owner/group/permissions) that it had at build time. The user must ensure that file attributes in the build root directory are correct prior to running mkinstallp.
Note
Keywords with a * are required, and will cause mkinstallp to fall if left blank or omitted in the template file.
Creating a package file
Once the template file is prepared, run the mkinstallp command to create a package file. In the following example, the template file is redbook.tmplt and we invoked the command in the build root directory,/tmp/packages:
# pwd /tmp/packages # ls -l total 16 -rw-r--r-- 1 root system 837 Feb 24 15:01 redbook.tmplt drwxr-xr-x 4 root system 512 Feb 24 15:00 usr/ # mkinstallp -T redbook.tmplt Using '/tmp/packages' as the base package directory. Cannot find '/tmp/packages/.info'. Attempting to create. Using '/tmp/packages/.info' to store package control files. Cleaning intermediate files from '/tmp/packages/.info'. Using 'redbook.tmplt' as the template file. vmgetinfo 1.0.0.1 I processing vmgetinfo.rte processing vmgetinfo.src creating ./.info/liblpp.a ar: Creating an archive file ./.info/liblpp.a. creating ./tmp/vmgetinfo.1.0.0.1.bff
The command will generate the package file in the ./tmp directory underneath the build root directory as shown in the following example:
# ls ./tmp vmgetinfo.1.0.0.1.bff # inutoc ./tmp # ls ./tmp .toc vmgetinfo.1.0.0.1.bff # installp -ld ./tmp Fileset Name Level I/U Q Content ==================================================================== vmgetinfo.rte 1.0.0.1 I N usr # vmgetinfo runtime vmgetinfo.src 1.0.0.0 I N usr # vmgetinfo source
12.2.3. Verification of packages
Once the package is created, it must be verified before the actual software deployment phase on production systems.
Installation verification
The created package must be smoothly installed on the target system if it satisfies the install requisite conditions. If the target system does not satisfy the conditions, the package must be prevented from being installed.
In this example, the following tests must be done:
Installing only the vmgetinfo.rte fileset on AIX 5L Version 5.2 and later.
The vmgetinfo.src fileset should not be installed automatically.
Installing only the vmgetinfo.src fileset on AIX 5L Version 5.2 and later.
The vmgetinfo.src fileset should not be installed automatically, unless the following conditions are met:
Installing the filesets on AIX 5L Version 5.1 and earlier.
The filesets must not be installed.
Verification of the installed files
Check if the installed files are placed, according to the fileset inventory information, with the lppchk command. There are four flags of the lppchk command for verifying the files:
| -f | Fast check (file existence, file length) |
| -c | Checksum verification |
| -v | Fileset version consistency check |
| -l | File link verification |
All four calls of lppchk with the different flags has to return with a zero exit code; if not, there are some inconsistent files, as shown in the following example:
$ lppchk -f -m 3 vmgetinfo.rte; echo $? lppchk: 0504-230 3 files have been checked. 0 $ lppchk -c -m 3 vmgetinfo.rte; echo $? lppchk: 0504-230 3 files have been checked. 0 $ lppchk -l -m 3 vmgetinfo.rte; echo $? 0 $ lppchk -v -m 3 vmgetinfo.rte; echo $? 0
Verification of correct functionality
Use the lslpp command to show all installed files:
# lslpp -L vmgetinfo.rte
Fileset Level State Type Description (Uninstaller)
----------------------------------------------------------------------------
vmgetinfo.rte 1.0.0.1 C F vmgetinfo runtime
# lslpp -f vmgetinfo.rte
Fileset File
----------------------------------------------------------------------------
Path: /usr/lib/objrepos
vmgetinfo.rte 1.0.0.1
/usr/redbooks/bin/vmgetinfo
/usr/redbooks
/usr/redbooks/bin
After installing and validating of the installed package, test your installed application to see if it works as designed. In this example, we have confirmed that the command returned the same output shown in Example 3-16 on page 148.
Uninstallation verification
As the last step of the verification process, check if the package can be un-installed correctly by using the installp -u command, as shown in the following example:
# installp -u vmgetinfo.rte
+-----------------------------------------------------------------------------+
Pre-deinstall Verification...
+-----------------------------------------------------------------------------+
Verifying selections...done
Verifying requisites...done
Results...
SUCCESSES
---------
Filesets listed in this section passed pre-deinstall verification
and will be removed.
Selected Filesets
-----------------
vmgetinfo.rte 1.0.0.1 # vmgetinfo runtime
<< End of Success Section >>
FILESET STATISTICS
------------------
1 Selected to be deinstalled, of which:
1 Passed pre-deinstall verification
----
1 Total to be deinstalled
+-----------------------------------------------------------------------------+
Deinstalling Software...
+-----------------------------------------------------------------------------+
installp: DEINSTALLING software for:
vmgetinfo.rte 1.0.0.1
Finished processing all filesets. (Total time: 0 secs).
+-----------------------------------------------------------------------------+
Summaries:
+-----------------------------------------------------------------------------+
Installation Summary
--------------------
Name Level Part Event Result
------------------------------------------------------------------------------
vmgetinfo.rte 1.0.0.1 USR DEINSTALL SUCCESS
After removing the fileset, the installation target directory (if it is unique to the fileset) should be removed also. In this example, all files and sub-directories under/usr/redbooks are removed.
Now this package is ready to be deployed on production systems.
12.2.4. Optional installation control executable files
The AIX standard packaging format allows you not only to package your applications, but also to add optional files in order to control the installation process. For example, if your application requires a configuration file that depends on the host name where the application is installed, an optional executable file, fileset.config, can be used to automatically create the configuration file upon the fileset installation.
The optional installation control executable files shown in Table 12-5 are called during the installation process. Unless otherwise noted, file names that end in_i are used during installation processing only, and file names that end in_u are used in file set update processing only. All files in Table 12-5 are optional and can be either shell scripts or executable object modules. Each program should have a return value of 0 (zero), unless the program is intended to cause the installation or update to fail.
In order to include these optional installation control executable files, create the files in the .info sub-directory underneath the build root directory before creating the package.
| File name | Description |
|---|---|
| fileset.config fileset.config_u | Modifies configuration near the end of the default installation or update process. Fileset.config is used during installation processing only. |
| fileset.odmdel fileset.*.odmdel | Updates ODM database information for the file set prior to adding new ODM entires for the file set. The odmdel file naming conventions enables a file set to have multiple odmdel files. |
| fileset.pre_d | Indicates whether a file set may be removed. The program must return a value of 0 (zero) if the file set may be removed. File sets are removable by default. The program should generate error messages indicating why the file set is not removable. |
| fileset.pre_i fileset.pre_u | Runs prior to restoring or saving the files from the apply list in the package, but after removing the files from a previously installed version of the file set. |
| fileset.pre_rm | Runs during a file set installation prior to removing the files from a previously installed version of the file set. |
| fileset.post_i fileset.post_u | Runs after restoring the files from the apply list of the file set installation or update. |
| fileset.unconfig fileset.unconfig_u | Undoes configuration processing performed in the installation or update. Fileset.unconfig is used during installation processing only. |
| fileset.unodmadd | Deletes entries that were added to ODM databases during the installation or update. |
| fileset.unpost_i_0 fileset.unpost_u | Undoes processing that is performed following the restoration of the files from the apply list in the installation or update. |
| fileset.unpre_i fileset.unpre_u | Undoes processing performed prior to restoring the files from the apply list in the installation or update. |
For more information, please refer to the “Packaging Software for Installation” section in the AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.