
Building mTCP
Michael Brutman, May 2011



Development environment

  I started the mTCP project using Borland's Turbo C++ for DOS version 3.0.
  It worked well enough for a few years but I decided to look for a
  compiler that produced better code.  (The code generation of that
  compiler is very simplistic.)  I settled on Open Watcom 1.8 and ported
  all of the code to it.

  Initially I maintained the code so that it would build in both
  environments.  I have since abandoned that strategy and have moved
  exclusively to Open Watcom.  It would be possible to make things
  compile and run under Turbo C++ but that requires a lot of extra work,
  both for maintaining the code and doing proper testing.  The Turbo C++
  runtime is missing some useful functions like strncmp, which help to
  avoid buffer overflow conditions.

  For now plan on using Open Watcom 1.8 or 1.9 (the current version).
  Ports to other compilers are possible but it might make a mess of the
  code with #defines.

  Open Watcom can be found at: http://www.openwatcom.org/index.php/Main_Page

  My normal development environment is a Windows XP machine with Open
  Watcom 1.9.  I use the native Win32 version of Open Watcom and have it
  cross compile for 16 bit DOS.



Directory structure

  These are the directories where code is located.

    TCPINC   Includes for the TCP/IP library
    TCPLIB   Code for the TCP/IP library
    INCLUDE  Includes that might be useful across multiple applications
    UTILS    Utilities used during the build process.  (Patch.cpp)
    APPS     Top level directory for applications

  I generally use upper case letters and adhere to classic DOS 8.3
  filenames for the code in case we need to compile under a more
  limited environment, like the original compilers that were used for
  the project.



Compiling programs

  Each application lives in a separate directory under APPS.  Each
  application has a MAKEFILE in that directory.  Compiling should be
  as simple as executing "wmake" within a particular application
  directory.

  There are generally three targets in a MAKEFILE:

    "clean" erases the executables and object files

    "all" does a clean and builds the application

    "patch" calls the patch utility to fix the Watcom runtime
      for two irritants.  (See the next section for a detailed
      explanation.)  This step is optional.
  


The "Patch" utility

  At the moment the UTILS directory has one program in it called PATCH.
  PATCH modifies the program binaries after they have been built,
  fixing two small problems I perceive in the Open Watcom runtime:

    - The runtime looks for a copyright date in the BIOS of your
      machine and if it does not find one in a the correct format
      it assumes you are on some strange NEC PC98 compatible machine.
      This is disasterous when the runtime makes BIOS calls for keyboard
      handling and generating sound.  Affected machines include the old
      Epson Equity series and early Compaq machines.

    - The runtime expands the near heap to maximum size in large
      data model programs when it first starts up.  This makes the
      programs look like they are consuming 64KB more memory than
      they actually are.

  I "fixed" the problems by patching the code in the runtime.  The correct
  way to fix these problems would be to fix Open Watcom but I have not
  tackled that yet.  (The fix involves modifying the routines so that
  they return immediately instead of running.)

  The MAKEFILE for PATCH will build it so that it runs under your current
  host operating system; it can run under 16 bit DOS but you don't need
  to be in 16 bit DOS to patch the programs.  It is going to read the map
  file generated by the linker, look for the routines to patch, and patch
  them if they are present.

  You don't need to patch the executables - that is an optional step.
  But if you don't you may have problems with older machines that do not
  have a BIOS copyright date in them at the right spot, and your memory
  consumption will look artificially high.



Compiler options

  Within each MAKEFILE there is a set of compiler options that are
  specific to each program.  There is also a set of comments that
  describe the options kind of like a "quick" reference; the actual
  Open Watcom docs should be consulted for detailed explanations.

  Options generally fall into three classes:

    - Error checking
    - Code generation for performance
    - Calling conventions and memory model configuration

  Programs that are performance sensitive will tend to use compiler
  options that favor fast code generation at the expense of program
  size.  Where performance is not terribly important the compiler
  be directed to produce more compact code.

  Stack bounds checking is normally turned off.  This is for performance
  and code size reasons.  You can turn it on during development, but
  be sensitive to the number of objects you are putting on the stack,
  your call depth, and the stack size.  (See DOSTEST.TXT for a
  discussion on stack space usage.)

