NOTE: Build instructions for TWAPI 4.0 have changed significantly from
previous versions.

NOTE: This file primarily describes building TWAPI with the Microsoft
toolchain. A section at the end briefly discusses building with the
GNU MinGW tools.


What you need (or the official build environment):
--------------------------------------------------

- To compile the 32-bit version of TWAPI, you need Visual C++ 6.0. The 64-bit
version is built with the compiler that ships with the SDK. The primary
reason for not moving to later versions of Visual Studio is that these
compilers use C runtime libraries that are present on every version
of Windows. Later versions would require to ship the Microsoft runtime
redistributable package.

- Microsoft Platform SDK for Windows Server 2003 SP1. Earlier versions
will not do. Later versions will but you may need to do some tweaking.
It is unfortunate that you need to install a 350MB package just for
some headers and libraries but that's life. When installing, make sure
you include the AMD64 build environment if you want to do 64-bit
builds. Also ensure you include the Web Workshop component as some
Windows Shell headers are included there.

- Some version of Mercurial to check out code from the SourceForge repository.

Here is the step-by-step procedure for compiling twapi on a PC:

Source code checkout
--------------------

Clone the twapi repository from SourceForge.

If you are using the command line Mercurial client, the command would be

    hg clone http://twapi.hg.sourceforge.net:8000/hgroot/twapi/twapi my_twapi

This will create a my_twapi/ subdirectory in your current working
directory.

For more detail about using Mercurial, you might want to
start with the SourceForge Mercurial instructions at
http://sourceforge.net/apps/trac/sourceforge/wiki/Mercurial.


Customize for your environment
------------------------------

Edit the files twapi/include/tooldefs.inc to fix up paths
specific to your environment. This is generally not required.


Set up 32-bit environment (only for 32-bit builds)
-------------------------

NOTE: This assumes the VC++ 6 compiler. For newer compilers, run the
appropriate batch file that comes with the compiler to set up the
environment.

In a DOS command window, set up the build environment by typing the commands

     "%ProgramFiles%\Microsoft Visual Studio\vc98\bin\vcvars32"
     "%ProgramFiles%\Microsoft Platform SDK\setenv.cmd" /XP32 /RETAIL

Note the locations of the Visual Studio and SDK directories may be different
on your system.


Set up 64-bit environment (only for 64-bit builds)
-------------------------

NOTE: This assumes the SDK 2003 64-bit compiler. For newer compilers, run the
appropriate batch file that comes with the compiler to set up the
environment.

In a DOS command window, set up the build environment by typing the command

     "%ProgramFiles%\Microsoft Platform SDK\setenv.cmd" /XP64 /RETAIL

NOTE: /XP64 and /RETAIL MUST BE IN UPPER CASE.

The locations of the Visual Studio and SDK directories may be different
on your system.


Building the extension
----------------------

There are several different variations of the extensions These are
described in the documentation in detail. To build a specific variation,
first cd to the twapi directory and set up the appropriate
build environment as described above. Then run one of the following
commands:

	nmake twapi MAKEDIST=1

This will build the standard distribution with a single DLL and external
Tcl scripts.

    nmake twapi-bin MAKEDIST=1

This will build a single DLL with all scripts embedded as resources in it.

     nmake twapi-modular MAKEDIST=1

This will build separate DLL's for each component, each with the associated
script embedded.

     nmake twapi-lib MAKEDIST=1

This will build the static library version of TWAPI.

By default, the builds will be the twapi/build directory and the
distributions in the twapi/dist directory.

If you leave off the MAKEDIST=1 parameter, only the build will be done
but not the zipped distribution.

Note building the extension or distribution only builds either the 32-bit
or 64-bit versions. Each has to be built separately in their respective
build environments.

Building a full distribution
----------------------------

The above steps are combined into the release.cmd batch file.
Run this file from a DOS prompt WITHOUT setting up the environment as
described above. It will then build all the above distributions
for both 32- and 64-bit versions.

The release1.cmd file is invoked by the release.cmd file to build
binaries for a single architecture (x86 or amd64).


Building for debugging
----------------------

For debugging, build a version with the NOOPTIMIZE option as follows:

    nmake twapi NOOPTIMIZE=1

Building with MinGW-W64
-----------------------

To build with the MinGW toolchain, do something along the lines of

    cd <BUILDDIR>
    c:/src/twapi/configure --prefix=c:/tcl/mingw --enable-threads --enable-64bit --with-tcl=c:/tcl/mingw/lib
    make clean
    make 2> errors.log
    make install

That's for the 64-bit build within the mingw 64-bit build shell. For a
32-bit build, do something similar from a 32-bit mingw shell.

IMPORTANT: In this case, the Tcl binaries must also have been built
with the MinGW-W64 toolchain.