Pismere Installer Build Documentation

The Build Script

The Pismere team uses the script buildinst.pl to build its installers. This script has been tested with ActivePerl build 522 and 618. (www.activestate.com). Newer builds probably work...try them at your own risk.

Running the Build

Go to the directory you want to build and invoke the build script. The invocation will vary depending on how your system is set up. Here some common ways to build:

You may need to put perl at the start of each of the above commands, depending on whether your shell knows how to execute a .pl file.

Adding a subdirectory to the build

If you need to build subdirectories, create a Makefile.dir in the directory. At least one of these variables must be defined in Makefile.dir.

PREDIRS
List of directories to build before building the current directory.
DIRS
List of directories to build after building the current directory.
OPTDIRS
List of optional directories to build after building the current directory. (These directories will only be built if at least one of dirname/Makefile.src, dirname/Makefile.dir, or dirname/Makefile exists).

Example

DIRS=dir_1 dir_2
Where dir_n is the name of the subdirectory you want to build. The build will first build the current directory then the subdirectories.

Creating Modular Installers

Many Pismere deliverables need to exist in two installers:

For example, customers running Windows NT may like to install the KLP printing system. This is also a component of a Pismere Workstation install.

Creating a modular installer can be broken down into several steps:

  1. Create the notes.txt file
  2. Create the Makefile.inst file
  3. Execute buildinst.pl getfiles
  4. Create x.wsm as defined in notes.txt
  5. Execute buildinst.pl module
  6. (If stand-alone) Create x.wsi as defined in notes.txt
  7. (If desired) Incorporate into a larger installer

Create the notes.txt file

Create a notes.txt file defining all of the steps that the installer should accomplish. This document should be sufficiently verbose to allow someone to recreate the installer without having a working copy. This document should be checked into the tree in the 'doc' subfolder of the installer you are creating. For examples, see notes.txt in klp\doc and athinfod\doc.

Create the Makefile.inst file

The next step in creating a modular installer is to create the Makefile.inst file. This file basically tells the build script what files your installer will use, and where to get them from. See the documentaion below for specific details on syntax.

Execute buildinst.pl getfiles

This will parse your Makefile.inst, and retrieve the files your installer will use.

Create x.wsm as defined in notes.txt

This should implement the modular section in your notes.txt file

Execute buildinst.pl module

This will build the module, so that it can be incorporated into installers.

(If stand-alone) Create x.wsi as defined in notes.txt

This will allow people to test the component separately.

(If desired) Incorporate into a larger installer

You might want to incorporate your module into the pismere installer (ask Joe, Qing or Paul before you do this), or you might want to bundle several modules together (e.g. the Kerberos module and some of the redist modules).

Makefile.inst Reference

A ‘#’ comments out the rest of a line. To escape a '#', use '^#'.

Lines can be continued by using the ‘\’ character.

The following are required and can only occur once in a valid Makefile.inst:
NAME
Base name of target (don’t specify extension)
TYPE
Initially, only wsi and wsm types will be accepted. You can specify both but make sure wsm comes before wsi. (space delimited)
The following are optional and can only occur once in a valid Makefile.inst:
OUTPUT
Name of output files (.msi or .msm extension added automatically)
NOPLACE
Don’t place the output files
Some of the source we build (e.g. AFS 3.6) does not use the Pismere target directories. For this reason, properties starting with PATH_ or FILES_ are special.
They will not get passed to the compiler. Instead, they are used when getting the files for an installer. For example, the AFS 3.6 Makefile.inst includes:
PATH_ROOT.SERVER=$(PISMERE)\athena\afs-3.6\dest\$(CPU)\$(T)\root.server\usr\afs\bin
FILES_ROOT.SERVER= \ ...

The files listed in FILES_ROOT.SERVER will be copied from the path given by PATH_ROOT.SERVER into the .\files\root.server directory.
For convenience, the following common PATH_ properties have defaults:

PATH_BIN
Source directory for binary files, defaults to $(PISMERE)\target\bin\$(CPU)\$(T)
PATH_LIB
Source directory for library files, defaults to $(PISMERE)\target\lib\$(CPU)\$(T)
PATH_INC
Source directory for header files, defaults to $(PISMERE)\target\inc
PATH_EXTRA
Source directory for random files, defaults to .
When copying, the following rules apply:
FILES_BIN
Files to copy from PATH_BIN into files\bin (space delimited)
FILES_LIB
Files to copy from PATH_LIB into files\lib (space delimited)
FILES_INC
Files to copy from PATH_INC into files\inc (space delimited)
FILES_EXTRA
Files to copy from PATH_EXTRA into files\extra (space delimited)
Any other value of the form "PROP=VAL" will set the property PROP to the value VAL in the installers.
buildinst.pl passes the DEBUGBUILD property in by default during debug builds, so that actions inside the
installer can be conditioned on this property.

For an example, see the notes for the KLP installer, which uses a custom action to redefine the product name for debug installations.