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

- `build.pl -?` - show usage information.
- `build.pl --docs` - show this documentation.
- `build.pl` (or `build.pl all`)- builds debug target.
- `build.pl NODEBUG=1` (or `build.pl all NODEBUG=1`) - builds release target.
- `build.pl clean` - cleans debug target.
- `build.pl clean NODEBUG=1` - cleans release target.

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.