CD Actual 11

home *** CD-ROM | disk | FTP | other *** search

/ CD Actual 11 / CDACTUAL11.iso / cdactual / demobin / share / os2 / XCO212P / DOC / INTRO.TXT < prev next >

Wrap

Text File | 1996-03-06 | 23.3 KB | 674 lines

INTRO.TXT Copyright (c) 1991,96 xTech Ltd ---------------------------------------------------------------- Welcome to the pre-release version of XDS v2.12 ----------------------------------------------- XDS is a professional development system available for most popular platforms, including PC/MS-DOS, Unix workstations (Sun, HP, DEC, MIPS, etc), Macintosh, etc via the C generation. The native code compilers are available currently for Windows NT, Windows 95, OS/2 and Linux. The previous version of XDS was known as "Extacy". The native code versions of the system were distributed as "Extacy.EXE" and "OM2". XDS contains both Modula-2 and Oberon-2 compilers. The source language of XDS Modula-2 compiler is fully compatible with ISO Modula-2 standard. We are expecting that adaptation of the ISO standard will cause the new wave of interest to Modula-2. The ISO Modula-2 includes features important for industry programming such as standard library set, exceptions, and support of concurrency. Oberon-2 is an object-oriented programming (OOP) language based on Modula-2. With introduction of object-oriented facilities, extensible project design became much easier. Meanwhile Oberon-2 is quite simple and easy to learn and use, unlike other OOP languages such as C++ or Smalltalk. Moving to a new language usually means throwing away or rewriting your existing library set which could have been the work of many years. XDS allows programmer to mix Modula-2, Oberon-2, C and Assembler modules and libraries in a single project. XDS includes subsets of standard ISO and PIM Modula-2 libraries complete with ANSI C standard interface which can be accessed and used from both Modula-2 and Oberon-2. About the pre_release Version ----------------------------- This version is a pre-release distribution of XDS OS/2 package, including: - "xds" - interactive programming environment - "xc" utility, which combines Modula-2 and Oberon-2 to compilers and "make" facilities - ISO Modula-2 Library - A subset of the PIM Compliant Library - A subset of the ANSI C Library Interfaces The "xc" utility will only operate on computers that are IBM PS2 or IBM AT compatible and contain an 80386 processor with numerical coprocessor or better. Using XDS --------- The XDS Modula-2 and Oberon-2 compilers are activated from a single utility "xc". When invoked without parameters, the utility shows some "help" information. The working configuration includes: xc.exe Modula-2/Oberon-2 development system xc.msg Contains texts of error messages xc.red Search path redirection file (optional) xc.cfg Configuration file (optional) When invoked the "xc" tries to locate the xc.red file in the current directory or in the directory where "xc.exe" (C:\XDS\BIN) is placed. Other system files ("xc.msg" and "xc.cfg") are sought by paths defined by "xc.red". If "xc.red" is not found, or it does not contain paths for a system file, the system file is sought in the current directory or in the directory where "xc.exe" is placed. Redirection File ---------------- The file "xc.red" consists of several lines of the form: pattern = directory_path {";" directory_path} Example of redirection file: *.def = def *.mod = mod *.sym = sym; c:\xds\sym; xc.cfg = .; c:\xds\bin XDS will search definition modules in the "def" sub-directory, symbol files in the "sym" sub-directory and then in "c:\xds\sym" and files "xc.cfg", "xc.msg" will be sought in the current directory and then in "c:\xds\bin". Configuration File ------------------ The configuration file can be used to set the default values of options and equations. When invoked, XDS searches for configuration file "xc.cfg". Every line in the configuration file can contain only one compiler option or equation setup directive. It is possible to put comment lines into configuration file. Comment lines should start with a "%" symbol. setup_directive = declare_option | declare_synonym | set_option_on | set_option_off | set_equation declare_option = '-' name ':' [ '+' | '-' ] declare_synonym = '-' name ':=' name set_option_on = '-' name '+' set_option_off = '-' name '-' set_equation = '-' name ['='] value To set an option ON, use "-OPTION+" directive. To set an equation, use "-OPTION = VALUE" directive. Option and equation names are case independent. Arbitrary spaces are permitted in the configuration file. Example: % this is a comment % equation option - set Oberon-2 file extension - Oberon = ob2 % boolean option - allow Modula-2 extensions - M2extensions + % end of configuration file Invoking XDS ------------ "xc" is invoked from the command line of the following form xc { OPERATION MODE | OPTION | NAME } where NAME for different operation modes is a module name, file name or a project name. XDS has the following modes of operation: Mode | Meaning ------------+--------------------------------------------------- COMPILE | Compile all modules given in the command line PROJECT | Make all projects given in the command line MAKE | Check dependencies and recompile GEN | Generate makefile for all projects BROWSE | Extract definitions from symbol files HELP | Print help and abort the program ------------+--------------------------------------------------- Both the PROJECT and MAKE modes have two optional submodes of operation: BATCH and ALL. Two auxiliary operation submodes - OPTIONS and EQUATIONS can be used to inspect the set of compiler options and equations and their values. From the command line, the compiler mode is set using '=', followed by the required mode. Only the unique portion of a name need be specified. Operation mode names are not case sensitive, thus =PROJECT is equivalent to =p =BROWSE is equivalent to =Bro Operation modes and options can be placed everywhere in the command line. Thus the following two invocation are equal: xc =make hello.mod =all -checknil+ xc -checknil+ =a =make hello.mod COMPILE mode ------------ xc [=compile] { FILENAME | OPTION } COMPILE is the default mode, and can be invoked simply by supplying "xc" with a source module(s) to compile. If xc is invoked without a given mode, COMPILE mode is assumed. In order to determine which compiler to use, xc looks at the extensions of given source files. The default mapping of extensions is given below : .mod - Modula-2 implementation module .def - Modula-2 definition module .ob2 - Oberon-2 module For example: xc hello.mod will invoke Modula-2 compiler, whilst: xc hello.ob2 will invoke Oberon-2 compiler. The user is able to reconfigure the extension mapping. It is also possible to override this extension mapping from the command line, using options M2 and O2: xc hello.mod +o2 (* invokes O2 compiler *) xc hello.ob2 +m2 (* invokes M2 compiler *) MAKE mode --------- xc =make [=batch] [=all] { FILENAME | OPTION } In the MAKE mode the compiler calculates module dependencies (using IMPORT clauses) and then recompiles all modules that necessary. Starting from the files in the command line it tries to find an Oberon module or a definition and implementation module for each imported module. It then tries to do the same for each of the imported modules until all modules are located. Note that search is made for source files only, if a source file is not found, the imported modules will not be appended to the project. Usually, only a Modula-2 program module or Oberon-2 top-level module should be given in the command line. When all modules are gathered, XDS looks to an operation submode. If the BATCH submode is specified, the XDS creates a batch file of all necessary compilations, rather than actually calling the compilers and compiling the source code. If the ALL submode is specified, all gathered files are recompiled, otherwise XDS calculates conditions for recompilation and recompiles only those files that necessary. PROJECT mode ------------ xc =project [=batch] [=all] { PROJECTFILE | OPTION } PROJECT mode is essentially the same as MAKE mode except that the modules to be `made' are provided in a project file. A project file consists of options settings and a list of modules: { OPTION } { !module { FILENAME } } where OPTIONs are the compiler options that all modules should be compiled with, and FILENAMEs are modules in the project. XDS recursively looks at all the given files for any imported modules. Thus, usually, a project file would consist of one single module, the main program module. As in MAKE mode, ALL and BATCH submodes can be used. GEN mode -------- xc =gen { PROJECTFILE | OPTION } The GEN operation mode allows you to generate a file, containing information about your project. The most important usage is to generate a makefile or task file for linker. This DEMO documentation does not contain the description of template files. The DEMO package contains the "xds.tem" template file (See on C:\XDS\BIN) which can be used to create task file for link386. XDS also process a template if the option MAKEFILE is set on, when invoking the xc utility in the PROJECT mode. BROWSE mode ----------- xc =browse { MODULENAME | OPTION } The BROWSE operation mode allows you to generate a pseudo definition module for an Oberon-2 module. In this mode "xc" scans the corresponding symbol file and outputs definitions of all client-visible symbols in a Modula-2-like definition module in Oberon-2 syntax. This pseudo definition module will not necessarily contain legal Modula-2 or Oberon-2 and thus any output should not be treated as such. The MAKEDEF option provides an alternative method of producing pseudo definition modules, preserving so-called exported comments if necessary. If the option is set the compiler will create a definition for the each Oberon module compiled. ALL submode ---------- In both PROJECT and MAKE modes, XDS checks the time stamps of the files concerned and only recompiles when necessary. If ALL submode is set, the time stamps are ignored, and all files are compiled. BATCH submode ------------- The BATCH submode, creates a batch file of all necessary compilations when specified from either PROJECT or MAKE modes, rather than actually calling the compilers and compiling the source code. OPTIONS submode --------------- The OPTIONS submode allows you to inspect the values of options set in the configuration file, project file and on the command line. It can be used along with COMPILE, MAKE and PROJECT modes. The following invocation will print (to the standard output) the list of all defined options, including all pre-declared options, all options declared in the configuration file, in the project file "my.prj" and on the command line (XYZ option): xc =options -prj=my.prj -xyz:+ In the PROJECT mode options are listed for each project file given on the command line. EQUATIONS submode ----------------- The EQUATIONS submode allows you to inspect the values of options set in the configuration file, project file and on the command line. It can be used along with COMPILE, MAKE and PROJECT modes. Using the Modula-2 Compiler --------------------------- Create a file called "hello.mod", containing the following text: MODULE hello; IMPORT InOut; BEGIN InOut.WriteString("Hello World"); InOut.WriteLn; END hello. Now type: xc hello.mod It will generate hello.obj. Using the Oberon-2 Compiler --------------------------- The Modula-2 source code just shown is also perfectly valid Oberon-2. Rename the source file to "hello.ob2". As in Modula-2, this source code in Oberon-2 constitutes a top-level module or program module. Unlike Modula-2, there is no syntactic distinction between a top-level module and any other service module. The Oberon-2 compiler must be specifically told that this is a program module by using option "MAIN". Type: xc hello.ob2 +MAIN +DEF During the compilation, the Oberon-2 compiler produces files "hello.obj" and "hello.sym". Running a Program ----------------- After compilation of all modules composing your project you have to link the program. link386 hello.obj, ,\xds\lib\libxds.lib+\xds\lib\os2min; After that, one can invoke the program: hello It may be necessary to specify additional options to put debug information into hello.exe file, or to specify stack size. Check "link386" documentation to get help. To simplify linking, XDS allows to specify a linker command line in the XDS environment, using the LINK equation. A command line, specified by the equation will be executed after successful compilation of the whole project. Usually, the equation is specified in the project file. Example of project file hello.prj: -link="link386 hello.obj, ,\\xds\\lib\\libxds.lib;" !module hello.mod The project file contains the LINK equation and a name of program module. The following invokation xc hello.prj =project will compile modules constituting the project (if required) and then execute the linker command line specified. If your project contains more than one module, it'd be better to use universal scheme. The XDS distibution contains the template file "xds.tem" (C:\XDS\BIN\xds.tem). To use it, write a project file hello.prj: -template = xds.tem -mkfname = tmp -mkfext = lnk -makefile+ -link = "link386 @%s",mkfname !module hello.ob2 Then call xc hello =p After the successful compilation xc will call linker. See also SAMPLES.TXT for more information. Configuring XDS for a C Compiler -------------------------------- XDS allows to use C functions and libraries in your projects. Different C compilers have different naming and calling conventions. Your have to specify your C compiler in XDS environment, using the CC equation. The equation forces XDS to call all C functions in a way compatible with the specified C compiler. Also the compiler sets default values of additional configuration options according to the value of the equation. Currently, XDS supports Watcom compiler and SysCall calling conventions. The corresponding values of the CC equations are WATCOM and OS2SYSCALL (written in any case). To configure XDS append the line -cc=Watcom or -cc=OS2SYS_CALL in your configuration file. Options and Equations --------------------- A rich set of XDS options and equations allows one to control source language, code generated and internal limits and settings. Note: All options in the command line are applied to all operands. Precedence of Compiler Options ------------------------------ The "xc" utility can receive its options from - configuration file "xc.cfg" - command line - project file (if present) - inline in source text (not all options may be used there) At any point during operation, the most recent option value setting will be in effect. Thus, if the compiler equation OBERON was set to ".ob2" in the configuration file, but then set on the command line as "OBERON=.o", then XDS will recognize ".o" as the Oberon-2 module extension. Compiler Options ---------------- The following is the subset of compiler options (default values are pointed out as [ON] or [OFF]: CHECKDINDEX [ON] Dynamic array bounds check CHECKINDEX [ON] Static array bounds check CHECKNIL [ON] NIL pointer dereference check CHECKPROC [ON] NIL formal procedure call check CHECKRANGE [ON] Range checks for ranges and enumerations CHECKSET [ON] Range check in set operations CHECKTYPE [ON] (Oberon-2 only) Dynamic type guards generation DEF [OFF] Permission to change symbol file. XDS creates a temporary symbol file every time an Oberon-2 module is compiled and compares this symbol file with the existing one, overriding the file with the new one if necessary. If option DEF is OFF (default), the compiler will give an error if the symbol file (and the module interface respectively) had been changed and will not replace the old symbol file. M2ADDTYPES [OFF] (Modula-2 only) Add SHORT and LONG types. When ON, the compiler will recognize as pervasive identifiers the types SHORTINT, LONGINT, SHORTCARD and LONGCARD. M2BASE16 [OFF] (Modula-2 only) When ON, basic types (INTEGER, CARDINAL and BITSET) are 16-bits wide in Modula-2. M2EXTENSIONS [OFF] (Modula-2 only) XDS Modula-2 extensions. When ON, the compiler will allow the use of XDS Modula-2 language extensions. MAIN [OFF] (Oberon-2 only) Oberon-2 main module. When ON, the compiler will generate a program entry point ("main" function) for this Oberon-2 module. Inline usage recommended, ie: <*+ MAIN *> MODULE Example; ... END Example. O2EXTENSIONS [OFF] (Oberon-2 only) XDS Oberon-2 extensions. When ON, the compiler will allow the use of XDS Oberon-2 language extensions. O2ISOPRAGMA [OFF] (Oberon-2 only) When ON, the compiler will allow the use of ISO M2 style pragmas <* *>. The option is set ON in "C:\XDS\BIN\xc.cfg". It is required to compile Oberon samples, containing ISO style pragmas, such as <*+ MAIN *>. O2NUMEXT [OFF] (Oberon-2 only) Enables Oberon-2 numeric extensions (complex types and in-line exponentiation operator "**"). WOFF[number] [OFF] WOFF without parameter turn all warnings OFF. When WOFF<number> (i.e. WOFF301) is ON, the compiler will not report warning <number> (i.e. 301). See "xc.msg" file for warning texts and numbers. Libraries --------- The pre-release package contains libraries from the following library sets: - Interface to ANSI C libraries - PIM compliant libraries - ISO standard Modula-2 libraries - Interface to Oberon run-time support All these libraries can be used in both Modula-2 and Oberon-2 programs. We recommend to use ISO libraries to improve portability of your software. This documentation does not contain the description of libraries, use corresponding definition modules instead (C:\XDS\DEF). Interface to ANSI C libraries ----------------------------- The following libraries provides an interface to ANSI C libraries: stdlib interface to <stdlib.h> stdio interface to <stdio.h> math interface to <math.h> time interface to <time.h> PIM compliant libraries ----------------------- The following libraries defined in PIM ("Programming in Modula-2") are provided: InOut general purpose IO operations MathLib0 mathematical functions RealInOut REAL numbers IO operations LongInOut LONGREAL numbers IO operations Terminal computer's terminal IO operations Since PIM "Storage" library is not compatible with the corresponding ISO library, it is omitted. ISO standard Modula-2 libraries ------------------------------- The following ISO libraries are included in the package: ProgramArgs Access to program arguments StreamFile Sequentional data streams IOConsts Types and constants for IO modules TextIO Character and strings type IO operations STextIO TextIO over default channels WholeIO Whole numbers IO operations SWholeIO WholeIO over default channels RealIO Real number IO operations SRealIO RealIO over default channels IOResult Read results for specified channels SResultIO Read results for the default input channel ConvTypes Common types used in the string conversion modules RealStr REAL/string conversions WholeStr Whole-number/string conversions CharClass provides predicates to test a given value of the character type RealMath Mathematical functions for the type REAL LongMath Mathematical functions for the type LONGREAL Storage Facilities for dynamically allocating and deallocating storage Strings Facilities for manipulating strings SysClock Facilities for accessing a system clock The following system libraries are available in the package: TERMINATION Facilities for enquiries concerning the occurrence of termination events. EXCEPTIONS Facilities for raising user exceptions and for making enquiries concerning the current execution state. M2EXCEPTION Facilities for identifying language exceptions. Note: all these system libraries are not embedded in the compiler, ie. the corresponding symbol files shall be available to use them. The system module "COROUTINES" is not available in the DEMO version. Interface to Oberon run-time support ------------------------------------ The "oberonRTS" library provides an interface to Oberon-2 run-time support functions, including garbage collection and meta-language facilities. See also SAMPLES.TXT. Further Reading --------------- [1] H. Mossenbock, N. Wirth The Programming Language Oberon-2 Structured Programming, 1991, 12, 179-195 [2] N. Wirth Programming in Modula-2 (4th edition) Springer-Verlag, 1988. ISBN 0-387-50150-9 [3] N. Wirth From Modula-2 to Oberon Software, Practice and Experience 18:7 (1988), 661-670 [4] M. Reiser, N. Wirth Programming in Oberon-2 - Steps Beyond Pascal and Modula ACM Press, Addison Wessley, 1992. ISBN 0-201-56543-9 [5] H. Mossenbock Object-Oriented Programming in Oberon-2 Springer-Verlag, 1993. ISBN 0-387-56411-X, 0-387-56411-X Internet newsgroups comp.lang.modula2 and comp.lang.oberon are useful not only for beginners but for experienced Modula-2 programmers as well. [end of document]