This is gpc.info, produced by makeinfo version 4.0 from gpc.texi.

INFO-DIR-SECTION GNU programming tools
START-INFO-DIR-ENTRY
* GPC: (gpc).                   The GNU Pascal Compiler.
END-INFO-DIR-ENTRY
INFO-DIR-SECTION Individual utilities
START-INFO-DIR-ENTRY
* GPC: (gpc)Invoking GPC.       The GNU Pascal Compiler.
END-INFO-DIR-ENTRY

   This file documents the GNU Pascal Compiler.

   Copyright (C) 1988, 1996-2000 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "GNU General Public License", "The GNU
Project", "The GNU Manifesto" and "Funding for Free Software" are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the sections entitled "GNU General Public
License", "The GNU Project", "The GNU Manifesto" and "Funding for Free
Software" and this permission notice, may be included in translations
approved by the Free Software Foundation instead of in the original
English.


File: gpc.info,  Node: Implemented Features,  Prev: Fixed Bugs,  Up: Done

Features that have been implemented
-----------------------------------

   This section lists the new features implemented since 1st Nov 1997,
together with the date (YYYYMMDD) on which they were implemented.

   After the release of GPC 2.1, this section will be cleared, and the
features implemented after that release will either be listed in a new
section here or directly in the "news".

   * 20001017: DisposePPStrings

   * 20001016: `GetIOErrorMessage' now returns a string rather than a
     `CString'

   * 20001016: RegExType: changed the field `Error' from `CString' to
     `PString'

   * 20001016: GlobBuffer: replaced fields `Count' and `Result' by
     `Result' (`PPStrings')

   * 20001015: `GetOptErrorFlag' is now True by default

   * 20001014: StringUtils: new functions StrCount, StrReplace,
     Char2Digit, QuoteString, UnQuoteString, ExpandTabs,
     ExpandCEscapeSequences

   * 20001007: many new docdemo programs

   * 20001007: new options `-W[no-]underscore'

   * 20001003: many new docdemo programs

   * 20001001: many new `Reference' entries and new material in the
     `Programming' chapter in the manual

   * 20000917: added the `Size' field of BindingType again

   * 20000910: don't add a newline on `Extend' to text files that were
     bound as binary

   * 20000909: `GetOptLong' can now optionally derive the short options
     from the `LongOptions' array

   * 20000909: `CStringCharPos', `CStringLastCharPos': renamed to
     `CStringChPos' and `CStringLastChPos' to avoid confusion with
     `CharPos' and `LastCharPos'

   * 20000902: CRT: new procedure CRTSetTerminal

   * 20000828: new procedure FileMove

   * 20000826: new constant DayOfWeekName

   * 20000825: integrated the FAQ into the GPC Manual

   * 20000820: new routines SystemInfo, FileLock, FileUnlock, Alarm

   * 20000819: StringUtils: new unit, implementing a string hash table
     (further routines to be added)

   * 20000817: CRT: new routines CRTSavePreviousScreen,
     CRTSavePreviousScreenWorks

   * 20000806: new function GetTerminalName

   * 20000803: new functions UserID, GroupID

   * 20000723: new parameter `AccessTime' to SetFileName

   * 20000716: renamed the file mode constants from `fmFOO' to `fm_FOO'

   * 20000716: new routines MemoryMap, MemoryUnMap

   * 20000626: the default make target for testing GPC is called
     `pascal.check' (or `check-pascal') rather than `check-gpc' now;
     the test must be run in the build directory (not the `p'
     subdirectory) or in the `test' subdirectory of the source
     directory now

   * 20000619: `--borland-pascal': ignore everything after `end.' (also
     takes care of "^Z" characters at the end of Dos text files)

   * 20000613: Dos: special versions of GetCBreak and SetCBreak for
     MS-Windows

   * 20000612: Dos: new procedures (not only on DJGPP) DosVersion,
     SetDate, SetTime

   * 20000611: CRT: new procedures `SetScreenSize', `SetMonochrome';
     renamed `IsMonoMode' to `IsMonochrome'

   * 20000610: each of the parameters `Dir', `Name' and `Ext' to
     `FSplit' may now be null

   * 20000607: Single RTS command line options are now recognized with
     `--gpc-rts=OPTION' as well, and this can be given multiple times

   * 20000607: new procedure ResetGetOpt

   * 20000606: CRT: new functions CtrlKey, AltKey; new constants
     chCtrlA ... chCtrlZ, kbCtrlA ... kbCtrlZ

   * 20000605: new routines BlockSignal, SignalBlocked

   * 20000605: CRT with ncurses: changing the screen is now done
     through a shell command definable in the environment variable
     `RESIZETERM' (which defaults to `resize', `SVGATextMode' and
     `setfont'); the variables `crt_setfont_command_80_25',
     `crt_setfont_command_80_50', `crt_setfont_command_40_25' and
     `crt_setfont_command_40_50' (Linux only) were removed

   * 20000604: Dos: new procedures (not only on DJGPP) GetCBreak,
     SetCBreak, GetVerify, SetVerify

   * 20000604: new routines SetInputSignals, GetInputSignals

   * 20000531: new demo program `DynamicArrayDemo'

   * 20000530: integrated the interface of all units included with GPC
     into the GPC Manual; formatted the interfaces, also of gpc.pas,
     more nicely

   * 20000528: integrated the To-Do list and the list of new GPC
     features into the GPC Manual

   * 20000528: include the demo programs printed in the GPC Manual
     (currently 59, but expected to become more) into binary
     distributions in a directory `docdemos'

   * 20000527: restructured the GPC Manual

   * 20000526: in the GPC Manual, the list of command-line options and
     the list of keywords for the various dialects were updated, and
     from now on, they are automatically kept up to date, directly from
     the source

   * 20000526: changed the license of most units and the RTS from LGPL
     + exception to GPL + exception

   * 20000525: ReverseBytes, ConvertFromLittleEndian,
     ConvertFromBigEndian, ConvertToLittleEndian, ConvertToBigEndian:
     new parameter `ElementSize'; new demo program `EndianDemo'

   * 20000523: derive the keyword list in the documentation directly
     from the source

   * 20000521: WinCRT: new unit (identical to CRT)

   * 20000521: CRT: GetScreenSize renamed to ScreenSize (WinCRT
     compatibility); added some missing WinCRT compatibility stuff

   * 20000519: new function GetMountPoint

   * 20000516: new field Device in BindingType

   * 20000516: BlockReadLittleEndian, BlockReadBigEndian,
     BlockWriteLittleEndian, BlockWriteBigEndian: new parameter
     `ElementSize'

   * 20000516: new procedures ReadStringLittleEndian,
     ReadStringBigEndian, WriteStringLittleEndian, WriteStringBigEndian

   * 20000509: System: new functions Ofs, Seg, Ptr, CSeg, DSeg, SSeg,
     SPtr and a number of variables (mostly useless and only for BP
     compatibility)

   * 20000507: new procedure IOErrorFile

   * 20000505: `asmname' in variable and constant declarations must now
     come after the type; furthermore, `asmname' doesn't imply
     `external' anymore

   * 20000502: SeekEOF, SeekEOLn

   * 20000421: new function InstallSignalHandler

   * 20000418: recognize files with `.pp' or `.dpr' extension as Pascal
     sources

   * 20000415: new switch `{$[no-]debug-statement[=foo]}' (call a
     procedure automatically before each statement for debugging)

   * 20000415: RTS command line options are now recognized after
     `--gpc-rts' instead of `-Grts'

   * 20000415: removed `__cstring__', `__void__'

   * 20000414: the RTS command line options are now also available as
     long options; new RTS options `--version' (print RTS version and
     exit), `--abort-on-error' (abort with SIGABRT on runtime error),
     `--error-file', `--error-fd' (dump runtime error messages and
     strack trace to given file name or FD)

   * 20000412: runtime errors are now printed with their address to
     help debugging (using addr2line), and the address is stored in
     ErrorAddr

   * 20000411: new functions ReturnAddress, FrameAddress

   * 20000411: local compiler directives and defines with `{$local}'
     and `{$endlocal}' (fjf430*.pas)

   * 20000409: `{$ifopt}'

   * 20000409: case-[in]sensitve defines with {{$csdefine}} and
     {{$cidefine}} (or `-csdefine' and `cidefine'); `{$define}' (but
     not `--define') is now case-insensitive

   * 20000407: make `mod' with negative right operand work like in BP;
     allow expressions like `-2 * +3'

   * 20000407: `make check' now runs the current test suite rather than
     the (obsolete and removed) dejagnu tests; the test suite now
     produces a summary output by default, `make pascal.check-long' (or
     `check-pascal-long') produces the long output format as before

   * 20000407: new option `-W[no-]warnings' (enable/disable warnings)

   * 20000407: make single-letter compiler directives BP compatible
     (`--borland-pascal': ignore `$F', `$O' etc., ignore numbers after
     `$M'); new option `--[no-]stack-checking', also as compiler
     directives `{$[no-]stack-checking}' or `{$S+}'/`{$S-}'; new option
     `--[no-]typed-address', also as compiler directives
     `{$[no-]typed-address}' or `{$T+}'/`{$T-}'; replace
     `{$P+}'/`{$P-}' by `{$[no-]pedantic}' (or `--[no-]pedantic' on the
     command line); ignore `{W+}'/`{W-}' in `--borland-pascal' mode

   * 20000406: CRT: new variable CRTAutoInitProc; new procedure
     CRTNotInitialized

   * 20000405: new switches `--[no-]macros'

   * 20000402: new switches `-W[no-]field-name-problem'

   * 20000402: allow all `-Wfoo' options also as `{$W foo}' directives
     (no more `{$Wfoo}' like in the last alpha release!)

   * 20000331: replace `--no-nested-comments' by `--mixed-comments'
     (and vice versa); new options `--[no-]nested-comments',
     `-W[no-]mixed-comments', `-W[no-]nested-comments' (mixcom*.pas,
     nest*.pas); allow comments (but not compiler directives) within
     compiler directives

   * 20000331: make C style char escapes the default for strings
     enclosed in `""' (like `--char-escapes' used to do), and use `\"'
     rather than `""' to get a verbatim `"' in them; remove the
     `--[no-]char-escapes' switch and the `{$E[+-]}' compiler directive

   * 20000331: Delphi style `//' comments, new switch
     `--[no-]delphi-comments' and compiler option
     `{$[no-]delphi-comments}'

   * 20000327: new header gpc-in-c.h for inclusion of GPC code into C
     programs; new demo program GPC_C_Pas to demonstrate this

   * 20000327: allow `^const' to create a pointer to a constant

   * 20000327: don't expand macros in `--borland-pascal' and `--delphi'

   * 20000327: Dos: added the unportable Dos-only routines under DJGPP
     if `__BP_UNPORTABLE_ROUTINES__' is defined

   * 20000326: removed `__asmname__', `__const__', `__external__',
     `__inline__', `__static__', `__volatile__', `__byte__',
     `__short__', `__long__', `__longlong__', `__unsigned__'

   * 20000322: cleaned up the lexer; removed some fossils, e.g.
     `--c-numbers'

   * 20000306: file sizes can now be bigger than `Integer' (e.g. 64 bit
     files on 32 bit machines) if supported by the OS via lseek64() or
     llseek() (e.g. Linux, Solaris, IRIX)

   * 20000221: new types ByteBool, ShortBool, WordBool, MedBool,
     LongBool, LongestBool, Boolean(n) (fjf395.pas)

   * 20000219: build in Include, Exclude

   * 20000213: make `nil' also a value of any procedural/functional
     type (fjf258[a-e].pas)

   * 20000211: new functions `PathExists', `DataDirectoryName', new
     parameter `Prefix' to `ConfigFileName'

   * 20000211: new fields SymLink, TextBinary in BindingType; new
     procedure AssignBinary; removed variable TextFilesBinary

   * 20000202: new options `--[no-]progress-messages',
     `--[no-]progress-bar'

   * 20000202: ignore `{$L+}'/`{$L-}' directives (for BP compatibility)

   * 20000131: new unit MD5; new demo program MD5Demo

   * 20000124: new unit FileUtils; new demo program FindFilesDemo

   * 20000111: changed the internal file handling from using `FILE *'
     to integer file handles, to make it more efficient and get rid of
     some problems; replaced the `CFile' field in `BindingType' by a
     `Handle' field; replaced the `AssignCFile' procedure by an
     `AssignHandle' procedure; removed the `GetFile' function (note
     `FileHandle')

   * 20000111: new function Integer2String

   * 20000106: new functions IsPrintable, CharSet2RegEx

   * 19991217: System: new functions RealToBPReal, BPRealToReal

   * 19991217: new functions IsInfinity, IsNotANumber, SplitReal

   * 19991124: new demo program ProcVarDemo

   * 19991117: new function LongReal2Str to work-around the `Work
     (Real)' problem under IRIX

   * 19991110: CRT: DJGPP: added support for 40 column modes (requires
     updated PDCurses library)

   * 19991104: new demo program FExpandDemo

   * 19991103: CRT: changed the define to get an X11 version from
     XCURSES to X11

   * 19991102: added `Special' field to BindingType

   * 19991101: new function GetShellPath

   * 19991101: new option `--[no-]transparent-file-names' to derive the
     external file names from the file variable names
     <199909010105.VAA23844@kaylor.ncifcrf.gov> (fjf394.pas)

   * 19991025: CRT: new procedures SimulateBlockCursor,
     SimulateBlockCursorOff

   * 19991023: CRT: don't initialize curses at the beginning of the
     program, but initialize it automatically when the first CRT
     routine is called (for BP compatiblity); new procedure CRTInit to
     explicitly initialize CRT which also sets some defaults (PCCharSet
     and update level) to more natural (and less BP compatible) values

   * 19991023: CRT: allow any of the parameters to GetWindow to be null

   * 19991014: new procedure ReAlloc; previous ReAlloc function (libc)
     renamed to CReAlloc; new variable ReAllocPtr

   * 19991014: new functions GetPasswordEntryByName,
     GetPasswordEntryByUID, GetPasswordEntries; make ExpandEnvironment
     recognize `~user'

   * 19991006: RegEx: support for converting subexpression references
     to upper/lower case while replacing them with `\u7'/`\l7'

   * 19990924: new functions MemCompCase, StrEqualCase, PosCase,
     LastPosCase, PosFromCase, LastPosTillCase, IsPrefixCase,
     IsSuffixCase, ExecuteNoTerminal

   * 19990922: System: new procedure SetTextBuf for BP compatibility

   * 19990905: before building the RTS, make sure that the compiler
     version used is current, to prevent strange bugs when building
     with an older version <17698.990820@mg.dp.ua>

   * 19990805: new procedure SeedRandom; new variable SeedRandomPtr;
     automatically initialize the random number generator like
     Randomize does at the first call to Random unless SeedRandom was
     called before (only for the default RNG; not the BP compatible one
     in the System unit)

   * 19990802: new procedure RestoreTerminalClearCRT

   * 19990801: CRT: added support for panels (overlapping windows); new
     routines GetActivePanel, PanelNew, PanelDelete,
     PanelBindToBackground, PanelIsBoundToBackground, PanelActivate,
     PanelHide, PanelShow, PanelHidden, PanelTop, PanelBottom,
     PanelMoveAbove, PanelMoveBelow, PanelAbove, PanelBelow,
     IgnoreCursor

   * 19990728: new demo program ArraySliceDemo

   * 19990727: CRT: replaced the variables PCCharSet and
     UseControlChars by routines SetPCCharSet, GetPCCharSet,
     SetControlChars, GetControlChars

   * 19990727: GMP: new procedures mpf_exp, mpf_ln, mpf_pow,
     mpf_arctan, mpf_pi

   * 19990726: implemented environment variable management in Pascal,
     so that it's independent of libc differences (e.g. the presence or
     not of `environ'); new routines UnSetEnv, GetCEnvironment; removed
     PutEnv and CSystem functions (obsoleted by SetEnv and Execute);
     turned the Environment variable into a schema which contains the
     environment variables as CStrings; allow empty and case-sensitive
     environment variables within GPC programs even under Dos

   * 19990723: make `{$gnu-pascal}' completely equivalent to
     `--gnu-pascal'; add `{$gnu-pascal}' to all included units so they
     can also be compiled with `--automake' when `--foo-pascal' options
     are given (dialec[1-6].pas)

   * 19990723: new options `-W[no-]typed-const' and `-W[no-]near-far'

   * 19990720: new functions SetTerminalProcessGroup,
     GetTerminalProcessGroup

   * 19990719: new demo program RealPower

   * 19990709: new constants for signals; new routines Kill, WaitPID,
     SetProcessGroup (formerly in the Pipe unit)

   * 19990622: new function FileHandle; un-built-in GetFile - it is now
     in the GPC unit, but obsolete

   * 19990622: new routines AllocateBigMem, DisposeBigMem,
     MoveToBigMem, MoveFromBigMem, MapBigMem for uniform access to big
     memory blocks for GPC and BP; new demo program BigMemDemo

   * 19990617: integrated the PExecute unit into the RTS

   * 19990612: `register' directive

   * 19990609: integrated the GetOpt unit into the RTS (because the RTS
     uses it, anyway); removed the Internal unit from the installation
     (because using it from programs is really not recommendable)

   * 19990603: new procedure SetEnv (makes obsolete libc's PutEnv)

   * 19990601: included a `GPC' unit for BP to provide some GPC
     compatibility to BP programs

   * 19990527: new demo program TrapDemo

   * 19990527: new units HeapMon, Trap

   * 19990527: new function ReleaseCount

   * 19990526: new routines RegisterRestoreTerminal,
     UnregisterRestoreTerminal, RestoreTerminal

   * 19990502: new routine SetProcessGroup

   * 19990424: new function RegExPosFrom

   * 19990403: new constant FileNamesCaseSensitive, new function
     FileNameLoCase

   * 19990327: added 20 demo programs

   * 19990325: new function GetMicroSecondTime

   * 19990324: renamed the CString routines in the RTS so they get a
     `CString' prefix, moved the BP compatibility identifiers for the
     same routines into the `Strings' unit

   * 19990308: `--no-default-paths'

   * 19990307: new functions IOSelect, IOSelectRead

   * 19990225: `--no-{unit,object}-path'

   * 19990225: `--[no-]io-checking' and `{$[no-]io-checking}' as
     synonyms for `{$I+-}'

   * 19990219: recognize (but currently ignore)
     published/public/protected/private

   * 19990218: renamed DataReady to CanRead

   * 19990213: change warnings of the form `Foo-Pascal does not have
     foobars' into `foobars are {GPC-specific|a GPC extension}' and add
     spaces before all but the first line of multi-line messages

   * 19990211: new procedures Sleep, SleepMicroSeconds, GetCPUTime

   * 19990211: CRT: new procedures CRTUpdate, CRTRedraw, SetScroll,
     CRTSetCursesMode

   * 19990209: renamed the __BP_INTEGERS__ (System unit) and
     _Borland_16_Bit_ (Dos and WinDos units) defines to
     __BP_TYPE_SIZES__

   * 19990209: Pipe: new parameter `Process' to Pipe; new functions
     WaitPipeProcess, StrSignal, Kill, WaitPID; new constants (actually
     variables) for the signals

   * 19990205: new routines HasWildCardsOrBraces, BraceExpand,
     MultiFileNameMatch, GlobOn, MultiGlob, MultiGlobOn, QuoteFileName,
     UnQuoteFileName, FExpandQuoted, ForceAddDirSeparator,
     FindNonQuotedChar, FindNonQuotedStr, NameExtFromPath; new
     parameter `Quoted' to RelativePath

   * 19990202: new declarations DirRoot, QuotingCharacter, EnvVarChars,
     EnvVarCharsFirst, WildCardChars, FileNameSpecialChars,
     ShellExecCommand

   * 19990127: new functions IsUpCase, IsLoCase, IsAlphaNum,
     IsAlphaNumUnderscore

   * 19990127: CRT: catch some signals and return pseudo function keys
     for them if CheckBreak is False

   * 19990125: added `User', `Group', `Mode' and `INode' fields to
     BindingType; new procedure ChMod

   * 19990125: CRT: react to screen size changes by external events and
     return a pseudo function key

   * 19990115: built in `null' (= `nil^')

   * 19990115: Pipe unit (also for Dos!)

   * 19990115: new function DataReady to check if data can be read from
     a file without blocking

   * 19990110: integrated the `PExecute' unit into GPC

   * 19990102: pass all given options to automake compilations too
     (without having to repeat them with `--automake="foo"'), remove
     `--automake="foo"'

   * 19990101: `--[no-]autolink' (default is autolink)

   * 19981228: `--[no-]executable-path',
     `--[no-]unit-destination-path', `--[no-]object-destination-path'

   * 19981222: implemented buffering to speed up reading from files

   * 19981213: integrated the following units into GPC: `GetOpt',
     `RegEx', `GMP', `Ports'

   * 19981212: new string routines: SetString, StringOfChar (Delphi
     compatibility)

   * 19981212: integrated the `DosUnix' unit into GPC

   * 19981210: integrated the `GPCUtil' unit into GPC

   * 19981208: integrated the following units into GPC: `System',
     `Turbo3'

   * 19981208: remove {$W-} as much as possible in the units

   * 19981208: built in Addr, Assigned

   * 19981207: integrated the following units into GPC: `CRT', `Dos',
     `Overlay', `Printer', `Strings', `WinDos'

   * 19981206: `--unit-path' (upath.pas), `--object-path' (opath.pas);
     don't allow them in a source file

   * 19981206: allow `Copy' with 2 arguments (fjf40e.pas)

   * 19981205: `FileName' function with a Pascal string return value

   * 19981205: interpret `{$L foo}' as `-lfoo'; accept files with `.so'
     extension in `{$L}'

   * 19981203: pre-define `__OS_DOS__' on Dos-like systems

   * 19981202: `--uses=foo(bar.pas),bar,baz(../baz.pas)' (fjf101b.pas)

   * 19981202: make `=' and so on for strings work as exact comparisons
     (`--borland-pascal'; `--[no-]exact-compare-strings')
     (fjf38{,[a-f]}.pas)

   * 19981201: pre-define __BORLAND_PASCAL__ etc. depending on the
     dialect options and __GNU_PASCAL__ if no dialect option was given
     (dialdef{,[1-6]}.pas)

   * 19981108: new time routines UnixTimeToTimeStamp and
     TimeStampToUnixTime

   * 19981108: added `AccessTime', `ModificationTime' and `ChangeTime'
     fields to BindingType

   * 19981021: added a `Force' field to BindingType

   * 19980921: procedures to convert the endianness of single variables
     (ReverseBytes, Convert{From,To}{Little,Big}Endian) and to do this
     while reading/writing them from/to untyped files
     (Block{Read,Write}{Little,Big}Endian)

   * 19980919: MaxLongInt

   * 19980918: a number of new CString routines, including almost all
     (that weren't already there) of BP's strings unit

   * 19980918: WinDos: portable BP compatible unit with most of the
     routines (those that can possibly be implemented in a portable way)

   * 19980917: CRT: some win (TP 5), wincrt and tpcrt compatibility
     routines and some extensions added

   * 19980915: Internal: unit, with the internal RTS declarations from
     gpc.pas moved into it

   * 19980914: System: remove built-in procedures UpCase, LoCase,
     ChDir, MkDir, RmDir, FileSize, AddNullTerminator, InOutRes,
     IOResult, FileMode

   * 19980914: System: GetDir, Lo, Hi, Swap, MemAvail, MaxAvail,
     HeapError, HeapErrorNilReturn

   * 19980912: declared CGetMem, CFreeMem, ReAlloc

   * 19980909: build in GetMemPtr, FreeMemPtr

   * 19980830: allow `RunError' without arguments (error code -1)

   * 19980830: `--no-automake', `--no-autobuild', `--no-autolink' (each
     of them disables all of `--autolink', `--automake' and
     `--autobuild')

   * 19980822: internally remove the `type' parameter to _p_bind()

   * 19980818: build in GPC_StatFS

   * 19980724: procedures UpCaseString, LoCaseString, functions
     UpCaseStr, LoCaseStr

   * 19980722: longest{int,real}-field-width (fieldw.pas)

   * 19980722: allow collecting options in several `--automake' oder
     `--autobuild' options

   * 19980719: build in ExitCode, ErrorAddr

   * 19980719: Dos: portable BP compatible unit with most of the
     routines (those that can possibly be implemented in a portable way)

   * 19980717: added a `DayOfWeek' field to TimeStamp and a DayOfWeek
     function

   * 19980715: define __GPC_RELEASE__

   * 19980702: new CString functions: StrLen, StrEnd, StrScan,
     StrRScan, StrDup, StrCmp, StrCaseCmp

   * 19980701: new file name declarations and routines: PathSeparator,
     DirSeparator, DirSeparators, ExtSeparator, DirSelf, DirParent,
     NullDevice, TTYDevice, ConsoleDevice, GetCurrentDirectory,
     GetTempDirectory, GetTempFileName, GetTempFileName_CString,
     Slash2OSDirSeparator, OSDirSeparator2Slash,
     Slash2OSDirSeparator_CString, OSDirSeparator2Slash_CString,
     FileExists, DirectoryExists, FSearch, FSearch_Executable,
     Expand_Environment, FExpand, FSplit, DirFromPath, NameFromPath,
     ExtFromPath, OpenDir, ReadDir, CloseDir

   * 19980629: runtime I/O error handling with {$I+-}

   * 19980629: build in NewCString, StrPCopy, CString2String
     (fjf156.pas); String2CString

   * 19980629: build in UpCase, LoCase (locale-dependent, except in
     `--borland-pascal', there only 7 bit ASCII)
     (fjf165a.pas,fjf165b.pas)

   * 19980629: build in High, Low (for ordinal types and arrays)

   * 19980629: build in Random (for LongestCard and LongestReal),
     Randomize

   * 19980629: build in SizeType, PtrDiffType

   * 19980629: build in Pi
     <Pine.SGI.3.96.980318113542.2662B-100000@pugh.bip.bham.ac.uk>

   * 19980629: build in Erase, Rename, ChDir, MkDir, RmDir, FileMode,
     Flush

   * 19980628: internally remove the unused second parameter of
     Dispose/FreeMem

   * 19980626: allow mixing of New/GetMem/Dispose/FreeMem with
     malloc()/free() and with Mark/Release (except free() with Release
     in some cases)

   * 19980623: Turbo3 unit

   * 19980619: Printer: portable (piping to lpr under Un*x)

   * 19980613: `--gnu-pascal'

   * 19980611: CRT: portable ncurses-based unit

   * 19980604: print error messsages in the form: `a.out: [internal
     error:] unknown code in `Write' (error #904)'

   * 19980531: when opening a file with a file name, do a binding
     actually (fjf169.pas)

   * 19980523: added a `MicroSecond' field to TimeStamp

   * 19980520: printer unit for Dos

   * 19980520: `--uses="foo"' (fjf101.pas,fjf101a.pas)

   * 19980511: build in FilePos, FileSize, Truncate, Append

   * 19980511: build in RunError

   * 19980405: accept (but currently ignore) {$ifopt}

   * 19980405: When passing a long string value to a PChar parameter,
     automatically add a #0 terminator

   * 19980405: allow `type y(b:integer)=array[1..b] of integer; x=y;'
     (fjf115.pas)

   * 19980405: Fail (FreeMem, when constructor called by New)

   * 19980405: rename AssignLength and AssignType to SetLength and
     SetType, resp., for Delphi compatibility

   * 19980405: warn about absolute declarations and type casts that can
     cause alignment problems

   * 19980405: `--autobuild'

   * 19980129: predefine symbols for endianness

   * 19980114: recognize `--[no-]truncate-strings' in WriteStr
     (fjf59.pas,truncstr.pas)

   * 19980114: build in untyped files and BlockRead, BlockWrite
     (blockop.pas)

   * 19971230: build in Int, Frac (fjf129.pas)

   * 19971215: build in PtrInt, PtrCard, PtrWord

   * 19971130: allow opening files to `''' or `'-'' for stdin/stdout

   * 19971121: different versions of math functions for LongReal

   * 19971121: allow `with' for schema types
     <199710152102.XAA04800@helena.mi.uni-erlangen.de> (fjf70.pas)

   * 19971121: allow `(var) := expr' (fjf100.pas)

   * 19971112: build in ParamCount, ParamStr (params.pas)

   * 19971112: initialize arrays of text in a loop rather than
     individually (fh19971016) (fjf64.pas)

   * 19971112: build in Seek

   * 19971112: build in FillChar, Move (moving whole words), MoveLeft,
     MoveRight (moving single bytes) (moves.pas)

   * 19971106: build in Delete (fjf62.pas) (fh19971008), Pos
     (delinspos.pas), Copy

   * 19971106: AssignLength (alength.pas)

   * 19971101: make the char array in a String `[1..Capacity+1]' so
     that there's always space for a #0 terminator

   * 19971101: build in Str and Val; Str in `--borland-pascal': only
     one argument

   * 19971101: build in StdErr

   * 19971101: optimize `in' with set constructors

   * 19971101: build in Insert (fjf61.pas)


File: gpc.info,  Node: Internals,  Next: Contributors,  Prev: To Do,  Up: Top

The GPC Source Reference
************************

     "The Source will be with you. Always."

   This chapter describes internals of GPC. It is meant for GPC
developers and those who want to become devlopers, or just want to know
more about how the compiler works. It does not contain information
needed when using GPC to compile programs.

   This chapter tells you how to look up additional information about
the GNU Pascal compiler from its source code.

   *Note:* If you intend to modify GPC's source, please check the top
of each file you're going to modify. A number of files are generated
automatically by various tools. The top of these files will tell you by
which tool and from what file they were generated.  Modifying a
generated file is pointless, since it will be overwritten the next time
the tool is run. Instead, modify the original source (which will often
be easier, anyway, e.g. a bison input file vs. the generated C code).
This also holds for various documentation files.

   Proprietary compilers often come with a lot of technical information
about the internals of the compiler. This is necessary because their
vendors want to avoid to distribute the source of the compiler - which
is always the most definitive source of this technical information.

   With GNU compilers, on the other hand, you are free to get the
source code, look how your compiler works internally, customize it for
your own needs, and to re-distribute it in modified or unmodified form.
You may even take money for this redistribution.  (For details, see the
GNU General Public License, *Note Copying::.)

   The following subsections are your guide to the GNU Pascal source
code. If you have further questions, be welcome to ask them at the GNU
Pascal mailing list (see *Note Support::).

   All file paths mentioned in this chapter are relative to the GNU
Pascal source directory, usually a subdirectory `p' of the GCC source.

* Menu:

* Lexical analyzer::     `gpc-lex.c' -- How GPC reads your source.
* Language definition::  `parse.y' -- ``Syntax diagrams'' as ``Bison'' source.
* Tree nodes::           `../tree.*' -- How GPC stores your program internally.
* Parameter passing::    `gpc-typeck.c' -- How GPC passes parameters.
* GPI files::            `module.c' -- How GPC's precompiled Module/Unit interfaces work.
* AutoMake::             `module.c' -- How GPC automatically ``makes'' a large project.
* File Layout::          Files that make up GPC; Integrating GNU Pascal in GCC

   (Under construction.)

   For more information, see chapters "Portability" through "Fragments"
in *Note the GCC documentation: (gcc)Top.


File: gpc.info,  Node: Lexical analyzer,  Next: Language definition,  Up: Internals

GPC's Lexical Analyzer
======================

   The source file `gpc-lex.c' contains the so-called _lexical
analyzer_ of the GNU Pascal compiler.  (For those of you who know
`flex':  This file was _not_ created using `flex' but is maintained
manually.)  This very-first stage of the compiler (after the
preprocessor which is a separate executable) is responsible for reading
what you have written and dividing it into _tokens_, the "atoms" of
each computer language.  The source `gpc-lex.c' essentially contains
one large function, `yylex()'.

   Here is, for example, where the real number `3.14' and the subrange
`3..14' are distinguished, and where Borland-style character constants
like `#13' and `^M' are recognized.  This is not always a trivial task,
for example look at the following type declaration:

     type
       X = ^Y;
       Y = packed array [^A .. ^B] of Char;
       Z = ^A .. ^Z;

   If you wish to know how GPC distinguishes the pointer forward
declaration `^Y' and the subrange `^A..^Z', see `gpc-lex.c', function
`yylex()', `case '^':' in the big `switch' statement.

   There are several situation where GPC's lexical analzyer becomes
context-sensitive.  One is described above, another example is the token
`protected', a reserved word in ISO-10206 Extended Pascal, but an
ordinary identifier in ISO-7185 Standard Pascal.  It appears in
parameter lists

     procedure foo (protected bar: Integer);

   and says that the parameter `bar' must not be changed inside the
body of the procedure.

   OTOH, if you write a valid ISO-7185 Standard Pascal program, you can
declare a parameter `protected':

     procedure foo (protected, bar: Integer);

   Here both standards contradict each other.  GPC solves this problem
by checking explicitly for "protected" in the lexical analyzer:  If a
comma or a colon follows, this is an ordinary identifier, otherwise
it's a reserved word.  Having this, GPC even understands

     procedure foo (protected protected: Integer);

   without losing the special meaning of `protected' as a reserved word.

   The responsible code is in `gpc-lex.c' - look out for `PROTECTED'.

   If you ever encouter a bug with the lexical analyzer - now you know
where to hunt for it.


File: gpc.info,  Node: Language definition,  Next: Tree nodes,  Prev: Lexical analyzer,  Up: Internals

Language Definition: GPC's Parser
=================================

   The file `parse.y' contains the "bison" source code of GNU Pascal's
parser.  This stage of the compilation analyzes and checks the syntax of
your Pascal program, and it generates an intermediate,
language-independent code which is then passed to the GNU back-end.

   The _bison_ language essentially is a machine-readable form of the
Backus-Naur Form, the symbolic notation of grammars of computer
languages.  "Syntax diagrams" are a graphical variant of the
Backus-Naur Form.

   For details about the "bison" language, see *Note the Bison
documentation: (bison).  A short overview how to pick up some
information you might need for programming follows.

   Suppose you have forgotten how a variable is declared in Pascal.
After some searching in `parse.y' you have found the following:

     /* variable declaration part */
     
     variable_declaration_part:
         LEX_VAR variable_declaration_list semi
       | LEX_VAR semi
           { error ("missing variable declaration"); }
       ;
     
     variable_declaration_list:
         variable_declaration
       | variable_declaration_list semi variable_declaration
           { yyerrok; }
       | error
       | variable_declaration_list error variable_declaration
           {
             error ("missing semicolon");
             yyerrok;
           }
       | variable_declaration_list semi error
       ;

   Translated into English, this means: "The variable declaration part
consists of the reserved word (lexical token) `var' followed by a
`variable declaration list' and a semicolon.  A semicolon immediately
following `var' is an error.  A `variable declaration list' in turn
consists of one or more `variable declarations', separated by
semicolons." (The latter explanation requires that you understand the
recursive nature of the definition of `variable_declaration_list'.)

   Now we can go on and search for `variable_declaration'.

     variable_declaration:
         id_list
           {
             [...]
           }
         enable_caret ':' optional_qualifier_list type_denoter
           {
             [...]
           }
         absolute_or_value_specification
           {
             [...]
           }
       ;

   (The `[...]' are placeholders for some C statements which aren't
important for understanding GPC's grammar.)

   From this you can look up that a variable declaration in GNU Pascal
consists of an "id list", followed by "enable_caret" (whatever that
means), a colon, an "optional qualifier list", a "type denoter", and an
"absolute or value specification".  Some of these parts are easy to
understand, the others you can look up from `parse.y'.  Remember that
the reserved word `var' precedes all this, and a semicolon follows all
this.

   Now you know the procedure how to get the exact grammar of the GNU
Pascal language from the source.

   The C statements, not shown above, are in some sense the most
important part of the bison source, because they are responsible for
the generation of the intermediate code of the GNU Pascal front-end,
the so-called _tree nodes_.  For instance, the C code in "type denoter"
juggles a while with variables of the type `tree', and finally returns
(assigns to `$$') a so-called _tree list_ which contains the information
about the type.  The "variable declaration" gets this tree list (as the
argument `$6') and passes the type information to the C function
`declare_vars()' (declared in `util.c').  This function
`declare_vars()' does the real work of compiling a variable declaration.

   This, the parser, is the place where it becomes Pascal.


File: gpc.info,  Node: Tree nodes,  Next: Parameter passing,  Prev: Language definition,  Up: Internals

Tree Nodes
==========

   If you want really to understand how the GNU Pascal language
front-end works internally and perhaps want to improve the compiler, it
is important that you understand GPC's internal data structures.

   The data structure used by the language front-end to hold all
information about your Pascal program are the so-called "tree nodes".
(Well, it needn't be Pascal source - tree nodes are language
independent.)  The tree nodes are kind of objects, connected to each
other via pointers.  Since the GNU compiler is written in C and was
created at a time where nobody really thought about object-orientated
programming languages yet, a lot of effort has been taken to create
these "objects" in C.

   Here is an extract from the "object hierarchy".  Omissions are marked
with "..."; nodes in parentheses are "abstract":  They are never
instantiated and aren't really defined.  They only appear here to
clarify the structure of the tree node hierarchy.  The complete list is
in `../tree.def'; additional information can be found in `../tree.h'.

     (tree_node)
     |
     |--- error_mark  (* enables GPC to continue after first error *)
     |
     |--- (identifier)
     |    |
     |    |--- identifier_node
     |    |
     |    \--- op_identifier
     |
     |--- tree_list  (* general-purpose "container object" *)
     |
     |--- tree_vec
     |
     |--- block
     |
     |--- (type)  (* information about types *)
     |    |
     |    |--- void_type
     |    |
     |    |--- integer_type
     |   ...
     |    |
     |    |--- record_type
     |    |
     |    |--- function_type
     |    |
     |    \--- lang_type  (* for language-specific extensions *)
     |
     |--- integer_cst  (* an integer constant *)
     |
     |--- real_cst
     |
     |--- string_cst
     |
     |--- complex_cst
     |
     |--- (declaration)
     |    |
     |    |--- function_decl
     |   ...
     |    |
     |    |--- type_decl
     |    |
     |    \--- var_decl
     |
     |--- (reference)
     |    |
     |    |--- component_ref
     |   ...
     |    |
     |    \--- array_ref
     |
     |--- constructor
     |
     \--- (expression)
          |
          |--- modify_expr  (* assignment *)
          |
          |--- plus_expr  (* addition *)
         ...
          |
          |--- call_expr  (* procedure/function call *)
          |
          |--- goto_expr
          |
          \--- loop_expr  (* for all loops *)

   Most of these tree nodes - struct variables in fact - contain
pointers to other tree nodes.  A `tree_list' for instance has a
`tree_value' and a `tree_purpose' slot which can contain arbitrary
data; a third pointer `tree_chain' points to the next `tree_list' node
and thus allows us to create linked lists of tree nodes.

   One example:  When GPC reads the list of identifiers in a variable
declaration

     var
       foo, bar, baz : Integer;

   the parser creates a chain of `tree_list's whose `tree_value's hold
`identifier_node's for the identifiers `foo', `bar', and `baz'.  The
function `declare_vars()' (declared in `util.c') gets this tree list as
a parameter, does some magic, and finally passes a chain of `var_decl'
nodes to the back-end.

   The `var_decl' nodes in turn have a pointer `tree_type' which holds
a `_type' node - an `integer_type' node in the example above.  Having
this, GPC can do type-checking when a variable is referenced.

   For another example, let's look at the following statement:

     baz := foo + bar;

   Here the parser creates a `modify_expr' tree node.  This node has two
pointers, `tree_operand[0]' which holds a representation of `baz', a
`var_decl' node, and `tree_operand[1]' which holds a representation of
the sum `foo + bar'.  The sum in turn is represented as a `plus_expr'
tree node whose `tree_operand[0]' is the `var_decl' node `foo', and
whose `tree_operand[1]' is the `var_decl' node `bar'.  Passing this
(the `modify_expr' node) to the back-end results in assembler code for
the assignment.

   If you want to have a closer look at these tree nodes, write a line
`(*$debug-tree="Foobar"*)' into your program with `FooBar' being some
identifier in your program.  (Note the capitalization of the first
character in the internal representation.)  This tells GPC to output the
`identifier_local_value' tree node - the meaning of this identifier -
to the standard error device in human-readable form.

   While hacking and debugging GPC, you will also wish to have a look
at these tree nodes in other cases.  Use the `debug_tree()' function to
do so.  (In fact `(*$debug-tree="Foobar"*)' does nothing else than to
`debug_tree()' the `identifier_local_value' of the `Foobar' identifier
node.)


File: gpc.info,  Node: Parameter passing,  Next: GPI files,  Prev: Tree nodes,  Up: Internals

Parameter Passing
=================

   GPC supports a lot of funny things in parameter lists:  `protected'
and `const' parameters, strings with specified or unspecified length,
conformant arrays, objects as `var' parameters, etc.  All this requires
sophisticated type-checking; the responsible function is
`convert_arguments()' in the source file `gpc-typeck.c'.  Every detail
can be looked up from there.

   Some short notes about the most interesting cases follow.

*Conformant arrays:*
     First, the array bounds are passed (an even number of parameters
     of an ordinal type), then the address of the array itself.

*Procedural parameters:*
     These need special care because a function passed as a parameter
     can be confused with a call to the function whose result is then
     passed as a parameter.  See also the functions
     `maybe_call_function()' and `probably_call_function()' in `util.c'.

*Chars:*
     According to ISO-10206 Extended Pascal, formal char parameters
     accept string values.  GPC does the necessary conversion
     implicitly.  The empty string produces a space.

*Strings and schemata:*
     Value parameter strings and schemata of known size are really
     passed by value.  Value parameter strings and schemata of unknown
     size are passed by reference, and GPC creates temporary variable
     to hold a copy of the string.

*`const' parameters:*
     If a constant value is passed to a `const' parameter, GPC assigns
     the value to a temporary variable whose address is passed.

     Even if the parameter is passed by value??? - Frank

*Typeless parameters:*
     These are denoted by `var foo' or `var foo: Void' and are
     compatible to C's `void *' parameters; the size of such entities
     is _not_ passed. Maybe we will change this in the future and pass
     the size for `var foo' parameters whereas `var foo: Void' will
     remain compatible to C.  (Same with `const' instead of `var'.)

*`CString' parameters:*
     GPC implicitly converts any string value such that the address of
     the actual string data is passed.  However, GPC did not implicitly
     append a `Chr (0)' terminator, except for string constants.  It
     does so now.


File: gpc.info,  Node: GPI files,  Next: AutoMake,  Prev: Parameter passing,  Up: Internals

GPI files - GNU Pascal Interfaces
=================================

   This section documents the mechanism how GPC transfers information
from the exporting modules and units to the program, module or unit
which imports (uses) the information.

   A GPI file contains a precompiled GNU Pascal interface.
"Precompiled" means in this context that the interface already has been
parsed (i.e. the front-end has done its work), but that no assembler
output has been produced yet.

   The GPI file format is an implementation-dependent (but not _too_
implementation-dependent ;-) file format for storing GNU Pascal
interfaces to be exported - Extended Pascal and PXSC module interfaces
as well as interface parts of Borland Pascal Units compiled with GNU
Pascal.

   To see what information is stored in or loaded from a GPI file, run
GPC with an additional command-line option `--debug-gpi'.  Then, GPC
will write a human-readable version of what is being stored/loaded to
the standard error device.  (See also: *Note Tree nodes::.)

   While parsing an interface, GPC stores the names of exported objects
in tree lists - in `gpc-parse.y', the bison (yacc) source of GPC's
parser, search for `handle_autoexport'.  At the end of the interface,
everything is stored in one or more GPI files.  This is called in
`gpc-parse.y' - search for `create_gpi_files'.  (See also: *Note
Language definition::, for an introduction to `gpc-parse.y')

   Everything else is done in gpc-module.c.  Here you can find the
source of `create_gpi_files()' which documents the file format:  First,
a header of 33 bytes containing the string `GNU Pascal Module/Unit
Interface\n' is stored, then the name of the primary source file of the
module as a string, then the name of the exported interface as a tree
node (see below), after that all exported names in the order as they
were stored while parsing.

   The names and the objects (i.e. constants, data types, variables and
functions) they refer to are internally represented as so-called _tree
nodes_ as defined in the files `../tree.h' and `../tree.def' from the
GNU compiler back-end.  (See also: *Note Tree nodes::.)  The names are
stored as `identifier_node's, their meanings as
`identifier_global_value's of these nodes.  The main problem when
storing tree nodes is that they form a complicated tree in memory with
a lot of circular references making it hard to decide which information
must be stored and which mustn't.

   The functions `load_tree()' and `store_tree' load/store a tree node
with the contents of all its contained pointers in a GPI file.

   Each tree node has a `tree_code' indicating what kind of information
it contains.  Each different tree node must be stored in a different
way.  See the source of `load_tree()' and `store_tree()' for details.

   Most tree nodes contain pointers to other tree nodes; therefore
`load_tree()' and `store_tree()' are recursive functions.  The
`--debug-gpi' debugging informations contains the recursion level in
parantheses, e.g. `loaded (2):' means that the loaded information was
requested by a pointer contained in a tree node requested by a pointer
contained in a tree node representing an exported symbol.

   Since this recursion can be circular (think of a record containing a
pointer to a record of the same type), we must resolve references to
tree nodes which already have been loaded.  For this reason, all nodes
are recorded in a hash buffer - see `gpi-hash.c'.

   There are some special tree_nodes (e.g. `integer_type_node' or
`NULL_TREE') which are used very often.  They have been assigned
(normally invalid) unique `tree_code's, so they can be stored in a
single byte.

   That's it.  Now you should be able to "read" GPI files using GPC's
`--debug-gpi' option.  If you encounter a case where the loaded
information differs too much from the stored information, you have
found a bug - congratulations!  What "too much" means, depends on the
object being stored in or loaded from the GPI file.  Remind that the
order things are loaded from a GPI file is the _reversed_ order things
are stored when considering _different_ recursion levels, but the
_same_ order when considering ths _same_ recursion level.

