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 Options³Directories 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 utilities³Link 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; - Run³Until 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.