---------------------------------------------------------------------
----------- Zinc Application Framework 5.3 - README.WIN -------------
----------- COPYRIGHT (C) 1990-1999. All Rights Reserved. -----------
-------- Wind River Systems Incorporated. Alameda, CA, USA ----------
---------------------------------------------------------------------

This file provides important information for Zinc Application
Framework (ZAF) users on Microsoft Windows. It contains the following
sections:

    Building ZAF 5.3 Libraries and Examples
    Setting Up Environment Variables
    Running ZMAKE
    Hints
    Building Your Own Make Files

---------------------------------------------------------------------
--- Building ZAF 5.3 Libraries and Examples ------------------------
---------------------------------------------------------------------

The ZAF libraries and examples for Microsoft Windows can be built
from a command prompt by following two easy steps:

    1. Set up environment variables.
    2. Run zmake.

---------------------------------------------------------------------
--- Setting Up Environment Variables --------------------------------
---------------------------------------------------------------------

Before libraries can be built, the following environment variables
must be set up:

    PATH            System path
    INCLUDE         Include file path
    LIB             Library file path
    ZINC_COMPILER   Name of compiler to be used
    ZAF_ROOT        Root of ZAF installation

These variables can be set in AUTOEXEC.BAT or in another batch file.  
Details are given below (actual directory names may vary):

    1. The PATH environment variable must be modified to include the
"zaf\bin" directory, as well as the directory containing the
compiler's command line utilities. Below are examples of setting the
PATH for various compilers:

    Borland:
        SET PATH=%PATH%;c:\zaf\bin;c:\bc50\bin

    Microsoft:
        SET PATH=%PATH%;c:\zaf\bin;c:\msvc\bin;c:\msvc\sharedIDE\bin

    Watcom 32 bit:
        SET PATH=%PATH%;c:\zaf\bin;c:\watcom\binp;c:\watcom\binnt

    Watcom 16 bit:
        SET PATH=%PATH%;c:\zaf\bin;c:\watcom\binp;c:\watcom\binw

    2. The INCLUDE environment variable tells the compiler where to
look for included header files. It must be set to include the
"zaf\include" directory and the compiler specific directories
containing the compiler's header files. Below are examples of setting
the INCLUDE environment variable:

    Borland:
        SET INCLUDE=c:\zaf\include;c:\bc50\include

    Microsoft:
        SET INCLUDE=c:\zaf\include;c:\msvc\include

    Watcom 32 bit:
        SET INCLUDE=c:\zaf\include;c:\watcom\h;c:\watcom\h\nt

    Watcom 16 bit:
        SET INCLUDE=c:\zaf\include;c:\watcom\h;c:\watcom\h\win

    3. The LIB environment variable tells the linker where to look
for libraries needed in linking the application. It must be set to
include the appropriate "zaf\lib\<compiler>" directory, as well as
the compiler specific directories containing the compiler's
libraries. Below are examples of setting the LIB environment
variable:

    Borland:
        SET LIB=c:\zaf\lib\borland;c:\bc50\lib

    Microsoft:
        SET LIB=c:\zaf\lib\microsft;c:\msvc\lib

    Watcom 32 bit:
        SET LIB=c:\zaf\lib\watcom;c:\watcom\lib386;
        c:\watcom\lib386\nt

    Watcom 16 bit:
        SET LIB=c:\zaf\lib\watcom;c:\watcom\lib386;
        c:\watcom\lib386\win

    4. The ZINC_COMPILER environment variable tells the ZAF make
files which compiler to use when building the ZAF libraries. Below
are examples of setting the ZINC_COMPILER environment variable:

    Borland:
        SET ZINC_COMPILER=borland

    Microsoft:
        SET ZINC_COMPILER=microsoft

    Watcom:
        SET ZINC_COMPILER=watcom

    5. The ZAF_ROOT environment variable tells the ZAF make files
where to find the ZAF installation. It must specify the root of the
ZAF installation. An example is given below:

    SET ZAF_ROOT=c:\zaf

---------------------------------------------------------------------
--- Running ZMAKE ---------------------------------------------------
---------------------------------------------------------------------

ZAF provides its own make utility called "zmake.exe". To build a
library or an example with zmake, simply change to the appropriate
directory and type "zmake <target>", where target is "win16",
"win32", or "win32dll". Examples are given below:

    Building the 32-bit Windows libraries:
        cd c:\zaf\source
        zmake win32

    Building the 32-bit dll versions of Hello World examples:
        cd c:\zaf\example\hello
        zmake win32dll

The same utility is also provided in a Windows 32 bit executable
form, "zmake32.exe".  This executable should be used if your
operating system supports long names.  It used as described above.

---------------------------------------------------------------------
--- Hints -----------------------------------------------------------
---------------------------------------------------------------------

By default, ZAF libraries are built using 3D controls. When running 
on systems without native 3D support (Window 3.1, Windows 32s, or 
Window NT versions less than 4.0) 3D controls require an additional
DLL. The required DLL is CTL3DV2.DLL for 16 bit apps, and CTL3D32.DLL
for 32 bit apps. These DLLs are usually supplied with the compiler.

To disable 3D controls, comment out the following line near the top
of the include file "w_env.hpp":

    #define ZAF_MSWINDOWS_3D

---------------------------------------------------------------------
--- Building Your Own Make Files ------------------------------------
---------------------------------------------------------------------

Zinc provides its own make utility called "zmake.exe". This utility
simplifies the building of make projects from the command prompt. In
addition to making it easy to create make files, this strategy
ensures that all projects will use the same options as the ZAF
libraries.

The four files used to build ZAF projects are:

    zmake.mak       User-supplied make file (see example below)
    zaf.mak         The main ZAF make file included by user make file
    opts???.mak     Compiler-specific options shared by ZAF and apps
    zaf???.mak      Compiler-specific rules for building ZAF and apps

The default make file used by zmake is "zmake.mak". It should take
the following form (example only):

    --- zmake.mak ------------------------------
    # Define general macros used for all targets
    SOURCE_FILES = myapp1.cpp myapp2.cpp
    RESOURCE_FILE = bitmaps.rc
    DEBUG = off

    # Define macros used for 16 bit target
    TARGET = myapp16.exe
    TARGET_TYPE = EXE
    PLATFORM = WIN16
    DEFINITION_FILE = myapp.def

    #Generate the rules for the 16 bit target.
    !include <zaf.mak>

    # Define macros used for the 32 bit target
    TARGET = myapp32.exe
    TARGET_TYPE = EXE
    PLATFORM = WIN32
    DEFINITION_FILE = myapp.def

    #Generate the rules for the 32 bit target.
    !include <zaf.mak>
    --------------------------------------------

The following options can be set. They can be defined either by
using make file macros or environment variables. (All environment
variables are seen as macros by the zmake utility):

    ZAF_ROOT        Root directory of the ZAF installation

    PLATFORM        Target platform supported by this make file
    options:        WIN32   32 bit Microsoft Windows
                    WIN16   16 bit Microsoft Windows

    TARGET_TYPE     The type of target to be built
    options:        EXE     Executable statically linked with ZAF
                    EXEDLL  Executable dynamically linked with ZAF
                    LIB     Library
                    LIBDLL  Library that calls functions in a ZAF DLL
                    DLL     Dynamically linked library

    TARGET          Name of the target file

    SOURCE_FILES    Source files needed to build the target

    IMPORT_LIBRARY (DLLs only)
                    Name of import library used with DLL

    ADD_DEPENDENCIES (optional)
                    Additional dependencies, if any

    ADD_COMPILE_OPTS (optional)
		    Additional compiler options, if any

    ADD_LINK_OPTS (optional)
		    Additional linker options, if any

    ADD_OBJECT_FILES (optional)
                    Additional object files, if any

    ADD_LIBRARIES (optional)
                    Additional libraries, if any

    DEFINITION_FILE (optional)
                    Microsoft Windows definition file, if any

    RESOURCE_FILE (optional)
                    Microsoft Windows resource file, if any

    DEBUG (optional)
                    Build with debug information
    options:        off     No debug information (default)
                    on      Debug information included
