Pismere Build Documentation

The Build Script

The tree uses the Pismere build script, build.pl. This script is known to work with ActivePerl builds 517 and 522 (www.activestate.com). Older builds of ActivePerl had subtle incompatibility problems. Newer builds probably work...try them at your own risk.

The build works under Windows NT. It should work under Windows 95, but we do not test it regularly under that OS. You should use the default command-line shell for those OSes, or something fairly compatible.

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 are the most 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.

Using the Build Script to Build Your Code

The build script works by entering a directory, and looking for a Makefile.src, a Makefile.dir, or a Makefile file.

If the Makefile.src is present, the script will try to create the target defined by this file. Therefore, only one target can be created per directory. The target cannot consist of source files from other directories. If this is necessary, you should first build the other directory, creating a library, and then include that library as part of the target you're trying to build. If you need to create multiple targets from a set of source files, you can simply create additional directories that link in the object or library files created by the sources.

If the Makefile.dir is present, the script will try to build the directories indicated in this file. The directories can be build before and/or after the current directory.

If neither of the above files exist, the script will simply invoke the make utility on Makefile.

Adding a component to the build

First, go to the directory where the component is located. Then, create a Makefile.src as described below.

You will then be able to run build.pl in a variety of ways to get the most common types of builds. See Running the Build above for information on how to run build.pl.

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.

Build Options Reference

Below are the options that control the build. These are in addition to any flags shown when you do a build.pl -?.

Common Global Build environment options

These are some of the common options you may want to use in building. You can set any option at the build.pl command-line. The default build is a debug build.

NODEBUG
Set to 1 to build an optimized version of your app with no debug info (i.e., a release build).
SELF_REGISTER
Set to 1 to have self-registerable components register themselves during the build. Do this only if you need to test the component(s) you are building on the local workstation. This option does not affect components that are not marked as SELF_REGISTERABLE (see below).
VENDORMOD
Set to the organization making a modification to the sources. This helps figure out who made this modified build.

Uncommon Global Build environment options

You should not have to play with the settings in this section. They are here for completeness.

APPVER
[ 4.0 | 5.0 ] - For build time checking for OS version dependencies and to mark the executable with OS version information. (Default is 4.0.) [not much reason to use this]
TARGETOS
[ WIN95 | WINNT | BOTH ] - For some build time checking for platform dependencies. (Default is WINNT.) [not much reason to use this]
TARGETLANG
[ LANG_JAPANESE | LANG_CHINESE | LANG_KOREAN ] - For compile & link flags for building applications to run on Far-East Windows. (This is an optional parameter. The system locale is the default.) [not much reason to use this]
_WIN32_IE
[ 0x0300 | 0x0400 ] - For compile and link flags for building applications and components to run on Internet Explorer. (This is an optional parameter. IE 4.0 is the default.) [not much reason to use this]
NO_DEBUG_CRT
Set to 1 to not use the debug version of the CRT when building a debug application.
TUNE
Set to 1 to get working set tuner info.
PROFILE
Set to 1 to get call attributed profiling info.

Note: NODEBUG, TUNE, and PROFILE are mutually exclusive.

Makefile.src options

At this point, $(O) is the output directory. NODEBUG will indicate whether you're doing a release or debug build. STD_LIBS consists of standard Win32 libraries.

Required

NAME
Base name of target (no extension).
TARGETTYPE
[ EXE | DLL | LIB | CPL | SCR | NONE ] - Type of target. Note: When the target type is NONE, it is not necessary (or even desirable) to define NAME, TARGETSS, or OBJS. NONE is very useful as a means to use PLACE when not doing any kind of build at all, when building files that the build does not yet support (e.g., help files), or when trying to integrate with a package with its own separate build.
TARGETSS
[ console | windows ] - Target subsystem.
OBJS
List of object files (i.e., $(O)\foo.obj).

Optional

DEF_FILE
Name of .def file, if any.
RES
Name of resource file, if any (i.e., $(O)\foo.res).

PLACE
List of additional files to place. The build fails if these files do not exist (unless NO_PLACE is used).
PLACE_OPTIONAL
List of additional optional files to place. If these do not exist, the build continues.
NO_PLACE
If defined, will not try to place output files.
NO_EXTERNAL_DEPS
If defined, will not use $(NAME).dep and Makefile.dep as a dependency file (overrides USE_EXTERNAL_DEPS). The default is to silently try to use a $(NAME).dep and Makefile.dep. (Note: Usage of just Makefile.dep is preferred.)
USE_EXTERNAL_DEPS
If defined, will give warning if $(NAME).dep and Makefile.dep are not present. The default is to silently try to use $(NAME).dep and Makefle.dep. (Note: Usage of just Makefile.dep is preferred.)

INCLUDES
List of include dirs, ;-delimtited (e.g., INCLUDES=..\include;..\foo\inc;"..\annoying path with spaces\inc").
LIB_PATHS
List of lib dirs, ;-delimited (e.g., LIB_PATHS=..\lib;..\foo\lib).
LIBS
Libraries to use (e.g., LIBS=foo.lib bar.lib ..\baz\$(O)\baz.lib or LIBS=$(STD_LIBS)).
DEP_LIBS
Anything that the output file depends on. This is not used for linking, but it is used to determine whether the file to be linked is out of date. It may be useful to include this variable in the LIBS line too. (e.g., LIBS=subcomponent/a.lib ../other/component.lib).
USE_DEFAULTLIB
If defined, will use default libraries (the default is to only use the libraries specified in LIBS).

UNICODE
Define this to use unicode libraries and entry points.

USE_MFC
Use MFC (DLL by default).
USE_MFC_STATIC
Use static MFC.

USE_LIBC_STD
Use static libc (not thread-safe).
USE_LIBC_MT
Use thread-safe satic libc.
USE_LIBC_DLL
Use thread-safe libc DLL (default)
NO_LIBC
Do not use any libc.
NO_LIBC_LINK
Do not explicitly specify the libc on the linker line. This is needed if you need to override stuff in libc (like operator new). (NOTE: Perhaps this should be the default.)

USE_PCH
Define to use automatic pre-compiled headers (which will be in $(NAME).pch).
USE_MINIMAL
Define for minimal rebuilds (-Gm). This setting is ignored in a release build. Note: Minimal rebuild relies on class definitions not changing between include files. Class definitions must be global for a project (there should be only one definition of a given class), because the dependency information in the .IDB file is created for the entire project. If you have more than one definition for a class in your project, disable minimal rebuild.
NO_MINIMAL
Define to not do a minimal rebuild (overrides USE_MINIMAL).
USE_CPP_RTTI
Define to get C++ run-time type information (-GR).
USE_CPP_EH
Define to get C++ exception handling (-GX).
PCH_FILE
Set to header file to use for pre-compiled header (implies USE_PCH). Note that this option is not needed if you want the compiler to automatically handle pre-compiled headers. It's only needed if you need to control how pre-compiled headers are handled.
GEN_BSC
Define for SBR/BSC creation.
NO_BSC
Define for no SBR/BSC creation (overrides GEN_BSC).
KEEP_SBRS
Define to not truncate .SBR files when building a .BSC file.

GEN_MAP
Generates a .MAP file in the build.

C_DEFINE
Only for -D style definitions to pass to the C/C++ compiler.
RC_DEFINE
Only for -D style definitions to pass to the resource compiler.
C_FLAGS
Any additional flags to pass to the C/C++ compiler. You should not use this unless absolutely necessary. Using this may signal a need to have the build system support more options. If it's a -D definition, put it in C_DEFINE.
RC_FLAGS
Any additional flags to pass to the resource compiler. You should not use this unless absolutely necessary. Using this may signal a need to have the build system support more options. If it's a -D definition, put it in RC_DEFINE.

USE_SUFFIX_CP
Define this to allow .cp files to be treated as C++ source files.

SELF_REGISTERABLE
Define this to specify that the component being built is self-registerable.