How to build a new VM with Win32
================================

NOTE: The following assumes that you are working with
      Microsoft Visual C++ >= 2.0 unless otherwise
      stated.


1. Quickstart
1.1 How do I recompile the standard VM?
1.2 How do I build a JIT VM?

2. So, I got this compiler, what now?
2.1 How do I recompile the VM using Borland C?
2.2 How do I recompile the VM using Watcom C?
2.3 How do I recompile the VM using Cygnus GCC Win32?

3. I've made a modification, should I send you the file sqXYZ?!
3.1 Changing a file not prefixed sqWin32
3.2 Changing Win32 support code

4. Preprocessor definitions
4.1 Global Definitions
4.2 Taking out sub-systems
4.3 Taking out VM stuff
4.4 Changing standard behavior
4.4.1 NO_STANDARD_COLORS
4.4.2 NO_BYTE_REVERSAL
4.4.3 NO_STD_BYTE_REVERSAL
4.4.4 WIN32_FILE_SUPPORT
4.5 Removing static strings
4.6 The "MINIMAL" Symbol

5. What is sqWin32Generic.c?

6. How do I port to a different platform running Win32?

7. Disclaimer



1. Quickstart
=============

1.1 How do I recompile the standard VM?
---------------------------------------
First of all, you have to decide for which platform you want 
to compile the VM. The Win32 source directory contains support for
a) Windows 95 and Windows NT (3.xx and 4.0)
b) Windows CE
These platforms have different support files that can be found
in the appropriate sub-directories (e.g., "Win95" for Win95 and NT, and
"WinCE" for Windows CE).

STEP 1:
COPY ALL OF THE FILES FROM THE APPROPRIATE SUB-DIRECTORY TO THE BASE DIRECTORY!

[Note: If a sub-directory contains a file that's also in the base directory,
       use the one from the sub-directory!]

STEP 2:
Create a plain Win32 project (no app-wizards; no console) and add all
the ".c" files from the base directory, EXCEPT FROM THE FILE
"translator.c". For the current version (e.g., 2.2) these files are

a) For Win95/WinNT
  + interp.c
  + sqFilePrims.c
  + sqMiscPrims.c
  + sqOldSoundPrims.c
  + sqSoundPrims.c
  + sqWin32Alloc.c
  + sqWin32Args.c
  + sqWin32AsyncFilePrims.c
  + sqWin32Directory.c
  + sqWin32FilePrims.c
  + sqWin32Intel.c
  + sqWin32Joystick.c
  + sqWin32MIDI.c
  + sqWin32Net.c
  + sqWin32SerialPort.c
  + sqWin32Service.c
  + sqWin32Stubs.c 
  + sqWin32Sound.c
  + sqWin32Utils.c
  + sqWin32Window.c
  + Squeak.rc

b) For Windows CE
  + interp.c
  + sqMiscPrims.c
  + sqOldSoundPrims.c
  + sqSoundPrims.c
  + sqWin32Alloc.c
  + sqWin32AsyncFilePrims.c
  + sqWin32Directory.c
  + sqWin32FilePrims.c
  + sqWin32Joystick.c
  + sqWin32MIDI.c
  + sqWin32Net.c
  + sqWin32SerialPort.c
  + sqWin32Stubs.c 
  + sqWin32Sound.c
  + sqWin32Utils.c
  + sqWin32Window.c
  + sqWin32CE.c
  + sqWinCEMem.c
  + sqWinCEStdio.c
  + sqWinCEString.c
  + sqWinCEtime.c
  + Squeak.rc

Make sure your projects linker section has the following libraries
added (these are not in Win32 project by default)
  + winmm.lib
  + wsock32.lib

If you want maximum speed then go to the optimization section and 
enable the following optimizations:
  + optimize for speed
  + any suitable inline functions

NOTE: The "optimize speed" option may not work depending on the
      compiler version you use (there are various different bugs
      known when enabling this optimization).

Compile the VM. That's all.

1.2 Building a JIT VM
---------------------

[NOTE: The JIT VM is currently not supported by the WinCE port]

If you want to build the JIT version of the VM follow the steps
outlined in section 1.1 *BUT* replace the file "interp.c" by 
"translator.c" (that is, *ADD* "translator.c" to the project and
*REMOVE* "interp.c" from the project.

Then, go to the projects compiler settings and add the following
symbol to the pre-processor definition:

  JITTER

Compile the VM. That's all.

2. So, I got this compiler, what now?
=====================================

2.1 How do I recompile the VM using Borland C?
----------------------------------------------

I'm not sure. I did not have the time to clean up the code
for Borland C. If you're experienced enough to get it running, 
then *please* send me the necessary modifications plus build 
instructions.


2.2 How do I recompile the VM using Watcom C?
---------------------------------------------

I don't know. I don't have Watcom C and so I cannot try it.
If you're experienced enough to get it running, then *please* 
*please* send me the necessary modifications plus build 
instructions.


2.3 How do I recompile the VM using Cygnus GCC Win32?
-----------------------------------------------------

You don't. Cygnus GCC can currently *NOT* be used to recompile Squeak.
Here are the reasons why:
 * Header files
   Cygnus provides its own header files which are not compatible with
   the Win32 SDK. In particular, the header files lack many of the
   multi-media (sound, joystick, MIDI) and Win32 networking functions.
   Even worse, the standard headers and libraries *freely* available
   from Microsoft do not work with Cygnus GCC Win32.
 * Exception Handling
   The structured exception handling is required for the virtual
   memory support. This can be taken out (see NO_VIRTUAL_MEMORY)
   but it's still a limitation.
 * Threads
   Due to Cygnus ignorance of basic Win32 functionality and the
   increasing use of threads in the VM you would have to rewrite
   a substantial part of the code.
The bottom line is: As long as Cygnus aims at Unix-portability
rather than Win32 compatibility there will be no way of compiling
Squeak with Cygnus GCC. Period.

3. I've made a modification, should I send you the file sqXYZ?!
===============================================================

3.1 Changing a file not prefixed sqWin32
----------------------------------------

Don't even think of sending these changes to me. All files
not prefixed with "sqWin32" are *generated* from Smalltalk
code and maintained by Squeak Central. Talk to Dan Ingalls
(DanI@wdi.disney.com) or John Maloney (JohnM@wdi.disney.com)
about your problem / modification.

3.2 Changing Win32 support code
-------------------------------
If you are changing Win32 support code and want me to integrate
this, I'll be happy to do so; GIVEN THAT YOU FOLLOW A FEW RULES!

Rule #1: Do not change any of the sqWin32 files except from:
         * Adding #ifdefs to disable an existing implementation
         * Removing the keyword "static" if a function / variable is 
           needed outside this module.

Rule #2: Create a new file for your code. Implement the new method
         in this file.

Rule #3: Send me the file containing *your* code. Do not send me
         the original files with the modifications stated in rule #1.

If you follow the above three rules, then I can figure out what you
have done and how it can be best integrated without having to review
an awful lot of code. Your (probably short) file should then be sent
to the following address:

  raab@isg.cs.uni-magdeburg.de

4. Preprocessor definitions
===========================
The following is a list of preprocessor definitions which
might be used for configuring certain parts when recompiling
the VM.

4.1 Global Definitions
----------------------

JITTER - The symbol *MUST* be defined if you want to build
         a JIT version of the VM.

4.2 Taking out sub-systems
--------------------------

NO_SOUND       - Removes the sound support

NO_SERIAL_PORT - Removes the serial port support

NO_JOYSTICK    - Removes the joystick support

NO_MIDI        - Removes the MIDI support

NO_ASYNC_FILES - Removes the async file support

NO_PRINTER     - Removes printing support

4.3 Taking out VM stuff
-----------------------

NO_VIRTUAL_MEMORY - Removes virtual memory support

NO_SERVICE        - Removes service support

NO_PREFERENCES    - Removes preferences


4.4 Changing standard behavior
------------------------------

4.4.1 NO_STANDARD_COLORS

Even though Squeak defines a certain color table there are
systems on which this cannot be used (such as Blair's WinCE port).
Those ports, which require a special setup in of colors and bitmaps
should define NO_STANDARD_COLORS. This will leave the standard 
implementation of SetupPixmaps() out. On the other hand, you'll have
to write your own SetupPixmaps() function. This function should
provide the same basic functionality but may treat colors differently.
In the case that certain color depths are not supported the
appropriate BITMAPINFO pointers must be set to NULL.

4.4.2 NO_BYTE_REVERSAL

On machines running Win32 with the same byte order as PPC (as opposed
to Intel x86) there is no need to reverse the image bytes/words when
performing bitmap output. Define NO_BYTE_REVERSAL if you don't need
to reverse bytes on the fly.

4.4.3 NO_STD_BYTE_REVERSAL

In the case that you actually need to modify images (such as on Intel x86)
but want to do it differently from the standard implementation then define
NO_STD_BYTE_REVERSAL. You'll have to provide your own reverse_image_bytes
and reverse_image_words functions (see prototypes in sqWin32.h). As an
example, the standard (Intel) VM uses inline assembly for speeding up
this operation.

4.4.4 WIN32_FILE_SUPPORT

Some systems running Win32 may not provide the standard io
functionality for accessing files and require the use of explicit Win32
functions instead. To simplify the task of porting to these systems
a complete implementation of the necessary file primitives is provided.
This implementation can be activated by defining WIN32_FILE_SUPPORT.

NOTE: In order to work properly, the activation of WIN32_FILE_SUPPORT
      requires the removal of the file sqFilePrims.c from the project!


4.5 Removing static strings
---------------------------
When trying to compile a small VM you can define the following symbols.

NO_RCSID      - Removes the static RCS id strings

NO_WARNINGS   - Removes a number of (less significant) warnings


4.6 The "MINIMAL" Symbol
------------------------
MINIMAL is an experimental definition trying to compile a VM that
is as small as possible. It can be used when starting a port to
a new platform. MINIMAL will take out all subsystems stated above
will remove all the VM support code stated above and will also
remove static strings. That is, MINIMAL defines all the symbols
from section 4.2, 4.3 and 4.5.


5. What is sqWin32Generic.c?
============================
Win32 can look fairly different than one would expect. The features
of Windows 95, Windows 98, Windows NT 3, Windows NT 4, Windows CE,
Windows NT for Alpha are all *slightly* different even though all 
claim to run Win32. For instance, some of the Win32 implementations 
(e.g., WindowsCE) require Unicode. Others (e.g., Windows95) do not 
support Unicode at all. Then, there are different processors we 
must know about for some of the JIT stuff.

sqWin32Generic.c is provided as a starting point for what is actually
needed when porting to a new platform running Win32. It is intended
as a starter, not an actual implementation running across *all* platforms
(even though this would be nice).

As an example, you might compare the contents of sqWin32Generic.c
and sqWin32Intel.c to see how different the actual support code can look.

6. How do I port to a different platform running Win32?
=======================================================
Good question. I know that there are people out there planning to port
the latest VM versions to WinCE / Alpha. But since the structure of
the files has been re-worked to simplify the task there is no experience
with it. Anyways, here is what I suggest:

Start with a project containing the following files:
  + interp.c
  + sqMiscPrims.c
  + sqOldSoundProms.c
  + sqSoundPrims.c
  + sqWin32Directory.c
  + sqWin32FilePrims.c
  + sqWin32Generic.c
  + sqWin32Stubs.c
  + sqWin32Utils.c
  + sqWin32Window.c

NOTE: 1) The file "sqFilePrims.c" is *NOT* included in the list above.
      2) You may want to create a copy of sqWin32Generic.c to work with.

In your compiler settings, define MINIMAL taking out as many
subsystems as possible. 

Then, change the stuff necessary in the Win32 support code (be sure
you have read the part about submitting code) and implement the
new methods in your sqWin32Generic copy.

After this basic version is running, you can go on integrating 
the various subsystems.

Once your port is running you have to decide what to do with it. You
may look if some of your changes are of general interest to the Win32
community. If so, you should create a new file containing these 
modifications and send them to me.

You may also send me the latest version of your sqWin32Generic copy
to be included in the source code release of the Win32 VM. I'm planning
to have sub directories for each Win32 version but as long as I don't
have source code to integrate I'll not start to do so.


7. Disclaimer
=============

This file has been last updated for Squeak 2.2 and may not reflect
changes made later on.


    Andreas Raab (raab@isg.cs.uni-magdeburg.de)
