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:
- Create the
notes.txt
file
- Create the
Makefile.inst
file
- Execute
buildinst.pl getfiles
- Create x.wsm as defined in notes.txt
- Execute
buildinst.pl module
- (If stand-alone) Create x.wsi as defined in notes.txt
- (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.