
                                        
                         ToolBuster 1.2 - Release Notes

Congruent Corporation
110 Greene Street
New York City, NY 10012
(212) 431 - 5100
(212) 219 - 1532 (f)


                 For ToolBuster support inquiries please use our
                             support e-mail address:
                              support@congruent.com
                                        
     Make sure to include:
     
     1.   Your ToolBuster Serial Number (A number prefixed by TB imprinted  on the
       surface of  your CD or on the disk labelled intel1).
     2.   Your name, address, e-mail address, phone and fax numbers.
     3.   For bug reports, please send us a SHORT sample that will recreate the bug
       on our machines.



Setting Up The ToolBuster Environment:

1.     /usr/local/congruent/setenv.bat  contains  a  sample  script  to  set  up
  environment  variables  for  ToolBuster. Call  setenv  with  the  drive  where
  ToolBuster is installed. For example,  use setenv c: if ToolBuster was installed
  on  drive c:. Setenv Uses your system defaults to define environment variables
  accessed by gnu programs. ToolBuster must be installed on an NTFS volume since
  it uses filenames longer than the 8.3 width allowed by the FAT filesystem.
2.   If your TEMP or HOMEPATH environment variables point to FAT directories you
  must edit setenv.bat, replacing any use of these variables with an appropriate
  NTFS directory name.
3.   You can invoke setenv automatically by  creating a ToolBuster icon with the
  command line:
   "CMD.EXE /K c:\usr\local\congruent\setenv c:"
    using  the  program manager (where c: is the drive ToolBuster  is  installed
  on).


Cutomizing The ToolBuster Environment:

1.    Path Substitution: Many gnu programs refer to  "hardcoded" Unix path names
  that  don't normally exist under windows, or exist under different names.  The
  ToolBuster environment variable TB_PATHSUB defines a mapping from UNIX pathnames
  into user defined NTFS or FAT paths. TB_PATHSUB defines a mapping from hardcoded
  UNIX  pathnames into convenient places on your computer's filesystem, allowing
  you to place your directories on arbitrary drives or in more suitable locations.
  For example, many gnu programs read and write temporary files from the directory
  /usr/temp.   To   map   this  into  c:\temp  use  the  shell   command,   "set
  TB_PATHSUB=/usr/temp,c:\temp".
2.    TB_PATHSUB syntax: The TB_PATHSUB variable contains a list of  Unix  style
  pathnames paired with their actual NT pathnames delimited by semicolons. There
  must  be  a comma between the Unix path and the NT path and no spaces  between
  them. Also, to resolve possible ambiguities both the Unix and the NT pathnames
  must  be  absolute, the Unix path starting with a `/' and the NT path starting
  with `d:\' where d is a drive letter defined on your system. Substitutions using
  the  TB_PATHSUB list are done by length, replacing the longest  prefix of  the
  given Unix pathname with the NT prefix of the matching pair.  Hence trying  to
  access the path /usr/tmp with ,
       TB_PATHSUB=/usr,b:\moo;/usr/tmp,a:\foo
  results in two possible matches:
       "b:\moo\tmp"  & "a:\foo."
  However,  since  the  latter matches the original name  more  completely  (ie.
  it's a longer match) a:\foo is the directory accessed.
3.    Environment  Variables:   Generally,  pathnames  specified  to  ToolBuster
  programs  via  environment variables (like HOME or TMP) should be  given  with
  forward slashes (`/') , in Unix style.
4.   Libraries: All ToolBuster programs use the dynamic link library
  win32gnu.dll. To use any ToolBuster program, win32gnu.dll MUST be in a directory
  in your path.


Useful Tips and Caveats
1.   Microsoft includes a version of rm that doesn't actually delete your files,
  instead  it stores them in a "deleted" directory. You may want to rename  this
  program before using ToolBuster.
2.    Make  sure  your temp directories don't reside on FAT file  systems.  Unix
  programs generate temporary file names which are illegal under FAT. They  look
  for temp directories defined by the environment variables TMP and TMPDIR as well
  as  in the absolute paths /tmp, /usr/tmp. Setenv.bat contains both environment
  variable definitions and path substitutions (for the hard coded paths) defining
  your temp directory all of which must not point to a FAT filesystem.
3.    Make  sure  your  HOME environment variable (also defined  in  setenv.bat)
  points to an NTFS directory, for similar reasons.
4.   In this release, programs that manipulate object code (gcc,gas,binutils),
  only support i386 object format (but they can be executed on any ToolBuster
  platform).
5.    The following programs REQUIRE an explicit mapping of a Unix directory  to
  an  NT  directory name. The setenv.bat script should initialize the TB_PATHSUB
  environment variable (described above) to make these work  correctly with  the
  default toolbuster setup:

  Program Unix Directory          Files
  -----   --------------         ---------
  bison   /usr/local/lib         bison.sim
                                 ple
                                 bison.hai
                                 ry
  flex   /usr/local/lib          flex.skel
  gcc    /usr/local/lib/gcc-     cpp.exe
         lib/                    cc1.exe
         winnt386/2_4_5          specs
                                 ld.exe

ToolBuster Programs:

*    binutils-2.2.1: Display information about object code files.1

     Program        Description
     -------        -----------	
     nm.exe         Names defined by an
                    object file
     objdump.exe    Dumps various
                    components of object
                    file
     size.exe       Display size of object
                    file's sections

*    bison-1.21: A parser generator, compatible with yacc.

     Program        Description
     -------        -----------	
     bison.exe      Parser generator.

     Auxiliary      Description
     Files
     bison.simple   Parser templates.
     bison.hairy    

     Note:  bison.simple  &  bison.hairy  must be in the  directory  aliased  to
     usr/local/lib by TB_PATHSUB.

*    compress: File compression/decompression tools.

     Program           Description
     -------        -----------	
     compress.exe      compresses file.
     uncompress.exe    uncompresses file.
     zcat.exe          uncompress file to
                       stdout.

*    cvs-1.3: concurrent version system.

     Program        Description
     -------        -----------	
     cvs.exe        Concurrent version
                    system
     mkmodules.exe  Rebuild module
                    database.

*    diff-2.3:

     Program        Description
     -------        -----------	
     diff.exe       Compare two text files.
     cmp.exe        Compare two binary
                    files.

*    elvis-1.7:

     Program        Description
     -------        -----------	
     elvis.exe      Clone of vi editor.

*    emacs-19.16:

     Program        Description
     -------        -----------	
     ntemacs.exe    A general purpose
                    editor, programmable in
                    lisp

     Auxiliary      Description
     Directories
     -----------    -----------
     (in
     /usr/local/emacs)

     lisp           Emacs elisp programs.
     etc            Extra programs and self
                    documenting
                    information.
     lock           Locking directory.
     info           Info files for various
                    programs.

     Auxiliary      Description
     Programs
     ---------      -----------------------
     tcp.exe        Connects to NNTP server
                    for reading news
     ls.exe         Called by dired.

     Note: To conserve space, nt emacs lisp files are distributed uncompiled. The
     first time you use ntemacs it will compile all its lisp files, taking a  few
     minutes for the full build. After building, exit and restart ntemacs to load
     in  the  compiled files (regular startup should take less than 10  seconds).
     The build commands are in /usr/local/emacs/lisp/site-start.el.

     Setting Up Ntemacs:
       1.   Path substitution must define NT equivalents for the following Unix Paths:
       
       
     Unix Path             Maps to NT Path
     ----------            ----------------
     /usr/local/emacs      The base emacs
                           directory (containing
                           the /lisp, /etc &
                           /lock directories).
          
     /bin/cmd.exe          Absolute path of
                           cmd.exe on your
                           system.
          
       2.   The environment variable HOME should be defined as your home directory . By
          default your home directory is set to, %HOMEDRIVE%%HOMEPATH% in setenv.bat. If
          you define the environment variable HOME, then ntemacs uses its value as your
          home directory. If your default home directory is on a FAT filesystem, you
          should override it by setting  HOME appropriately.
       3.   If you have TCP/IP support running and are on a network with a Unix NNTP
          host include the following lines in your ~/.emacs file:

       ;; The network name of the NNTP server.
       (setq gnus-nntp-server  "congrunt")
       ;;  Your local domain
       (setq gnus-local-domain "congruent.com")
       ;; Your organization's name
       (setq gnus-local-organization "Congruent Corporation")

     Using Ntemacs:
       1.   Adding Personal elisp code: Use the file ~/.emacs to add your own personal
          elisp definitions.
       2.   Pathname syntax: NTemacs interprets `~ `at the start of a file name as your
          "home directory" (defined by HOME). When giving filenames at the emacs prompt,
          follow the Unix convention of using '/' as a path delimiter.
       3.   Adding Site Specific elisp code: Currently, the file
          /usr/local/emacs/lisp/site-start.el contains NT specific startup code. You can
	  customize this further for your site by adding to the end of the file. After
	  making changes byte-compile the file again.
       4.   Changing fonts: Ntemacs uses the system's default fixed width font. To
	start ntemacs with another font use the command option -
	ntfont{font_name,font_height}. For example,
       
         > ntemacs -ntfont{Courier,20}
       
         starts  ntemacs  with the courier font and characters 20  pixels  high.
          You  can  specify any font your system defines, but only  fixed  width
          fonts will refresh the display correctly.
       
     Caveats:
       1.   Inferior command shells started by 'M-x shell' should be terminated by
          typing 'exit' before killing the buffer, otherwise it may be necessary to
          explicitly kill the CMD job using the process viewer. Also, looping subjobs
          created by 'M-x compile','M-x grep', etc. should be killed explicitly with the
          process viewer.
       
       2.   Mouses, Menus and Frames are currently not supported.

*    fgrep-1.1: Search files for regular expression match.

     Program        Description
     -------        -----------	
     fgrep.exe      Grep for pattern in
                    files.

*    fileutils-3.5: File utilities

     Program        Description
     -------        -----------	
     chmod.exe      Change r/w/x
                    permissions.
     cp.exe         Copy files.
     dd.exe         Convert format.
     du.exe         Disk Usage.
     ls.exe,        List files in directory
     dir.exe,
     vdir.exe
     mkdir.exe      Make a directory
     rmdir.exe      Remove a directory
     mv.exe         Move file.
     rm.exe         Remove files.
     rmdir.exe      Remove directory.
     touch.exe      Touch files.
     df.exe         Filesystem usage.

     Caveats:
       1.    NTFS  allows  only r or r/w permissions on a file. User/Group/Other
          permissions are treated equivalently.
       2.   The FAT filesystem has restrictions on filename length and composition.
          Hence, you cannot aribitrarily copy files and directories from NTFS to FAT
       3.    The -f option for rm means ignore missing files, not changing write
          ownership

*    find-3.8:  Search for files and map a command over them.

     Program        Description
     -------        -----------	
     find.exe       Find files by name or
                    characteristic
     xargs.exe      Construct and argument
                    list and execute a
                    command

     Caveats:
          1.   With no command specified, xargs uses "/bin/echo." Either echo must be
            accessible along your path (modulo renaming) or you must specify  an explicit
            command accessible along your path. Also, be careful when using MS echo and the
            single '/' which MS interprets as an option delimiter, but UNIX commands use as
            the filesystem root.

*    flex-2.3.8: Generates lexical analyzers

     Program        Description
     -------        -----------	
     flex.exe       A lexical analyzer
                    generator
     flexlib.lib    Library with default
                    lexer.
     flex.skel      Template for analyzer

*    gas-2.0: gnu assembler (see gcc-2.4.5)

*    gawk-2.15: gnu awk

     Program        Description
     -------        -----------	
     gawk.exe       C-like scripting
                    language

*    gcc-2.4.5: gnu c-compiler.

     Program        Description
     -------        -----------	
     gcc.exe        Top level program that
                    invokes cpp, cc1, as &
                    ld iwith the
                    appropriate args.
                    

     Environment    Description
     Variables
     ------------   -----------
     TMPDIR         Directory for temporary
                    files.
     LIB            Directory path to
                    search for libraries.
     INCLUDE        Directory path to look
                    for include files

     Only  gcc  targeted to i386 has been implemented, if you are using  gcc  on
     another  architecture, you must give gcc the flag -bwinnti386 in  order  to
     cross compile to i386.
     
     Congruent Stdcall library for ToolBuster i386:
     
     Microsoft  uses a number of different calling conventions on i386 machines,
     including  one  named  Stdcall for calling library  routines.  Gcc  doesn't
     support  i386 Stdcall, hence you cannot make win32 system calls  from  a  C
     program  compiled with gcc. However, we include a set of  Stdcall libraries
     that  call  the  Microsoft  routines and can be called  directly  from  gcc
     compiled  programs. The name of the Stdcall library files are derived  from
     the  original  MS  library file names with the suffix "32"  removed  and  a
     underscore  appended to the end. Look in the Stdcall library directory  for
     the  exact  names. On mips & alpha, there are a uniform calling conventions
     and  no  need  for separate libraries on these machines. Note, the  Stdcall
     Libraries  are  a  seperately  licensed product  from  gcc  and  cannot  be
     distributed.
     
     Caveats:
     a)   Due to an incompatibility between gcc compilation of alloca and Windows NT
          manages  stack space, the "built-in" alloca provided by gcc will  fail
          unexpectedly when stack space exceeds the amount committed upon startup.
          Currently, there are two ways around this problem:
          i)   Instruct the linker, using the -stack option, to build the executable with
               a large amount of committed stack space. The option -stack:<reserve>[,commit]
               tells the linker to reserve <reserve> bytes for the size of the stack's virtual
               address splace and  commit <commit> physical bytes for execution on a by need
               basis as the stack grows. For example, saying:

                    link32: ... -stack:0x40000,0x40000 ...

               Tells the linker to both reserve and commit 0.25Mb for the stack. Without
               the -stack option only 4k are committed.

          ii)  Use the "portable" alloca provided with gcc. The portable alloca uses
               malloc and hence is less efficient than using the built-in alloca.

     b)   Similarly, there is a problem when calling procedures that use more than 4k
          of local variable space if the variables get touched in the wrong order. There's
          no simple solution for this at the moment but using  (a)  should fix the problem
          in the short term.

     c)   Debugging Support:  Currently gcc does not generate NT compatible debugging
          information, hence source line information is not available. However, one can
          link using symbolic names and set breakpoints in the assembly code.

*    grep-1.6: Search for a pattern.

     Program        Description
     -------        -----------	
     grep.exe       search for a pattern
     egrep.exe      search for a regular
                    expression

*    gzip-1.2.3: Gnu compression tools.

     Program        Description
     -------        -----------	
     gzip.exe       Gnu compress file
     gunzip.exe     Gnu uncompress file.
     gzcat.exe      Gnu uncompress to
                    stdout.

*    indent-1.7: C program formatter.

     Program        Description
     -------        -----------	
     indent.exe     C program formatter

*    less-177: Gnu version of more.

     Program        Description
     -------        -----------	
     less.exe       Paging program.

*    m4-1.0.3: Sophisticated macro-processor.

     Program        Description
     -------        -----------	
     m4.exe         Macro processor.

*    make-3.67: Build programs.

     Program        Description
     -------        -----------	
     make.exe       Builds programs.

     Additional Features:
     1.   ToolBuster make can execute multiple jobs in parallel. To execute (at most)
       n jobs concurrently use the -j flag followed by n. Without the -j option, make
       executes one job at a time.
     2.   ToolBuster make supports the Windows NT filename extensions (.obj, .asm,
       .lib, .exe) in its implicit and user-defined rules.
     3.   By default, ToolBuster make will look for a ".obj" suffixed file if it
       can't find a ".o" suffixed one, and vice versa. Similarly, ToolBuster make
       provides equivalences for other suffixes:

     Unix suffix    Equivalent NT suffix
     -----------    --------------------
     .o             .obj
     .a             .lib
     (empty         .exe
     suffix)

     The following environment variables control equivalencing:

     Environment         Description
     Variable
     ------------------  --------------------
     TB_RETAIN_SUFFIX=1  Disables
                         equivalencing

     TB_SHOW_TRANSLATI   Output a message to
     ON=1                stderr for every
                         translation

*    man-1.0: Display manual pages.

     Program               Description
     -------               -----------	
     man.exe               Display manual
                           pages
     /usr/local/lib/       Text file
     man/manpath.config    pointing to
                           manpage
                           directories

     Put   additional   manpages  in  MANDATORY_MANPATH/cat1   ..   /cat9   (see
     manpath.config). Troff format is currently not supported.

*    patch-2.1: Patch files together from diffs.

     Program        Description
     -------        -----------	
     patch.exe      Path together diffs

*    perl-4.036:

     Program        Description
     -------        -----------	
     perl.exe       perl language
                    interpreter

     Directory      Description
     ---------      -----------
     lib/perl       Library of standard
                    perl functions

     Caveats:
     a)   Parts of perl that are very Unix dependent are still shaky:
          i)   Some socket support is available, full support will be avaiable with NT's
               next release.
          ii)  Spawn, rather than fork is supported to start subprocesses.

*    rcs-5.6.0.1: Revision control system.

     Program        Description
     -------        -----------	
     ci.exe         Check in a file.
     co.exe         Check out a file.
     ident.exe      
     merge.exe      
     rcs.exe        
     rcsdiff.exe    
     rcsmerge.exe   
     rlog.exe       

*    sed-2.02: A stream editor

     Program        Description
     -------        -----------	
     sed.exe        Executes sed scripts

*    shellutils-1.8:  Shell utilities.

     Program        Description
     -------        -----------	
     basename.exe   Dissect a pathname.
     dirname.exe
     date.exe       Current date.
     echo.exe       Echo its arguments
     id.exe         Print user/group ids
     pathchk.exe    Check files for
                    properties
     printf.exe     Formatted output.
     tee.exe        Output to a file and
                    stdout.
     test.exe       Test conditions.
     yes.exe        Repeatedly true.
     env.exe        Altre the environment
                    and execute.
     sleep.exe      Suspend execution
     uname.exe      Print             system
                    information

*    tar-1.11.2: File archiving.

     Program        Description
     -------        -----------	
     tar.exe        Archive files.

     Writing to Tapes: : ToolBuster tar supports writing to tape drives.
     1.   /dev/rst8 and /devnrst8 are standard Unix names for tape devices:
     2.   /dev/rst8  accesses the tape and rewinds when done.
     3.   /dev/nrst8 accesses the tape with no concluding rewind.
     4.   Use the -f option with argument /dev/rst8 or /dev/nrst8 to tell tar to read
       or write from the tape.

     Caveats:
       1.   For reasons of unix compatibility we map the names:
       
         rst8,nrst8 into tape0
         rst9,nrst9 into tape1
         ...
         rst(k),nrst(k) into tape(k mod 8).

*    textutils: Text utilities.

     Program        Description
     -------        -----------	
     cat.exe        Catenate files
     cksum.exe,     Crc check.
     sum.exe
     comm.exe       Display common lines
     csplit.exe,    split a file
     split.exe
     expand.exe,    (un)Expand tabs to
     unexpand.exe   spaces.
     fold.exe       Fold lines.
     head.exe       First lines of a file.
     join.exe       Relational db operator.
     nl.exe         Line number filter.
     od.exe         Octal dump
     paste.exe      Join corresponding
                    lines
     pr.exe         Prepare for print
     sort.exe       Sort.
     tac.exe        Reverse records.
     tail.exe       Last lines of a file.
     tr.exe         Translate characters.
     uniq.exe       Unique.
     wc.exe         Word count.

       
_______________________________
1Toolbuster currently supports only i386 object code format.
