

             Readme.txt for Compiling XML4J


Revision: 39 1.4 scripts/buildReadmePub.txt, xml4jsrc, xml4j-jtcsv, xml4j_1_1_16 


XML4J build scripts are Bourne shell script files.

   (On Windows NT, 95 & 98 you can use MKS Toolkit or Cygnus-Win32 toolkit.)


This file describes what other software is required for compiling
and generating XML4J API documentation.


OTHER SOFTWARE REQUIRED
-----------------------

  * Requires JDK 1.1.7, or JDK 1.2, to compile the sources.
    http://www.javasoft.com/products/jdk/1.1/
    http://www.javasoft.com/products/jdk/1.2/

  * Requires (Windows only) Cygnus-Win32 tools (bash, sed, find etc...)
    or MKS Toolkit (sh, sed, find etc.) Cygnus-Win32 toolkit is free
    and is available from:
      http://www.cygnus.com/misc/gnu-win32/
    MKS Toolkit is a commercial software. Evaluation copy is available at
      http://www.mks.com/

  * Requires swing-1.1/swingall.jar, or later, to build samples if you
    use JDK 1.1. Swing is shipped with JFC and is available at:
    http://www.javasoft.com/products/jfc/index.html

  * Requires JDK 1.2 for building JavaDocs.
    http://www.javasoft.com/products/jdk/1.2/



Cygnus-Win32 TOOLKIT SETUP (Windows only)
-----------------------------------------

  This step is required only if you installed Cygnus-Win32 toolkit. If you
  have MKS Toolkit, read the 'MKS TOOLKIT SETUP' section.


  * Rename 'sh.exe' to 'ash.exe' and then copy 'bash.exe' to 'sh.exe'.

  * Ensure that you can execute the scripts when you type the script
    file name with the extension, i.e. you should be able to execute the
    script 'foo.ksh' by typing 'foo.ksh' on the command line.

	To do this, you will have to create an association of the extension
    '.ksh' with 'cygnus\bin\sh.exe' executable. Under NT 4.0, the steps
    for doing this are:
      - c:\> assoc .ksh=kShell
      - c:\> ftype kShell=d:\utils\cygnus\b19\h-i386-cygwin32\bin\sh.exe %1 %*

  * Also ensure that shell is able to find scripts in the current directory.
    For this, your PATH environment variable should explicitly have '.' in it.

  * Cygnus-Win32 Toolkit contains certain executable files which have the same
    name as those shipped with WINDOWS NT/95/98. They each behave differently
    and have different command lines. To have access to both of these
    executables, you may have to rename one of them.

    Usually we have WINDOWS system directories first in the PATH
    before any other directories like d:\utils\cygnus\b19\h-i386-cygwin32\bin.
    We therefore rename the following executables as:
        find.exe        --->    uFind.exe
        sort.exe        --->    uSort.exe
        expand.exe      --->    uExpand.exe

  * Some other quirks with Cygnus-Win32 installation.

    - When you run 'bash.exe' and you get the message
        "WARNING: bash couldn't find /tmp, please create one!"
      This happens because the tools expect the directory '/tmp' to exist. By
      default the '/' directory is 'mount'ed on the system drive. So either
      you create a '/tmp' directory on the system drive or mount the '/'
      directory on to your working drive which has /tmp directory.

      To mount the '/' directory onto another drive, you will have to first
      'unmount' the '/' directory and then mount it again. You can do this
      from within the bash shell as:
		  bash> umount /
          bash> mount e: /
	  where 'bash> ' is the prompt.



MKS TOOLKIT SETUP (Windows only)
--------------------------------

  This is required only if you have MKS Toolkit installed on your system.
  If you are using Cygnus-Win32 toolkit, then read the 'Cygnus-Win32 TOOLKIT
  SETUP' section.


  * Ensure that the shell 'sh.exe' can execute shell scripts '.ksh' files
    without typing in the '.ksh' extension. Example, you should be able to
    execute the shell script 'foo.ksh' by just typing 'foo'.

    Depending on which version of MKS Toolkit you have, the setup steps are
    different. Either make sure that the shell variable PATHEXT is either
      - not set at all, or
      - if defined, then ensure that '.ksh' is also mentioned in the
        definition.
    You can define PATHEXT variable in '$HOME/environ.ksh' and then invoke
    the shell as 'sh -L'.


  * Also ensure that shell is able to find scripts in the current directory.

    For this, either your PATH environment variable should have a trailing
    semi-colon ';', or you have explicitly specified the '.' directory.


  * MKS Toolkit contains certain executable files which have the same
    name as those shipped with WINDOWS NT/95/98. They each behave
    differently and have different command lines. To have access to
    both of these executables, you may have to rename one of them.

    Usually we have WINDOWS system directories first in the PATH
    before any other directories like MKSToolkit/mksnt/bin.
    We therefore rename the following MKSToolkit executables:
        find.exe        --->    uFind.exe
        sort.exe        --->    uSort.exe
        expand.exe      --->    uExpand.exe



ENVIRONMENT VARIABLES
---------------------

The exact commands to setup environment variables differ for each platform.
Particularly:
    - path separator '\' under NT vs. '/' under Unix.
    - path delimiter ';' under NT vs. ':' under Unix.

Whats described below is for Windows NT. It should not be difficult to do
the similar thing under Unix or any other OS.


Make sure PATH environment includes the directories
    'e:/xml4j/scripts', 'e:/jdk1.2/bin', and '.'
eg:
    PATH=".;e:/xml4j/scripts;$PATH;e:/jdk1.2/bin"

IMPORTANT        This following step is needed.
---------

    Other variables needed are defined in the file 'setupEnvVars.ksh'.
    PLEASE CUSTOMIZE THE DEFINITIONS FOR YOUR INSTALLATION.

Under Windows NT/95, its convenient to set the PATH variable before invoking
the shell 'sh'.



BUILDING XML4J
--------------

Invoke the shell ('bash' or 'sh'). Commands are issued in the shell.

To Compile all .java sources
    > compileAllSources.ksh [all]
  or
    > cd $SRCDIR; makeit.ksh [all]

To Generate the API documentation using JavaDoc.
    > makeApiDocs.ksh


CLEANING UP
-----------

To delete all the .class files and directory.
    > cleanupClassFiles.ksh

To delete only the .class files
    > compileAllSources.ksh veryclean
  or
    > cd $SRCDIR; makeit.ksh veryclean

To delete all the generated API documentation.
    > cleanupApiDocs.ksh

