diff --git a/docs/Makefile b/docs/Makefile index 4431d53560..ae138d8df1 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -93,12 +93,12 @@ endif # Conversion from types ##################################################################### -.PHONY: all clean dvi help html ps psdist htmldist htm txt pdf refex +.PHONY: clean dvi help html ps psdist htmldist pdfdist txtdist \ + htm txt pdf refex alldist .SUFFIXES: .dvi .tex .ps .txt .pdf # default show help -all: help .dvi.ps: $(DVIPS) $< @@ -119,6 +119,7 @@ all: help $(PDFLATEX) $*pdf -$(MAKEINDEX) $*pdf $(PDFLATEX) $*pdf + mv $*pdf.pdf $*.pdf $(TXT) : %.txt: %.dvi @@ -132,11 +133,19 @@ $(PDF) : %.pdf: %.tex help: @echo 'Possible targets :' - @echo ' dvi : Make documentation using latex.' - @echo ' ps : Make documentation using latex and dvips.' - @echo ' html : Make documentation using latex2html.' - @echo ' htm : Convert .html to .htm files, zip result' - @echo ' clean : Clean up the mess.' + @echo ' dvi : Make documentation using latex.' + @echo ' ps : Make documentation using latex and dvips.' + @echo ' html : Make documentation using latex2html.' + @echo ' pdf : Make documentation using pdflatex' + @echo ' txt : dvi, convert to text using dvi2tty' + @echo ' htm : Convert .html to .htm files, zip result' + @echo ' clean : Clean up the mess.' + @echo ' linuxexamples : Compile all examples for linux' + @echo ' dosexamples : Compile all examples for dos' + @echo ' htmldist : html, and rchive result.' + @echo ' psdist : ps, and archive result.' + @echo ' pdfdist : pdf, and archive result.' + clean: -rm -rf $(HTML) @@ -169,13 +178,19 @@ units.dvi: units.tex $(CHAPTERS) unitex.chk ref.dvi: ref.tex refex.chk +units.pdf: units.tex $(CHAPTERS) unitex.chk + +ref.pdf: ref.tex refex.chk + dvi : $(DVI) txt : dvi $(TXT) ps : dvi $(PS) -pdf : unitex.chk refex.chk $(PDF) +pdf : $(PDF) + +all : dvi ps pdf txt html user: user.chk @@ -220,13 +235,13 @@ prog.chk: prog.tex html: $(HTML) -htm: +htm: html makehtm `find . -name '*.html'` - zip fpcdoc `find . -name '*.htm'` + zip -q fpcdoc `find . -name '*.htm'` `find . -name '*.gif'` rm `find -name '*.htm'` -all-formats: ps txt pdf html - +htmdist: htm + ##################################################################### # Installation ##################################################################### @@ -242,26 +257,52 @@ www-install: psdist htmldist htm ssh tfdec1 '(cd htdocs/fpk/docs ; /usr/local/bin/tar -xzf ../fpcdoc.tar.gz)' ##################################################################### -# Distribution +# Archives ##################################################################### -psdist: ps - tar -cvzf fpcdocps.tar.gz *.ps - zip fpcdocps *.ps +psdist: $(PS) + tar -cvzf fpcdocps.tar.gz $(PS) + zip fpcdocps $(PS) pdfdist: pdf - zip fpcdocpdf *.pdf + zip fpcdocpdf $(PDF) + +dvidist: dvi + zip fpcdocdvi $(DVI) htmldist: html find . -name '*.html' >htmllist find . -name '*.gif' >>htmllist - tar -czvf fpcdoc.tar.gz --files-from=htmllist + tar -czf fpcdoc.tar.gz --files-from=htmllist rm -f htmllist - -dist: - -mkdir $(DISTDIR)/docs - cp Makefile README.DOCS makehtm fpktoc.html $(DISTDIR)/docs - cp *.tex *.sty *.perl *.doc $(DISTDIR)/docs +txtdist: txt + zip fpcdoctxt $(TXT) + +alldist: dvidist psdist txtdist pdfdist htmldist htmdist + distclean: clean -rm -f *.tar.gz *.zip + +##################################################################### +# Examples +##################################################################### + +examples: + $(MAKE) -C crtex + $(MAKE) -C dosex + $(MAKE) -C crtex + $(MAKE) -C dosex + $(MAKE) -C optex + $(MAKE) -C printex + $(MAKE) -C refex + $(MAKE) -C sockex + $(MAKE) -C stringex + +dosexamples: examples + $(MAKE) -C go32ex + $(MAKE) -C mouseex + +linuxexamples: examples + $(MAKE) -C linuxex + $(MAKE) -C sockex diff --git a/docs/crt.tex b/docs/crt.tex index 7a2c4933a2..b033ec7c2a 100644 --- a/docs/crt.tex +++ b/docs/crt.tex @@ -151,7 +151,7 @@ Not implemented on \linux.} \procedure{Delay}{(DTime: Word)} {Delay waits a specified number of milliseconds. The number of specified -seconds is a approximation, and may be off a lot, if system load is high.} +seconds is an approximation, and may be off a lot, if system load is high.} {None}{\seep{Sound}, \seep{NoSound}} \input{crtex/ex15.tex} @@ -194,7 +194,7 @@ The cursor doesn't move.} \Function {KeyPressed}{Boolean} { The Keypressed function scans the keyboard buffer and sees if a key has been pressed. If this is the case, \var{True} is returned. If not, -\var{False} is returned. The \var{Shift, Alt, Ctrl} are not reported. +\var{False} is returned. The \var{Shift, Alt, Ctrl} keys are not reported. The key is not removed from the buffer, and can hence still be read after the KeyPressed function has been called. } diff --git a/docs/crtex/ex11.pp b/docs/crtex/ex11.pp index 634c3cf2c1..e708a2c081 100644 --- a/docs/crtex/ex11.pp +++ b/docs/crtex/ex11.pp @@ -11,7 +11,8 @@ begin WriteLn('Line 2'); WriteLn('Line 3'); WriteLn; - WriteLn('Oops, Line 2 is listed twice, let''s delete the line at the cursor postion'); + WriteLn('Oops, Line 2 is listed twice,', + ' let''s delete the line at the cursor postion'); GotoXY(1,3); ReadKey; DelLine; diff --git a/docs/crtex/ex2.pp b/docs/crtex/ex2.pp index 65c7b88969..c9fb3a0500 100644 --- a/docs/crtex/ex2.pp +++ b/docs/crtex/ex2.pp @@ -7,5 +7,6 @@ begin WriteLn('Waiting until a key is pressed'); repeat until KeyPressed; -{The key is not Read, so it should also be outputted at the commandline} + { The key is not Read, + so it should also be outputted at the commandline} end. diff --git a/docs/crtex/ex9.pp b/docs/crtex/ex9.pp index cdb9583d09..a2d896d182 100644 --- a/docs/crtex/ex9.pp +++ b/docs/crtex/ex9.pp @@ -4,7 +4,8 @@ uses Crt; { Program to demonstrate the ClrEol function. } begin - Write('This line will be cleared from the cursor postion until the right of the screen'); + Write('This line will be cleared from the', + ' cursor postion until the right of the screen'); GotoXY(27,WhereY); ReadKey; ClrEol; diff --git a/docs/dos.tex b/docs/dos.tex index c2a8fd215d..8a9a501d63 100644 --- a/docs/dos.tex +++ b/docs/dos.tex @@ -98,39 +98,47 @@ Under \linux, the \var{Fill} array is replaced with the following: This is because the searching meachanism on Unix systems is substantially different from \dos's, and the calls have to be mimicked. \begin{verbatim} -{$PACKRECORDS 2} - FileRec = Record - Handle : word; - Mode : word; - RecSize : word; - _private : array[1..26] of byte; - UserData: array[1..16] of byte; - Name: array[0..255] of char; - End; +const + filerecnamelength = 255; + +type + FileRec = Packed Record + Handle, + Mode, + RecSize : longint; + _private : array[1..32] of byte; + UserData : array[1..16] of byte; + name : array[0..filerecnamelength] of char; + End; \end{verbatim} \var{FileRec} is used for internal representation of typed and untyped files. Text files are handled by the following types : \begin{verbatim} - TextBuf = array[0..127] of char; +const + TextRecNameLength = 256; + TextRecBufSize = 256; - TextRec = record - handle : word; - mode : word; - bufSize : word; - _private : word; - bufpos : word; - bufend : word; - bufptr : ^textbuf; - openfunc : pointer; - inoutfunc : pointer; - flushfunc : pointer; +type + TextBuf = array[0..TextRecBufSize-1] of char; + TextRec = Packed Record + Handle, + Mode, + bufsize, + _private, + bufpos, + bufend : longint; + bufptr : ^textbuf; + openfunc, + inoutfunc, + flushfunc, closefunc : pointer; - userdata : array[1..16] of byte; - name : array[0..127] of char; - buffer : textbuf; - End; + UserData : array[1..16] of byte; + name : array[0..textrecnamelength-1] of char; + buffer : textbuf; + End; \end{verbatim} -The size of the \var{name} field is 255 under \linux. +Remark that this is not binary compatible with the Turbo Pascal definition +of \var{TextRec}, since the sizes of the different fields are different. \begin{verbatim} Registers = record case i : integer of @@ -183,9 +191,15 @@ Other values are possible, but are not documented. \section{Functions and Procedures} \procedure{AddDisk}{(Const S : String)} -{\var{AddDisk} adds a filenme \var{S} to the internal list of filenames. +{\var{AddDisk} adds a filename \var{S} to the internal list of disks. It is +implemented for \linux only. This list is used to determine which disks to use in the \seef{DiskFree} -and \seef{DiskSize} calls. The names are added sequentially. The dos +and \seef{DiskSize} calls. + +The \seef{DiskFree} and \seef{DiskSize} functions need a file on the +specified drive, since this is required for the \var{statfs} system call. + +The names are added sequentially. The dos initialization code presets the first three disks to: \begin{itemize} \item \var{'.'} for the current drive, @@ -195,7 +209,7 @@ initialization code presets the first three disks to: \end{itemize} The first call to \var{AddDisk} will therefore add a name for the second harddisk, The second call for the third drive, and so on until 23 drives -have been added (corresponding to \var{'D:'} to \var{'Z:'}) +have been added (corresponding to drives \var{'D:'} to \var{'Z:'}) }{None}{\seef{DiskFree}, \seef{DiskSize} } \function{DiskFree}{(Drive: byte)}{longint}{ @@ -208,9 +222,10 @@ Typically, the free space is the size of a disk block, multiplied by the number of free blocks on the disk. \textbf{For \linux only:}\\ -The \var{diskfree} and \var{disksize} functions need a file on the specified drive, since this -is required for the \var{statfs} system call. - These filenames are set in the initialization of the dos unit, and have +The \var{diskfree} and \var{disksize} functions need a file on the +specified drive, since this is required for the \var{statfs} system call. + +These filenames are set in the initialization of the dos unit, and have been preset to : \begin{itemize} \item \var{'.'} for the current drive, @@ -223,7 +238,7 @@ There is room for 1-26 drives. You can add a drive with the These settings can be coded in \var{dos.pp}, in the initialization part. }{-1 when a failure occurs, or an invalid \var{drivenr} is given.} -{\seef{DiskSize}} +{\seef{DiskSize}, \seep{AddDisk}} \input{dosex/ex6.tex} @@ -249,7 +264,7 @@ There is room for 1-26 drives. You can add a drive with the These settings can be coded in \var{dos.pp}, in the initialization part. }{-1 when a failure occurs, or an invalid drive number is given.} -{\seef{DiskFree}} +{\seef{DiskFree}, \seep{AddDisk}} For an example, see \seef{DiskFree}. diff --git a/docs/fpc-html.tex b/docs/fpc-html.tex index 5b43ab78e8..477584126a 100644 --- a/docs/fpc-html.tex +++ b/docs/fpc-html.tex @@ -81,6 +81,7 @@ \newcommand{\msdos}{\textsc{ms-dos} } \newcommand{\ostwo}{\textsc{os/2} } \newcommand{\windowsnt}{\textsc{WindowsNT} } +\newcommand{\windows}{\textsc{Windows} } \newcommand{\docdescription}[1]{} \newcommand{\docversion}[1]{} \newcommand{\unitdescription}[1]{} diff --git a/docs/linux.tex b/docs/linux.tex index 8bd6d53bba..00c85b20c9 100644 --- a/docs/linux.tex +++ b/docs/linux.tex @@ -45,16 +45,16 @@ TGlob = record The following types are used in the signal-processing procedures. \begin{verbatim} {$Packrecords 1} -SignalHandler = Procedure ( Sig : Integer); +SignalHandler = Procedure ( Sig : Integer);cdecl; PSignalHandler = SignalHandler; -SignalRestorer = Procedure; +SignalRestorer = Procedure;cdecl; PSignalrestorer = SignalRestorer; SigActionRec = Record - Sa_Handler : PSignalhandler; + Sa_Handler : Signalhandler; Sa_Mask : Longint; Sa_flags : Integer; - Sa_Restorer : PSignalRestorer; + Sa_Restorer : SignalRestorer; end; PSigActionRec = ^SigActionRec; \end{verbatim} @@ -1782,7 +1782,7 @@ given in \var{Mask}, and then suspends the process until a signal is received. {\seep{SigAction}, \seep{SigProcMask}, \seef{SigPending}, \seef{Signal}, \seef{Kill}, \seem{SigSuspend}{2} } -\function{Signal}{(SigNum : Integer; Handler : PSignalHandler)}{PSignalHandler} +\function{Signal}{(SigNum : Integer; Handler : SignalHandler)}{SignalHandler} { Signal installs a new signal handler for signal \var{SigNum}. This call has the same functionality as the \textbf{SigAction} call. @@ -1796,6 +1796,8 @@ The return value for Signal is the old signal handler, or nil on error. } {\seep{SigAction},\seef{Kill}, \seem{Signal}{2} } +\input{linuxex/ex58.tex} + \function{SymLink}{(OldPath,NewPath : pathstr)}{Boolean} {\var{SymLink} makes \var{Newpath} point to the file in \var{OldPath}, which doesn't necessarily exist. The two files DO NOT have the same inode number. diff --git a/docs/linuxex/Makefile b/docs/linuxex/Makefile index 54c212846a..82b2887966 100644 --- a/docs/linuxex/Makefile +++ b/docs/linuxex/Makefile @@ -36,7 +36,7 @@ OBJECTS=ex1 ex2 ex3 ex4 ex5 ex6 ex7 ex8 ex9 ex10 ex11 ex12 ex13 ex14 \ ex15 ex16 ex17 ex18 ex19 ex20 ex21 ex22 ex23 ex24 ex25 ex26 ex27 \ ex28 ex29 ex30 ex31 ex32 ex33 ex34 ex35 ex36 ex37 ex38 ex39 ex40 \ ex41 ex42 ex43 ex44 ex45 ex46 ex47 ex48 ex49 ex51 ex52 ex53 ex54 ex55 \ - ex56 ex57 + ex56 ex57 ex58 # ex58 ex59 ex60 ex61 ex62 ex63 ex64 ex65 ex66 \ # ex67 ex68 ex69 ex70 ex71 ex72 ex73 ex74 ex75 ex76 ex77 diff --git a/docs/linuxex/README b/docs/linuxex/README index ccd1e2e7fd..feb3e26a35 100644 --- a/docs/linuxex/README +++ b/docs/linuxex/README @@ -58,3 +58,4 @@ ex54.pp contains an example of the IOCtl function. ex55.pp contains an example of the TCGetAttr,TCSetAttr,CFMakeRaw functions. ex56.pp contains an example of the Shell function. ex57.pp contains an example of the SigAction function. +ex58.pp contains an example of the Signal function. diff --git a/docs/linuxex/ex29.pp b/docs/linuxex/ex29.pp index afb24b2808..61c3d6cbfe 100644 --- a/docs/linuxex/ex29.pp +++ b/docs/linuxex/ex29.pp @@ -36,7 +36,7 @@ begin writeln ('ctime : ',info.ctime); If not SymLink ('test.fil','test.lnk') then - writeln ('Link failed !': linuxerror); + writeln ('Link failed ! Errno :',linuxerror); if not lstat ('test.lnk',info) then begin diff --git a/docs/linuxex/ex57.pp b/docs/linuxex/ex57.pp index c35c37ea15..099c695258 100644 --- a/docs/linuxex/ex57.pp +++ b/docs/linuxex/ex57.pp @@ -32,5 +32,6 @@ begin writeln('Error: ',linuxerror,'.'); halt(1); end; + Writeln ('Send USR1 signal or press to exit'); readln; end. diff --git a/docs/optex/optex.pp b/docs/optex/optex.pp index 2f730c36e9..cf3a65ed82 100644 --- a/docs/optex/optex.pp +++ b/docs/optex/optex.pp @@ -2,11 +2,18 @@ program testopt; { Program to depmonstrate the getopts function. } +{ + Valid calls to this program are + optex --verbose --add me --delete you + optex --append --create child + optex -ab -c me -d you + and so on +} uses getopts; var c : char; - optionindex : integer; - theopts : array[1..7] of option; + optionindex : Longint; + theopts : array[1..7] of TOption; begin with theopts[1] do diff --git a/docs/pp2tex b/docs/pp2tex index 3a5cd6a448..a22142c727 100644 --- a/docs/pp2tex +++ b/docs/pp2tex @@ -1,5 +1,6 @@ #!/bin/sh # Simply paste a header and footer to the program. +# cat head.tex > $1.tex cat $1.pp >> $1.tex cat foot.tex >> $1.tex diff --git a/docs/prog.tex b/docs/prog.tex index e9a046d77f..7d40664bc4 100644 --- a/docs/prog.tex +++ b/docs/prog.tex @@ -98,6 +98,47 @@ compiler's behaviour from the moment they're encountered until the moment another switch annihilates their behaviour, or the end of the unit or program is reached. +\subsection{\var{\$A} or \var{\$ALIGN}: Align Data} + +This switch is recognized for Turbo Pascal Compatibility, but is not +yet implemented. The alignment of data will be different in any case, since +\fpc is a 32-bit compiler. + +\subsection{\var{\$ASMMODE} : Assembler mode} +\label{se:AsmReader} + +The \var{\{\$ASMMODE XXX} directive informs the compiler what kind of assembler +it can expect in an \var{asm} block. The \var{XXX} should be replaced by one +of the following: +\begin{description} +\item [att\ ] Indicates that \var{asm} blocks contain AT\&T syntax assembler. +\item [intel\ ] Indicates that \var{asm} blocks contain Intel syntax +assembler. +\item [direct\ ] Tells the compiler that asm blocks should be copied +directly to the assembler file. +\end{description} +These switches are local, and retain their value to the end of the unit that +is compiled, unless they are replaced by another directive of the same type. +The command-line switch that corresponds to this switch is \var{-R}. + +\subsection{\var{\$B} or \var{\$BOOLEVAL}: Complete boolean evaluation} + +This switch is understood by the \fpc compiler, but is ignored. The compiler +always uses shortcut evaluation, i.e. the evaluation of a boolean expression +is stopped once the result of the total exression is known with certainty. + +So, in the following example, the function \var{Bofu}, which has a boolean +result, will never get called. +\begin{verbatim} +If False and Bofu then + ... +\end{verbatim} + +\subsection{\var{\$C} or \var{\$ASSERTIONS} : Assertion support} + +This switch is recognised for Delphi compatibility only. Assertions are not +yet supported by the compiler, but will be implemented in the future. + \subsection{\var{\$DEFINE} : Define a symbol} The directive @@ -364,20 +405,9 @@ an environment variable. It's value will be fetched. % Assembler type \subsection{\var{\$I386\_XXX} : Specify assembler format} -This switch can only be used in the i386 assembler. -This switch informs the compiler what kind of assembler it can expect in an -\var{asm} block. The \var{XXX} should be replaced by one of the following: -\begin{description} -\item [att\ ] Indicates that \var{asm} blocks contain AT\&T syntax assembler. -\item [intel\ ] Indicates that \var{asm} blocks contain Intel syntax -assembler. -\item [direct\ ] Tells the compiler that asm blocks should be copied -directly to the assembler file. -\end{description} -These switches are local, and retain their value to the end of the unit that -is compiled, unless they are replaced by another directive of the same type. -The command-line switch that corresponds to this switch is \var{-R}. +This switch selects the assembler reader. \var{\{\$I386\_XXX\}} +has the same effect as \var{\{\$ASMMODE XXX\}}, \sees{AsmReader} \subsection{\var{\$L} or \var{\$LINK} : Link object file} The \var{\{\$L filename\}} or \var{\{\$LINK filename\}} directive @@ -445,6 +475,17 @@ ppc386 -k-lc foo.pp This switch is recognized for Delphi compatibility only since the generation of type information isn't fully implemented yet. + +\subsection{\var{\$MESSAGE} : Generate info message} + +If the generation of info is turned on, through the \var{-vi} command-line +option, then +\begin{verbatim} +{$MESSAGE This was coded on a rainy day by Bugs Bunny } +\end{verbatim} +will display an info message when the compiler encounters it. The effect is +the same as the \var{\{\$INFO\}} directive. + \subsection{\var{\$MMX} : Intel MMX support} As of version 0.9.8, \fpc supports optimization for the \textbf{MMX} Intel @@ -558,6 +599,9 @@ Type saturday, sunday); \end{verbatim} +{\em Remark:} +Sets are always put in 32 bit or 32 bytes, this cannot be changed + \subsection{\var{\$PACKRECORDS} : Alignment of record elements} This directive controls the byte alignment of the elements in a record, @@ -578,6 +622,49 @@ contrary to Turbo Pascal, where it is 1. More information of this can be found in the reference guide, in the section about record types. +{\em Remark:} +Sets are always put in 32 bit or 32 bytes, this cannot be changed + +\subsection{\var{\$Q} \var{\$OVERFLOWCHECKS}: Overflow checking} +The \var{\{\$Q+\}} or \var{\{\$OVERFLOWCHECKS ON\}} directive turns on +integer overflow checking. This means that the compiler inserts code +to check for overflow when doing computations with integers. +When an overflow occurs, the run-time library will print a message +\var{Overflow at xxx}, and exit the program with exit code 215. + +\emph{ Remark: } Overflow checking behaviour is not the same as in +Turbo Pascal since all arithmetic operations are done via 32-bit +values. Furthermore, the Inc() and Dec() standard system procedures +\emph{ are } checked for overflow in \fpc, while in Turbo Pascal they +are not. + +Using the \var{\{\$Q-\}} switch switches off the overflow checking code +generation. + +The generation of overflow checking code can also be controlled +using the \var{-Co} command line compiler option (see \userref). + +\subsection{\var{\$R} or \var{\$RANGECHECKS} : Range checking} +By default, the computer doesn't generate code to check the ranges of array +indices, enumeration types, subrange types, etc. Specifying the +\var{\{\$R+\}} switch tells the computer to generate code to check these +indices. If, at run-time, an index or enumeration type is specified that is +out of the declared range of the compiler, then a run-time error is +generated, and the program exits with exit code 201. + +The \var{\{\$RANGECHECKS OFF\}} switch tells the compiler not to generate range checking +code. This may result in faulty program behaviour, but no run-time errors +will be generated. + +{\em Remark: } Range checking for sets and enumerations are not yet fully +implemented. + +\subsection{\var{\$SATURATION} : Saturation operations} +This works only on the intel compiler, and MMX support must be on +(\var{\{\$MMX +\}}) for this to have any effect. See the section on +saturation support (\sees{SaturationSupport}) for more information +on the effect of this directive. + \subsection{\var{\$STOP} : Generate fatal error message} The following code @@ -589,6 +676,13 @@ The compiler will immediatly stop the compilation process. It has the same effect as the \var{\{\$FATAL\}} directive. +\subsection{\var{\$T} or \var{\$TYPEDADDRESS} : Typed address operator (@)} + +In the \var{\{\$T+\}} or \var{\{\$TYPEDADDRESS ON\}} state the @ operator, +when applied to a variable, returns a result of type \var{\^{}T}, if the +type of the variable is \var{T}. In the \var{\{\$T-\}} state, the result is +always an untyped pointer, which is assignment compatible with all other +pointer types. \subsection{\var{\$UNDEF} : Undefine a symbol} @@ -637,6 +731,33 @@ will display a warning message when the compiler encounters it. Contrary to the command-line option \var{-vw} this is a local switch, this is useful for checking parts of your code. +\subsection{\var{\$X} or \var{\$EXTENDEDSYNTAX} : Extended syntax} +Extended syntax allows you to drop the result of a function. This means that +you can use a function call as if it were a procedure. Standard this feature +is on. You can switch it off using the \var{\{\$X-\}} or +\var{\{\$EXTENDEDSYNTAX OFF\}}directive. + +The following, for instance, will not compile : +\begin{verbatim} +function Func (var Arg : sometype) : longint; +begin +... { declaration of Func } +end; + +... + +{$X-} +Func (A); +\end{verbatim} +The reason this construct is supported is that you may wish to call a +function for certain side-effects it has, but you don't need the function +result. In this case you don't need to assign the function result, saving +you an extra variable. + +The command-line compiler switch \var{-Sa1} has the same effect as the +\var{\{\$X+\}} directive. + + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Global switches \section{Global directives} @@ -645,25 +766,6 @@ Global directives affect the whole of the compilation process. That is why they also have a command - line counterpart. The command-line counterpart is given for each of the directives. -\subsection{\var{\$A} or \var{\$ALIGN}: Align Data} - -This switch is recognized for Turbo Pascal Compatibility, but is not -yet implemented. The alignment of data will be different in any case, since -\fpc is a 32-bit compiler. - -\subsection{\var{\$B} or \var{\$BOOLEVAL}: Complete boolean evaluation} - -This switch is understood by the \fpc compiler, but is ignored. The compiler -always uses shortcut evaluation, i.e. the evaluation of a boolean expression -is stopped once the result of the total exression is known with certainty. - -So, in the following example, the function \var{Bofu}, which has a boolean -result, will never get called. -\begin{verbatim} -If False and Bofu then - ... -\end{verbatim} - \subsection{\var{\$D} or \var{\$DEBUGINFO}: Debugging symbols} When this switch is on (\var{\{\$DEBUGINFO ON\}}), @@ -685,7 +787,8 @@ a warning. The compiler itself doesn't do the emulation of the coprocessor. To use coprocessor emulation under \dos go32v1 there is nothing special -required, as it is handled automatically. +required, as it is handled automatically. (As of version 0.99.10, the +go32v1 platform will no longer be supported) To use coprocessor emulation under \dos go32v2 you must use the emu387 unit, which contains correct initialization code for the @@ -739,40 +842,6 @@ mathematics. This switch is recognised for Turbo Pascal compatibility, but is otherwise ignored. -\subsection{\var{\$Q} \var{\$OVERFLOWCHECKS}: Overflow checking} -The \var{\{\$Q+\}} or \var{\{\$OVERFLOWCHECKS ON\}} directive turns on -integer overflow checking. This means that the compiler inserts code -to check for overflow when doing computations with integers. -When an overflow occurs, the run-time library will print a message -\var{Overflow at xxx}, and exit the program with exit code 215. - -\emph{ Remark: } Overflow checking behaviour is not the same as in -Turbo Pascal since all arithmetic operations are done via 32-bit -values. Furthermore, the Inc() and Dec() standard system procedures -\emph{ are } checked for overflow in \fpc, while in Turbo Pascal they -are not. - -Using the \var{\{\$Q-\}} switch switches off the overflow checking code -generation. - -The generation of overflow checking code can also be controlled -using the \var{-Co} command line compiler option (see \userref). - -\subsection{\var{\$R} or \var{\$RANGECHECKS} : Range checking} -By default, the computer doesn't generate code to check the ranges of array -indices, enumeration types, subrange types, etc. Specifying the -\var{\{\$R+\}} switch tells the computer to generate code to check these -indices. If, at run-time, an index or enumeration type is specified that is -out of the declared range of the compiler, then a run-time error is -generated, and the program exits with exit code 201. - -The \var{\{\$RANGECHECKS OFF\}} switch tells the compiler not to generate range checking -code. This may result in faulty program behaviour, but no run-time errors -will be generated. - -{\em Remark: } Range checking for sets and enumerations are not yet fully -implemented. - \subsection{\var{\$S} : Stack checking} The \var{\{\$S+\}} directive tells the compiler to generate stack checking code. This generates code to check if a stack overflow occurred, i.e. to see @@ -785,39 +854,23 @@ Specifying \var{\{\$S-\}} will turn generation of stack-checking code off. The command-line compiler switch \var{-Ct} has the same effect as the \var{\{\$S+\}} directive. -\subsection{\var{\$T} or \var{\$TYPEDADDRESS} : Typed address operator (@)} -In the \var{\{\$T+\}} or \var{\{\$TYPEDADDRESS ON\}} state the @ operator, -when applied to a variable, returns a result of type \var{\^{}T}, if the -type of the variable is \var{T}. In the \var{\{\$T-\}} state, the result is -always an untyped pointer, which is assignment compatible with all other -pointer types. +\subsection{\var{\$W} or \var{\$STACKFRAMES} : Generate stackframes} -\subsection{\var{\$X} or \var{\$EXTENDEDSYNTAX} : Extended syntax} -Extended syntax allows you to drop the result of a function. This means that -you can use a function call as if it were a procedure. Standard this feature -is on. You can switch it off using the \var{\{\$X-\}} or -\var{\{\$EXTENDEDSYNTAX OFF\}}directive. +The \var{\{\$W\}} switch directove controls the generation of stackframes. +In the on state (\var{\{\$STACKFRAMES ON\}}), the compiler will generate a +stackframe for every procedure or function. -The following, for instance, will not compile : -\begin{verbatim} -function Func (var Arg : sometype) : longint; -begin -... { declaration of Func } -end; - -... - -{$X-} -Func (A); -\end{verbatim} -The reason this construct is supported is that you may wish to call a -function for certain side-effects it has, but you don't need the function -result. In this case you don't need to assign the function result, saving -you an extra variable. - -The command-line compiler switch \var{-Sa1} has the same effect as the -\var{\{\$X+\}} directive. +In the off state, the compiler will omit the generation of a stackframe if +the following conditions are satisfied: +\begin{itemize} +\item The procedure has no parameters. +\item The procedure has no local variables. +\item If the procedure is not an \var{assembler} procedure, it must not have +a \var{asm ... end;} block. +\item it is not a constuctor or desctructor. +\end{itemize} +If these conditions are satisfied, the stack frame will be omitted. \subsection{\var{\$Y} or \var{\$REFERENCEINFO} : Insert Browser information} @@ -1524,7 +1577,6 @@ More about this can be found in \seec{Linking} on linking. \subsection{ Ix86 calling conventions } - Standard entry code for procedures and functions is as follows on the x86 architecture: \begin{verbatim} @@ -1541,7 +1593,7 @@ The generated exit sequence for procedure and functions looks as follows: Where \var{xx} is the total size of the pushed parameters. To have more information on function return values take a look at the -\seec{RegConvs} section. +\sees{RegConvs} section. \subsection{ M680x0 calling conventions } @@ -1564,7 +1616,7 @@ The generated exit sequence for procedure and functions looks as follows: Where \var{xx} is the total size of the pushed parameters. To have more information on function return values take a look at the -\seec{RegConvs} section. +\sees{RegConvs} section. @@ -1634,9 +1686,7 @@ However, there are times that you want to C libraries, or to external object files that are generated using a C compiler (or even another pascal compiler). The \fpc compiler can generate calls to a C function, and can generate functions that can be called from C (exported functions). -However, these exported functions cannot be called from -inside Pascal anymore. More on these calling conventions can be found in -\sees{Calling}. +More on these calling conventions can be found in \sees{Calling}. In general, there are 2 things you must do to use a function that resides in an external library or object file: @@ -1646,16 +1696,21 @@ want to use. \item You must tell the compiler where the function resides, i.e. in what object file or what library, so the compiler can link the necessary code in. \end{enumerate} +The same holds for variables. To access a variable that resides in an +external object file, you ust declare it, and tell the compiler where to +find it. The following sections attempt to explain how to do this. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Declaring an external function or procedure -\section{Declaring an external function or procedure} -\label{se:ExternalDeclaration} +\section{Using external functions or procedures} +\label{se:ExternalFunction} The first step in using external code blocks is declaring the function you want to use. \fpc supports Delphi syntax, i.e. you must use the -\var{external} directive. +\var{external} directive. The \var{external} directive replaces, in effect, +the code block of the function. As such, It cannot be used in an interface +section of a unit, but must always reside in the implementation section. There exist four variants of the external direcive : \begin{enumerate} @@ -1722,19 +1777,95 @@ This method is equivalent to the following statement: \begin{verbatim} Procedure ProcName (Args : TPRocArgs); cdecl; external; \end{verbatim} -However, the \var{[ C ]} directive is no longer supoerted as of version -0.99.5 of \fpc, therefore you should use the -\var{external} directive, with the \var{cdecl} directive, if needed. +However, the \var{[ C ]} directive is no longer supported as of version +0.99.5 of \fpc, therefore you should use the \var{external} directive, +with the \var{cdecl} directive, if needed. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Declaring an external variabl +\section{Using external variables} +\label{se:ExternalVars} + +Some libaries or code blocks have variables which they export. You can access +these variables much in the same way as external functions. To access an +external variable, you declare it as follows: + +\begin{verbatim} +Var + MyVar : MyType; external name 'varname'; +\end{verbatim} +The effect of this declaration is twofold: +\begin{enumerate} +\item No space is allocated for this variable. +\item The name of the variable used in the assebler code is \var{varname}. +This is a case sensitive name, so you must be careful. +\end{enumerate} +The variable will be +accessible with it's declared name, i.e. \var{MyVar} in this case. + +A second possibility is the declaration: +\begin{verbatim} +Var + varname : MyType; cvar; external; +\end{verbatim} +The effect of this declaration is twofold as in the previous case: +\begin{enumerate} +\item The \var{external} modifier ensures that no space is allocated for +this variable. +\item The \var{cvar} modifier tells the compiler that the name of the +variable used in the assebler code is exactly as specified in the +declaration. This is a case sensitive name, so you must be careful. +\end{enumerate} +In this case, you access the variable with it's C name, but case +insensitive. The first possibility allows you to change the name of the +external variable for internal use. + +In order to be able to compile such statements, the compiler switch \var{-Sv} +must be used. + +As an example, let's look at the following C file (in \file{extvar.c}): +\begin{verbatim} +/* +Declare a variable, allocate storage +*/ +int extvar = 12; +\end{verbatim} +And the following program (in \file{extdemo.pp}): +\begin{verbatim} +Program ExtDemo; + +{$L extvar.o} + +Var { Case sensitive declaration !! } + extvar : longint; cvar;external; + I : longint; external name 'extvar'; +begin + { Extvar can be used case insensitive !! } + Writeln ('Variable ''extvar'' has value : ',ExtVar); + Writeln ('Variable ''I'' has value : ',i); +end. +\end{verbatim} +Compiling the C file, and the pascal program: +\begin{verbatim} +gcc -c -o extvar.o extvar.c +ppc386 -Sv extdemo +\end{verbatim} +Will produce a program \file{extdemo} which will print +\begin{verbatim} +Variable 'extvar' has value : 12 +Variable 'I' has value : 12 +\end{verbatim} +on your screen. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Linking an object file in your program \section{Linking to an object file} \label{se:LinkIn} -Having declared the external function that resides in an object file, +Having declared the external function or variable that resides in an object file, you can use it as if it was defined in your own program or unit. To produce an executable, you must still link the object file in. -This can be done with the \var{\{\$L 'file.o'\}} directive. +This can be done with the \var{\{\$L file.o\}} directive. This will cause the linker to link in the object file \file{file.o}. On \linux systems, this filename is case sensitive. Under \dos, case isn't @@ -1790,7 +1921,7 @@ end. With just two commands, this can be made into a program : \begin{verbatim} as -o fib.o fib.s -pp fibo.pp +ppc386 fibo.pp \end{verbatim} This example supposes that you have your assembler routine in \file{fib.s}, and your Pascal program in \file{fibo.pp}. @@ -1801,16 +1932,19 @@ and your Pascal program in \file{fibo.pp}. \label{se:LinkOut} To link your program to a library, the procedure depends on how you declared -the external procedure. If you used thediffers a little from the -procedure when you link in an object file. although the declaration step -remains the same (see \ref{se:ExternalDeclaration} on how to do that). +the external procedure. +%If you used thediffers a little from the +%procedure when you link in an object file. although the declaration step +%remains the same (see \ref{se:ExternalFunction} on how to do that). In case you used the follwing syntax to declare your procedure: \begin{verbatim} Procedure ProcName (Args : TPRocArgs); external 'Name'; \end{verbatim} You don't need to take additional steps to link your file in, the compiler -will do all that is needed for you. +will do all that is needed for you. On \windowsnt it will link to +\file{Name.dll}, on \linux your program will be linked to library +\file{libname}, which can be a static or dynamic library. In case you used \begin{verbatim} @@ -1851,7 +1985,7 @@ end. \end{verbatim} This program can be compiled with : \begin{verbatim} -pp prlen.pp +ppc386 prlen.pp \end{verbatim} Supposing, of course, that the program source resides in \file{prlen.pp}. @@ -1860,29 +1994,55 @@ arguments in C. Pascal doesn't support this feature of C. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Making a shared library -\section{Making a shared library} +\section{Making libraries} \label{se:SharedLib} -\fpc supports making shared libraries in a straightforward and easy manner. +\fpc supports making shared or static libraries in a straightforward and +easy manner. If you want to make libraries for other \fpc programmers, you just need to provide a command line switch. If you want C programmers to be able to use your code as well, you will need to adapt your code a little. This process is described first. -% Adapting your code -\subsection{Adapting your code} +% Exporting functions. +\subsection{Exporting functions} + +When exporting functions from a library, there are 2 things you must take in +account: + +\begin{enumerate} +\item Calling conventions. +\item Naming scheme. +\end{enumerate} +The calling conventions are controlled by the modifiers \var{cdecl}, +\var{popstack}, \var{pascal}, \var{stdcall}. See \sees{Calling} for more +information on the different kinds of calling scheme. + +The naming conventions can be controlled by 3 modifiers: +\begin{description} +\item [cdecl:\ ] A function that has a \var{cdecl} modifier, will used +with C calling conventions, that is, the caller clears the stack. Also +the mangled name will be the name {\em exactly} as in the declaration. +\var{cdecl} is part of the function declaration, and hence must be present +both in the interface and implementation section of a unit. + +\item [export:\ ] A function that has an export modifier, uses also the +exact declaration name as its mangled name. Under \windowsnt and \ostwo, +this modifier signals a function that is exported from a DLL. +The calling conventions used by a \var{export} procedure depend on the OS. +this keyword can be used only in the implementation section. +\item [Alias: ] The \var{alias} modifier can be used to give a supplementary +assembler name to your function. This doesn't modify the calling conventions +of the function. +\end{description} If you want to make your procedures and functions available to C programmers, you can do this very easily. All you need to do is declare the -functions and procedures that you want to make available as \var{Export}, as +functions and procedures that you want to make available as \var{export}, as follows: \begin{verbatim} -Procedure ExportedProcedure ; export; +Procedure ExportedProcedure; export; \end{verbatim} -This tells the compiler that it shouldn't clear the stack upon exiting the -procedure (see \sees{Calling}), thus enabling a C program to call your -function. It also means that your Pascal program can't call this function, -since it will be using the C calling mechanism. {\em Remark :} You can only declare a function as exported in the \var{Implementation} section of a unit. This function may {\em not} appear @@ -1892,11 +2052,11 @@ cannot call an exported function, anyway. However, the generated object file will not contain the name of the function as you declared it. The \fpc compiler ''mangles'' the name you give your function. It makes the name all-uppercase, and adds the types of all -parameters to it. For \fpc units, this doesn't matter, since the \file{.ppu} -unit file contains all information to map your function declaration onto the -mangled name in the object file. For a C programmer, who has no access to -the \var{.ppu} file, this is not very convenient. That is why \fpc -has the \var{Alias} modifier. The \var{Alias} modifier allows you to specify +parameters to it. There are cases when you want to provide a mangled name +without changing the calling convention. In such cases, you can use the +\var{Alias} modifier. + +The \var{Alias} modifier allows you to specify another name (a nickname) for your function or procedure. The prototype for an aliased function or procedure is as follows : @@ -1906,19 +2066,31 @@ Procedure AliasedProc; [ Alias : 'AliasName']; The procedure \var{AliasedProc} will also be known as \var{AliasName}. Take care, the name you specify is case sensitive (as C is). -Of course, you want to combine these two features of \fpc, to export a -function under a reasonable name; If you want to do that, you must first -specify that the function is to be exported, and then only declare an alias: -\begin{verbatim} -Procedure ExportToCProc; Export; [Alias : 'procname']; -\end{verbatim} -After that, any C program will be able to use your procedure or function. - {\em Remark: } If you use in your unit functions that are in other units, or system functions, then the C program will need to link in the object files from the units too. +% Exporting variable. +\subsection{Exporting variables} + +Similarly as when you export functions, you can export variables. +when exportig variables, one should only consider the names of the +variables. To declare a variable that should be used by a C program, +one declares it with the \var{cvar} modifier: +\begin{verbatim} +Var MyVar : MyTpe; cvar; +\end{verbatim} +This will tell the compiler that the assembler name of the variable (the one +which is used by C programs) should be exactly as specified in the +declaration, i.e., case sensitive. + +It is not allowed to declare multiple variables as \var{cvar} in one +statement, i.e. the following code will produce an error: +\begin{verbatim} +var Z1,Z2 : longint;cvar; +\end{verbatim} + % Compiling libraries \subsection {Compiling libraries} @@ -1929,27 +2101,27 @@ to transform it into a \var{static} or \var{shared} (\var{dynamical}) library. You can do this as follows, for a dynamical library: \begin{verbatim} -ppc386 -Uld myunit +ppc386 -CD myunit \end{verbatim} On \linux this will leave you with a file \file{libmyunit.so}. On \windows and \ostwo, this will leave you with \file{myunit.dll}. If you want a static library, you can do \begin{verbatim} -ppc386 -Uls myunit +ppc386 -CS myunit \end{verbatim} -This will leave you with \file{libmyunit.a} and a file \file{myunit.ppl}. -The \file{myunit.ppl} is the unit file needed by the \fpc compiler. -The extension \file{.ppl} means that the file describes a unit that resides -in a library. +This will leave you with \file{libmyunit.a} and a file \file{myunit.ppu}. +The \file{myunit.ppu} is the unit file needed by the \fpc compiler. The resulting files are then libraries. To make static libraries, you need the \file{ranlib} or \var{ar} program on your system. It is standard on any \linux system, and is provided with the \file{GCC} compiler under \dos. +For the dos distribution, a copy of ar is included in the file +\file{gnuutils.zip}. {\em BEWARE:} This command doesn't include anything but the current unit in -thelibrary. Other units are left out, so if you use code from other units, -you must dpley them together with your library. +the library. Other units are left out, so if you use code from other units, +you must deploy them together with your library. % Moving units \subsection{Moving units into a library} @@ -1957,7 +2129,7 @@ You can put multiple units into a library with the \var{ppumove} command, as follows: \begin{verbatim} -ppumove unit1 unit2 unit3 name +ppumove -e ppl -o name unit1 unit2 unit3 \end{verbatim} This will move 3 units in 1 library (called \file{libname.so} on linux, \file{name.dll} on \windows) and it will create 3 files \file{unit1.ppl}, @@ -1972,13 +2144,74 @@ libraries. It is provided with the compiler. When you compile a program or unit, the compiler will by default always look for \file{.ppl} files. If it doesn't find one, it will -look for a \file{.ppu} file. You can disable this behaviour by -specifying the \var{-Cs} switch. This tells the compiler to make a static -binary, and refrains it from looking for units which reside in a library. +look for a \file{.ppu} file. -You can tell the compiler only to use dynamic libraries by specifying -the \var{-Cd} switch; the compiler will then only look for \var{.ppl} files, -and will give an error if it doesn't find one. +To be able to differentiate between units that have been compiled as static +or dynamic libraries, there are 2 switches: + +\begin{description} +\item [-XD:\ ] This will define the symbol \var{FPC\_LINK\_DYNAMIC} +\item [-XS:\ ] This will define the symbol \var{FPC\_LINK\_STATIC} +\end{description} +Definition of one symbol will automatically undefine the other. + +These two switches can be used in conjunction with the configuration file +\file{ppc386.cfg}. The existence of one of these symbols can be used to +decide which unit search path to set. For example: +\begin{verbatim} +# Set unit paths + +#IFDEF FPC_LINK_STATIC +-Up/usr/lib/fpc/linuxunits/staticunits +#ENDIF +#IFDEF FPC_LINK_DYNAMIC +-Up/usr/lib/fpc/linuxunits/sharedunits +#ENDIF +\end{verbatim} +With such a configuration file, the compiler will look for it's units in +different directories, depending on whether \var{-XD} or \var{-XS} is used. + +\section{Using smart linking} +\label{se:SmartLinking} + +You can compile your units using smart linking. When you use smartl linking, +the compiler creates a series of code blocks that are as small as possible, +i.e. a code block will contain only the code for one procedure or function. + +When you compile a program that uses a smart-linked unit, the compiler will +only link in the code that you actually need, and will leave out all other +code. This will result in a smaller binary, which is loaded in memory +faster, thus speeding up execution. + +To enable smartlinking, one can give the smartlink option on the command +line : \var{-Cx}, or one can put the \var{\{\$SMARTLINK ON\}} directive in +the unit file: +\begin{verbatim} +Unit Testunit + +{SMARTLINK ON} +Interface +... +\end{verbatim} +Smartlinking will slow down the compilation process, expecially for large +units. + +When a unit \file{foo.pp} is smartlinked, the name of the codefile is +changed to \file{libfoo.a}. + +Technically speaking, the compiler makes small assembler files for each +procedure and function in the unit, as well as for all global defined +variables (whether they're in the interface section or not). It then +assembles all these small files, and uses \file{ar} to collect the resulting +object fioles in one archive. + +Smartlinking and the creation of shared (or dynamic) libraries are mutually +exclusive, that is, if you turn on smartlinking, then the creation of shared +libraries is turned of. The creation of static libraries is still possible. +The reason for this is that it has little sense in making a smarlinked +dynamica library. The whole shared library is loaded into memory anyway by +the dynamic linker (or \windowsnt), so there would be no gain in size by +making it smartinked. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Objects @@ -2069,7 +2302,8 @@ what is generated when you compile a unit or a program. \label{se:Units} When you compile a unit, the \fpc compiler generates 2 files : \begin{enumerate} -\item A unit description file (with extension \file{.ppu}). +\item A unit description file (with extension \file{.ppu}, or \file{.ppw on +\windowsnt}). \item An assembly language file (with extension \file{.s}). \end{enumerate} The assembly language file contains the actual source code for the @@ -2081,7 +2315,8 @@ units and your program, to form an executable. By default (compiler version 0.9.4 and up), the assembly file is removed after it has been compiled. Only in the case of the \var{-s} command-line option, the assembly file must be left on disk, so the assembler can be -called later. +called later. You can disable the erasing of the assembler file with the +\var{-a} switch. The unit file contains all the information the compiler needs to use the unit: @@ -2671,9 +2906,9 @@ were evaluted. \subsection{ Constant set inlining } Using the \var{in} operator is always more efficient then using the -equivalent <>, =, <=, >=, < and > operators. This is because -range comparisons can be done more easily with \var{in} then with -normal comparison operators. +equivalent \verb|<>|, \verb|=|, \verb|<=|, \verb|>=|, \verb|<| and \verb|>| +operators. This is because range comparisons can be done more easily with +\var{in} then with normal comparison operators. \subsection{ Small sets } @@ -2731,6 +2966,9 @@ look at the reference manual under the \var{record} heading. This feature removes all unreferenced code in the final executable file, making the executable file much smaller. +Smart linking is switched on with the \var{-Cx} command-line switch, or +using the \var{\{\$SMARTLINK ON\}} global directive. + \emph{ Remark: } Smart linking was implemented starting with version 0.99.6 of \fpc. @@ -2752,33 +2990,35 @@ case statement execute faster. \subsection{ Stack frame omission } -When using the \var{-Ox} switch, under certain specific conditions, -the stack frame (entry and exit code for the routine) will be omitted, and +Under certain specific conditions, the stack frame (entry and exit code +for the routine, see section \ref{se:Calling}) will be omitted, and the variable will directly be accessed via the stack pointer. Conditions for omission of the stack frame : \begin{itemize} -\item Routine does not call other routines -\item Routine does not contain assembler statements -\item Routine is not declared using the \var{Interrupt} directive -\item Routine is not a constructor or destructor +\item The function has no parameters nor local variables. +\item Routine does not call other routines. +\item Routine does not contain assembler statements. However, +a \var{assembler} routine may omit it's stack frame. +\item Routine is not declared using the \var{Interrupt} directive. +\item Routine is not a constructor or destructor. \end{itemize} \subsection{ Register variables } -When using the \var{-Ox} switch, local variables or parameters +When using the \var{-Or} switch, local variables or parameters which are used very often will be moved to registers for faster access. \emph{ Remark: } Register variable allocation is currently -broken and should not be used. +an experimental feature, and should be used with caution. \subsection{ Intel x86 specific } Here follows a listing of the opimizing techniques used in the compiler: \begin{enumerate} -\item When optimizing for a specific Processor (\var{-O3, -O4, -O5 -O6}, +\item When optimizing for a specific Processor (\var{-Op1, -Op2, -Op3}, the following is done: \begin{itemize} \item In \var{case} statements, a check is done whether a jump table @@ -2787,18 +3027,18 @@ or a sequence of conditional jumps should be used for optimal performance. \var{movzbl (\%ebp), \%eax} on PentiumPro and PII systems will be changed into \var{xorl \%eax,\%eax; movb (\%ebp),\%al } for lesser systems. \end{itemize} -Cyrix \var{6x86} processor owners should optimize with \var{-O4} instead of -\var{-O5}, because \var{-O5} leads to larger code, and thus to smaller +Cyrix \var{6x86} processor owners should optimize with \var{-Op3} instead of +\var{-Op2}, because \var{-Op2} leads to larger code, and thus to smaller speed, according to the Cyrix developers FAQ. - \item When optimizing for speed (\var{-OG}) or size (\var{-Og}), a choice is + \item When optimizing for speed (\var{-OG}, the default) or size (\var{-Og}), a choice is made between using shorter instructions (for size) such as \var{enter \$4}, or longer instructions \var{subl \$4,\%esp} for speed. When smaller size is requested, things aren't aligned on 4-byte boundaries. When speed is requested, things are aligned on 4-byte boundaries as much as possible. \item Simple optimization (\var{-Oa}) makes sure the peephole optimizer is used, as well as the reloading optimizer. -\item Uncertain optimizations (\var{-Oz}): With this switch, the reloading -optimizer (enabled with \var{-Oa}) can be forced into making uncertain +\item Uncertain optimizations (\var{-Ou}): With this switch, the reloading +optimizer can be forced into making uncertain optimizations. You can enable uncertain optimizations only in certain cases, @@ -2903,6 +3143,86 @@ runtime library call will be generated runtime library call will be generated \end{itemize} +\section{Optimization switches} +This is where the various optimizing switches and their actions are +described, grouped per switch. + +\begin{description} +\item [-On:\ ] with n = 1..3: these switches activate the optimizer. +A higher level automatically includes all lower levels. +\begin{itemize} +\item Level 1 (\var{-O1}) activates the peephole optimizer + (common instruction sequences are replaced by faster equivalents). +\item Level 2 (\var{-O2}) enables the assembler data flow analyzer, +which allows the common subexpression elimination procedure to +remove unnecessary reloads of registers with values they already contain. +\item Level 3 (\var{-O3}) enables uncertain optimizations. For more info, see -Ou. +\end{itemize} +\item[-OG:\ ] +This causes the code generator (and optimizer, IF activated), to favor +faster, but code-wise larger, instruction sequences (such as +"\verb|subl $4,%esp|") instead of slower, smaller instructions +("\verb|enter $4|"). This is the default setting. + +\item[-Og:\ ] This one is exactly the reverse of -OG, and as such these +switches are mutually exclusive: enabling one will disable the other. + +\item[-Or:\ ] this setting (once it's fixed) causes the code generator to +check which variables are used most, so it can keep those in a register. + +\item[-Opn:\ ] with n = 1..3: setting the target processor does NOT +activate the optimizer. It merely influences the code generator and, +if activated, the optimizer: +\begin{itemize} +\item During the code generation process, this setting is used to +decide whether a jump table or a sequence of successive jumps provides +the best performance in a case statement. +\item The peephole optimizer takes a number of decisions based on this +setting, for example it translates certain complex instructions, such +as +\begin{verbatim} +movzbl (mem), %eax| +\end{verbatim} +to a combination of simpler instructions +\begin{verbatim} +xorl %eax, %eax +movb (mem), %al +\end{verbatim} +for the Pentium. +\end{itemize} +\item[-Ou:\ ] This enables uncertain optimizations. You cannot use these +always, however. The previous section explains when they can be used, and +when they cannot be used. +\end{description} + +\section{Tips to get faster code} +Here some general tips for getting better code are presented. They are +mainly concerned with coding style. + +\begin{itemize} +\item Find a better algorithm. No matter how muck you and the compiler +tweak the code, a quicksort will (almost) always outperform a bubble +sort, for example. + +\item Use variables of the native size of the processor you're writing +for. For the 80x86 and compatibles, this is 32 bit, so you're best of +using longint and cardinal variables. + +\item Turn on the optimizer. + +\item If you are allocating and disposing a lot of small memory blocks, +check out the heapblocks variable. (\refref) + +\item Profile your code (see the -pg switch) to find out where the +bottlenecks are. If you want, you can rewrite those parts in assembler. +You can take the code generated by the compiler as a starting point. When +given the \var{-a} command-line switch, the compiler will not erase the +assembler file at the end of the assembly process, so you can study the +assembler file. + +{\em Note:} code blocks which contain an assembler block, are not processed +at all by the optimizer at this time. +\end{itemize} \section{ Floating point } diff --git a/docs/ref.tex b/docs/ref.tex index 703e507d61..b254c6d7e0 100644 --- a/docs/ref.tex +++ b/docs/ref.tex @@ -27,6 +27,9 @@ \usepackage{html} \latex{\usepackage{fpc}} \html{\input{fpc-html.tex}} +\usepackage{fancyheadings} +\pagestyle{fancy} +\renewcommand{\chaptermark}[1]{\markboth{#1}{}} \makeindex % % start of document. @@ -123,14 +126,16 @@ The true Turbo Pascal compatible types are listed in \begin{FPCltable}{lccr}{Supported Real types}{Reals} Type & Range & Significant digits & Size\footnote{In Turbo Pascal.} \\ \hline Single & 1.5E-45 .. 3.4E38 & 7-8 & 4 \\ +Real & 5.0E-324 .. 1.7E308 & 15-16 & 8 \\ Double & 5.0E-324 .. 1.7E308 & 15-16 & 8 \\ Extended & 1.9E-4951 .. 1.1E4932 & 19-20 & 10\\ -%Comp\footnote{\var{Comp} only holds integer values.} & -2E64+1 .. 2E63-1 & 19-20 & 8 \\ +Comp\footnote{\var{Comp} only holds integer values.} & -2E64+1 .. 2E63-1 & 19-20 & 8 \\ \end{FPCltable} Until version 0.9.1 of the compiler, all the real types are mapped to type \var{Double}, meaning that they all have size 8. The \seef{SizeOf} function -is your friend here. +is your friend here. The \var{Real} type of turbo pascal is automatically +mappe to Double. \subsection{Character types} \subsubsection{Char} @@ -355,7 +360,22 @@ begin end. \end{verbatim} \end{CodEx} -\fpc doesn't support pointer arithmetic as C does, however. +\fpc supports pointer arithmetic as C does. This means that, if \var{P} is a +typed pointer, the instructions +\begin{verbatim} +Inc(P); +Dec(P); +\end{verbatim} +Will increase, respecively descrease the address the pointer points to +with the size of the type \var{P} is a pointer to. For example +\begin{verbatim} +Var P : ^Longint; + +... + + Inc (p); +\end{verbatim} +will increase \var{P} with 4. \subsection{Procedural types} \fpc has support for procedural types, although it differs from the Turbo @@ -384,7 +404,29 @@ Func:=@Pi; \end{verbatim} From this example, the difference with Turbo Pascal is clear: In Turbo Pascal it isn't necessary to use the address operator (\var{@}) -when assigning a procedural type variable, whereas in \fpc it is required. +when assigning a procedural type variable, whereas in \fpc it is required +(unless you use the \var{-So} switch) + +Remark that the modifiers concerning the calling conventions (\var{cdecl}, +\var{pascal}, \var{stdcall} and \var{popstack} stick to the declaration; +i.e. the following code would give an error: +\begin{verbatim} +Type TOneArgCcall = Procedure (Var X : integer);cdecl; + +var proc : TOneArgCcall; + +Procedure printit (Var X : Integer); + +begin + writeln (x); +end; + +begin +P:=@printit; +end. +\end{verbatim} +Because the \var{TOneArgCcall} type is a procedure that uses the cdecl +calling convention. \subsection{Records} @@ -508,9 +550,10 @@ Intersection & * \\ \hline You can compare two sets with the \var{<>} and \var{=} operators, but not (yet) with the \var{<} and \var{>} operators. -From compiler version 0.9.5, the compiler stores small sets (less than 32 +As of compiler version 0.9.5, the compiler stores small sets (less than 32 elements) in a longint, if the type range allows it. This allows for faster -processing and decreases program size. +processing and decreases program size. Otherwise, sets are stored in 32 +bytes. \subsection{Enumeration types} @@ -533,10 +576,39 @@ Type \end{verbatim} It is necessary to keep \var{forty} and \var{Thirty} in the correct order. -{\em Remark :} You cannot use the \var{Pred} and \var{Succ} functions on +{\em Remarks :} +\begin{enumerate} +\item You cannot use the \var{Pred} and \var{Succ} functions on this kind of enumeration types. If you try to do that, you'll get a compiler error. +\item Enumeration types are by default stored in 4 bytes. You can change +this behaviour with the \var{\{\$PACKENUM \}} compiler directive, which +tells the compiler the minimal number of bytes to be used for enumeration +types. +For instance +\begin{verbatim} +Type + LargeEnum = ( BigOne, BigTwo, BigThree ); +{$PACKENUM 1} + SmallEnum = ( one, two, three ); + +Var S : SmallEnum; + L : LargeEnum; + +begin + Writeln ('Small enum : ',Sizeof(S)); + Writeln ('Large enum : ',SizeOf(L)); +end. +\end{verbatim} +will, when run, print the following: +\begin{verbatim} +Small enum : 1 +Large enum : 4 +\end{verbatim} +\end{enumerate} +More information can be found in the \progref, in the compiler directives +section. \section{Constants} Just as in Turbo Pascal, \fpc supports both normal and typed constants. @@ -613,20 +685,15 @@ Const The order of the fields in a constant record needs to be the same as in the type declaration, otherwise you'll get a compile-time error. + \section{Objects} \fpc supports object oriented programming. In fact, part of the compiler is written using objects. Here we present some technical questions regarding object oriented programming in \fpc. -\fpc supports 2 programming models for object-oriented programming. -You can choose to program object oriented using the Turbo Pascal approach, -or you can prefer the Delphi approach. - -\subsection{The Turbo Pascal approach} -In the Turbo Pascal approach, Objects should be treated as a special kind of -record. The record contains all the fields that are declared in the objects -definition, and pointers to the methods that are associated to the objects' -type. +Objects should be treated as a special kind of record. The record contains +all the fields that are declared in the objects definition, and pointers +to the methods that are associated to the objects' type. An object is declared just as you would declare a record; except that you can now declare procedures and fuctions as of they were part of the record. @@ -667,7 +734,25 @@ TObj = Object [(ParentObjectType)] end; \end{verbatim} You can repeat as many \var{private} and \var{public} blocks as you want. -\var{Method}s are normal function or procedure declarations. +\var{Method}s are normal function or procedure declarations. You cannot put +fields after methods in the same block, i.e. the following will generate an +error when compiling: +\begin{verbatim} +Type MyObj = Object + Procedure Doit; + Field : Longint; + end; +\end{verbatim} +But the following will be accepted: +\begin{verbatim} +Type MyObj = Object + Public + Procedure Doit; + Private + Field : Longint; + end; +\end{verbatim} +because the field is in a different section. As can be seen in the prototype object declaration, \fpc supports constructors and destructors. You are responsible for calling the @@ -731,11 +816,17 @@ Var PP : Pobj; \end{verbatim} Similarly, the \var{\{\$PACKRECORDS \}} directive acts on objects as well. -\subsection{The Delphi approach} +\section{Classes} In the Delphi approach to Object Oriented Programming, everything revolves -around the concept of 'Classes'. -A class can be seen as a pointer to an object, or a pointer to a record. +around the concept of 'Classes'. A class can be seen as a pointer to an +object, or a pointer to a record. +In order to use objects, it is necessary to put the \file{objpas} unit in the +uses clause of your unit or program. This unit contains the basic +definitions of \var{TObject} and \var{TClass}, as well as some auxiliary +methods for using classes. + +\subsection{Class definitions} The prototype declaration of a class is as follows : \begin{verbatim} TObj = Class [(ParentClassType)] @@ -752,15 +843,38 @@ TObj = Class [(ParentClassType)] PrFieldn : PrTypen; PrMethod1; ... - PrMethodn;] + PrMethodn; + ] + [protected + PuField1 : PuType1; + .. + Pufield1 : PuTypen; + PuMethod1; + ... + PuMethodn; + Property1; + ... + Propertyn; [public PuField1 : PuType1; .. Pufield1 : PuTypen; PuMethod1; ... - PuMethodn;] - end; + PuMethodn; + Property1; + ... + Propertyn;] + [published + PuField1 : PuType1; + .. + Pufield1 : PuTypen; + PuMethod1; + ... + PuMethodn; + Property1; + ... + Propertyn;] \end{verbatim} You can repeat as many \var{private} and \var{public} blocks as you want. \var{Method}s are normal function or procedure declarations. @@ -769,7 +883,23 @@ As you can see, the declaration of a class is almost identical to the declaration of an object. The real difference between objects and classes is in the way they are created; -Classes must be created using their constructor. Remember that A class is a +The visibility of the different sections is as follows: +\begin{description} +\item [Private\ ] All fields and methods that are in a \var{private} block, can +only be accessed in the module (i.e. unit) that contains the class definition. +They can be accessed from inside the classes' methods or from outside them +(e.g. from other classes' methods) +\item [Protected\ ] Is the same as \var{Private}, except that the members of +a \var{Protected section} are also accessible to descendent types, even if +they are implemented in other modules. +\item [Public\ ] sections are always accessible. +\item [Published\ ] Is the same as a \var{Public} section, but the compiler +generates also type information that is needed for automatic streaming of +these classes. Fields defined in a \var{published} section must be of class type. +Array peroperties cannot be in a \var{published} section. +\end{description} + +Classes must be created using their constructor. Remember that a class is a pointer to an object, so when you declare a variable of some class, the compiler just allocates a pointer, not the entire object. The constructor of a class returns a pointer to an initialized instance of the object. @@ -781,7 +911,6 @@ So, to initialize an instance of some class, you do the following : {\em Remark :} \begin{itemize} -\item \fpc doesn't support the concept of properties yet. \item The \var{\{\$Packrecords \}} directive also affects classes. i.e. the alignment in memory of the different fields depends on the value of the \var{\{\$Packrecords \}} directive. @@ -790,6 +919,139 @@ This has the same effect as on an object, or record, namely that the elements are aligned on 1-byte boundaries. i.e. as close as possible. \end{itemize} +\subsection{Properties} + +Classes can contain properties as part of their fields list. A property +acts like a normal field, i.e. you can get or set it's value, but allows to redirect the access of the field through +functions and procedures. Moreover, properties can be read-only. + +the prototype declaration of a property is +\begin{verbatim} +property Name : Type [Read ReadSpecifier [write WriteSpecifier]]; +\end{verbatim} +A \var{ReadSpecifier} is either the name of a field that contains the +property, or the name of a method function that has the same return type as +the property type. In the case of a simple type, this +function must not accept an argument. + +A \var{WriteSpecifier} is optional: If there is no write specifier, the +property is read-only. A write specifier is either the name of a field, or +the name of a method procedure that accepts as a sole argument a variable of +the same type as the property. You cannot specify only a write specifier. + +The section (\var{private}, \var{published} in which the specified function or +procedure resides is irrelevant. Usually, however, this will be a protected +or private method. + +Example: +Given the following declaration: +\begin{verbatim} +Type + MyClass = Class + Private + Field1 : Longint; + Field2 : Longint; + Field3 : Longint; + Procedure Sety (value : Longint); + Function Gety : Longint; + Function Getz : Longint; + Public + Property X : Longint Read Field1 write Field2; + Property Y : Longint Read GetY Write Sety; + Property Z : Longint Read GetZ; + end; + +Var MyClass : TMyClass; +\end{verbatim} +The following are valid statements: +\begin{verbatim} +Writeln ('X : ',MyClass.X); +Writeln ('Y : ',MyClass.Y); +Writeln ('Z : ',MyClass.Z); +MyClass.X:=0; +MyClass.Y:=0; +\end{verbatim} +But the following would generate an error: +\begin{verbatim} +MyClass.Z:=0; +\end{verbatim} +because Z is a read-only property. + +What happens in the above statements is that when a value needs to be read, +the compiler inserts a call to the various \var{getNNN} methods of the +object, and the result of this call is used. When an assignment is made, +the compiler passes the value that must be assigned as a paramater to +the various \var{setNNN} methods. + +Because of this mechanism, properties cannot be passed as var arguments to a +function or procedure, since there is no known address of the property (at +least, not always). + +You can also have array properties. These are properties that accept an +index, just as an array. Only now the index doesn't have to be an ordinal +type, but can be any type. An array Property is defined as follows: +\begin{verbatim} +property Name[Index : IndexType]: Type [Read ReadSpecifier [write WriteSpecifier]]; +\end{verbatim} +A \var{ReadSpecifier} is the name method function that has the same return +type as the property type. The function must accept as a sole arguent a +variable of the same type as the index type. You cannot specify fields as +arrar types. + +A \var{WriteSpecifier} is optional: If there is no write specifier, the +property is read-only. A write specifier is the name of a method procedure +that accepts two arguments: The first argument has the same type as the +index, and the second argument is a variable of the same type as the +property type. You cannot specify only a write specifier. + +As an example, see the following declaration: +\begin{verbatim} +Type TIntList = Class + Private + Function GetInt (I : Longint); + Function GetAsString (A : String) : String; + Procedure SetInt (I : Longint; Value : longint;); + Procedure SetAsString (A : String; Value : String); + Public + Property Items [i : Longint] : Longint Read GetInt Write SetInt; + Property StrItems [S : String] : String Read GetAsString Write SetAsstring; + end; + +Var AIntList : TIntList; +\end{verbatim} +Then the following statements would be valid: +\begin{verbatim} +AIntList.Items[26]:=1; +AIntList.StrItems['twenty-five']:='zero'; + +Writeln ('Item 26 : ',AIntList.Items[26]); +Writeln ('Item 25 : ',AIntList.StrItems['twenty-five']); +\end{verbatim} +While the following statements would generate errors: +\begin{verbatim} +AIntList.Items['twenty-five']:=1; +AIntList.StrItems[26]:='zero'; +\end{verbatim} +Because the index types are wrong. + +Array properties can be declared as \var{default} properties. This means that +it is not necessary to specifiy the property name when assigning or readin +it. If, in the previous example, the definition of the items property would +have been +\begin{verbatim} + Property Items [i : Longint] : Longint Read GetInt Write SetInt; Default; +\end{verbatim} +Then the assignment +\begin{verbatim} +AIntList.Items[26]:=1; +\end{verbatim} +Would be equivalent to the following abbreviation. +\begin{verbatim} +AIntList[26]:=1; +\end{verbatim} +You can have only one default property per class, and descendent classes +cannot redeclare the default property. + \section{Statements controlling program flow.} \subsection{Assignments} @@ -847,30 +1109,6 @@ end; The compiler will generate a \var{Duplicate case label} error when compiling this, because the 3 also appears (implicitly) in the range \var{1..5} -{\em Remark:} In versions earlier than 0.9.7, there was an incompatibility here -with Turbo Pascal. Where in Turbo Pascal you could do the following: -\begin{verbatim} -case Pivot of - ... -Else - begin - Statement1 - Statement2 - end; -\end{verbatim} -You needed to do the following in \fpc : -\begin{verbatim} -case Pivot of - ... -Else - begin - Statement1 - Statement2 - end; -end; -\end{verbatim} -So there's an extra \var{end} keyword at the end. But from version 0.9.7 -this has been fixed. \subsection{The \var{For..to/downto..do} statement} \fpc supports the \var{For} loop construction. The prototypes are: \begin{verbatim} @@ -882,7 +1120,12 @@ For Counter:=Upperbound downto Lowerbound Do Statement; \end{verbatim} \var{Statement} can be a compound statement. In the first case, if \var{Lowerbound} is larger than \var{Upperbound} then \var{Statement} will -never be executed. +never be executed. \var{Counter} must be an ordinal type, no other types can +be used as counters in a loop. + +{\em Remark:} Contrary to ANSI pascal specifications, \fpc first initializes +the counter variable, and only then calculates the upper bound. + \subsection{The \var{Goto} statement} \fpc supports the \var{goto} jump statement. Its prototype is \begin{verbatim} @@ -987,6 +1230,159 @@ that are surrounded by the keywords \var{Begin} and \var{End}. The Last statement doesn't need to be followed by a semicolon, although it is allowed. +\subsection{Exceptions} + +As of version 0.99.7, \fpc supports exceptions. Exceptions provide a +convenient way to program error and error-recovery mechanisms, and are +closely related to classes. + +Exception support is based on 3 constructs: +\begin{description} +\item [Raise\ ] statements. To raise an exeption. This is usually done to signal an +error condition. +\item [Try ... Except\ ] blocks. These block serve to catch exceptions +raised within the scope of the block, and to provide exception-recovery +code. +\item [Try ... Finally\ ] blocks. These block serve to force code to be +executed irrespective of an exception occurrence or not. They generally +serve to clean up memory or close files in case an exception occurs. +code. +\end{description} + +The \var{raise} statement is as follows: +\begin{verbatim} + Raise [ExceptionInstance [at Address]]; +\end{verbatim} +This statement will raise an exception. If specified, \var{ExceptionInstance} +must be an initialized instance of a class, which is the raise type. If +specified, \var{Address} must be an expression that returns an address. + +If \var{ExceptionInstance} is omitted, then the Current exception is +re-raised. This construct can only be used in an exception handling +block. + +As an example: The following division checks whether the denominator is +zero, and if so, raises an exception of type \var{EDivException} +\begin{verbatim} +Type EDivException = Class(Exception); + +Function DoDiv (X,Y : Longint) : Integer; + +begin + If Y=0 then + Raise EDivException.Create ('Division by Zero would occur'); + Result:=X Div Y; +end; +\end{verbatim} +The class \var{Exception} is defined in the \file{Sysutils} unit of the rtl. + +An exception handling block is of the following form : +\begin{verbatim} + Try + ...Statement List... + Except + [On [E:] ExceptionClass do CompoundStatement;] + [ Default exception handler] + end; +\end{verbatim} +If an exception occurs during the execution of the \var{statement list}, the +program flow fill be transferred to the except block. There, the type of the +exception is checked, and if there is a \var{On ExcType} statement where +\var{ExcType} matches the exception object type, or is a parent type of +the exception object type, then the statements follwing the corresponding +\var{Do} will be executed. The first matching type is used. After the +\var{Do} block was executed, the program continues after the \var{End} +statement. + +The identifier \var{E} is optional, and declares an exception object. It +can be used to manipulate the exception object in the exception handling +code. The scope of this declaration is the statement block foillowing the +\var{Do} keyword. + +If none of the \var{On} handlers matches the exception object type, then the +\var{Default exception handler} is executed. If no such default handler is +found, then the exception is automatically re-raised. This process allows +to nest \var{try...except} blocks. + +As an example, given the previous declaration of the \var{DoDiv} function, +consider the following +\begin{verbatim} +Try + Z:=DoDiv (X,Y); +Except + On EDivException do Z:=0; +end; +\end{verbatim} +If \var{Y} happens to be zero, then the DoDiv function code will raise an +exception. When this happens, program flow is transferred to the except +statement, where the Exception handler will set the value of \var{Z} to +zero. If no exception is raised, then program flow continues past the last +\var{end} statement. + +To allow error recovery, the \var{Try ... Finally} block is supported. +A \var{Try...Finally} block ensures that the statements following the +\var{Finally} keyword are guaranteed to be executed, even if an exception +occurs. + +A \var{Try..Finally} block has the following form: + +\begin{verbatim} + Try + ...Statement List... + Finally + [ Finally Statements ] + end; +\end{verbatim} +If no exception occurs inside the \var{Statement List}, then the program +runs as if the \var{Try}, \var{Finally} and \var{End} keywords were not +present. + +If, however, an exception occurs, the program flow is immediatly +transferred to the first statement of the \var{Finally statements}. +All statements of the \var{Finally Statements} will be executed, and then +the exception will be automatically re-raised. Any statements between the +place where the exception was raised and the first statement of the +\var{Finally Statements} are skipped. + +As an example consider the following routine: + +\begin{verbatim} +Procedure Doit (Name : string); + +Var F : Text; + +begin + Try + Assign (F,Name); + Rewrite (name); + + ... File handling ... + + Finally + Close(F); + end; +\end{verbatim} +If during the execution of the file handling an excption occurs, then +program flow will continue at the \var{close(F)} statement, skipping any +file operations that might follow between the place where the exception +was raised, and the \var{Close} statement. + +If no exception occurred, all file operations will be executed, and the file +will be closed at the end. + +It is possible to nest \var{Try...Except} blocks with \var{Try...Finally} +blocks. Program flow will be done according to a \var{lifo} (last in, first +out) principle: The code of the last encountered \var{Try...Except} or + \var{Try...Finally} block will be executed first. If the exception is not +caught, or it was a finally statement, program flow will we transferred to +the last but-one block, {\em ad infinitum}. + +If an exception occurs, and there is no exception handler present, then a +runerror 217 will be generated. If you use the \file{sysutils} unit, a default +handler is installed which ioll show the exception object message, and the +address where the exception occurred, after which the program will exit with +a \var{Halt} instruction. + \section{Using functions and procedures} \fpc supports the use of functions and procedures, but with some extras: Function overloading is supported, as well as \var{Const} parameters and @@ -1199,6 +1595,9 @@ an external object file. It allows you to use the function in your code, and at linking time, you must link the object file containing the implementation of the function or procedure. +It replaces, in effect, the function or procedure code block. As such, it +can be present only in an implementation block of a unit, or in a program. + As an example: \begin{CodEx} \begin{verbatim} @@ -1354,7 +1753,7 @@ listed in \seet{Modifs}. Modifier & Why not supported ? \\ \hline Near & \fpc is a 32-bit compiler.\\ Far & \fpc is a 32-bit compiler. \\ -External & Replaced by \var{C} modifier. \\ \hline +%External & Replaced by \var{C} modifier. \\ \hline \end{FPCltable} % diff --git a/docs/refex/ex79.pp b/docs/refex/ex79.pp index 3319a1f670..dc99e00b98 100644 --- a/docs/refex/ex79.pp +++ b/docs/refex/ex79.pp @@ -1,4 +1,4 @@ -program example79 +program example79; { Program to demonstrate the setjmp, longjmp functions } diff --git a/docs/units.tex b/docs/units.tex index 7d151daa0c..648044b9f4 100644 --- a/docs/units.tex +++ b/docs/units.tex @@ -29,8 +29,10 @@ \usepackage{html} \latex{\usepackage{fpc}} \html{\input{fpc-html.tex}} +\usepackage{fancyheadings} +\pagestyle{fancy} +\renewcommand{\chaptermark}[1]{\markboth{#1}{}} \makeindex - % % start of document. % diff --git a/docs/user.tex b/docs/user.tex index c963649ed7..b21583d22f 100644 --- a/docs/user.tex +++ b/docs/user.tex @@ -26,6 +26,9 @@ \latex{\usepackage{fpcman}} \latex{\usepackage{epsfig}} \html{\input{fpc-html.tex}} +\usepackage{fancyheadings} +\pagestyle{fancy} +\renewcommand{\chaptermark}[1]{\markboth{#1}{}} \newcommand{\remark}[1]{\par$\rightarrow$\textbf{#1}\par} \newcommand{\olabel}[1]{\label{option:#1}} % We should change this to something better. See \seef etc. @@ -68,16 +71,17 @@ The \file{README} files are, in case of conflict with this manual, % About the compiler \section{About the compiler} \fpc is a 32-bit compiler for the i386 and m68k processors\footnote{Work is being done -on a port to ALPHA Architecture}. Currently, it supports 2 operating systems: +on a port to ALPHA Architecture}. Currently, it supports 3 operating systems: \begin{itemize} \item \dos \item \linux +\item \windowsnt \end{itemize} and work is in progress to port it to other platforms (notably, \ostwo and -\windowsnt). +). \fpc is designed to be, as much as possible, source compatible with -Turbo Pascal 7.0 and Delphi II (although this goal is not yet attained), +Turbo Pascal 7.0 and Delphi 4 (although this goal is not yet attained), but it also enhances these languages with elements like function overloading. And, unlike these ancestors, it supports multiple platforms. @@ -106,14 +110,16 @@ you can obtain more information on the Internet, on the following addresses: \begin{itemize} \item \htmladdnormallink{http://tfdec1.fys.kuleuven.ac.be/\~{}michael/fpc/fpc.html} -{http://tfdec1.fys.kuleuven.ac.be/\~{}michael/fpc/fpc.html} contains information -on the \linux port of the compiler. It contains also useful mail addresses and -links to other places. +{http://tfdec1.fys.kuleuven.ac.be/\~{}michael/fpc/fpc.html} is the main +site. It contains also useful mail addresses and +links to other places. +It also contains the instructions for inscribing to the +\textit{mailing-list}. + \item \htmladdnormallink{http://www.brain.uni-freiburg.de/\~{}klaus/fpc/fpc.html} -{http://www.brain.uni-freiburg.de/\~{}klaus/fpc/fpc.html} is the main \fpc information site. -It also contains the instructions for inscribing to the \textit{mailing-list}, -another useful source of information. +{http://www.brain.uni-freiburg.de/\~{}klaus/fpc/fpc.html} is a mirror +of the main \fpc information site. \end{itemize} Both places can be used to download the \fpc distribution, although you can probably find them on other places also. @@ -145,7 +151,7 @@ The compiler needs at least the following hardware: \item An I386 or higher processor. A coprocessor is not required, although it will slow down your program's performance if you do floating point calculations. \item 2 Mb of free memory. Under \dos, if you use DPMI memory management, -such as under Windows, you will need at least 8 Mb. +such as under Windows, you will need at least 16 Mb. \item At least 500 Kb. free disk space. \end{enumerate} @@ -175,15 +181,14 @@ Other than that, \fpc should run on almost any I386 \linux system. The installation of \fpc is easy, but is platform-dependent. We discuss the process for each platform separately. - -% -% - % Installing under DOS \subsection{Installing under DOS} \subsubsection{Mandatory installation steps.} First, you must get the latest distribution files of \fpc. They come as zip -files, which you must unzip first. The distribution zip file contains an +files, which you must unzip first, or you can download the compiler as a +series of separate files. This is especially useful if you have a slow +connection, but it is also nice if you want to install only some pats of the +compiler distribution. The distribution zip file contains an installation program \file{INSTALL.EXE}. You must run this program to install the compiler. @@ -203,29 +208,18 @@ The screen of the installation program looks like figure \ref{fig:install}. The program allows you to select: \begin{itemize} -\item What components you wish to install. (e.g do you want the sources or -not, do you want docs or not) Items that you didn't download will not -be enabled, i.e. you can't select them. +\item What components you wish to install. e.g do you want the sources or +not, do you want docs or not. Items that you didn't download when +downloading as separate files, will not be enabled, i.e. you can't +select them. \item Where you want to install (the default location is \verb|C:\PP|). \end{itemize} -The installation program generates a batch file which sets some environment -variables : \verb|SET_PP.BAT|. This file is located in the directory where -you installed \fpc. The installation program doesn't modify the -\file{AUTOEXEC.BAT}, since many people (including the authors of \fpc) -don't like this. -You can choose to insert a call to this batch file in your \file{AUTOEXEC.BAT} -file, like this : -\begin{verbatim} - CALL C:\PP\SET_PP.BAT -\end{verbatim} -(This is assuming that you installed \fpc in the default location.) In order to run \fpc from any directory on your system, you must extend your path variable to contain the \verb|C:\PP\BIN| directory. -You can choose to do this in your \file{AUTOEXEC.BAT} file, but you can also -insert a statement in the \verb|SET_PP.BAT| file. Whatever the location you -choose, It should look something like this : +Usually this is done in the \file{AUTOEXEC.BAT} file. +It should look something like this : \begin{verbatim} SET PATH=%PATH%;C:\PP\BIN \end{verbatim} @@ -242,13 +236,6 @@ coprocessor to do all floating point operations. The installation of the coprocessor emulation is handled by the installation program (\file{INSTALL.EXE}). However, -the installation program has currently a bug: If you select the -coprocessor emulation the program ignores this and you must do -this by hand. You should change the \var{GO32} environment variable in -the \verb|SET_PP.BAT| file, as follows: -\begin{verbatim} -SET GO32=emu C:\PP\DRIVERS\EMU387 -\end{verbatim} % % Installing under Linux @@ -257,7 +244,7 @@ SET GO32=emu C:\PP\DRIVERS\EMU387 \subsubsection{Mandatory installation steps.} The \linux distribution of \fpc comes in three forms: \begin{itemize} -\item a \file{tar.gz} version, +\item a \file{tar.gz} version, also available as seperate files. \item a \file{.rpm} (Red Hat Package Manager) version, and \item a \file{.deb} (debian) version. \end{itemize} @@ -280,9 +267,11 @@ Here again, \var{XXX} is the version number of the \file{.deb} file. You need root access to install these packages. The \file{.tar} file allows you to do an installation if you don't have root permissions. -When downloading the \var{.tar} file, installation is more interactive: +When downloading the \var{.tar} file, or the separate files, + installation is more interactive. -This means that you should first untar the file, in some directory where +I nCAse you downloaded the \file{.tar} file, you should first untar +the file, in some directory where you have write permission, using the following command: \begin{verbatim} tar -xvf fpc.tar @@ -292,7 +281,11 @@ from the Internet. (The real filename will have some version number in it, which we omit here for clarity.) When the file is untarred, you will be left with more archive files, and -an install program: an installation shell script. +an install program: an installation shell script. + +If you downloaded the files as separate files, you should at least download +the \file{install.sh} script, and the libraries (in \file{libs.tar.gz}). + To install \fpc, all that you need to do now is give the following command: \begin{verbatim} ./install.sh @@ -302,8 +295,13 @@ mainly concerned with 2 things : \begin{enumerate} \item Places where you can install different things. \item Deciding if you want to install certain components (such as sources -and demo programs). +and demo programs). \end{enumerate} +The script will automatically detect which components are present and can be +installed. It will only offer to install what has been found. +because of this feature, you must keep the original names when downloading, +since the script expects this. + If you run the installation script as the \var{root} user, you can just accept all installation defaults. If you don't run as \var{root}, you must take care to supply the installation program with directory names where you have write permission, @@ -325,17 +323,18 @@ setenv PPC_CONFIG_PATH /usr/lib/ppc/0.99.1 line to your \file{.login} file in your home directory. (see also the next section) -\subsubsection{Optional configuration steps} -You may wish to set some environment variables. The \linux version of \fpc +\section{Optional configuration steps} +You may wish to set some environment variables. The \fpc compiler recognizes the following variables : \begin{itemize} \item \verb|PPC_EXEC_PATH| contains the directory where '\file{as}' and '\file{ld}' are. (default \file{/usr/bin}) -\item \verb|PPC_GCCLIB_PATH| contains the directory where \file{libgcc.a} is (no default) +\item \verb|PPC_GCCLIB_PATH| contains the directory where \file{libgcc.a} +is (no default). This if for \linux only. \item \verb|PPC_CONFIG_PATH| specifies an alternate path to find -\file{ppc386.cfg} (default \file{/etc}) +\file{ppc386.cfg} (default under \linux is \file{/etc}) \item \verb|PPC_ERROR_FILE| specifies the path and name of the error-definition file. - (default \file{/usr/lib/ppc/errorE.msg}) + (default \file{/usr/lib/fpc/errorE.msg}) \end{itemize} These locations are, however, set in the sample configuration file which is @@ -367,10 +366,21 @@ To compile a program (e.g \verb|demo\hello.pp|) simply type : \begin{verbatim} ppc386 hello \end{verbatim} -at the command prompt. +at the command prompt. If you don't have a configuretion file, then you may +need to tell the compiler where it can find the units, for instance as +follows: +\begin{verbatim} +ppc386 -Upc:\pp\rtl\dos\go32v2 hello +\end{verbatim} +under \dos, and under\linux you could type +\begin{verbatim} +ppc386 -Up/usr/lib/fpc/0.99.7/linuxunits hello +\end{verbatim} +This is, of course, assuming that you installed under \verb|C:\PP| or +\file{/usr/lib/fpc/0.99.7}, respectively. If you got no error messages, the compiler has generated an executable -called \file{hello} (no extension) under \linux, and a file \file{hello.exe} +called \file{hello} (no extension) under \linux, and a file \file{hello.exe} under \dos. To execute the program, simply type : @@ -403,6 +413,159 @@ RTL units. In principle this file is generated by the installation program. You may have to check that it is in the correct place (see section \ref{se:config_file} for more information on this). +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Where the compiler looks for its files. +\section{File searching} +Before you start compiling a program or a series of units, it is +important to know where the compiler looks for its source files and other +files. In this section we discuss this, and we indicate how to influence +this. + +{\em Remark:} +The use of slashes (/) and backslahses ($\backslash$) as directory separators +is irrelevant, the compiler will convert to whatever character is used on +the current operating system. Examples will be given using slashes, since +this avoids problems on \linux. + +% Command-line files. +\subsection{Command line files} +The file that you specify on the command line, such as in +\begin{verbatim} +ppc386 foo.pp +\end{verbatim} +will be looked for ONLY in the current directory. If you specify a directory +in the filename, then the compiler will look in that directory: +\begin{verbatim} +ppc386 subdir/foo.pp +\end{verbatim} +will look for \file{foo.pp} in the subdirectory \file{subdir} of the current +directory. + +Under \linux, the name of this file is case sensitive, under other operating +systems (\dos, \windowsnt, \ostwo) this is not the case. + +% Unit files. +\subsection{Unit files} + +When you compile a unit or program that needs other units, the compiler will +look for compiled versions of these units in the following way: +\begin{enumerate} +\item It will look in the current directory. +\item It will look in the directory where the compiler binary is. +(not under \linux) +\item It will look in all the directories specified in the unit search path. +\end{enumerate} +You can add a directory to the unit search path with the \var{-Up} or +\var{-Fu} options (\seeo{Up}, \seeo{Fu}). Every occurrence of one of +those options will append a directory to the unit search path. + +On \linux, the compiler will first convert the filename of a unit to +all-lowercase. This is necessary, since Pascal is case-independent, and +the statements \var{Uses Unit1;} or \var{uses unit1;} should have the same +effect. +Also, unit names that are longer than 8 characters will first be looked for +with their full length. If the unit is not found with this name, the name +will be truncated to 8 characters, and the compiler will look again in the +same directories, but with the truncated name. + +For instance, suppose that the file \file{foo.pp} needs the unit +\file{bar}. Then the command +\begin{verbatim} +ppc386 -Up.. -Upunits foo.pp +\end{verbatim} +will tell the compiler to look for the unit \file{bar} in the following +places: +\begin{enumerate} +\item In the current directory. +\item In the directory where the compile binary is (not under \linux). +\item In the parent directory of the current directory. +\item In the subdirectory \file{units} of the current directory +\end{enumerate} + +If the compiler finds the unit it needs, it will look for the source file of +this unit in the same directory where it found the unit. +If it finds the source of the unit, then it will compare the file times. +If the source file was modified more recent than the unit file, the +compiler will attempt to recompile the unit with this source file. + +If the compiler doesn't find a compiled version of the unit, or when the +\var{-B} option is specified, then the compiler will look in the same +manner for the unit source file, and attempt to recompile it. + +It is recommended to set the unit search path in the configuration file +\file{ppc386.cfg}. If you do this, you don't need to specify the unit search +path on the command-line every time you want to compile something. + +% Include files. +\section{Include files} +If you include files in your source with the \var{\{\$I filename\}} +directive, the compiler will look for it in the following places: + +\begin{enumerate} +\item It will look in the path specified in the incude file name. +\item It will look in the directory where the current source file is. +\item it will look in all directories specified in the include file search +path. +\end{enumerate} +You can add files to the include file search + path with the \var{-I} (\seeo{I}) +option. + +As an example, consider the following include statement in a file +\file{units/foo.pp}: +\begin{verbatim} + +{$i ../bar.inc} + +\end{verbatim} +Then the following command : +\begin{verbatim} +ppc386 -Iincfiles units/foo.pp +\end{verbatim} +will cause the compiler to look in the following directories for +\file{bar.inc}: +\begin{enumerate} +\item the parent directory of the current directory +\item the \file{units} subdirectory of the current directory +\item the \file{incfiles} directory of the current directory. +\end{enumerate} + +% Object files. +\section{Object files} +When you link to object files (using the \var{\{\$L file.o\}} directive, +the compiler will look for this file in the same way as it looks for include +files: + +\begin{enumerate} +\item It will look in the path specified in the object file name. +\item It will look in the directory where the current source file is. +\item it will look in all directories specified in the object file search path. +\end{enumerate} +You can add files to the object file search path with the \var{-Fo} (\seeo{Fo}) +option. + +% Configuration file +\subsection{Configuration file} +Unless you specify the \var{-n} (\seeo{n}) option, the compiler will look +for a configuration file \file{ppc386.cfg} in the following places: + +\begin{itemize} +\item Under \linux +\begin{enumerate} +\item The current directory. +\item In your home directory, it looks for \file{.ppc386.cfg}. +\item The directory specified in the environment variable +\var{PPC\_CONFIG\_PATH}, and if it's not set under \file{/etc}. +\end{enumerate} +\item Under all other OSes: +\begin{enumerate} +\item The current directory. +\item If it is set, the directory specified in the environment variable. +\var{PPC\_CONFIG\_PATH}. +\item The directory where the compiler is. +\end{enumerate} +\end{itemize} + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Compiling a program @@ -412,7 +575,7 @@ in the file \file{prog.pp}, you can compile this with the following command: \begin{verbatim} ppc386 [options] prog.pp \end{verbatim} -The square brackets [] indicate that what is between them is optional. +The square brackets \var{[\ ]} indicate that what is between them is optional. If your program file has the \file{.pp} or \file{.pas} extension, you can omit this on the command line, e.g. in the previous example you @@ -424,18 +587,19 @@ could have typed: If all went well, the compiler will produce an executable, or, for version 1 of the \dos extender, a file which can be converted to an executable. -Under \linux and version 2 of the \dos extender, the file you obtained is -the executable. You can execute it straight away, you don't need to do -anything else. Under \dos, -additional processing is required. See the section on creating an -executable. +Unless you are using \dos and version 1 of the \dos extender, +the file you obtained is the executable. +You can execute it straight away, you don't need to do +anything else. Under version 1 of the \dos extender, +additional processing is required. See section \ref{go32v1} on how to +create an executable in this case. -You will notice that there is also anothe file in your directory, with -extensions \file{.o}. This contains, the object file for your program. +You will notice that there is also another file in your directory, with +extensions \file{.o}. This contains the object file for your program. If you compiled a program, you can delete the object file (\file{.o}), but not if you compiled a unit. Then the object file contains the code of the unit, and will be -linked in any program that uses the unit you compiled, so you shpuldn't +linked in any program that uses the unit you compiled, so you shouldn't remove it. @@ -478,9 +642,10 @@ letters. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Creating an executable for GO32V1, PMODE/DJ targets \section{Creating an executable for GO32V1 and PMODE/DJ targets} +\label{go32v1} -This section applies only to \dos users. \linux users can skip this -section (unless they're cross-compiling) +The GO32V1 platform is officially no longer supported, so this section +is of interest only to people who wish to make go32V1 binaries anyway. % % GO32V1 @@ -580,7 +745,15 @@ information from your program. This can lead to size reductions of up to 30 \%. You can use the \var{-Xs} switch to let the compiler do this stripping -automatically. +automatically at program compile time (the switch has no effect when +compiling units). + +Another technique to reduce the size of a program is to use smartlinking. +Normally, units (including the system unit) are linked in as a whole. +It is however possible to compile units such that the can be smartlinked. +This means that only the functions and procedures are linked in your +program, leaving out any unnecessary code. This technique is described in +full in the programmers guide. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Problems @@ -595,11 +768,13 @@ automatically. compiler startup. It means typically that the compiler doesn't find the error definitions file. You can correct this mistake with the \var{-Fr} option under \linux. (\seeo{Fr}) -\item \textbf {Error : File not found : xxx} This typically happens when +\item \textbf {Error : File not found : xxx} or \textbf{Error: couldn't compile +unit xxx}: This typically happens when your unit path isn't set correctly. Remember that the compiler looks for units only in the current directory, and in the directory where the compiler itself is. If you want it to look somewhere else too, you must explicitly -tell it to do so using the \var{-Up} option (\seeo{Up}). +tell it to do so using the \var{-Up} option (\seeo{Up}). Or you must set op +a configuration file. \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -625,7 +800,7 @@ a message that there is no coprocessor, install the coprocessor emulation. \item \textbf{Not enough DPMI memory}\\ If you want to use the compiler with \var{DPMI} you must have at least -7-8 MB free \var{DPMI} memory. +7-8 MB free \var{DPMI} memory, but 16 Mb is a more realistic amount. \end{itemize} @@ -667,19 +842,12 @@ The available options are listed by category: \item[-h] if you specify this option, the compiler outputs a list of all options, and exits after that. \olabel{h} -\item[-?] idem as \var{-h}. +\item[-?] idem as \var{-h}, waiting after every screenfull for the enter key. \item[-i] This option tells the compiler to print the copyright information. \olabel{i} \item[-l] This option tells the compiler to print the \fpc logo on standard output. It also gives you the \fpc version number. \olabel{l} -\item[-Lx] Set the language the compiler uses for its messages. -\olabel{L} -\var{x} can be one of the following: -\begin{itemize} -\item \textbf{D} : Use German. -\item \textbf{E} : Use English. -\end{itemize} \item [-n] Tells the compiler not to read the configuration file. \olabel{n} \end{description} @@ -709,9 +877,11 @@ conditional. \item \var{m} : Tells the compiler to write which macros are defined. \item \var{d} : Tells the compiler to write other debugging info. \item \var{a} : Tells the compiler to write all possible info. (this is the -same as spcifying all options) +same as specifying all options) \item \var{0} : Tells the compiler to write no messages. This is useful when you want to override the default setting in the configuration file. +\item \var{b} Tells the compiler to show all procedure declarations if an +overloaded function error occurs. \end{itemize} \end{description} @@ -720,7 +890,7 @@ you want to override the default setting in the configuration file. % \subsection{Options concerning files and directories} \begin{description} -\item [-exxx] (\linux only) \file{xxx} specifies the directory where the +\item [-exxx] \file{xxx} specifies the directory where the compiler can find the executables \file{as} (the assembler) and \file{ld} (the compiler). \olabel{e} @@ -736,11 +906,21 @@ its include files. \item [-Flxxx] Adds \var{xxx} to the library searching path, and is passed to the linker. \olabel{Fl} -\item [-Frxxx] (\linux only) \file{xxx} specifies the path where the -compiler can find the error-definitions file. +\item[-FLxxx] (\linux only) Tells the compiler to use \file{xxx} as the +dynamic linker. Default this is \file{/lib/ld-linux.so.2}, or +\file{lib/ld-linux.so.1}, depending on which one is found. +\olabel{FL} +\item[-Foxxx] Adds \file{xxx} to the object file path. This path is used +when looking for files that need to be linked in. +\olabel{Fo} +\item [-Frxxx] \file{xxx} specifies the file which contain the compiler +messages. Default the compiler ahs built-in messages. Specifying this option +will override the default messages. \olabel{Fr} -\item [-Fuxxx] Idem as \var{-Up}. +\item [-Fuxxx] Idem as \var{-Up}: Add \file{xxx} to the object path. \olabel{Fu} +\item [-Ixxx] \olabel{I} Add \file{xxx} to the include file search path. +This path is used when looking for include files. \item [-P] uses pipes instead of files when assembling. This may speed up the compiler on \ostwo and \linux. Only with assemblers (such as \gnu \file{as}) that support piping.. @@ -757,49 +937,60 @@ for more information on these options, see also \progref \begin{description} \item [-a] \olabel{a} Tells the compiler not to delete the assembler file. This also counts for the (possibly) generated batch script. +\item [-al] \olabel{al} Tells the compiler to include the sourcecode lines +in the assembler file as comments. This feature is still experimental, and +should be used with caution. \item [-Axxx] \olabel{A}specifies what kind of assembler should be generated . Here \var{xxx} is one of the following : \begin{itemize} -\item \textbf{att} : AT\&T assembler. -\item \textbf{o} : A unix .o (object) file. -\item \textbf{obj} : A OMF file for using the NASM assembler. -\item \textbf{nasm} : a coff file using the NASM assembler. -\item \textbf{masm} : An assembler file for the Microsoft/Borland/Watcom assembler. +\item \textbf{o} : A unix .o (object) file, using \gnu \file{as}. +\item \textbf{nasmcoff} : a coff file using the \file{nasm} assembler. +\item \textbf{nasmelf} : a ELF32 file (\linux only) using the \file{nasm} assembler. +\item \textbf{nasmonj} : a obj file using the \file{nasm} assembler. +\item \textbf{masm} : An obj file using the Microsoft \file{masm} assembler. +\item \textbf{tasm} : An obj file using the Borland \file{tasm} assembler. \end{itemize} -\item [-CD] Force dynamic linking. -\item [-Chxxx] \olabel {Ch} Reserves \var{xxx} bytes heap. -\item [-Ci] \olabel{Ci} Generate Input/output checking code. +\item [-CD] Create dynamic library. +\item [-Chxxx] \olabel {Ch} Reserves \var{xxx} bytes heap. \var{xxx} should +be between 1024 and 67107840. +\item [-Ci] \olabel{Ci} Generate Input/Output checking code. \item [-Cn] \olabel{Cn} Omit the linking stage. \item [-Co] \olabel{Co} Generate Integer overflow checking code. \item [-Cr] \olabel{Cr} Generate Range checking code. -\item [-Csxxx] \olabel{Cs} Set stack size to \var{xxx}. (\ostwo only). -\item [CS] \olabel{CS} Statically link your program/unit. +\item [-Csxxx] \olabel{Cs} Set stack size to \var{xxx}. +\item [-CS] \olabel{CS} Create static library. \item [-Ct] \olabel{Ct} generate stack checking code. +\item [-Cx] \olabel{Cx} Use smartlinking when compiling and linking units. \item [-dxxx] \olabel{d} Define the symbol name \var{xxx}. This can be used to conditionally compile parts of your code. \item {-E} \olabel{E} Same as \var{-Cn}. \item [-g] \olabel{g} Generate debugging information for debugging with -\file{gdb}. -\item [-gp] \olabel{gp} Generate profiler code for \file{gprof}. -\item[-On] \olabel{O} optimize the compiler's output; \var{n} can have one +\file{gdb} +\item [-gg] idem as \var{-g}. +\item [-gd] \olabel{gd} generate debugging info for \file{dbx}. + +\item[-Oxxx] \olabel{O} optimize the compiler's output; \var{xxx} can have one of the following values : \begin{description} -\item[a] simple optimizations -\item[g] optimize for size -\item[G] optimize for time -\item[x] optimize maximum -\item[z] uncertain optimizations -\item[2] optimize for Pentium II (tm) -\item[3] optimize for i386 -\item[4] optimize for i486 -\item[5] optimize for Pentium (tm) -\item[6] optimizations for PentiumPro (tm) +\item[g] optimize for size, try to generate smaller code. +\item[G] optimize for time, try to generate faster code (default). +\item[r] keep certain variables in registers (experimental, use with +caution). +\item[u] uncertain optimizations +\item[1] Level 1 optimizations (quick optimizations). +\item[2] Level 2 optimizations (\var{-O1} plus some slower optimizations). +\item[3] Level 2 optimizations (\var{-O2} plus \var{-Ou}). +\item[Pn] Specify processor: \var{n} can be one of +\begin{description} +\item[1] optimize for 386/486 +\item[2] optimize for Pentium/PentiumMMX (tm) +\item[3] optimizations for PentiumPro/PII/Cyrix 6x86/K6 (tm) \end{description} -The exact effect of these effects can be found in the appendices of the -\progref. +\end{description} +The exact effect of these effects can be found in the \progref. \item [-oxxx] Tells the compiler to use \var{xxx} as the name of the output file (executable). Only with programs. -\item [-pg] Tells the compiler to issue code for profiling support. +\item [-pg] \olabel{gp} Generate profiler code for \file{gprof}. \item [-s] \olabel{s} Tells the compiler not to call the assembler and linker. Instead, the compiler writes a script, \file{PPAS.BAT} under \dos, or \file{ppas.sh} under \linux, which can then be executed to produce an @@ -807,23 +998,30 @@ executable. \item[-Txxx] \olabel{T}Specifies the target operating system. \var{xxx} can be one of the following: \begin{itemize} -\item \textbf{DOS} : \dos and the DJ DELORIE extender. -\item \textbf{OS2} : OS/2 (2.x) (this is still under development). -\item \textbf{LINUX} : \linux. -\item \textbf{WIN32} : Windows 32 bit (this is still under development). +\item \textbf{GO32V1} : \dos and version 1 of the DJ DELORIE extender. \item \textbf{GO32V2} : \dos and version 2 of the DJ DELORIE extender. +\item \textbf{LINUX} : \linux. +\item \textbf{OS2} : OS/2 (2.x) (this is still under development). +\item \textbf{WIN32} : Windows 32 bit (this is still under development). \end{itemize} +\item [-uxxx] \olabel{u} undefine the symbol \var{xxx}. This is the opposite +of the \var{-d} option. \item [-Uld] \olabel{Uld} make dynamic library from unit. \item [-Uls] \olabel{Uls} make static library from unit. \item [-uxxx] \olabel{U} Undefine symbol \var{xxx}. + \item [-Xx] \olabel{X} executable options. This tells the compiler what -kind of \linux executable should be generated. the parameter \var{x} +kind of executable should be generated. the parameter \var{x} can be one of the following: \begin{itemize} % \item \textbf{e} : (\linux only) Create an \file{ELF} executable (default). \item \textbf{c} : (\linux only) Link with the C library. You should only use this when -you start to port \fpc to another operating system. -\item \textbf{s} : (\dos only) Strip the symbols from the executable. + you start to port \fpc to another operating system. +\item \textbf{D} : Link with dynamic libraries (defines the +\var{FPC\_LINK\_DYNAMIC} symbol) +\item \textbf{s} : Strip the symbols from the executable. +\item \textbf{S} : Link with static libraries (defines the +\var{FPC\_LINK\_STATIC} symbol) \end{itemize} \end{description} @@ -831,6 +1029,7 @@ you start to port \fpc to another operating system. % % Options concerning the sources (language options) + \subsection{Options concerning the sources (language options)} for more information on these options, see also \progref \begin{description} @@ -845,6 +1044,8 @@ file. \item [-S2] \olabel{Stwo} Switch on Delphi 2 extensions. \item [-Sc] \olabel{Sc} Support C-style operators, i.e. \var{*=, +=, /= and -=}. +\item [-Sd] tells the compiler to dispose asmlists. This uses less memory, +but is slower. \item [-Se] \olabel{Se} The compiler stops after the first error. Normally, the compiler tries to continue compiling after an error, until 50 errors are reached, or a fatal error is reachd, and then it stops. With this switch, @@ -852,13 +1053,18 @@ the compiler will stop after the first error. \item [-Sg] \olabel{Sg} Support the \var{label} and \var{goto} commands. \item [-Si] \olabel{Si} Support \var{C++} style INLINE. \item [-Sm] \olabel{Sm} Support C-style macros. -\item [-So] \olabel{So} Try to be Borland TP compatible (no function +\item [-So] \olabel{So} Try to be Borland TP 7.0 compatible (no function overloading etc.). +\item [-Sp] \olabel{Sp} Try to be \file{gpc} (\gnu pascal compiler) +compatible. \item [-Ss] \olabel{Ss} The name of constructors must be \var{init}, and the name of destructors should be \var{done}. \item [-St] \olabel{St} Allow the \var{static} keyword in objects. -\item [-Un] \olabel{Un} Do not check the unit name. (Normally, the unit name -is the same as the filename. This option allows both to be different.) +\item [-Sv] allow variable directives (cvar, external, public, export). +You cannot use the \var{cvar} or \var{external} modifiers on variables, +unless you use this switch. +\item [-Un] \olabel{Un} Do not check the unit name. Normally, the unit name +is the same as the filename. This option allows both to be different. \item [-Us] \olabel{Us} Compile a system unit. This option causes the compiler to define only some very basic types. \end{description} @@ -1075,7 +1281,8 @@ on more than one operating system. In general we can say that if you keep your program code close to ANSI Pascal, you will have no problems porting from Turbo Pascal, or even Delphi, to \fpc. To a large extent, the constructs defined by Turbo Pascal are -supported. +supported. This is even more so if you use the \var{-So} or \var{-S2} +switches. In the following sections we will list the Turbo Pascal constructs which are not supported in \fpc, and we will list in what ways \fpc extends the Turbo @@ -1090,29 +1297,34 @@ which are not supported by \fpc. Where possible, we indicate the reason. \begin{enumerate} \item Parameter lists of previously defined functions and procedures must match exactly. The reason for this is the function overloading mechanism of -\fpc. (however, \seeo{So}) +\fpc. (however, the \var{-So} switch solves this. \seeo{So}) \item \var {(* ... *)} as comment delimiters are not allowed in versions older than 0.9.1. This can easily be remedied with a grown-up editor. \item The \var{MEM, MEMW, MEML} and \var{PORT} variables for memory and port access are not available. This is due to the operating system. Under -\dos, the extender unit (\file {GO32.PPU} provides functions to remedy this. -\item \var{PROTECTED, PUBLIC, TRY, THROW, EXCEPTION} are reserved words. -This means you cannot create procedures or variables with the same name. -While they are not reserved words in Turbo Pascal, they are in Delphi. +\dos, the extender unit (\file {GO32.PPU}) implements the mem constuct. +under \linux, the \file{ports} unit implements such a construct. +\item \var{PROTECTED, PUBLIC, PUBLISHED, TRY, FINALLY, EXCEPT, RAISE} +are reserved words. This means you cannot create procedures or variables +with the same name. While they are not reserved words in Turbo Pascal, +they are in Delphi. Using the \var{-So} switch will solve this problem if +you want to compile Turbo Pascal code that uses these words. \item The reserved words \var{FAR, NEAR} are ignored. This is because \fpc is a 32 bit compiler, so they're obsolete. \item \var{INTERRUPT} only will work on a DOS machine. \item Boolean expressions are only evaluated until their result is completely determined. The rest of the expression will be ignored. -\item At the moment of writing, the assembler syntax used in \fpc is \var{AT\&T} -assembler syntax. This is mainly because \fpc uses \gnu \var{as}. +\item By default the compiler uses \var{AT\&T} assembler syntax. +This is mainly because \fpc uses \gnu \var{as}. However other assembler +forms are available, \progref. \item Turbo Vision is not available. \item The 'overlay' unit is not available. It also isn't necessary, since \fpc is a 32 bit compiler, so program size shouldn't be a point. \item There are more reserved words. (see appendix \ref{ch:reserved} for a list of all reserved words.) \item The command-line parameters of the compiler are different. -\item The compiler switches behave different. +\item Compiler switches and directives are mostly the same, but some extra +exist. \item Units are not binary compatible. \end{enumerate} @@ -1283,24 +1495,117 @@ programs and units. Here we list these programs and units. % Supplied programs \section{Supplied programs} -\begin{itemize} -\item \file{dumppu} is a program which shows the contents of a \fpc unit. It -comes in source form, and must be compiled before you can use it. Once -compiled, you can just issue the following command +\subsection{ppudump program} + +\file{ppudump} is a program which shows the contents of a \fpc unit. It +is distributed with the compiler you can just issue the following command \begin{verbatim} - dumppu foo.ppu + ppudump [options] foo.ppu \end{verbatim} -to display the contents of the \file{foo.ppu} unit. -\item Also distributed with Free Pascal comes a series of demonstration programs. +to display the contents of the \file{foo.ppu} unit. You can specify multiple +files on the command line. + +The options can be used to change the verbosity of the display. By default, +all available information is displayed. +You can set the verbosity level using the \var{-Vxxx} option. +Here, \var{xxx} is a combination of the following +letters: +\begin{description} +\item [h:\ ] show header info. +\item [i:\ ] show interface information. +\item [m:\ ] show implementation information. +\item [d:\ ] show only (interface) definitions. +\item [s:\ ] show only (interface) symbols. +\item [b:\ ] show browser info. +\item [a:\ ] show everything (default if no -V option is present). +\end{description} + +\subsection{Demo programs} +Also distributed with \fpc comes a series of demonstration programs. These programs have no other purpose than demonstrating the capabilities of \fpc. They are located in the \file{demo} directory of the sources. -\item All example programs of the documentation are available. Check out the + +\subsection{Documentation Example programs} + +All example programs of the documentation are available. Check out the directories that end on \file{ex} in the documentation sources. There you will find all example sources. -\item \file{ppumove} is a program to make shared or static libraries from -units. It should be distributed in binary form along with the compiler. -\end{itemize} +\subsection{ppumove program} +\file{ppumove} is a program to make shared or static libraries from +multiple units. It can be compared with the \file{tpumove} program that +comes with +Turbo Pascal. + +It should be distributed in binary form along with the compiler. + +It's usage is very simple: +\begin{verbatim} +ppumove [options] unit1.ppu unit2.ppu ... unitn.ppu +\end{verbatim} +Where \var{options} is a combination of +\begin{description} +\item[-b:\ ] If specified, ppumve will generate a batch file that will +contain the external linking and archiving commands that must be +executed. The name of this batch file is \file{pmove.sh} on \linux, and +\file{pmove.bat} otherwise. +\item[-d xxx:\ ] If specified, the output files will put in the directory +\file{xxx} +\item[-e xxx:\ ] Sets the extension of the moved unit files to \file{xxx}. +By default, this is \file{.ppl}. You don't have to specify the dot. +\item[-o xxx:\ ] sets the name of the output file, i.e. the name of the file +containing all the units. This parameter is mandatory when you use multiple +files. On \linux, \file{ppumove} will prepend this name with \file{lib} if it isn't +already there, and will add an extension appropriate to the type of library. +\item [-q:\ ] Causes \file{ppumove} to operate silently. +\item [-s:\ ] Tells \file{ppumove} to make a static library instead of a +dynamic one; By default a dynamic library is made on \linux. +\item [-w:\ ] Tells ppumove that it is working under \windowsnt. This will +change the names of te linker and archiving program to \file{ldw} and +\file{arw}, respectively. +\item[-h or -?:\ ] will display a short help. +\end{description} + +The action of the ppumve program is as follows: +It takes each of the unit files, and modifies it so that the compile will +know that it should look for the unit code in the library. The new unit +files will have an extension \file{.ppu}, this can be changed with the +\var{-e} option. It will then put together all the object files of the units +into one library, static or dynamic, depending on the presence of the +\var{-s} option. + +The name of this library must be set with the \var{-o} option. +If needed, the prefix \file{lib} will be prepended under \linux.. +The extension will be set to \file{.a} for static libraries, +for shared libraries the extensions are \var{.so} on linux, and \var{.dll} +under \windowsnt and \ostwo. + +As an example, the following command +\begin{verbatim} +./ppumove -o both -e ppl ppu.ppu timer.ppu +\end{verbatim} +under linux, will generate the following output: +\begin{verbatim} +PPU-Mover Version 0.99.7 +Copyright (c) 1998 by the Free Pascal Development Team + +Processing ppu.ppu... Done. +Processing timer.ppu... Done. +Linking timer.o ppu.o +Done. +\end{verbatim} +And it will produce the following files: +\begin{enumerate} +\item \file{libboth.so} : The shared library containing the code from +\file{ppu.o} and \file{timer.o}. Under \windowsnt, this file would be called +\file{both.dll}. +\item \file{timer.ppl} : The unit file that tells the \fpc compiler to look +for the timer code in the library. +\item \file{ppu.ppl} : The unit file that tells the \fpc compiler to look +for the timer code in the library. +\end{enumerate} +You could then use or distribute the files \file{libboth.so}, \file{timer.ppl} +and \file{ppu.ppl}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Supplied units @@ -1373,6 +1678,16 @@ It also supports long options. code. \item [sockets] This unit gives you access to sockets and TCP/IP programming. +\item [graph] Is an implementation of Borlands \file{graph} unit, which +works on the Linux console. It's implementation is fairly complete, the only +non-functional things are the fillpatterns and line styles. It uses the +libvga and libvgagl graphics libraries, so you need these installed for this +unit to work. Also, programs using this library need to be run as root, or +setuid root, and hence are a potential security risk. +\item [ports] This implements the various \var{port[]} constructs. These are +provided for compatibility only, and it is not recommended to use them +extensively. Programs using this construct must be run as ruit or setuid +root, and are a serious security risk on your system. \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1612,6 +1927,11 @@ The two example programs in this chapter have been tested on the command line and worked, under the condition that no spaces were present in the name and value pairs provided to them. +There is however, a faster and generally better \file{uncgi} unit available, +you can find it on the contributed units page of the \fpc web site. It uses +techniques discussed here, but in a generally more efficient way, and it +also provides some extra functionality, not discussed here. + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Getting your data \section{Getting your data} @@ -1877,64 +2197,67 @@ generated by the compiler: ppc386 [options] [options] + switch option on, - off -a the compiler doesn't delete the generated assembler file - -B+ build + -al list sourcecode lines in assembler file (still BETA !!) + -B build all modules -C code generation options - -Ca not implemented - -Ce not implemented - -CD Dynamic linking - -Ch bytes heap (between 1023 and 67107840) - -Ci IO-checking - -Cn omit linking stage - -Co check overflow of integer operations - -Cr range checking - -Ct stack checking - -CS static linking + -CD create dynamic library + -Ch bytes heap (between 1023 and 67107840) + -Ci IO-checking + -Cn omit linking stage + -Co check overflow of integer operations + -Cr range checking + -Cs set stack size to + -Ct stack checking + -CS create static library + -Cx use smartlinking -d defines the symbol - -e set path to executables + -e set path to executable -E same as -Cn - -g generate debugger information - -gp generate also profile code for gprof -F set file names and paths - -Fe redirect error output to - -Fg search path for the GNU C lib - -Fr search path for the error message file - -Fi adds to include path - -Fl adds to library path - -Fu adds to unit path - -k Pass to the linker - -L set language - -LD german - -LE english - -l write logo + -Fe redirect error output to + -Fg same as -Fl + -Fi adds to include path + -Fl adds to library path + -FL uses as dynamic linker + -Fo adds to object path + -Fr load error message file + -Fu adds to unit path + -g generate debugger information + -gg use gsym + -gd use dbx -i information + -I adds to include path + -k Pass to the linker + -l write logo -n don't read the default config file -o change the name of the executable produced to -pg generate profile code for gprof -P use pipes instead of creating temporary assembler files -S syntax options - -S2 switch some Delphi 2 extension on - -Sc supports operators like C (*=,+=,/= and -=) - -Se compiler stops after the first error - -Sg allows LABEL and GOTO - -Si support C++ stlyed INLINE - -Sm support macros like C (global) - -So tries to be TP/BP 7.0 compatible - -Ss constructor name must be init (destructor must be done) - -St allows static keyword in objects + -S2 switch some Delphi 2 extensions on + -Sc supports operators like C (*=,+=,/= and -=) + -Sd compiler disposes asm lists (uses less memory but slower) + -Se compiler stops after the first error + -Sg allow LABEL and GOTO + -Si support C++ stlyed INLINE + -Sm support macros like C (global) + -So tries to be TP/BP 7.0 compatible + -Sp tries to be gpc compatible + -Ss constructor name must be init (destructor must be done) + -St allow static keyword in objects + -Sv allow variable directives (cvar,external,public,export) -s don't call assembler and linker (only with -a) -T Target operating system - -TGO32V1 DOS extender by DJ Delorie - -TOS2 OS/2 2.x - -TLINUX Linux - -TWin32 Windows 32 Bit - -TGO32V2 version 2 of DJ Delorie DOS extender + -TGO32V1 version 1 of DJ Delorie DOS extender + -TGO32V2 version 2 of DJ Delorie DOS extender + -TLINUX Linux + -TOS2 OS/2 2.x + -TWin32 Windows 32 Bit -u undefines the symbol -U unit options - -Uls make static library from unit - -Uld make dynamic library from unit - -Un don't check the unit name - -Up same as -Fu - -Us compile a system unit + -Un don't check the unit name + -Up same as -Fu + -Us compile a system unit -v Be verbose. is a combination of the following letters : e : Show errors (default) d : Show debug info w : Show warnings u : Show used files @@ -1943,32 +2266,39 @@ ppc386 [options] [options] i : Show general info p : Show compiled procedures l : Show linenumbers c : Show conditionals a : Show everything 0 : Show nothing (except errors) + b : Show all procedure + declarations if an error + occurs -X executable options - -Xc link with the c library - -Xs strip all symbols from executable + -Xc link with the c library + -XD link with dynamic libraries (defines FPC_LINK_DYNAMIC) + -Xs strip all symbols from executable + -XS link with static libraries (defines FPC_LINK_STATIC) Processor specific options: -A output format - -Aatt AT&T assembler - -Ao coff file using GNU AS - -Aobj OMF file using NASM - -Anasm coff file using NASM - -Amasm assembler for the Microsoft/Borland/Watcom assembler + -Ao coff file using GNU AS + -Anasmcoff coff file using Nasm + -Anasmelf elf32 (linux) file using Nasm + -Anasmobj obj file using Nasm + -Amasm obj using Masm (Mircosoft) + -Atasm obj using Tasm (Borland) -R assembler reading style - -Ratt read AT&T style assembler - -Rintel read Intel style assembler - -Rdirect copy assembler text directly to assembler file - -O optimizations - -Oa simple optimizations - -Og optimize for size - -OG optimize for time - -Ox optimize maximum - -Oz uncertain optimizes (see docs) - -O2 optimize for Pentium II (tm) - -O3 optimize for i386 - -O4 optimize for i486 - -O5 optimize for Pentium (tm) - -O6 optimizations for PentiumPro (tm) + -Ratt read AT&T style assembler + -Rintel read Intel style assembler + -Rdirect copy assembler text directly to assembler file + -O optimizations + -Og generate smaller code + -OG generate faster code (default) + -Or keep certain variables in registers (still BUGGY!!!) + -Ou enable uncertain optimizations (see docs) + -O1 level 1 optimizations (quick optimizations) + -O2 level 2 optimizations (-O1 + slower optimizations) + -O3 level 3 optimizations (same as -O2u) + -Op target processor + -Op1 set target processor to 386/486 + -Op2 set target processor to Pentium/PentiumMMX (tm) + -Op3 set target processor to PPro/PII/c6x86/K6 (tm) -? shows this help -h shows this help without waiting @@ -2005,7 +2335,7 @@ do downto else end -except +except exit export exports @@ -2014,7 +2344,7 @@ fail false far file -finally +finally for forward function @@ -2024,7 +2354,7 @@ implementation in index inherited -initialization +initialization inline interface interrupt @@ -2044,10 +2374,11 @@ operator or otherwise packed +popstack private procedure program -property +property protected public raise @@ -2688,127 +3019,6 @@ on the stack size. You should use less variables or try ro put large variables on the heap. \end{description} -\chapter{Run time errors} -The \fpc Run-tim library generates the following errors at run-time -\footnote{The \linux port will generate only a subset of these.}: - -\begin{description} -\item [1 Invalid function number] -You tried to call a \dos function which doesn't exist. -\item [2 File not found] -You can get this error when you tried to do an operation on a file which -doesn't exist. -\item [3 Path not found] -You can get this error when you tried to do an operation on a file which -doesn't exist, or when you try to change to, or remove a directory that doesn't exist, -or try to make a subdirectory of a subdirectory that doesn't exist. -\item [4 Too many open files] -When attempting to open a file for reading or writing, you can get this -error when your program has too many open files. -\item [5 File access denied] -You don't have access to the specified file. -\item [6 Invalid file handle] -If this happens, the file variable you are using is trashed; it -indicates that your memory is corrupted. -\item [12 Invalid file access code] -This will happen if you do a reset or rewrite of a file when \var{FileMode} -is invalid. -\item [15 Invalid drive number] -The number given to the Getdir function specifies a non-existent disk. -\item [16 Cannot remove current directory] -You get this if you try to remove the current diirectory. -\item [17 Cannot rename across drives] -You cannot rename a file such that it would end up on another disk or -partition. -\item [100 Disk read error] -\dos only. An error occurred when reading from disk. Typically when you try -to read past the end of a file. -\item [101 Disk write error] -\dos only. Reported when the disk is full, and you're trying to write to it. -\item [102 File not assigned] -This is reported by Reset, Rewrite, Append, Rename and Erase, if you call -them with an unassigne function as a parameter. -\item [103 File not open] -Reported by the following functions : Close , Read, Write, Seek, -EOf, FilePos, FileSize, Flush, BlockRead, and BlockWrite if the file isn't -open. -\item [104 File not open for input] -Reported by Read, BlockRead, Eof, Eoln, SeekEof or SeekEoln if the file -isn't opened with Reset. -\item [105 File not open for output] -Reported by write if a text file isn't opened with Rewrite. -\item [106 Invalid numeric format] -Reported when a non-numerice value is read from a text file, when a numeric -value was expected. -\item [150 Disk is write-protected] -(Critical error, \dos only.) -\item [151 Bad drive request struct length] -(Critical error, \dos only.) -\item [152 Drive not ready] -(Critical error, \dos only.) -\item [154 CRC error in data] -(Critical error, \dos only.) -\item [156 Disk seek error] -(Critical error, \dos only.) -\item [157 Unknown media type] -(Critical error, \dos only.) -\item [158 Sector Not Found] -(Critical error, \dos only.) -\item [159 Printer out of paper] -(Critical error, \dos only.) -\item [160 Device write fault] -(Critical error, \dos only.) -\item [161 Device read fault] -(Critical error, \dos only.) -\item [162 Hardware failure] -(Critical error, \dos only.) -\item [200 Division by zero] -You are dividing a number by zero. -\item [201 Range check error] -If you compiled your program with range checking on, then you can get this -error in the following cases: -\begin{enumerate} -\item An array was accessed with an index outside its declared range. -\item You're trying to assign a value to a variable outside its range (for -instance a enumerated type). -\end{enumerate} -\item [202 Stack overflow error] -The stack has grown beyond itss maximum size. This error can easily occur if -you have recursive functions. -\item [203 Heap overflow error] -The heap has grown beyond its boundaries, ad you are rying to get more -memory. Please note that \fpc provides a growing heap, i.e. the heap will -try to allocate more memory if needed. However, if the heap has reached the -maximum size allowed by the operating system or hardware, then you will get -this error. -\item [204 Invalid pointer operation] -This you will get if you call dispose or Freemem with an invalid pointer -(notably, \var{Nil}) -\item [205 Floating point overflow] -You are trying to use or produce too large real numbers. -\item [206 Floating point underflow] -You are trying to use or produce too small real numbers. -\item [207 Invalid floating point operation] -Can occur if you try to calculate the square root or logarithm of a negative -number. -\item [210 Object not initialized] -When compiled with range checking on, a program will report this error if -you call a virtal method without having initialized the VMT. -\item [211 Call to abstract method] -Your program tried to execute an abstract virtual method. Abstract methods -should be overridden, and the overriding method should be called. -\item [212 Stream registration error] -This occurs when an invalid type is registered in the objects unit. -\item [213 Collection index out of range] -You are trying to access a collection item with an invalid index. -(objects unit) -\item [214 Collection overflow error] -The collection has reached its maximal size, and you are trying to add -another element. (objects unit) -\item [216 General Protection fault] -You are trying to access memory outside your appointed memory. -\end{description} - %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Assembler reader errors \section{Assembler reader errors.} @@ -2974,7 +3184,7 @@ directive. \subsection{I386 specific errors} \begin{description} -\item [repeat prefix and a segment override on <= i386 may result in errors if an interrupt occurs] +\item [repeat prefix and a segment override on \var{<=} i386 ...] A problem with interrupts and a prefix instruction may occur and may cause false results on 386 and earlier computers. @@ -3073,6 +3283,131 @@ a slash. \item [68020+ mode required to assemble] \end{description} +\chapter{Run time errors} +The \fpc Run-tim library generates the following errors at run-time +\footnote{The \linux port will generate only a subset of these.}: + +\begin{description} +\item [1 Invalid function number] +You tried to call a \dos function which doesn't exist. +\item [2 File not found] +You can get this error when you tried to do an operation on a file which +doesn't exist. +\item [3 Path not found] +You can get this error when you tried to do an operation on a file which +doesn't exist, or when you try to change to, or remove a directory that doesn't exist, +or try to make a subdirectory of a subdirectory that doesn't exist. +\item [4 Too many open files] +When attempting to open a file for reading or writing, you can get this +error when your program has too many open files. +\item [5 File access denied] +You don't have access to the specified file. +\item [6 Invalid file handle] +If this happens, the file variable you are using is trashed; it +indicates that your memory is corrupted. +\item [12 Invalid file access code] +This will happen if you do a reset or rewrite of a file when \var{FileMode} +is invalid. +\item [15 Invalid drive number] +The number given to the Getdir function specifies a non-existent disk. +\item [16 Cannot remove current directory] +You get this if you try to remove the current diirectory. +\item [17 Cannot rename across drives] +You cannot rename a file such that it would end up on another disk or +partition. +\item [100 Disk read error] +\dos only. An error occurred when reading from disk. Typically when you try +to read past the end of a file. +\item [101 Disk write error] +\dos only. Reported when the disk is full, and you're trying to write to it. +\item [102 File not assigned] +This is reported by Reset, Rewrite, Append, Rename and Erase, if you call +them with an unassigne function as a parameter. +\item [103 File not open] +Reported by the following functions : Close , Read, Write, Seek, +EOf, FilePos, FileSize, Flush, BlockRead, and BlockWrite if the file isn't +open. +\item [104 File not open for input] +Reported by Read, BlockRead, Eof, Eoln, SeekEof or SeekEoln if the file +isn't opened with Reset. +\item [105 File not open for output] +Reported by write if a text file isn't opened with Rewrite. +\item [106 Invalid numeric format] +Reported when a non-numerice value is read from a text file, when a numeric +value was expected. +\item [150 Disk is write-protected] +(Critical error, \dos only.) +\item [151 Bad drive request struct length] +(Critical error, \dos only.) +\item [152 Drive not ready] +(Critical error, \dos only.) +\item [154 CRC error in data] +(Critical error, \dos only.) +\item [156 Disk seek error] +(Critical error, \dos only.) +\item [157 Unknown media type] +(Critical error, \dos only.) +\item [158 Sector Not Found] +(Critical error, \dos only.) +\item [159 Printer out of paper] +(Critical error, \dos only.) +\item [160 Device write fault] +(Critical error, \dos only.) +\item [161 Device read fault] +(Critical error, \dos only.) +\item [162 Hardware failure] +(Critical error, \dos only.) +\item [200 Division by zero] +You are dividing a number by zero. +\item [201 Range check error] +If you compiled your program with range checking on, then you can get this +error in the following cases: +\begin{enumerate} +\item An array was accessed with an index outside its declared range. +\item You're trying to assign a value to a variable outside its range (for +instance a enumerated type). +\end{enumerate} +\item [202 Stack overflow error] +The stack has grown beyond itss maximum size. This error can easily occur if +you have recursive functions. +\item [203 Heap overflow error] +The heap has grown beyond its boundaries, ad you are rying to get more +memory. Please note that \fpc provides a growing heap, i.e. the heap will +try to allocate more memory if needed. However, if the heap has reached the +maximum size allowed by the operating system or hardware, then you will get +this error. +\item [204 Invalid pointer operation] +This you will get if you call dispose or Freemem with an invalid pointer +(notably, \var{Nil}) +\item [205 Floating point overflow] +You are trying to use or produce too large real numbers. +\item [206 Floating point underflow] +You are trying to use or produce too small real numbers. +\item [207 Invalid floating point operation] +Can occur if you try to calculate the square root or logarithm of a negative +number. +\item [210 Object not initialized] +When compiled with range checking on, a program will report this error if +you call a virtal method without having initialized the VMT. +\item [211 Call to abstract method] +Your program tried to execute an abstract virtual method. Abstract methods +should be overridden, and the overriding method should be called. +\item [212 Stream registration error] +This occurs when an invalid type is registered in the objects unit. +\item [213 Collection index out of range] +You are trying to access a collection item with an invalid index. +(objects unit) +\item [214 Collection overflow error] +The collection has reached its maximal size, and you are trying to add +another element. (objects unit) +\item [216 General Protection fault] +You are trying to access memory outside your appointed memory. +\item [217 Unhandled expetion occurred] +An exception occurred, and there was no exception handler present. +The \file{sysutils} unit installs a default exception handler which catches +all excpetions and exits gracefully. +\end{description} + \chapter{The Floating Point Coprocessor emulator}