This directory includes files required to build TeX and related
programs with the DJGPP port of GNU tools for MS-DOS and MS-Windows.
DJGPP produces 32-bit protected-mode programs which run on all
Microsoft platforms.  On plain MS-DOS they need a DPMI server (a free
server is available as v2misc/csdpmiNb.zip that can be downloaded from
DJGPP archives on SimTel.NET mirrors).  MS-Windows have DPMI services
built into them.  When run on Windows 9X, the DJGPP-compiled programs
support long file names.


    Building the package from sources
    ---------------------------------

    - The following tools are REQUIRED to build and install Web2c
      programs (the parentheses list filenames of binary distributions
      you can download from DJGPP archives if you don't have a
      particular package):

        Bash (bsh1147b.zip)
	Fileutils (fil316b.zip)
	Textutils (txt122b.zip)
	Grep (grep21b.zip)
	Patch (pat25b.zip)
	Sh-utils (shl112b.zip)
	Sed (sed118b.zip)
	Diffutils (dif2721b.zip)
	Findutils (find41b.zip)
	Ed (ed-02b.zip)
	Gawk (gwk303b.zip)
	Bison (bsn125b.zip)
	Flex (flx254b.zip)
	cpio (cpio242b.zip; only for installing the VF fonts, see below)

      All of these are available from the v2gnu directory on the usual
      DJGPP sites, e.g. ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2gnu/.

      The above tools are IN ADDITION to the basic DJGPP development
      environment that is required to compile and link C programs.
      Consult the file v2/readme.1st and the DJGPP FAQ list in
      v2/faqNNNb.zip, for details about the basic package.

    - Unzip the downloaded Web2c and Texmflib distributions from the
      root of your DJGPP installation tree.  If you are doing this on
      Windows 9x, use an unzip program that supports long filenames.

      This will create the top directory and unpack the sources
      into the relevant subdirectories.  It will also create the
      `share/texmf' directory and unpack the contents of Texmflib
      library there.

    - At this point, I suggest you to read the file
      `kpathsea/INSTALL.txt'.  It includes a detailed yet very
      readable description of the various options available to you at
      build and installation time.

    - Make sure your TMPDIR environment variable points to a drive
      with enough free space.  Many DJGPP installations set this
      variable to a RAM disk for performance reasons.  Since RAM disks
      tend to be small (a few Megabytes), a complex shell script may
      fill it with temporary files, typically from pipes and `command`
      expansions, after which point programs run by that shell will
      start to fail.  The TeX build process runs some very long and
      complicated shell scripts which require around 4MB of free space
      on TMPDIR filesystem (it failed for me when I had only 2.5MB).
      If you cannot enlarge your RAM disk, point TMPDIR to a real disk
      (the effect on the overall build time is insignificant, since
      GCC will have hard time compiling some of the larger programs
      with -O2 switch).  TMPDIR is usually set on the DJGPP.ENV file,
      but you can override it by setting TMPDIR from the DOS prompt.

    - The default 256KB stack size limit of DJGPP programs is too
      small for compiling some of the TeX programs.  Make sure your
      cc1.exe program has at least 768KB of stack.  Here's how:

	      stubedit cc1.exe minstack=768k

      (`stubedit' is part of the basic DJGPP development
      environment).

    - To configure the package for DJGPP, run the `config.bat' batch
      file in the djgpp subdirectory.  This sets some environment
      variables and then invokes Bash to run the configuration script
      with necessary arguments.  (You can edit the batch file if you
      want to run the script with different arguments.)  The command
      is this:

		djgpp\config

    - It is possible to configure and build Web2c from a directory
      other than where the sources reside (useful when you cannot
      write to that directory, like if it's on a CD-ROM).  In that
      case, you need to invoke `config.bat' with a single argument
      which is the full pathname of the source directory.  For
      example:

		f:\gnu\web2c-7.2\djgpp\config f:/gnu/web2c-7.2

      Note that you MUST use Unix-style forward slashes in the
      argument you pass to `config.bat', or else it will fail.

    - The configure script will run for a while and recursively
      configure the programs in subdirectories.

    - After running `config', just say "make".

      Building the full Web2c package takes a while (about 1.5 hours
      on a 486/DX2-66, 20 minutes on a Pentium-166), so you might go
      for a cup of coffee while it compiles.

    - To build the emulation programs in the `contrib' directory,
      chdir into that directory and say "make".  Compiling `regex.c'
      triggers several warning messages about variables that ``might
      be used uninitialized''; you can safely disregard these
      warnings.

    - If you have changed some of the programs in the package, it is a
      good idea to run tests on them.  The Makefile in the web2c
      directory has a large number of xxx-check targets, where xxx is
      the name of a program; you can run these one by one by going
      into web2c and saying like so:

		 make gftopk-check

      You can also run all of them together by saying "make check" in
      the top-level directory.

      Some of the tests appear to fail (`diff' prints some actual
      differences between the test results and the reference files
      that come with the package.  In most cases, this is normal
      behavior (the programs were changed since the canonical results
      were computed); the file `web2c/tests/check.log' includes the
      output you should see for each test.  If your results coincide
      with `check.log' (except for the version of the package that the
      programs print), you are doing fine.

    - To install the programs, say "make install" in the top
      directory.  This will create missing directories and copy the
      programs and auxiliary files to their places.  The programs
      inside `contrib' need to be installed manually (typically, into
      the same directory where the executable programs go).


    Troubleshooting
    ---------------

    I do NOT intend here to replace the various chapters in the docs
    which explain how to solve problems and report bugs.  Please read
    the docs whenever you see any seemingly abnormal behavior.  What's
    below is intended to mention a few DOS- and DJGPP-specific
    problems that you might see, and how to get around them.

    First, a word of warning.  Web2c is a tremendously large and
    complex package, with dozens of different programs, some of them
    with many different options.  While porting it, I've made a good-
    faith effort to test everything I could, including using it to
    generate printed versions of various TeX and Texinfo documents.
    However, some bugs might still be there.  Please treat this port
    accordingly and report possible bugs to the DJGPP news group
    (comp.os.msdos.djgpp) first.

    One possible problem you could see is due to insufficient number
    of available file handles.  `Dvilj' is particularly prone to this
    problem.  If you ever see an error message to the effect that a
    program has no more handles, edit your CONFIG.SYS and enlarge the
    FILES= setting there.  (Don't forget to reboot so the new setting
    is in effect.)

    Another related problem manifests itself by an error message like
    so:

        c:\djgpp\bin/mf.exe: cannot open

    This usually happens when a DVI driver finds a missing font and
    invokes the MetaFont program to generate them on the fly.  Due to
    peculiarities of file handles inheritance from parent to child
    processes, the child process can sometimes fail to start because
    the stub cannot open the .exe file.  I think I've fixed these
    problems, so you shouldn't see such messages, but if you do,
    please report the details.

    If the font-creation fails, a file named `missfont.log' is created
    in the current directory, with the commands you should issue to
    make these fonts.  Many times, invoking that file as a batch file
    will create the missing fonts, so you could then invoke the DVI
    driver again and it will work.


    Happy TeXing!

				Eli Zaretskii <eliz@is.elta.co.il>
