windows-xp/Source/XPSP1/NT/sdktools/masm/readme

						MASM 5.NT Version Information

5.NT.01, 12/5/90 - Jeff Spencer. Initial release, same functionality as the
		  released product Masm 5.10A.

5.NT.02, 3/5/91 - Bugs fixed:
		- The xchg operator given two undefined symbols rather than
		  registers would GP fault. The problem was caused by referencing
		  an invalid pointer after having detected the error. The solution
		  was to stop processing the xchg instruction when this error
		  is detected.
		- Some symbols defined by equates were not being found by
		  the symsrch routine. The assembler was incorrectly attempting
		  to scope equates. This code just happend to work on 16
		  bit environments because of the memory alignment. It failed
		  on NT/386. The code was removed.



========================================================================

			MASM 5.NT.01

		Written 12/5/90, by Jeff Spencer.




Current state of MASM:

Masm 5.NT.01 is a portable version of MASM 5.10A. It works exactly like
MASM 5.10A with the following exceptions:

    - Masm 5.NT.01 does not support floating point initializers. This is
      because the strtod and _strtold C runtime functions are unavailable
      at this time. Future versions will support this capability
      (the code to support this has been ifdef'd out). Attempting to
      initialize a variable with a floating point number will result in a
      divide by zero error at assembly time.

    - Support for the MS floating point data format, and .MSFLOAT directive
      have been removed. Once floating point initializers are supported they
      will use the IEEE formats.

    - The time/date stamp in listing files has changed to the format
      provided by the standard C runtime libraries.


The code has been built and tested on NT/386 and NT/MIPS using the OS2
subsystem C runtime libraries. As of 12/5/90 there are no known bugs in
MASM.




General description of MASM 5.NT.01 code:

The code contained in this directory can produce an assembler to run on
OS2 1.2, OS2 2.0, and any version of NT. NT portability was achieved by
removing all assembly language and replacing all operating system
calls with C runtime calls.




Conditional Compilation Switches:

NOFLOAT 	- This constant is a binary switch. If it is absent the
		  code for floating point initializers is compiled. If it is
		  present then the floating point initializer code isn't
		  compiled. Currently the sources file does define this
		  constant. This allows MASM to be built despite the fact
		  that the strtod and _strtold functions don't exist
		  in the NT C runtime libraries. When these functions are
		  available the definition of NOFLOAT should be removed from
		  the sources file and masm rebuilt.

FIXCOMPILERBUG	- When defined allows some ifdef's to go around
		  some known compiler bugs. This include both CL386 and
		  MIPS compiler bugs. (These have been reported but not
		  fixed as of 12/5/90.)

<others>	- See asmconf.h.




General Info on building MASM for NT:

MASM 5.NT has been set up to use the standard NT build mechanism without
the requirement of the source actually being in the NT source tree. What
follows is a quick synopsis of my experiences with the NT build environment.

Building for the NT environment is not done through the standard
nmake mechanism. Instead the NT group uses a standard set of tools
that assume that the NT file tree starts at <current drive>\NT.
The best documentation I've found on how to set up to build files to run
on NT is in a file called newcomer.txt on \\ntos2\ntrel\release. KyleSh wrote
this document and can be quite helpful. Note that this document describes
both the development projects and the release project. It is only necessary
to enlist in one of these two projects. The advantage of enlisting in the
developer project is that you have the latest version of everything, and
with the right hardware, can build for MIPS. The disadvantage is
that this tree occupies over 100Mb of disk space. Although you can ghost
some of this I'm not sure which portions of the tree aren't needed. You also
have to build your own version of the NT kernel, OS2 subsystem, ect. The
advantage to enlisting in the release project is that you only have to build
your own code. And it requires only 21Mb of disk space. I found that for
building masm for NT/386 the release project was adequate. However, getting
the environment configuration files in the developr directory set up for
yourself can be a hassle. Also, be forewarned that sometimes the build tools
on the released project don't get updated as quickly as they should.
Note that the MASM tree must reside on the same logical drive (drive letter)
as the NT stuff. This is a limitation of how the NT tools work.

The masm project can be enlisted in from almost anywhere on the disk.
I suggest placing it in \MASM. Just make sure it is on the same drive
as the NT tree.

To use the developer projects rather than the released project you will
need to enlist in the projects: public, private, developr and os2.




Building MASM for NT/386:

    Released project method:
	- cd \NT (from \\os2nt\ntrel)
	- ssync -r
	- cd \MASM\510nt
	- build -esi -386 masm
	    Note: I've been having trouble with this hanging up at the link
	    step. Simply executing nmake at that point will finish the build,
	    assuming your environment variables are set up for 386 builds.

    Develeoper projects method:
	- cd \NT
	- ntsync
	- build -esi -386 os2 os2ss cmd cmd32
	    Note: This to build the necessary libraries to link with
		  and a version of NT to run on.
	- cd \MASM\510nt
	- build -esi -386 masm




Building MASM for NT/MIPS:

    As of this writing to build for the MIPS processor requires an Etherlink
    II network card and TCP/IP software. MarkL has this software and
    directions on how to install it. This is required because the
    actual MIPS compilation is done on a DEC server. The makefile.def
    file automatically ships the file to the server compiles it and ships
    it back.

    To build for the MIPS processor use the same procedure as for the 386
    except replace the -386 switch with the -mips switch.




Building MASM for OS2 1.2:

    The environment necessary:
	MASMOS = <nothing, i.e. not set>
	    - This causes the OS2 1.2 version to be built by makefile.os2
	      rather  than the OS2 2.0 version.
	PATH = <os2>;<LanMan>;<slm>;c:\tools\binb;c:\tools\binp
	LIB = c:\tools\lib
	INCLUDE = c:\tools\include
	Note: Tools directory comes from \\slug\tools\src\tools <pswd: vorga>

    The command line:
	- cd \MASM\510nt
	- md obj\os2.12 <if this hasn't been done yet>
	- nmake -f makefile.os2
	- The object and executable files will be in obj\os2.12




Building MASM for OS2 2.0:

    The environment necessary:
	MASMOS = OS2_2
		- This causes makefile.os2 to build the OS2 2.0 version when
		  it nmake is involked.
	PATH = <os2>;<LanMan>;<slm>;c:\c6_386\binb;c:\c6_386\binp
		- The release point for c6_386 is \\slproduct\current\c6_386
		  however the compiler code on \\sl\users\hanss\larch is
		  generally more current, and more bug free. The password
		  for \\slproduct\current is rikwrast, the password for
		  \\sl\users is soonhely.
	LIB = c:\c6_386\lib
		- this comes from \\slproduct\current\c6_386\lib
		  <pswd: rikwrast>
	INCLUDE = c:\c6_386\include
		- this comes from \\slproduct\current\c6_386\include

    The command line:
	- cd \MASM\510nt
	- md obj\os2.20 <if this hasn't been done yet>
	- nmake -f makefile.os2
	- The objects and executables will be in obj\os2.20



MASM execution speed:

In order to speed up the port from MASM to NT we decided to replace all
occurences of integer variables with either signed or unsigned short
variables. This was done at the expense of execution speed and size.
Therefore, this is one area that could be visited if execution speed
becomes an issue.




Testing MASM:

There are two different mechanisms available to test MASM on NT. The normal
mechanism uses the testing tool td. Although td is the preferred way to do
the testing it currently doesn't work on NT because of various subsystem bugs.
Because of this a set of very simple command files has been developed to run
the tests.




Testing MASM using TD:

    - Read the readme file on \\slog\slm\src\nt
    - Enlist in the NT project on \\slop\slm <pswd:ungepamm>
	- The directory you enlist must be on the same drive as the NT tree.
    - Build all the tools in the project (see readme)
    - Put the exe's built in a directory in the path on the NT test machine.
    - Put masm.exe in the same directory.
    - Tree copy \\loki\test\masmqa to \masmqa on the NT test machine.
    - Boot NT.
    - Start the OS2 cmd processor (cmd32).
    - cd to the masmqa directory.
    - Run the command "td masm=masm"
    - Within the masmqa directory will be a file called masm.log. This file
      contains the summary of the test results. Within each of the
      subdirectories below masmqa will be a log file with the same name as
      the subdirectory that contains the test results for that directory.




Testing MASM using command files:
    - Tree copy \\loki\test\masmqa to \masmqa on the NT test machine.
    - Over the top of this tree copy the masmqa tree contained under the
      masm 510nt project (this directory). This adds the necessary command
      files to the standard test tree.
    - Put masm.exe somewhere in the NT file execution path.
    - Boot NT
    - Start the OS2 command processor (cmd32).
    - cd to the masmqa directory.
    - Run the command file "testnt.cmd".
	- This will assemble all the test files and leave the resulting objects
	  on the hard disk.
    - Boot OS2 1.2.
    - cd to the masmqa directory and run the command file "checknt.cmd".
	- This will compare each of the object files with the pattern in
	  the results subdirectory. Note that a binary comparison is not
	  done. This is because the command line that td and the command
	  files use to invoke masm are slightly different. This results in
	  the file name stored in masm.obj having a slightly different mix
	  of upper and lower case. Rather than doing a binary compare a diff
	  is done of the decoded object files. Then expected differences are
	  thrown out.
    - Note: The command files currently skip any tests that would
      involve redirecting the error output to a file. This is because the
      NT command processor can't do redirection at the moment. Hopefully
      by the time a working command processor is running these command files
      can be abandoned completely in favor of td.
    - NT/386 status:
	Currently the top level command file must be cut in half and executed
	separately for the tests to run through. Otherwise NT gets tired and
	dies.
    - NT/MIPS status:
	Currently files can't be found unless they are in the root directory
	or a full path to the file is specified. This appears to be
	an NT problem and not related to MASM, therefore I've simply been
	working around this limitation. This should be fixed after the windows
	subsystem command processor is available. To work around the problem
	move the assembly file and all include files to the root directory.




Expected failures:

    - Some of the test files generate warnings. These can be safely ignored.
      Most of these warnings occur in the win386 subdirectories.
    - There is a test that checks the error output from code that has too
      long of a line in it. The error output will not match for this test.
      This is actually an improvement on MASM 5.NT. The MASM 5.10A assembler
      used to literally cut the line in half and try to process the second
      half of the line as a separate line. This would then generate more errors
      than actually existed in the file. MASM 5.NT doesn't do this but instead
      logs the line too long error and goes on to the next line.