# 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:

- `buildinst.pl -?` - show usage information.
- `buildinst.pl --docs` - show this documentation.
- `buildinst.pl` - builds release target.
- `buildinst.pl debug` - builds debug target.
- `buildinst.pl getfiles` - gets files only
- `buildinst.pl module` - getfiles and build module target.
- `buildinst.pl clean` - cleans all targets.

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:

- A stand-alone installer that only installs that component
- A large installer that installs most or all of our deliverables

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:

- filename1:filename2 will rename filename1 to filename2 during the copy
- $(PISMERE) will be replaced by the top pismere directory
- $(CPU) will be replaced by the cpu type
- $(T) will be replaced by 'dbg' if the target is debug, and 'rel' otherwise

`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.