added deterministic test method

[strongtalk-kjk.git] / README.txt

Caveats\r
-------\r
The Strongtalk project only started up again recently after having been inactive since 1996, and all VM development stopped at that point.   It is now starting up again, since Strongtalk is still by far the fastest Smalltalk implementation in existence, and is fully open-source unlike any other fast Smalltalk implementations, so there is much of value here.\r
\r
While the C++ parts of the system now build under VisualStudio 2005 (and the Express version), the assembler files still require Borland Turbo Assembler.  To enable compilation without purchasing the assembler, we have included the .obj files in COFF format from the assembler, for convenience (in bin/asm_objs.\r
\r
Requirements\r
------------\r
In order to run the Strongtalk VM, the following is required:\r
\r
1) Intel Pentium PC, 90MHz, at least 32MB of RAM.\r
\r
2) Windows NT 4.0 or Windows 95 or higher.\r
\r
In order to build the Strongtalk VM from scratch, additionally the following\r
software is required:\r
\r
3) MS VisualStudio 2005 or VisualStudio 2005 Express\r
\r
2) Assembler .obj files are included in the packaged source release, but if \r
   you wish to reassemble them,\r
   you will need Borland Turbo Assembler version 4.0. \r
   We don't know if things work properly with a newer version.\r
   An installed version of the assembler should be placed in\r
   the tools\tasm directory - extra installation may only be required\r
   if there's a problem with the current setup.\r
\r
Build instructions\r
------------------\r
\r
We will call the root strongtalk directory $STRTLK.\r
\r
1) Build the 'makedeps' utility:  In Explorer, navigate \r
   to $STRTLK\tools\makedeps. Open the VisualStudio project file for \r
   makedeps, makedeps.vcproj.  "Run Build/Build Solution" from the menu.  This\r
   should build $STRTLK\tools\makedeps.exe\r
\r
2) Use makedeps to build include file dependencies: From a command line, \r
   cd into the $STRTLK\bin directory.  Run 'nmake -f Makefile.win32 lists'.\r
\r
3) From Windows Explorer, start the VisualStudio project for Strongtalk by \r
   opening $(STRTLK)\bin\strongtalk.vcproj.\r
\r
4) In the VisualStudio IDE, choose Build -> Batch Build.\r
   Select the project configurations you want to build from the choices of\r
   Debug, Fast, and Product (ignore Release, that is spurious right now)\r
   and press Rebuild All.\r
\r
5) Remove intermediate files if desired from the command file in $STRTLK\bin:\r
   nmake -f Makefile.win32 clean\r
\r
The executables end up in the $STRTLK directory.  Intermediate build files (object files etc) end up in subdirectories of $STRTLK\bin.\r
\r
There are three configurations in the project - debug, fast and product.\r
Each has its own subdirectory under bin, and its own executable: \r
strongtalk_debug.exe, strongtalk_fast.exe and strongtalk.exe, respectively.\r
The differences between them are: \r
\r
- The debug configuration turns off C++ optimizations, turns on debugging \r
  options, and also turns on extensive assertions in the code, so it runs \r
  slowly.\r
\r
- The fast configuration is like the debug configuration except that it turns \r
  off assertions and turns on more C++ optimizations, so it runs quite fast \r
  yet is still debuggable.  This is a good one to use if you want to get real\r
  work done in it but still want to be able to debug crashes when they happen.\r
\r
- The product configuration turns off all the debugging options, links with\r
  the non-debug runtime libraries, and turns on more extensive C++ \r
  optimizations.  This is the version that should be used for benchmarking.\r
\r
Note: the code is formatted for a tab-width of 8, so the default of 4 must be changed when\r
using Visual Studio.   Go to Tools/Options/Text Editor/All Languages/Tabs.\r
\r
\r
Execute instructions\r
--------------------\r
\r
1) In the $STRLK directory, just run the VM executable you wish to use;\r
  for the product version that would be:\r
\r
        strongtalk\r
\r
  Files needed in that directory for running an application are: \r
  \r
     strongtalk.bst - the image file\r
\r
     .strongtalkrc - the VM configuration options file\r
\r
  If you wish to use the development environment, you will also need:\r
\r
     source - folder containing the source code for the Strongtalk libraries\r
\r
\r
\r
\r
Special situations\r
__________________\r
\r
If you do have access to TASM, you should be able to get by by using the object\r
files that are generated from the assembly code. If you are using  MS VC++ 4.0,\r
you should probably be able do place the object files found in strongtalk\bin\asm_objs\OMF\r
in the build subdirectories (debug, fast, product) and doing an incremental build. \r
\r
If you don't have an old version of MS VC++, you will either have to wait until\r
we provide a version of the code that builds under a newer C++ compiler, or try\r
and convert the code yourself. \r
\r
Issues: if you get the C++ code to compile, you\r
will find that VisualStudio 2005 will not link with the object files produced by TASM, which are in OMF format.  \r
You can substitute these with the COFF versions\r
found in strongtalk\bin\asm_objs\COFF and repeat the link phase. This should work\r
(it worked for us). \r
\r
If you want to build on a non-windows machine, we're all for it, but you have non-trivial work to do.\r
\r
Problems we have encountered\r
----------------------------\r
Occasionally, despite strict adherence to the build instructions, we have run into problems on some machines, \r
probably due to pre-existing installations of later versions of tools, environment variable differences, etc.\r
- Link errors (LNK1104): It appears that on some machines, some libraries (e.g. kernel32.lib) cannot be found. \r
By setting the full path (e.g., "C:\Program Files\MSDEV\LIB\kernel32.lib") we were able to circumvent this problem.\r
You can do this in MSDEV by choosing Build>Settings and choosing the Link tab, and ensuring that every library that is missing is\r
listed explicitly with its full path name in the Object files list. All 3 projects should have the same list of libraries:\r
"c:\Program Files\msdev\lib\kernel32.lib" "c:\Program Files\msdev\lib\user32.lib" "c:\Program Files\msdev\lib\gdi32.lib" "c:\Program Files\msdev\lib\winspool.lib" "c:\Program Files\msdev\lib\comdlg32.lib" "c:\Program Files\msdev\lib\advapi32.lib" "c:\Program Files\msdev\lib\shell32.lib" "c:\Program Files\msdev\lib\ole32.lib" "c:\Program Files\msdev\lib\oleaut32.lib" "c:\Program Files\msdev\lib\uuid.lib" "c:\Program Files\msdev\lib\LIBCD.lib" "c:\Program Files\msdev\lib\oldnames.lib" \r
\r
You can paste this in the Object files field of the Links tab under Buikd>Settings in MSDEV.\r