                WELCOME TO VIRTUAL PASCAL
                ~~~~~~~~~~~~~~~~~~~~~~~~~
                 Version 1.0 Beta (#003)

This README.TXT file contains important information about
Virtual Pascal Compiler (VPC), explains the contents and
directory structure, describes how to install VPC, introduces
VPC features and discusses some of the things that have been
changed and added for this release.


TABLE OF CONTENTS
~~~~~~~~~~~~~~~~~
1. Directory structure
2. Installation
3. Features
4. New features
5. Important information
6. License agreement
7. Contacting author
8. Trademarks


1. DIRECTORY STRUCTURE
~~~~~~~~~~~~~~~~~~~~~~
VPC package has the following directory structure:

\VP
 BIN            - VPC executable and help files
 EXAMPLES\...   - VPC examples
 LIB            - VPC object and import libraries
 OUT            - Output directory
 SOURCE\...     - VPC run-time library sources
 UNITS          - VPC run-time library


2. INSTALLATION
~~~~~~~~~~~~~~~
To install VPC, take the following steps:

  1. Unpack VPC.ZIP file into the X:\VP directory with
     subdirectories (/d PKUNZIP or UNZIP option), where
     X: is the drive on which you want to install VPC.

  2. Modify LIBPATH statement and PATH environment variable in
     the OS/2 CONFIG.SYS, so they include X:\VP\BIN directory.
     If you plan to use command line compiler, also include the
     following lines into OS/2 CONFIG.SYS:
       SET VPOUT=X:\VP\OUT
       SET VPLIB=X:\VP\LIB
     VPVIO.CMD and VPPM.CMD command files located in the
     \VP\BIN directory use these environment variables.

  3. Reboot OS/2 in order for changes to CONGIG.SYS to
     take place.

  4. Change to the X:\VP directory and run BLDRTL.CMD OS/2
     command file to build VPC run-time library.

  5. VP.EXE is the Integrated Development Environment (IDE)
     executable, VPC.EXE is a command line compiler. Type VP at
     the OS/2 command prompt to start the IDE. Go to the
     OptionsDirectories dialog box and include X: into
     all available paths.


3. FEATURES
~~~~~~~~~~~
Virtual Pascal is a professional quality 32-bit Object Pascal
compiler for OS/2 version 2.0 or above. It includes command
line compiler and the Integrated Development Environment with
integrated debugger. VPC can be used to develop a wide range of
text mode and Presentation Manager applications for OS/2 and
to port existing sofware products written in Borland Pascal
from DOS to OS/2.

  I. Virtual Pascal Compiler features
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  1. Borland Pascal version 7.0 compatibility including
     the latest extensions, such as open array parameters, open
     strings, null-terminated strings, dynamic methods, small
     (integer sized) sets.

  2. Built-in Make and Build tools.

  3. 386/486/Pentium built-in assembler(BASM).

  4. The maximum line length acceptable by the compiler is 255
     characters.

  5. VPC can generate object file, object library or readable
     assembly source that can be compiled by TASM 3.0+ or MASM
     6.0a+ to obtain equivalent object file. This solves the
     compatibility problem of the .TPU(TPP/TPW/DCU) files
     produced by different versions of the Borland Pascal and
     allows to mix Pascal code with code written in other
     languages.

  6. VPC supports Pascal, C, StdCall and far16 Pascal (without
     thunking) calling conventions, so
       - OS/2 API functions can be called directly without
         special interface libraries.
       - OS/2 Exception handlers, Presentation Manager window
         functions, etc, can be written in Pascal.
       - 16-bit OS/2 1.x API functions can be called directly
         without special interface thunk libraries.

  7. VPC provides direct I/O port and memory access (Port and
     Mem arrays).

  8. Standard units are highly compatible with DOS protected
     mode and Windows platforms of the Borland Pascal:
       - SYSTEM: Mark and Release real mode procedures
         are not implemented, Ptr function accepts only
         one argument - Offset).

       - CRT: Sound and NoSound procedures are not implemented
         (new procedure PlaySound can be used instead).

       - DOS, WINDOS: DOS specific procedures such as Keep,
         GetIntVec, SetIntVec, etc, are not implemented.

       - WINCRT and STRINGS: all Borland Pascal procedures and
         functions are implemented.

       - TURBO VISION: there is a patch on Turbo Vision 2.0
         source code to produce 32-bit Turbo Vision for OS/2.
         Drivers unit has been rewritten completely, in other
         units all BASM code is rewritten. Original Turbo
         Vision 2.0 source code is supplied with Borland Pascal
         7.0 (7.01) in the package that includes runtime
         library source code.

  9. Smart linking feature lets you create tiny executables
     even with static linking. The term "smart linking" means
     that if some variable, procedure, function or even object
     is not used by the program, it is not linked in the
     executable.

  10. VPC can generate dynamic link libraries (DLL). Unlike
      Borland Pascal it can export the whole interface part of
      any unit, including variables, typed constants,
      procedures, function and object methods! Program or
      library can use either static version of a unit (in this
      case object file or object library is linked into
      executable statically) or dynamic version of a unit
      (unit's object file is linked into DLL and import library
      is used to link the executable) with full source level
      integrated debugging support.

      There are two standard DLLs available:
       - VPRTL includes System, Crt, Dos and Strings units.
       - TVISION includes all Turbo Vision units (only users
         that have Turbo Vision source can generate this one).

  11. There are interface units for almost all OS/2 API:
       - Base OS/2 API.
       - 16-bit OS/2 1.x API (VIO/KBD/MOU/MON/NLS calls).
       - Presentation Manager API.
       - REXX API.

  12. All Turbo Pascal examples can be compiled by Virtual
      Pascal with minor changes (BREAKOUT, TVDEMO, TVEDIT, TVFM,
      etc.)

  13. Examples that show the use of standard units are
      supplied. Presentation Manager TRIPLEX game and CLOCK
      application are also given as an example.

  II. Virtual Pascal IDE features
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  1. Background compilation.

  2. Multi window editor that is able to edit text files of any
     size with:
       - Unlimited number of Undo and Redo;
       - Block operations with 3 block types: line, columnar
         and stream;
       - Clipboard operations: cut, copy and paste;
       - Syntax highlighting (2 types of comments, whitespace,
         reserved words, identifiers, symbols, strings, numbers
         and assembler);
       - Search and Replace with regular expressions in forward
         and backward directions;
       - Incremental search facility.

  3. Full keystroke macro support, including Macro List dialog
     box that displays keystroke macros and lets you add, remove
     and edit them.

  4. Context-sensitive help system:
       - If help window is resized, text will be wrapped to fit
         the window.
       - Topic search from editor and help windows.
       - Search for text in the current topic, index or
         in all topics with Case Sensitive and Whole Words Only
         options.
       - Clipboard Copy and Copy example commands.

  5. Integrated Debugger is a source level debugger that uses
     Editor windows to track source:
       - Sophisticated source tracing algorithm that allows
         even complex lines to be stepped over at high speed
         (E.g: for I := 1 to 100000 do SomeFuncCall; )
       - Watches window.
       - Call stack window.
       - Breakpoints window. Besides execution breakpoints
         it's possible to set up to four datapoints (that are
         supported by 386 hardware) with condition and pass
         count.
       - Register window that shows the values of the
         CPU registers and flags and allows to change them.
       - Numeric Coprocessor window with Stack registers, Control
         register and Status register panes that shows the
         state of the 387 coprocessor and lets you change it.
       - Dump window that shows the memory in all Pascal
         integer and floating point formats.
       - CPU window with Code, Data, Register and Stack panes
         displays the source lines and corresponding
         disassembled instructions. You can patch code using
         built-in assembler that is similar to BASM of the VPC.
       - Log window that collects the information about program
         flow (Module loads, thread creations and terminations,
         exceptions, breakpoints, user comments, etc).
       - Evaluate/Modify dialog.
       - Threads dialog lets you examine current program
         threads and freeze or resume them.
       - Exceptions dialog lists all OS/2 system exceptions and
         allows you to specify whether debugger will handle
         particular exception or user program is responsible
         for handling it.
       - Unit dialog lists the units used by the program along
         with the include files. If unit or include file is
         selected, the source file is loaded into editor window.

     IDE can be also used as a high speed assembler level
     debugger.


4. NEW FEATURES
~~~~~~~~~~~~~~~
  1. Compiler has been totally rewritten as 32-bit executable.
     As a result, the 64K limit for the size of code and data
     segments for a single unit and symbol size for a unit
     no longer exists.

  2. Compilation speed has been increased (up to 25%).

  3. Besides dollar symbol ($), the ampersand symbol (&) can be
     used to start compiler directive. You can use it to specify
     Virtual Pascal specific directives: other Pascal
     compilers, such as Borland Pascal, treat them as ordinal
     comments.

  4. All Borland Pascal directives are accepted now. Those
     ones that have no Virtual Pascal equivalents are ignored.
     $A is equivalent to $AlignData.

  5. $Alters directive is introduced. It complements $Saves
     directive.

  6. Smart linking is implemented. Instead of object file(.OBJ),
     compiler can produce object library file (.LIB) for a
     unit. You should NOT use this feature for debugging
     because of the following:
       - library files are larger in size;
       - linking of the units, compiled to object libraries
         can be several times slower than linking object
         files;
       - source level debugging in the IDE is not available for
         the units, compiled to object libraries;

     You may use smart linking for building of the final
     executable. It significantly decreases the size of the
     produced executable file.

  7. Long file names are supported by the run-time library:
       - Size of the file variables has been increased to hold
         long file name;
       - PathStr, DirStr, NameStr, ExtStr, SearchRec types in
         the DOS/WINDOS units has been modified accordingly.

  8. Indices of the dynamic methods are extended to the Longint
     type.

  9. Editor has been significantly improved. The following new
     features have been added:
       - BackSpace unident;
       - BackSpace in overwrite mode does not delete
         characters, but replaces them with blanks;
       - Block Indent/Unindent;
       - Set/Find place marker;
       - Non-Persistent blocks;
       - Delete Word Left (Ctrl-BackSpace)
       - Smart Tab;
       - Pair Matching for () and [];
       - Hide/Display Block works now as a toggle, hiding and
         showing the selected text;
       - PgUp/PgDn does not change cursor position within the
         window;
       - Block Read;
       - Block Write;
       - Incremental search facility;
       - Common clipboard for editor and input line boxes;
       - Print file and Print block commands.


5. IMPORTANT INFORMATION
~~~~~~~~~~~~~~~~~~~~~~~~
  1. Hardware requirements.
     VPC has been written on the PC AT-386DX-40Mhz-4MB of RAM.
     VPC requires PC with at least 386SX processor with 4 MB of
     RAM, but 8MB is strongly recommended (actually, these
     restrictions are not VPC, but OS/2 itself). VPC works
     fine on OS/2 2.1 and OS/2 3.0 Warp. It has not been
     checked on OS/2 2.0, but it should not be any problem.

  2. Linker and Resource Compiler.
     Virtual Pascal doesn't have its own linker and resource
     compiler, so LINK386 and RC shipped with OS/2 are used. If
     you have BC for OS/2 it is also possible to use TLINK (it
     is almost 2-9 times faster than LINK386, but produces
     larger executables) and BRCC (or Resource Workshop).

     Note: In order to use LINK386 and RC you have had to
     install OS/2 with Optional utilitiesLink Object Modules
     option enabled.

     Also make sure that linker and resource compiler
     executables are in the directory, mentioned in the PATH
     environment variable.

     It is recommended that the ALIGN, BASE, and EXEPACK
     LINK386 (-A,-B, -Oc TLINK) options be used when linking
     all executables. This will compress them in size and
     improve their performance. Use /ALIGN:4 (/A:4) for 32-bit
     applications. For .EXE files, /BASE:0x10000 (/B:0x10000)
     option must be used to remove internal fixups from
     executable.

     Note, that LINK386 prior to version 2.02.001 (which is
     supplied with OS/2 3.0 Warp) is not able to link
     executable, if more than 32 object libraries are
     specified. If you encounter this problem, look for a new
     version of LINK386 or disable $SmartLink compiler
     directive.

  3. Debug Information.
     Virtual Pascal uses debug information that is recorded
     in the interface information file (.VPI) and doesn't
     support IPMD, BC, CodeView or any other debug information.
     However VPC can put line number information to the object
     file, so for example, if you link it into program written
     in IBM C/C++, you can trace Pascal source in IPMD.

  4. Differences between Virtual Pascal and Borland Pascal 7.0.
     Read VP.TXT file that describes the differences between
     Virtual Pascal and Borland Pascal in detail.

  5. Known problems.
     Hard and soft debugging modes are not yet implemented, so
     when you debug Presentation Manager application you must
     not switch from the IDE to the other sessions.

     Multi-thread support is not yet ready, so switch off stack
     checking {$S-} for multi-thread programs.

  6. What is still not implemented:
       - Variables, Hierarchy and Inspector windows;
       - Breakpoint condition, pass count and action are not
         functioning yet. All breakpoints are unconditional
         and cause program to stop at the breakpoint location;
       - RunUntil return command.

6. LICENSE AGREEMENT
~~~~~~~~~~~~~~~~~~~~
Virtual Pascal is not a freeware product. Virtual Pascal and
programs produced by Virtual Pascal CANNOT be used in a
business, commercial, government or institutional environment
except for evaluation purposes. You may use Virtual Pascal
with the following restrictions:

  1. You may NOT change the Virtual Pascal executables in any
     way.
  2. You may NOT remove or change copyright notice from either
     object, library or executable files produced by Virtual
     Pascal.
  3. You may NOT sell, sublicense, rent, lease, or assign
     Virtual Pascal.
  4. If Virtual Pascal is to be distributed, it should be
     distributed unaltered and in full.
  5. Author can terminate this license at any time.

The usual disclaimers apply, expressed thus:

VIRTUAL PASCAL IS SUPPLIED "AS IS", AND WITHOUT ANY WARRANTIES,
EXPRESS OR IMPLIED, INCLUDING THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

YOU USE VIRTUAL PASCAL ENTIRELY AT YOUR OWN RISK. AUTHOR WILL
ACCEPT NO LIABILITY FOR ANY LOSS OR DAMAGE INCURRED BY ANYONE
FROM THE USE OR THE PURPORTED USE OF VIRTUAL PASCAL, FOR ANY
PURPOSE WHATSOEVER.

IF YOU USE VIRTUAL PASCAL YOU AGREE TO THESE TERMS.

If these terms are not acceptable to you, then this license is
void: you have no license to use Virtual Pascal and should
delete it from your disk(s).

7. CONTACTING AUTHOR
~~~~~~~~~~~~~~~~~~~~
This release of the Virtual Pascal is made in the hope that I
will find the people who might be interested in supporting
Virtual Pascal financially. This version has been made on the
sole enthusiasm of the author and long patience of my family,
but it can not last forever. I am looking either:
 - for people/organization who can support VPC financially to
   make its commercial version.
 - for a place, where I can create commercial version of the
   VPC with appropriate financing.
Commercial version of the Virtual Pascal would have the
following additional features:
 - Language would be highly compatible with Borland Delphi
   Pascal compiler, including new standard units;
 - GUI version of the IDE;
 - High speed linker;
 - Delphi VCL patches for OS/2;
 - Relicensed OS/2 developer's toolkit online documentation
   with Pascal bindings;
 - VPC Programmer's guide.

You can reach me at any time by e-mail:

----------------------------------
Mr Vitaly Miryanov
E-mail:  ukcuka@deer.icyb.kiev.ua
Fidonet: 2:463/702.44
----------------------------------

If you will find bugs in Virtual Pascal, please let me know.
Send brief description of an error and if it is possible, include
small code fragment, so I can reproduce it. I will update this
beta version, as I receive your bug reports and fix the
problems.


8. TRADEMARKS
~~~~~~~~~~~~~
Company names, brand names and product names are trademarks or
registered trademarks of their respective holders.
