

                Notes for Maintenance Software Developers

1.  Compiling native code on DOS platforms
------------------------------------------

    When the baseline is distributed, a pre-compiled version of several
    files are provided:
      $NMROOT/os/dos/dlls/nmsf.exe
      $NMROOT/os/dos/dlls/Convert_win.dll
      $NMROOT/os/dos/dlls/DataOp_win.dll
      $NMROOT/os/dos/dlls/NTerminal_win.dll

    By default, the software will use the pre-compiled files shipped as part
    of the baseline for DOS platforms.  If you wish to override and compile
    these files on your local machine, you can obtain a gcc compiler and
    compile the native code on your own machine.  


  a. Installing a gcc compiler on your local machine

    The following instructions contain information for installing/using one 
    of the following compilers, both of which are free:
          a1.  Cygnus Solutions (used by Gnu)
          a2.  EGCS (Experimental Gnu) [**** Recommended ]

  a1. Installing Cygnus Solutions C/C++ compiler

    You can obtain the gcc compiler provided by Cygnus Solutions at
    www.cygwin.com.  The cygwin software is free, covered by the GNU 
    software license and has a "FAQ" link that is quite useful for new users.

    NOTE:  The cygwin software provides Unix commands for a DOS 
    machine, as well as other tools (gnu compiler, CVS, etc) -- which
    means that your cygwin download could be quite large if you choose 
    all the tools. The minimum components required to compile the baseline 
    using this gcc compiler are:

       ash
       bash
       binutils
       cygwin
       fileutils
       gcc
       make
       mingw
       w32api

    The remainder of these instructions assume you have installed the
    cygwin product at   c:\cygwin.

    Update your PATH environment variable to include c:\cygwin\bin
    so that the compiler/linker can find all its required files.

    After you have installed your gcc compiler, verify that you can invoke 
    it from the command line:

        user> gcc -v
            (this should report the compiler version to you)

    www.cygwin.com.  The compile flags and include
    files in $NMROOT/os/dos/nmbld.bat are set for this compiler.
    If you use this compiler, be sure to put c:\cygwin\bin in your PATH
    environment variable so that the compiler/linker can find all its
    required files.

  a2. Installing the EGCS C/C++ compiler

    You can obtain the gcc compiler provided by EGCS from the
    NeXtMidas documentation baseline.  EGCS is free, but GNU appears 
    to recommend that Windows platforms use Cygwin.

    The remainder of these instructions assume you have installed the
    EGCS compiler at   c:\egcs.

    After you have installed your gcc compiler, verify that you can invoke 
    it from the command line:

        user> c:\egcs\bin\gcc -v
            (this should report the compiler version to you)


  b. Update NeXtMidas configuration to use the gcc compiler

     Edit %NMROOT%/os/dos/nmstart.bat and change:

       set NM_CC=none
       set NM_CC_INC=none

     to (for Cygwin Compiler:)
       set NM_CC=c:\cygwin\bin\gcc
       set NM_CC_INC=c:\cygwin\usr\include\mingw
               (add the cygwin\bin directory to the existing PATH, like: )
       set PATH=%NM_OS%;%PATH%;c:\cygwin\bin

     to (for ECGS Compiler:)
       set NM_CC=c:\egcs\bin\gcc
       set NM_CC_INC=c:\egcs\i386-mingw32\include

     By specifying a gcc compiler in NM_CC and the gcc compiler include
     directory in NM_CC_INC, the build software will create all
     the native code locally.  If you leave NM_CC=none, the build software will
     use the pre-compiled executables and libraries supplied by the baseline.
  
     To compile native files from within NeXtMidas edit
     %NMROOT%/nxm/sys/cfg/build.props and change the "native.win.compiler"
     from "none" to the compiler you wish to use.  

       native.win.compiler = c:\\cygwin\\bin\\gcc.exe

     Any additional include paths can be added to "native.win.cflags".  To
     ensure the compiler also looks in "c:\egcs\i386-mingw32\include" then
     add "-Ic:\\egcs\\i386-mingw32\\include" so the line looks like

       native.win.cflags = -Ic:\\egcs\\i386-mingw32\\include

  c. Re-run "nmstart" so that the debug information is defined
     nmstart   (or %nmstart% on DOS)

  d. To compile, you can either do the usual
        nm make all
     or elect to just compile the native code by
        nm make native


2.  Using a Debugger on the code
---------------------------------


  a. Compiling
     To compile code for use with a code debugger, the "-g" option needs to
     be passed to the compiler so that all debugging information is generated.
     The debug flag will be passed to both the Java and C compiler (if the
     NM_CC compiler is defined).

     (DOS) Edit $NMROOT/os/dos/nmstart.bat 
           change from:  NM_DEBUG=
           to:           NM_DEBUG=-g

     (UNIX) Edit $NMROOT/os/unix/nmstart
           change from:  setenv NM_DEBUG ""
           to:           setenv NM_DEBUG -g


  b. Running the code with a commerical debug tool (i.e., JBuilder)

    Edit $NMROOT/nxm/sys/inc/Installation.java
           change from:  DEBUGGER = false
           to:           DEBUGGER = true

    and recompile the code.  This change will ensure that the debugger
    will work correctly even though the nmstart script was not executed.
    When you want to return to running the code from the command line,
    just reset the DEBUGGER variable to "false" and recompile.

    Why the 'DEBUGGER' flag is needed:
    ----------------------------------
    This flag provides debug settings that allow a commercial debugger
    (such as JBuilder) to run the NeXtMidas code since the java debugger
    has no access to the setup performed by the nmstart shell scripts
    (nmstart, nmstart.bat) run by the user from the command line.

    1.  The NeXtMidas DOS/UNIX nmstart shell scripts set up the path
        and runs any local nmstartup.mm in the user's path.  When the debugger
        is invoked, these Unix/Dos scripts have not been run and therefore
        the debugger cannot "see" any option trees that the user might
        have specified in his local nmstartup.mm.

    2.  The NeXtMidas code utilizes native C routines to print text
        to a NeXtMidas terminal.  The C code buffers up any terminal text
        and it will not display this text in the java debugger until the
        program has terminated completely or until the output buffer is
        full enough to be flushed to the screen.  This flag
        allows the native C print routines to be bypassed when the code is
        running inside a debugger, thereby showing terminal print statements
        (such as from the "say" intrinsic) immediately to the screen.


