KfW is built on a Windows PC, in the default Windows shell (cmd.exe). These components must be installed:
All the components above must be in PATH. Installing ActivePerl puts perl in the PATH. Doxygen, Cygwin, hhc, wix and nsis need to be added.
perl must be installed so that .pl files are automatically executed with perl. The ActivePerl installation will do this for you.
In the INCLUDE path, the Microsoft Platform SDK must come before the Microsoft Visual C++ include files. In the PATH path, the Platform SDK bin area must come before the Visual Studio VC\bin area. Using a Platform SDK Build Environment window will set this up the right way. Make sure to use a Platform SDK Windows XP Build Environment shell.
If you make your path modifications permanent via Control Panel / System / Advanced / Environment Variables: If you use a Platform SDK Build Environment window, it appears that you need to put your PATH components in the System PATH, not the User PATH.
Visual Studio installs hhc in C:\Program Files\HTML Help Workshop.
nmake must be in PATH. If you use a Platform SDK build environment window, it is already done for you.
The build is a perl script controlled by command line switches and an XML configuration file. The config file is required. Settings in the config file can be overridden by optional command line switches.
There are options for controlling most steps of the build process. The steps are
The usage message shows the switches that control these steps:
C:\Projects\KfW>perl bkw.pl /?
Usage: bkw.pl [options] NMAKE-options
Options are case insensitive.
Options:
/help /?
usage information (what you now see).
/config /f path Path to config file. Default is
bkwconfig.xml.
/src /s dir Source directory to use.
Should contain
pismere/athena. If cvstag or svntag is null,
the directory should be prepopulated.
/out /o dir Directory to be created
where build results will go
/repository checkout | co \ What repository action to take.
/r
update | up \ Options are to checkout, update, export
export
| ex \ or take no action [skip].
skip
/username /u name username used to access svn if checking out.
/cvstag /c tag use -r <tag>
/svnbranch /b tag use
/branches/<tag>
/svntag /t tag use
/tags/<tag>
/debug
/d Do debug make instead of
release make.
/[no]make
Control the make
step.
/clean Build
clean target.
/[no]package Control the packaging step.
/[no]sign Control
signing
of executable files.
/verbose
/v Debug mode - verbose output.
/logfile /l path Where to write output.
Default is bkw.pl.log.
/nolog Don't
save output.
Other:
NMAKE-options any options you want to pass to NMAKE, which
can be:
(note: /nologo is always used)
NODEBUG=1
NMAKE-options any options you want to pass to NMAKE, which can be:
(note: /nologo is always used)
[ nmake options follow ]
Notes on the script steps:
Verifying the environment:
The script tests for each program that it needs and warns if the program isn't
found.
Fetching sources from repositories:
If building from a source distribution kit, this section does not apply.
CVSROOT and SVNURL must be specified in the configuration file.
A source zip file can only be produced if checking out fresh sources from a repository.
If checking out, the entire pismere directory will be deleted. A warning message requires that you confirm this action.
Building the sources:
/DEBUG controls whether a debug or release build is done. /CLEAN will
build the CLEAN target.
Setting up the packaging environment :
The pre-package steps gathers up build results and puts them in a
staging area.
If /SIGN is specified, .exes, .dlls and .cpls are signed. The signing command template is in the configuration file.
Building the installers:
The staging area is copied into a fresh area for
each of the installers. The installer results are copied back to the
staging area.
Building the rest of the components:
Zip files are built in temporary areas and copied to outdir.
The installers and assorted files are copied from staging
to outdir. If /SIGN is specified, the
installers will be signed.
CopyLists are used in many places. For example, files to be put into a .zip are copied to a fresh directory which is then zipped up. There is an optional Configuration section and a required Files section.
The configuration section defines the roots of the from and to paths and can optionally define path substitutions.
The to and from paths are forced by the script rather than being set in the config file. Comments in the copyfile xml indicate this.
Lengthy copy lists can be kept in separate files and included with the Include directive. Example:
<Include path="sdkfiles.xml" />
Filenames in copylists can contain variable 'tags' that are replaced before the file is copied. Some configuration files contain substitution tags which customize the configuration. The supported tags are
| %VERSION_MAJOR% | KfW Version from pismere/athena/include/kerberos.ver. |
| %VERSION_MINOR% | KfW Version from pismere/athena/include/kerberos.ver. |
| %VERSION_PATCH% | KfW Version from pismere/athena/include/kerberos.ver. |
| %filestem% | Defined as kfw-%VERSION_MAJOR%-%VERSION_MINOR%-%VERSION_PATCH%. |
| %debug% | 'dbg.' Only substituted during a debug build. |
| %release% | 'rel.' Only substituted during a release build. |
| %bldtype% | Always substituted, to 'dbg' or 'rel,' depending on the type of build. |
| %-DEBUG% | '-DEBUG' during a debug build; otherwise empty. |
| %BUILDDIR% | SRCDIR\pismere. Used in site-local installer configuration files. |
| %TARGETDIR% | SRCDIR\pismere\staging. Used in site-local installer configuration files. |
| %CONFIGDIR-WIX% | SRCDIR\pismere\staging\sample. Used in site-local installer configuration files. |
| %CONFIGDIR-NSI% | SRCDIR\pismere\staging. Used in site-local installer configuration files. |
The overall build configuration specifies a debug or release build. Debug and release results are put in different places. Files whose location depend on the build type can use %bldtype% in their names. The script will substitute %bldtype% with either dbg or rel, depending on the build type.
Here is a copylist entry. Each segment of the file's path that comes from a different place is in a different color.
Release build. Config file:
| <BKW_Config> | |||
| <Config> | |||
| <src value ="C:\bkw" /> | |||
Copylist comments:
<!-- File from paths are relative to
<!-- File to paths are relative to
When the script processes this copylist, it will force the from and to paths as indicated.
This line
<File name="comerr32.dll" from="..\target\bin\i386\%bldtype%\" to="\bin\i386" />
will result in C:\bkw\pismere\athena\..\target\bin\i386\rel\comerr32.dll
being copied to C:\bkw\pismere\staging\bin\i386\comerr32.dll.
Other possible attributes in a copylist entry:
By default, copylist entries are required and the script will die if they aren't present. To ignore missing files, add notrequired.
To rename the file, set the newname attribute.
Implement RETAIL, OFFICIAL, PRERELEASE, PRIVATE, SPECIAL.
Figure out what MIT_ONLY, BUILD_KFW, DEBUG_SYMBOL should be.
TARGET, APPVER.
NODEBUG=1. Set if release build.
Can't clean directory; can't delete file or directory
Make sure a file in the named directory isn't open in another application.
Can't find kerberos.ver
You skipped the repository step and are trying to build in an empty directory.
Directories don't exist or can't be created
This can be a symptom of the Platform SDK bin area not being before the Visual Studio bin areas, such that the version of nmake running is version 8.x.
[This explanation courtesy of Jeff Altman]:
nmake V8 appears to favor executables over shell commands. As a result, using 'mkdir' instead of 'md' in Makefiles, as a command for creating directory trees, fails when the Cygwin mkdir.exe is present in the PATH. Changing the
MKDIR=mkdir
RMDIR=rmdir
macros in the Makefiles to
MKDIR=md
RMDIR=rd
should make the shell versions execute in all cases.