PcsiKitBuilding

PCSI Kit Building

Overview

HP has documentation on building PCSI kits which describe the contents of the files and how to build the kits.

There is a bunch of information that the documentation leaves out.

1. The PCSI kits basically only understand the ODS-2 character set, even the versions that should support ODS-5 extended character sets.

2. Case of the file matters when restoring files to an ODS-5 volume.

3. The PCSI kitting algorithm considers all files with the same filename to be the same file regardless of what directory it is in.
   So if you have two different files named Readme. in two directories, the kitting procedure will only put one version of them in the kit and mark it to be used for both places.

4. The PCSI version naming convention has a prefix character of V for a release version, and other letters like "T" or "D" which can indicate test or development versions. The problem is that the the ECO level is not tied to the prefix level for newer kits. So that if you release an ECO for a test kit, you have to keep that ECO number with the release kit until you increment the major.minor-patch version of the kit. In practice, this is not a problem as a test version is usually wanted to be installed at the same time as a release version, but in a different directory, so the product name should be different.

5. Open source projects may have multiple files with the same name, and different contents, and may have files in them that use characters that are not legal for ODS-2.

6. I have noticed that staging some open source projects install staging step creates or updates a file that is also updated or created by other projects. The PCSI$DESC file used by the kitting procedure allows specifying a versioning system so that older generations do not replace a newer one. This is something I have tried to use in the past. I no longer think that is the correct approach, but instead a script to make sure that the file has the correct information for that installation of the product should be supplied and it should be run either at the product install or possibly as part of the startup script run when the system is booted. This makes it easy to recreate the file if it somehow gets corrupted or deleted.

Kit and File Naming

The kitting procedure needs the files it uses for configuration to have the version number of the package encoded in them, and also present in their contents.

The release notes file that will be installed in the [.syshlp] directory also should also have the version encoded in its name.

While you can manually create the files with the names, this becomes tedious when making an updates to the version name, as you have to get all the renames and edits correct for the kit to get built and then install properly.

I recommend instead to have command procedures generate the files based on more generically named input files.

I have not yet come up with a generic procedure to create PCSI kits.

I have been creating set of procedures that can be easily customized for a specific package, and then need a minimum of changes for new updates.

This consists of a master procedure like pcsi_product_zlib.com for ZLIB or pcsi_product_gnv_bash.com for bash.

This outer procedure then calls 5 other procedures to build each of the files needed for the PCSI kit before actually making the kit. Replace the xxx with the name of the project as these are not yet generic.

1. make_pcsi_xxx_name.com This calculates the kit name used for the files and inside the files.

2. build_xxx_release_notes.com This builds the release notes from a combination of input files.

3. backup_xxx_src.com This creates a pair of backup save sets for inclusion in the kit. I build the savesets only once and copy them to where the other VMS versions and architectures can include the save sets. This can result in a newer backup save set than the target of the kit. Backup seems to be flexible enough to handle this. Otherwise I would not be able to preserve the ODS-5 file names and exact case.
   It may require setting up a OpenVMS/Alpha 8.3 or later system to assist in the development.

4. build_xxx_pcsi_desc.com This reads an input file that contains a manifest of files and directories that will be included in the kit. It generates the .pcsi$desc file, and also the post processing commands that will add or remove alias links for ODS-5 files, and rename the files to the proper case for the kit.

5. build_xxx_pcsi_text.com This reads an input file that is used for the building the .pcsi$text file.

Once these are done for a package, usually only one of the files that is used to build the release notes needs to be edited when a new PCSI kit version is needed.

One factor that also affects creating a generic kit building procedure is that for the projects that will accept VMS specific files, they may put them into a directory such as packages/vms.

Branding or Identifying The Source Of The Kit

One thing that I deliberately leave out of the kitting command procedures is setting the PCSI Producer information. This is so that the person packaging the kit identifies the kit as one they built and helps to tell the difference.

This has a bit to do with branding that kit with the name of the company or individual that created it.

Related to this, if a product version display allows it, I like to add custom information to it to record the compile time of the version module and even the VMS specific ECO level.

This is useful when someone reports an issue and when they print the version, you can tell if it is a binary that you built or someone else built.

The kitting procedures get the producer information from a pair of logical names GNV_PCSI_PRODUCER and GNV_PCSI_PRODUCER_FULL_NAME. The first is used to set the prefix for the kit name. The second currently is written out to one or more of the input files to the kitting procedure. It should actually be a reference to a file with a paragraph, but this was not clear to me in the PCSI manual, and I have not had a chance to revise the procedures that I am using.

The build instructions cover this in the release notes that are added to the product so that if someone takes the trouble to build a PCSI kit, it will be a uniquely prefixed kit for a specific entity.

Handling Duplicate Filenames and Extended Characters

As mentioned before, the PCSI kitbuilding procedure assumes that all files with the same name are the same file, and that it really only supports the ODS-2 character set.

So you may need a procedure that goes over a staging directory of files to include in the kit. This procedure would have to have a list of files that need to be renamed before kitting.

What the procedure can do is use the DCL SET FILE/ENTER command to create ODS-2 unique files for the ones that are in conflict, such as readme_1.txt for the second readme.txt that may be in the distribution kit.

The procedure should also take a parameter to do a SET FILE/REMOVE on the files that it created.

The same procedure for handling files like foo++ which can be kitted as foo_pl_pl if that hack is needed.

Most products will not need that hack.

The kit will be built with post install and pre-uninstall procedures that will take care of creating and removing the entries for the ODS-5 files when the kit is installed on an ODS-5 volume. The post install procedure will also fix up the case of the files installed to be as the original program expects.

Source Kits

The source should be provided with an open source project in the same kit as the binary. This satisfies many open source requirements that you make the source available, with out you having to actually maintain a download site or distribution site for years in the future. While only some licenses require this, it is a good idea in general practice.

Generating the PCSI kit name

The PCSI kit name is generated from the prefix stored in the GNV_PCSI_PRODUCER, the GNV_PCSI_PRODUCER_FULL_NAME logical name, and then a header file like version.h. for the version information, and also a file name vms_eco_level.h for the VMS ECO level. If possible it is desirable to also patch the version report of the program to report the VMS ECO level.

At this time, this is a project specific configuration file because the name of the file with the version information in it may be different, and also the way to parse it.

So a more generic implementation would require a data file that described both what file(s) to read and how to parse them.

Generating the release notes

The release notes are usually generated from three input files.

A xxx_release_note_start.txt this file contains information to put at the beginning of the release notes.

The readme. file from the original source, if the source provides one.

A xxx_vms_build_steps.txt file that describes how to build and kit the project. This file should not change much with releases.

A command procedure is used to combine these as the VMS generate files may be in a different file format than the readme file.

Building the source save sets

The backup_xxx_src.com file is used to create typically two backup savesets. This procedure is typically only run by me on a VMS 8.3 or later system as that has the /interchange/noconvert qualifier to make a backup save set of ODS-5 files that is stripped of the original security information.

An ODS-5 save set is usually needed to preserve the extended filenames. Before VMS 8.3, an ODS-5 saveset could not be made /interchange.

In my specific build environment, my build environment is on NFS served disks. This complicates things as VMS backup will not read files from an NFS served disk.

This means I need an additional command procedure to make sure that a copy of the source files on a real ODS-5 volume is present.

Note that you can use the logical disk program to create an ODS-5 volume on an NFS served volume if you are short of disk space on the VMS system.

I typically make the backup save sets on only one system and then replicate them to be included in the building of other PCSI kits.

I supply the unmodified source as one save set, and another save set with the VMS specific modifications only. This is so that if someone wants to verify what was changed it is easy to do so. I have had problems in debugging some ports like bash 1.4.8 because it is hard to figure out what changes were made for VMS. In the case of Bash 1.4.8, I can not go back to the GNU bash archives to see what is different because GNU Bash 1.4.x ends at 1.4.7. So we do not know for sure what the original changes were.

Building the PCSI$DESC file

The PCSI$DESC file contains the post install and pre-install procedures, and also a list of files to install.

The build_xxx_pcsi_desc.com procedure reads in a text file named pcsi_xxx_file_list.txt to generate the PCSI$DESC file.

The pcsi_xxx_file_list.txt has a format to give simple instructions for building the file. This format is described in comments to the file.

! File list for building a PCSI kit.
! Very simple format so that the parsing logic can be simple.
! links first, directory second, and files third.
!
! link -> file tells procedure to create/remove a link on
!         install/uninstall
! If more than one link, consider using an alias file.
!
! [xxx.yyy]foo.dir is a directory file for the rename phase.
! [xxx.yyy.foo] is a directory file for the create phase.
! Each subdirectory needs to be on its own pair of lines.
!
! [xxx.yyy]file.ext is a file for the rename and add phases.

This is a simpler file to maintain than the actual PCSI$DESC format.

Building the PCSI$TEXT file

The build_xxx_file_list.txt is generated from four components.

The generated product header section.

The readme file from the distribution if it has one. It needs to be modified to fit a pcsi$text file format.

The copying or other licensing file from the distribution if it has one. It needs to be modified to fit a pcsi$text file format.

A generated producer section.

The build_xxx_pcsi_desc.com puts these together for the proper architecture. It needs to also set the dependencies on the VMS version and any other PCSI kits that need to also be installed. Currently I modify the procedure for this.

A more generic procedure would use a data file to drive the sections.

Putting it all together

The pcsi_product_xxx.com is used to run all of these procedures as needed to build the kit with one command.

On VAX/VMS, the product command always prompts to the terminal for confirmation, which is preventing just running a command file.

I have not determined if I can use the product command on Alpha to build a VAX PCSI kit, especially when it is targeting an older version of VMS to do the install than was was used to build the kit.

The VAX product command can not make a compressed kit.

The procedure currently does not ZIP the file, but a future enhancement could be to create self extracting ZIP exe files, or normal ZIP files.

Signing a kit

I have not learned the procedures for signing a kit well enough to try signing a kit.

For signing to authenticate a kit, the certificate used to sign the kit needs to be signed by a certificate authority that is trusted by the operating system, and unique to the entity building the kit.

Otherwise a kit being signed or a md5sum for a kit is not really securing the kit from tampering unless the person doing the tampering does not think to either resign the kit or post an a new md5sum at the site of the tampered kit.

This is something that needs to be looked into further, as HP is sometimes warning if a kit is not signed.