From 071ce784ef9245635909708c1f5908bd6f45d476 Mon Sep 17 00:00:00 2001 From: michael Date: Mon, 30 Mar 1998 16:01:34 +0000 Subject: [PATCH] + New version for release --- docs/Makefile | 16 +- docs/README.DOCS | 20 +- docs/crt.tex | 3 +- docs/crtex/foot.tex | 2 +- docs/crtex/head.tex | 2 +- docs/dosex/foot.tex | 2 +- docs/dosex/head.tex | 2 +- docs/fpc-html.tex | 1 + docs/fpc.sty | 2 +- docs/fpcman.sty | 1 + docs/go32.tex | 26 +- docs/linuxex/foot.tex | 2 +- docs/linuxex/head.tex | 2 +- docs/mmx.tex | 6 +- docs/onechap.tex | 4 +- docs/optex/foot.tex | 2 +- docs/optex/head.tex | 2 +- docs/printex/foot.tex | 2 +- docs/printex/head.tex | 2 +- docs/prog.tex | 653 ++++++++++++++++++---------- docs/ref.tex | 170 ++++---- docs/refex/foot.tex | 2 +- docs/refex/head.tex | 2 +- docs/sockex/foot.tex | 2 +- docs/sockex/head.tex | 2 +- docs/stringex/foot.tex | 2 +- docs/stringex/head.tex | 2 +- docs/strings.tex | 2 +- docs/units.tex | 6 +- docs/user.tex | 946 ++++++++++++++++++++++++++++------------- 30 files changed, 1237 insertions(+), 651 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index fb52b8e925..69040617d3 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -129,7 +129,7 @@ help: clean: -rm -rf $(HTML) - -rm -f *.aux *.log *.dvi *.ps *.toc *.i* *.lot *.pdf *.txt + -rm -f *.aux *.log *.dvi *.ps *.toc *.i* *.lot *.pdf *.txt *.chk -$(MAKE) -C refex clean -$(MAKE) -C linuxex clean -$(MAKE) -C crtex clean @@ -139,7 +139,7 @@ clean: -$(MAKE) -C stringex clean -$(MAKE) -C sockex clean -unitex: +unitex.chk: $(MAKE) -C crtex tex $(MAKE) -C linuxex tex $(MAKE) -C dosex tex @@ -147,13 +147,15 @@ unitex: $(MAKE) -C printex tex $(MAKE) -C stringex tex $(MAKE) -C sockex tex + touch unitex.chk -refex: +refex.chk: $(MAKE) -C refex tex + touch refex.chk -units.dvi: units.tex $(CHAPTERS) unitex +units.dvi: units.tex $(CHAPTERS) unitex.chk -ref.dvi: ref.tex refex +ref.dvi: ref.tex refex.chk dvi : $(DVI) @@ -171,14 +173,14 @@ user: rm -f user/labels.pl user/internals.pl user/.*.pag user/.*.dir rm -f user/images.* user/*.log -units: unitex +units: unitex.chk $(LATEX2HTML) $(LATEX2HTMLOPTS) -split 3 -link 2\ -t "Unit reference for Free Pascal" units.tex sed -f foot.sed units/footnote.html mv units/footnote.html units/footnode.html rm -f units/labels.pl units/internals.pl units/.*.pag units/.*.dir -ref: refex +ref: refex.chk $(LATEX2HTML) $(LATEX2HTMLOPTS) -split 3 -link 2\ -t "Free Pascal reference guide" ref.tex sed -f foot.sed ref/footnote.html diff --git a/docs/README.DOCS b/docs/README.DOCS index 981eb13dc7..96945461b3 100644 --- a/docs/README.DOCS +++ b/docs/README.DOCS @@ -1,14 +1,14 @@ -This is the README for the FPK linux documentation. +This is the README for the Free Pascal documentation. All documentation is stored here, in LaTeX format. -it uses special style files (fpk*.sty) which are also in the directory. +it uses special style files (fpc*.sty) which are also in the directory. do a 'make dvi' to produce the dvi format of the docs. a 'make html' will produce the html version (using latex2html). a 'make ps' will produce PostScript documents. If you want to produce dos docs, you can do a 'make htm' this will convert -the .htl files to .htm files (including all references), suitable for a 8:3 +the .html files to .htm files (including all references), suitable for a 8:3 format. The rest of this document is only interesting if you want to write docs. @@ -23,28 +23,28 @@ Why LaTeX ? - many other reasons. In order to translate the things to HTML, I use latex2html, since it is the -most powerful and flexible. -For it to be able to use the fpk.sty, I had to write a fpk.perl script +most powerful and flexible, although sluggish... +For it to be able to use the fpc.sty, I had to write a fpc.perl script which it loads. The script seems to run fine when used standalone, but in conjunction with latex2html, I get a out of memory... ?? I'm not familiar with perl, so if someone is, and can fix the thing, please do. (and let me know :) ) Then how to proceed ? -If you just want to write latex docs, just use fpk.sty. (you don't need +If you just want to write latex docs, just use fpc.sty. (you don't need html.sty) If you want to be able to convert to html, (you need html.sty) the following fixes the perl-problem : In the preamble of your document, type : \usepackage{html} -\latex{\usepackage{fpk}} -\html{\input{fpk-html.tex}} +\latex{\usepackage{fpc}} +\html{\input{fpc-html.tex}} -The fpk-html.tex defines the same commands as fpk.sty, only in a language +The fpc-html.tex defines the same commands as fpc.sty, only in a language that latex2html understands. -fpk.sty.doc describes what fpk.sty does. (one day I'll integrate them using +fpc.sty.doc describes what fpc.sty does. (one day I'll integrate them using the doc package, but I need some time for it) Happy TeXing, diff --git a/docs/crt.tex b/docs/crt.tex index 6066743fd7..ec6d3ae80d 100644 --- a/docs/crt.tex +++ b/docs/crt.tex @@ -19,6 +19,7 @@ % Boston, MA 02111-1307, USA. % \chapter{The CRT unit.} +\label{ch:crtunit} This chapter describes the \var{CRT} unit for Free Pascal, both under \dos and \linux. The unit was first written for \dos by Florian kl\"ampfl. @@ -72,7 +73,7 @@ Miscellaneous constants ScreenHeight = 25; \end{verbatim} Some variables for compatibility with Turbo Pascal. However, they're not -used by \fpk. +used by \fpc. \begin{verbatim} var checkbreak : boolean; diff --git a/docs/crtex/foot.tex b/docs/crtex/foot.tex index 83788a402a..4b6c233a40 100644 --- a/docs/crtex/foot.tex +++ b/docs/crtex/foot.tex @@ -1,2 +1,2 @@ \end{verbatim} -\end{FPKList} \ No newline at end of file +\end{FPCList} \ No newline at end of file diff --git a/docs/crtex/head.tex b/docs/crtex/head.tex index b2ed5b6603..2699f37d16 100644 --- a/docs/crtex/head.tex +++ b/docs/crtex/head.tex @@ -1,3 +1,3 @@ -\begin{FPKList} +\begin{FPCList} \item[Example] \begin{verbatim} diff --git a/docs/dosex/foot.tex b/docs/dosex/foot.tex index 83788a402a..4b6c233a40 100644 --- a/docs/dosex/foot.tex +++ b/docs/dosex/foot.tex @@ -1,2 +1,2 @@ \end{verbatim} -\end{FPKList} \ No newline at end of file +\end{FPCList} \ No newline at end of file diff --git a/docs/dosex/head.tex b/docs/dosex/head.tex index b2ed5b6603..2699f37d16 100644 --- a/docs/dosex/head.tex +++ b/docs/dosex/head.tex @@ -1,3 +1,3 @@ -\begin{FPKList} +\begin{FPCList} \item[Example] \begin{verbatim} diff --git a/docs/fpc-html.tex b/docs/fpc-html.tex index 7fcb51f16b..5b43ab78e8 100644 --- a/docs/fpc-html.tex +++ b/docs/fpc-html.tex @@ -93,6 +93,7 @@ \newcommand{\progref}{\htmladdnormallink{Programmer's guide}{../prog/prog.html}\ } \newcommand{\refref}{\htmladdnormallink{Reference guide}{../ref/ref.html}\ } \newcommand{\userref}{\htmladdnormallink{Users' guide}{../user/user.html}\ } +\newcommand{\unitsref}{\htmladdnormallink{Unit reference}{../units/units.html}\ } \newcommand{\seecrt}{\htmladdnormallink{CRT}{../crt/crt.html}} \newcommand{\seelinux}{\htmladdnormallink{Linux}{../linux/linux.html}} \newcommand{\seestrings}{\htmladdnormallink{strings}{../strings/strings.html}} diff --git a/docs/fpc.sty b/docs/fpc.sty index 0130af4bb7..dd930432eb 100644 --- a/docs/fpc.sty +++ b/docs/fpc.sty @@ -152,7 +152,7 @@ \newcommand{\progref}{\htmladdnormallink{Programmers' guide}{../prog/prog.html}\ } \newcommand{\refref}{\htmladdnormallink{Reference guide}{../ref/ref.html}\ } \newcommand{\userref}{\htmladdnormallink{Users' guide}{../user/user.html}\ } -\newcommand{\unitsref}{\htmladdnormallink{Unit reference}}{../units/units.html} +\newcommand{\unitsref}{\htmladdnormallink{Unit reference}{../units/units.html}\ } \newcommand{\seecrt}{\htmladdnormallink{CRT}{../crt/crt.html}} \newcommand{\seelinux}{\htmladdnormallink{Linux}{../linux/linux.html}} \newcommand{\seestrings}{\htmladdnormallink{strings}{../strings/strings.html}} diff --git a/docs/fpcman.sty b/docs/fpcman.sty index 3fcbdda947..abceef8758 100644 --- a/docs/fpcman.sty +++ b/docs/fpcman.sty @@ -120,6 +120,7 @@ \newcommand{\progref}{\htmladdnormallink{Programmer's guide}{../prog/prog.html}\ } \newcommand{\refref}{\htmladdnormallink{Reference guide}{../ref/ref.html}\ } \newcommand{\userref}{\htmladdnormallink{Users' guide}{../user/user.html}\ } +\newcommand{\unitsref}{\htmladdnormallink{Unit reference}{../units/units.html}\ } \newcommand{\seecrt}{\htmladdnormallink{CRT}{../crt/crt.html}} \newcommand{\seelinux}{\htmladdnormallink{Linux}{../linux/linux.html}} \newcommand{\seestrings}{\htmladdnormallink{strings}{../strings/strings.html}} diff --git a/docs/go32.tex b/docs/go32.tex index d372e71b81..0918b40b77 100644 --- a/docs/go32.tex +++ b/docs/go32.tex @@ -56,7 +56,7 @@ function shift_state : byte; \subsection{I/O port access} The I/O port access is done by the \var{inport} and \var{outport} functions. -It's not necessary to use these functions but it makes life easier. \fpk +It's not necessary to use these functions but it makes life easier. \fpc \textbf {doesn't} support the \var{PORT} array, as under Turbo Pascal. \subsection{Processor access} @@ -66,7 +66,7 @@ your work easier. \subsection{Interrupt redirection} The \file{GO32} unit helps you to redirect interrupts. \var{SetIntVec} -and \var{GetIntVec} don't work with \fpk. This is now done via the functions +and \var{GetIntVec} don't work with \fpc. This is now done via the functions \var{set\_pm\_interrupt} and \var{get\_pm\_interrupt}. As an example we show how to redirect the interrupt \var{8h}. @@ -81,7 +81,7 @@ var ds : word; procedure s; { interrupt;} - { comes with versions > 0.9.2 of FPKPascal } + { comes with versions > 0.9.2 of FPCPascal } begin asm @@ -370,7 +370,7 @@ calculated by adding the value returned by \seep{FreeLdtDescriptor}, \seef{GetNextSelectorIncrementValue} } -\begin{FPKList} +\begin{FPCList} \item[Example] \begin{verbatim} uses go32; @@ -402,7 +402,7 @@ begin {...} end. \end{verbatim} -\end{FPKList} +\end{FPCList} \procedurel{Free\_Ldt\_Descriptor}{FreeLdtDescriptor}{(Sel : word)} { @@ -447,7 +447,7 @@ the base address as necessary. } {None.} {} -\begin{FPKList} +\begin{FPCList} \item[Example] \begin{verbatim} uses go32; @@ -467,7 +467,7 @@ begin r.realeax := $3; realintr($10, r); end. \end{verbatim} -\end{FPKList} +\end{FPCList} \Functionl{Get\_Next\_Selector\_Increment\_Value} @@ -503,7 +503,7 @@ from the LDT descriptor for the specified segment (\var{Sel}). {None.} {\seep{SetSegmentBaseAddress}} -\begin{FPKList} +\begin{FPCList} \item[Example:] \begin{verbatim} uses go32; @@ -512,7 +512,7 @@ begin Writeln(get_segment_base_address(get_ds)); end. \end{verbatim} -\end{FPKList} +\end{FPCList} \procedurel{Set\_Segment\_Base\_Address}{SetSegmentBaseAddress} {(var Des : word;Sel : longint)} @@ -564,7 +564,7 @@ changed, the two descriptors will no longer map the same memory. } {None.} {} -\begin{FPKList} +\begin{FPCList} \item[Example] \begin{verbatim} uses go32; @@ -577,7 +577,7 @@ begin free_ldt_descriptor(copysel); end. \end{verbatim} -\end{FPKList} +\end{FPCList} \functionl{Get\_Linear\_Addr}{GetLinearAddr}{(PhysAddr : longint;Size : longint)}{longint} {\var{Get\_Linear\_Addr} converts a physical address \var{PhysAddr} into @@ -612,7 +612,7 @@ single block needs an unique selector. \end{itemize} }{None.}{\seep{GlobalDosFree}} -\begin{FPKList} +\begin{FPCList} \item[Example] \begin{verbatim} uses go32; @@ -653,7 +653,7 @@ begin dosfree(selector); { free selector afterwards } end. \end{verbatim} -\end{FPKList} +\end{FPCList} \procedurel{Global\_Dos\_Free}{GlobalDosFree}{(Sel : word)} {var{Global\_Dos\_Free} frees a previously allocated \dos memory diff --git a/docs/linuxex/foot.tex b/docs/linuxex/foot.tex index 83788a402a..4b6c233a40 100644 --- a/docs/linuxex/foot.tex +++ b/docs/linuxex/foot.tex @@ -1,2 +1,2 @@ \end{verbatim} -\end{FPKList} \ No newline at end of file +\end{FPCList} \ No newline at end of file diff --git a/docs/linuxex/head.tex b/docs/linuxex/head.tex index b2ed5b6603..2699f37d16 100644 --- a/docs/linuxex/head.tex +++ b/docs/linuxex/head.tex @@ -1,3 +1,3 @@ -\begin{FPKList} +\begin{FPCList} \item[Example] \begin{verbatim} diff --git a/docs/mmx.tex b/docs/mmx.tex index 670b81d9fe..c2a29b8ae3 100644 --- a/docs/mmx.tex +++ b/docs/mmx.tex @@ -20,7 +20,7 @@ % \chapter{The MMX unit} This chapter describes the \file{MMX} unit. This unit allows you to use the -\var{MMX} capabilities of the \fpk compiler. It was written by Florian +\var{MMX} capabilities of the \fpc compiler. It was written by Florian Kl\"ampfl for the \var{I386} processor. \section{Variables, Types and constants} The following types are defined in the \var{MMX} unit: @@ -67,7 +67,7 @@ use this function. } {None.} { \progref } -\begin{FPKList} +\begin{FPCList} \item[Example:] \begin{verbatim} Program MMXDemo; @@ -90,4 +90,4 @@ begin { now we can do floating point arithmetic again } end. \end{verbatim} -\end{FPKList} \ No newline at end of file +\end{FPCList} \ No newline at end of file diff --git a/docs/onechap.tex b/docs/onechap.tex index 53c8b835c6..8b6cc76330 100644 --- a/docs/onechap.tex +++ b/docs/onechap.tex @@ -22,8 +22,8 @@ \usepackage{a4} \usepackage{makeidx} \usepackage{html} -\latex{\usepackage{fpk}} -\html{\input{fpk-html.tex}} +\latex{\usepackage{fpc}} +\html{\input{fpc-html.tex}} \begin{document} %\input{crt.tex} %\input{dos.tex} diff --git a/docs/optex/foot.tex b/docs/optex/foot.tex index 83788a402a..4b6c233a40 100644 --- a/docs/optex/foot.tex +++ b/docs/optex/foot.tex @@ -1,2 +1,2 @@ \end{verbatim} -\end{FPKList} \ No newline at end of file +\end{FPCList} \ No newline at end of file diff --git a/docs/optex/head.tex b/docs/optex/head.tex index b2ed5b6603..2699f37d16 100644 --- a/docs/optex/head.tex +++ b/docs/optex/head.tex @@ -1,3 +1,3 @@ -\begin{FPKList} +\begin{FPCList} \item[Example] \begin{verbatim} diff --git a/docs/printex/foot.tex b/docs/printex/foot.tex index 83788a402a..4b6c233a40 100644 --- a/docs/printex/foot.tex +++ b/docs/printex/foot.tex @@ -1,2 +1,2 @@ \end{verbatim} -\end{FPKList} \ No newline at end of file +\end{FPCList} \ No newline at end of file diff --git a/docs/printex/head.tex b/docs/printex/head.tex index b2ed5b6603..2699f37d16 100644 --- a/docs/printex/head.tex +++ b/docs/printex/head.tex @@ -1,3 +1,3 @@ -\begin{FPKList} +\begin{FPCList} \item[Example] \begin{verbatim} diff --git a/docs/prog.tex b/docs/prog.tex index ec8956071a..7e062ce4ed 100644 --- a/docs/prog.tex +++ b/docs/prog.tex @@ -22,18 +22,17 @@ \usepackage{a4} \usepackage{html} \latex{\usepackage{multicol}} -\latex{\usepackage{fpkman}} -\html{\input{fpk-html.tex}} -% define the version number here, and not in the fpk.sty !!! -\newcommand{\fpkversion}{0.9.7} +\latex{\usepackage{fpcman}} +\html{\input{fpc-html.tex}} +% define the version number here, and not in the fpc.sty !!! \newcommand{\remark}[1]{\par$\rightarrow$\textbf{#1}\par} \newcommand{\olabel}[1]{\label{option:#1}} % We should change this to something better. See \seef etc. \begin{document} -\title{Free Pascal \\ Programmer's manual} -\docdescription{Programmer's manual for \fpk, version \fpkversion} -\docversion{1.0} -\date{July 1997} +\title{Free Pascal \\ Programmers' manual} +\docdescription{Programmers' manual for \fpc, version \fpcversion} +\docversion{1.1} +\date{March 1998} \author{Micha\"el Van Canneyt} \maketitle \tableofcontents @@ -43,9 +42,9 @@ % Introduction %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section*{About this document} -This is the programmer's manual for \fpk. +This is the programmer's manual for \fpc. -It describes some of the peculiarities of the \fpk compiler, and provides a +It describes some of the peculiarities of the \fpc compiler, and provides a glimp of how the compiler generates its code, and how you can change the generated code. It will not, however, provide you with a detailed account of the inner workings of the compiler, nor will it tell you how to use the @@ -68,7 +67,7 @@ updated. If you find something which isn't correct, or you think something %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Compiler directives} \label{ch:CompSwitch} -\fpk supports compiler directives in your source file. They are not the same +\fpc supports compiler directives in your source file. They are not the same as Turbo Pascal directives, although some are supported for compatibility. There is a distinction between local and global directives; local directives take effect from the moment they are encountered, global directives have an @@ -136,7 +135,7 @@ testf.pp(3) Warning: NEAR ignored \subsection{\var{\$I} : Input/Output checking} The \var{\{\$I-\}} directive tells the compiler not to generate input/output checking code in your program. If you compile using the \var{-Ci} compiler -switch, the \fpk compiler inserts input/output +switch, the \fpc compiler inserts input/output checking code after every input/output call in your program. If an error occurred during input or output, then a run-time error will be generated. Use this switch if you wish to avoid this behavior. @@ -172,7 +171,7 @@ specify an extension yourself. Do not put the filename between quotes, as they will be regarded as part of the file's name. You can nest included files, but not infinitely deep. The number of files is -restricted to the number of file descriptors available to the \fpk compiler. +restricted to the number of file descriptors available to the \fpc compiler. Contrary to Turbo Pascal, include files can cross blocks. I.e. you can start a block in one file (with a \var{Begin} keyword) and end it in another (with @@ -220,7 +219,7 @@ The command-line switch that corresponds to this switch is \var{-R}. \subsection{\var{\$MMX} : MMX support} -As of version 0.9.8, \fpk supports optimization for the \textbf{MMX} Intel +As of version 0.9.8, \fpc supports optimization for the \textbf{MMX} Intel processor (see also \ref{ch:MMXSupport}). This optimizes certain code parts for the \textbf{MMX} Intel processor, thus greatly improving speed. The speed is noticed mostly when moving large amounts of data. Things that change are @@ -268,13 +267,13 @@ generated. You can specify this switch \textbf{only} befor the \var{Program} or \var{Unit} clause in your source file. The different kinds of formats are shown in \seet{Formats}. -\begin{FPKltable}{ll}{Formats generated by the compiler}{Formats} \hline +\begin{FPCltable}{ll}{Formats generated by the compiler}{Formats} \hline Switch value & Generated format \\ \hline att & AT\&T assembler file. \\ o & Unix object file.\\ obj & OMF file.\\ wasm & assembler for the Watcom assembler. \\ \hline -\end{FPKltable} +\end{FPCltable} \subsection{\var{\$V} : Var-string checking} @@ -294,11 +293,11 @@ given for each of the directives. This switch is recognized for Turbo Pascal Compatibility, but is not yet implemented. The alignment of data will be different in any case, since -\fpk is a 32-bit compiler. +\fpc is a 32-bit compiler. \subsection{\var{\$B} : Complete boolean evaluation} -This switch is understood by the \fpk compiler, but is ignored. The compiler +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. @@ -425,7 +424,7 @@ The command-line compiler switch \var{-Sa1} has the same effect as the %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Using conditionals, Messages and macros} \label{ch:CondMessageMacro} -The \fpk compiler supports conditionals as in normal Turbo Pascal. It does, +The \fpc compiler supports conditionals as in normal Turbo Pascal. It does, however, more than that. It allows you to make macros which can be used in your code, and it allows you to define messages or errors which will be displayed when compiling. @@ -448,11 +447,11 @@ command line as you want. Undefining an existing symbol is done in a similar way: \begin{verbatim} -{$Undefine Symbol } +{$Undef Symbol } \end{verbatim} If the symbol didn't exist yet, this doesn't do anything. If the symbol existed previously, the symbol will be erased, and will not be recognized -any more in the code following the \verb|{$Undefine ...}| statement. +any more in the code following the \verb|{$Undef ...}| statement. You can also undefine symbols from the command line with the \var{-u} command-line switch.. @@ -461,7 +460,7 @@ To compile code conditionally, depending on whether a symbol is defined or not, you can enclose the code in a \verb|{$ifdef Symbol}| .. \verb|{$endif}| pair. For instance the following code will never be compiled : \begin{verbatim} -{$Undefine MySymbol} +{$Undef MySymbol} {$ifdef Mysymbol} DoSomething; ... @@ -473,7 +472,7 @@ pair. Then the code between the pair will only be compiled when the used symbol doesn't exist. For example, in the following example, the call to the \var{DoSomething} will always be compiled: \begin{verbatim} -{$Undefine MySymbol} +{$Undef MySymbol} {$ifndef Mysymbol} DoSomething; ... @@ -492,10 +491,11 @@ In this example, if \var{MySymbol} exists, then the call to \var{DoSomething} will be compiled. If it doesn't exist, the call to \var{DoSomethingElse} is compiled. -The \fpk compiler defines some symbols before starting to compile your +The \fpc compiler defines some symbols before starting to compile your program or unit. You can use these symbols to differentiate between different versions of the compiler, and between different compilers. -In \seet{Symbols}, a list of pre-defined symbols is given. In that table, +In \seet{Symbols}, a list of pre-defined symbols is given\footnote{Remark: +The \var{FPK} symbol is still defined for compatibility with older versions.}. In that table, you should change \var{v} with the version number of the compiler you're using, \var{r} with the release number and \var{p} with the patch-number of the compiler. 'OS' needs to be changed by the type @@ -506,29 +506,29 @@ the \var{-TSomeOS} option on the command line will define the \var{SomeOS} symbo and will undefined the existing platform symbol\footnote{In versions prior to 0.9.4, this didn't happen, thus making Cross-compiling impossible.}. -\begin{FPKltable}{c}{Symbols defined by the compiler.}{Symbols} \hline +\begin{FPCltable}{c}{Symbols defined by the compiler.}{Symbols} \hline Free \\ VER\var{v} \\ VER\var{v}\_\var{r} \\ VER\var{v}\_\var{r}\_\var{p} \\ OS \\ \hline -\end{FPKltable} +\end{FPCltable} As an example : Version 0.9.1 of the compiler, running on a Linux system, defines the following symbols before reading the command line arguments: -\var{FPK}, \var{VER0}, \var{VER0\_9}, \var{VER0\_9\_1} and \var{LINUX}. +\var{FPC}, \var{VER0}, \var{VER0\_9}, \var{VER0\_9\_1} and \var{LINUX}. Specifying \var{-TOS2} on the command-line will undefine the \var{LINUX} symbol, and will define the \var{OS2} symbol. {\em Remark: } Symbols, even when they're defined in the interface part of a unit, are not available outside that unit. -\fpk supports the \var{\{\$IFOPT \}} directive for Turbo Pascal +\fpc supports the \var{\{\$IFOPT \}} directive for Turbo Pascal compatibility, but doesn't act on it. It always rejects the condition, so code between \var{\{\$IFOPT \}} and \var{\{\$Endif\}} is never compiled. Except for the Turbo Pascal constructs, from version 0.9.8 and higher, -the \fpk compiler also supports a stronger conditional compile mechanism: +the \fpc compiler also supports a stronger conditional compile mechanism: The \var{\{\$If \}} construct. The prototype of this construct is as follows : @@ -561,22 +561,22 @@ precedence of the operators. The following example shows you many of the possibilities: \begin{verbatim} -{$ifdef fpk} +{$ifdef fpc} var y : longint; -{$else fpk} +{$else fpc} var z : longint; -{$endif fpk} +{$endif fpc} var x : longint; begin -{$if (fpk_version=0) and (fpk_release>6) and (fpk_patch>4)} +{$if (fpc_version=0) and (fpc_release>6) and (fpc_patch>4)} {$info At least this is version 0.9.5} {$else} {$fatalerror Problem with version check} @@ -626,47 +626,24 @@ begin {$fatalerror $if 12<=312 rejected} {$endif} -{$if 121234>=312} -{$info $if 121234>=312 is ok} -{$else} -{$fatalerror $if 121234>=312 rejected} -{$endif} - {$if 12<312} {$info $if 12<312 is ok} {$else} {$fatalerror $if 12<312 rejected} {$endif} -{$if 122134>312} -{$info $if 122134>312 is ok} -{$else} -{$fatalerror $if 122134>312 rejected} -{$endif} {$if a12=a12} {$info $if a12=a12 is ok} {$else} {$fatalerror $if a12=a12 rejected} {$endif} -{$if a12<>z312} -{$info $if a12<>z312 is OK} -{$else} -{$fatalerror $if a12<>z312 rejected} -{$endif} - - {$if a12<=z312} {$info $if a12<=z312 is ok} {$else} {$fatalerror $if a12<=z312 rejected} {$endif} -{$if z121234>=a312} -{$info $if z121234>=a312 is OK} -{$else} -{$fatalerror $if z121234>=a312 rejected} -{$endif} {$if a12a312} -{$info $if z122134>a312 is OK} -{$else} -{$fatalerror $if z122134>a312 rejected} -{$endif} - -{$if not z122134>a312} -{$fatalerror $if not z122134>a312 accepted} -{$else} -{$info $if not z122134>a312 is OK} -{$endif} - {$if not(0)} {$info $if not(0) is OK} {$else} @@ -713,7 +678,7 @@ switch on macro support, with the \var{-Sm} command-line switch. % Macros \section{Messages} \label{se:Messages} -\fpk lets you define normal, warning and error messages in your code. +\fpc lets you define normal, warning and error messages in your code. Messages can be used to display useful information, such as copyright notices, a list of symbols that your code reacts on etc. @@ -830,13 +795,13 @@ convenience, or in conditional compiles. By default, from version 0.9.8 of the compiler on, the compiler predefines three macros, containing the version number, the release number and the patch number. They are listed in \seet{DefMacros}. -\begin{FPKltable}{ll}{Predefined macros}{DefMacros} \hline +\begin{FPCltable}{ll}{Predefined macros}{DefMacros} \hline Symbol & Contains \\ \hline -\var{FPK\_VERSION} & The version number of the compiler. \\ -\var{FPK\_RELEASE} & The release number of the compiler. \\ -\var{FPK\_PATCH} & The patch number of the compiler. \\ +\var{FPC\_VERSION} & The version number of the compiler. \\ +\var{FPC\_RELEASE} & The release number of the compiler. \\ +\var{FPC\_PATCH} & The patch number of the compiler. \\ \hline -\end{FPKltable} +\end{FPCltable} {\em Remark: } Don't forget that macros support isn't on by default. You need to compile with the \var{-Sm} command-line switch. @@ -846,114 +811,21 @@ need to compile with the \var{-Sm} command-line switch. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Using assembly language} \label{ch:AsmLang} -\fpk supports inserting of assembler instructions in your code. The +\fpc supports inserting of assembler instructions in your code. The mechanism for this is the same as under Turbo Pascal. There are, however some substantial differences, as will be explained in the following. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% AT&T syntax -\section{AT\&T Syntax} -\label{se:AttSyntax} -\fpk uses the \gnu \var{as} assembler to generate its object files. Since -the \gnu assembler uses AT\&T assembly syntax, the code you write should -use the same syntax. The differences between AT\&T and Intel syntax as used -in Turbo Pascal are summarized in the following: -\begin{itemize} -\item The opcode names include the size of the operand. In general, one can -say that the AT\&T opcode name is the Intel opcode name, suffixed with a -'\var{l}', '\var{w}' or '\var{b}' for, respectively, longint (32 bit), -word (16 bit) and byte (8 bit) memory or register references. As an example, -the Intel construct \mbox{'\var{mov al bl}} is equivalent to the AT\&T style '\var{movb -\%bl,\%al}' instruction. -\item AT\&T immediate operands are designated with '\$', while Intel syntax -doesn't use a prefix for immediate operands. Thus the Intel construct -'\var{mov ax, 2}' becomes '\var{movb \$2, \%al}' in AT\&T syntax. -\item AT\&T register names are preceded by a '\var{\%}' sign. -They are undelimited in Intel syntax. -\item AT\&T indicates absolute jump/call operands with '\var{*}', Intel -syntax doesn't delimit these addresses. -\item The order of the source and destination operands are switched. AT\&T -syntax uses '\var{Source, Dest}', while Intel syntax features '\var{Dest, -Source}'. Thus the Intel construct '\var{add eax, 4}' transforms to -'\var{addl \$4, \%eax}' in the AT\&T dialect. -\item Immediate long jumps are prefixed with the '\var{l}' prefix. Thus the -Intel '\var{call/jmp section:offset'} is transformed to '\var{lcall/ljmp -\$section,\$offset}'. Similarly the far return is '\var{lret}', instead of the -Intel '\var{ret far}'. -\item Memory references are specified differently in AT\&T and Intel -assembly. The Intel indirect memory reference -\begin{quote} -\var{Section:[Base + Index*Scale + Offs]} -\end{quote} -is written in AT\&T syntax as : -\begin{quote} -\var{Section:Offs(Base,Index,Scale)} -\end{quote} -Where \var{Base} and \var{Index} are optional 32-bit base and index -registers, and \var{Scale} is used to multiply \var{Index}. It can take the -values 1,2,4 and 8. The \var{Section} is used to specify an optional section -register for the memory operand. -\end{itemize} - -More information about the AT\&T syntax can be found in the \var{as} manual, -although the following differences with normal AT\&T assembly must be taken -into account : -\begin{itemize} -\item Only the following directives are presently supported: - \begin{description} -\item[.byte] -\item[.word] -\item[.long] -\item[.ascii] -\item[.asciz] -\item[.globl] -\end{description} -\item The following directives are recognized but are not - supported: -\begin{description} -\item[.align] -\item[.lcomm] -\end{description} -Eventually they will be supported. -\item Directives are case sensitive, other identifiers are not case sensitive. -\item Contrary to GAS local labels/symbols {\em must} start with \var{.L} -\item The nor operator \var{'!'} is not supported. -\item String expressions in operands are not supported. -\item Constant expressions which represent memory references are not -allowed even though constant immediate value expressions are supported. \\ -examples: -\begin{verbatim} -const myid = 10; -... -movl $myid,%eax -- allowed -movl myid(%esi),%eax -- not allowed. -\end{verbatim} -\item When the \var{.globl} directive is found, the symbol following - it is made public and is immediately emitted. - Therefore label names with this name will be ignored. -\item Only Single and Double FPU opcodes are supported. -\end{itemize} - -The AT\&T inline assembler supports the following macros : -\begin{description} -\item [\_\_RESULT] represents the function result return value. -\item [\_\_SELF] represents the object method pointer in methods. -\item [\_\_OLDEBP] represents the old base pointer in recusrive routines. -\end{description} - - %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Intel syntax \section{Intel syntax} \label{se:Intel} -As of version 0.9.7, \fpk supports Intel syntax in it's \var{asm} blocks. +As of version 0.9.7, \fpc supports Intel syntax in it's \var{asm} blocks. The Intel syntax in your \var{asm} block is converted to AT\&T syntax by the compiler, after which it is inserted in the compiled source. -The supported assembler constructions are a subset of the normal assembly +The supported assembler constructs are a subset of the normal assembly syntax. In what follows we specify what constructs are not supported in -\fpk, but which exist in Turbo Pascal: +\fpc, but which exist in Turbo Pascal: \begin{itemize} \item The \var{TBYTE} qualifier is not supported. @@ -1058,7 +930,7 @@ lds si,@mylabel -- not allowed \var{SEGSS} segment overrides are presently not supported. (This is a planned addition though). \item Contrary to Turbo Pascal where memory sizes specifiers can - be practically anywhere, the \fpk Intel inline assembler requires + be practically anywhere, the \fpc Intel inline assembler requires memory size specifiers to be outside the brackets. \\ example: \begin{verbatim} @@ -1082,6 +954,99 @@ The Intel inline assembler supports the following macros : \item [Self] represents the object method pointer in methods. \end{description} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% AT&T syntax +\section{AT\&T Syntax} +\label{se:AttSyntax} +\fpc uses the \gnu \var{as} assembler to generate its object files. Since +the \gnu assembler uses AT\&T assembly syntax, the code you write should +use the same syntax. The differences between AT\&T and Intel syntax as used +in Turbo Pascal are summarized in the following: +\begin{itemize} +\item The opcode names include the size of the operand. In general, one can +say that the AT\&T opcode name is the Intel opcode name, suffixed with a +'\var{l}', '\var{w}' or '\var{b}' for, respectively, longint (32 bit), +word (16 bit) and byte (8 bit) memory or register references. As an example, +the Intel construct \mbox{'\var{mov al bl}} is equivalent to the AT\&T style '\var{movb +\%bl,\%al}' instruction. +\item AT\&T immediate operands are designated with '\$', while Intel syntax +doesn't use a prefix for immediate operands. Thus the Intel construct +'\var{mov ax, 2}' becomes '\var{movb \$2, \%al}' in AT\&T syntax. +\item AT\&T register names are preceded by a '\var{\%}' sign. +They are undelimited in Intel syntax. +\item AT\&T indicates absolute jump/call operands with '\var{*}', Intel +syntax doesn't delimit these addresses. +\item The order of the source and destination operands are switched. AT\&T +syntax uses '\var{Source, Dest}', while Intel syntax features '\var{Dest, +Source}'. Thus the Intel construct '\var{add eax, 4}' transforms to +'\var{addl \$4, \%eax}' in the AT\&T dialect. +\item Immediate long jumps are prefixed with the '\var{l}' prefix. Thus the +Intel '\var{call/jmp section:offset'} is transformed to '\var{lcall/ljmp +\$section,\$offset}'. Similarly the far return is '\var{lret}', instead of the +Intel '\var{ret far}'. +\item Memory references are specified differently in AT\&T and Intel +assembly. The Intel indirect memory reference +\begin{quote} +\var{Section:[Base + Index*Scale + Offs]} +\end{quote} +is written in AT\&T syntax as : +\begin{quote} +\var{Section:Offs(Base,Index,Scale)} +\end{quote} +Where \var{Base} and \var{Index} are optional 32-bit base and index +registers, and \var{Scale} is used to multiply \var{Index}. It can take the +values 1,2,4 and 8. The \var{Section} is used to specify an optional section +register for the memory operand. +\end{itemize} + +More information about the AT\&T syntax can be found in the \var{as} manual, +although the following differences with normal AT\&T assembly must be taken +into account : +\begin{itemize} +\item Only the following directives are presently supported: + \begin{description} +\item[.byte] +\item[.word] +\item[.long] +\item[.ascii] +\item[.asciz] +\item[.globl] +\end{description} +\item The following directives are recognized but are not + supported: +\begin{description} +\item[.align] +\item[.lcomm] +\end{description} +Eventually they will be supported. +\item Directives are case sensitive, other identifiers are not case sensitive. +\item Contrary to GAS local labels/symbols {\em must} start with \var{.L} +\item The nor operator \var{'!'} is not supported. +\item String expressions in operands are not supported. +\item Constant expressions which represent memory references are not +allowed even though constant immediate value expressions are supported. \\ +examples: +\begin{verbatim} +const myid = 10; +... +movl $myid,%eax -- allowed +movl myid(%esi),%eax -- not allowed. +\end{verbatim} +\item When the \var{.globl} directive is found, the symbol following + it is made public and is immediately emitted. + Therefore label names with this name will be ignored. +\item Only Single and Double FPU opcodes are supported. +\end{itemize} + +The AT\&T inline assembler supports the following macros : +\begin{description} +\item [\_\_RESULT] represents the function result return value. +\item [\_\_SELF] represents the object method pointer in methods. +\item [\_\_OLDEBP] represents the old base pointer in recusrive routines. +\end{description} + + + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Calling mechanism \section{Calling mechanism} @@ -1090,7 +1055,7 @@ Procedures and Functions are called with their parameters on the stack. Contrary to Turbo Pascal, {\em all} parameters are pushed on the stack, and they are pushed {\em right} to {\em left}, instead of left to right for Turbo Pascal. This is especially important if you have some assembly -subroutines in Turbo Pascal which you would like to translate to \fpk. +subroutines in Turbo Pascal which you would like to translate to \fpc. Function results are returned in the first register, if they fit in the register. For more information on this, see \sees{Stack} @@ -1123,7 +1088,7 @@ been passed to a function, the generated exit sequence looks as follows: When you want your code to be called by a C library or used in a C program, you will run into trouble because of this calling mechanism. In C, the calling procedure is expected to clear the stack, not the called -procedure. To avoid this problem, \fpk supports the \var{export} modifier. +procedure. To avoid this problem, \fpc supports the \var{export} modifier. Procedures that are defined using the export modifier, use a C-compatible calling mechanism. This means that they can be called from a C program or library, or that you can use them as a callback function. @@ -1143,10 +1108,10 @@ Comparing this exit sequence with the previous one makes it clear why you cannot call this procedure from within Pascal: The arguments still are on the stack when the procedure exits. -As of version 0.9.8, the \fpk compiler supports also the \var{cdecl} and +As of version 0.9.8, the \fpc compiler supports also the \var{cdecl} and \var{stdcall} modifiers, as found in Delphi. The \var{cdecl} modifier does the same as the \var{export} modifier, and \var{stdcall} does nothing, since -\fpk pushes the paramaters from right to left by default. +\fpc pushes the paramaters from right to left by default. All this is summarized in \seet{Calling}. The first column lists the modifier you specify for a procedure declaration. The second one lists the @@ -1155,14 +1120,14 @@ is responsible for cleaning the stack: the caller or the called function. Finally, the last column specifies if registers are used to pass parameters to the function. -\begin{FPKltable}{llll}{Calling mechanisms in \fpk}{Calling}\hline +\begin{FPCltable}{llll}{Calling mechanisms in \fpc}{Calling}\hline Modifier & Pushing order & Stack cleaned by & Parameters in registers \\ \hline (none) & Right-to-left & Function & No \\ cdecl & Right-to-left & Caller & No \\ export & Right-to-left & Caller & No \\ stdcall & Right-to-left & Function & No \\ \hline -\end{FPKltable} +\end{FPCltable} More about this can be found in \seec{Linking} on linking. @@ -1174,7 +1139,7 @@ When the compiler uses variables, it sometimes stores them, or the result of some calculations, in the processor registers. If you insert assembler code in your program that modifies the processor registers, then this may interfere with the compiler's idea about the registers. To avoid this -problem, \fpk allows you to tell the compiler which registers have changed. +problem, \fpc allows you to tell the compiler which registers have changed. The compiler will then avoid using these registers. Telling the compiler which registers have changed, is done by specifying a set of register names behind an assembly block, as follows: @@ -1210,7 +1175,7 @@ the linker isn't invoked. 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 \fpk compiler can generate calls to a C function, +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 @@ -1232,7 +1197,7 @@ The following sections attempt to explain how to do this. \label{se:ExternalDeclaration} The first step in using external code blocks is declaring the function you -want to use. \fpk supports Delphi syntax, i.e. you must use the +want to use. \fpc supports Delphi syntax, i.e. you must use the \var{external} directive. There exist four variants of the external direcive : @@ -1291,7 +1256,7 @@ dynamic link library, with index {SomeIndex}. \em{Remark:} Note that this is ONLY available under \windows and \ostwo. \end{enumerate} -In earlier versions of the \fpk compiler, the following construct was +In earlier versions of the \fpc compiler, the following construct was also possible : \begin{verbatim} Procedure ProcName (Args : TPRocArgs); [ C ]; @@ -1301,7 +1266,7 @@ This method is equivalent to the following statement: Procedure ProcName (Args : TPRocArgs); cdecl; external; \end{verbatim} However, the \var{[ C ]} directive is deprecated, and may no longer be -supported in future versions of \fpk, therefore you should use the +supported in future versions of \fpc, therefore you should use the \var{external} directive, with the \var{cdecl} directive, if needed. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1399,7 +1364,7 @@ Procedure ProcName (Args : TPRocArgs); [ C ]; You still need to explicity link to the library. This can be done in 2 ways: \begin{enumerate} \item You can tell the compiler in the source file what library to link to -using the \var{\{\$LinkLib 'Name'} directive: +using the \var{\{\$LinkLib 'Name'\}} directive: \begin{verbatim} {$LinkLib 'gpm'} \end{verbatim} @@ -1420,6 +1385,8 @@ As an example; consider the following program : \begin{verbatim} program printlength; +{$linklib c} { Case sensitive } + { Declaration for the standard C function strlen } Function strlen (P : pchar) : longint; cdecl;external; @@ -1429,7 +1396,7 @@ end. \end{verbatim} This program can be compiled with : \begin{verbatim} -pp -k'-lc' prlen.pp +pp prlen.pp \end{verbatim} Supposing, of course, that the program source resides in \file{prlen.pp}. @@ -1440,6 +1407,16 @@ arguments in C. Pascal doesn't support this feature of C. % Making a shared library \section{Making a shared library} \label{se:SharedLib} + +\fpc supports making shared 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} + 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 @@ -1458,12 +1435,12 @@ in the interface part of a unit. This is logical, since a Pascal routine cannot call an exported function, anyway. However, the generated object file will not contain the name of the function -as you declared it. The \fpk compiler ''mangles'' the name you give your +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 \fpk units, this doesn't matter, since the \file{.ppu} +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 \fpk +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 another name (a nickname) for your function or procedure. @@ -1474,7 +1451,7 @@ 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 \fpk, to export a +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} @@ -1487,6 +1464,66 @@ 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. +% Compiling libraries +\subsection {Compiling libraries} + +Once you have your (adapted) code, with exported and other functions, +you can compile your unit, and tell the compiler to make it into a library. +The compiler will simply compile your unit, and perform the necessary steps +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 +\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 +\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. + +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. + +{\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. + +% Moving units +\subsection{Moving units into a library} +You can put multiple units into a library with the \var{ppumove} command, as +follows: + +\begin{verbatim} +ppumove unit1 unit2 unit3 name +\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}, +\file{unit2.ppl} and \file{file3.ppl}, which are unit files, but which tell +the compiler to look in library \var{name} when linking your executable. + +The \var{ppumove} program has options to create statical or dynammical +libraries. It is provided with the compiler. + +% unit searching +\subsection{Unit searching strategy} + +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. + +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. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Objects @@ -1531,13 +1568,13 @@ in the VMT pointer. This ensures that the size of objects is equal, whether they have virtual methods ore not. The memory allocated looks as in \seet{ObjMem}. -\begin{FPKltable}{ll}{Object memory layout}{ObjMem} \hline +\begin{FPCltable}{ll}{Object memory layout}{ObjMem} \hline Offset & What \\ \hline +0 & Pointer to VMT. \\ +4 & Data. All fields in the order the've been declared. \\ ... & \\ \hline -\end{FPKltable} +\end{FPCltable} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % The virtual method table. @@ -1551,7 +1588,7 @@ methods. The VMT layout is illustrated in \seet{VMTMem}. The VMT is constructed by the compiler. Every instance of an object receives a pointer to its VMT. -\begin{FPKltable}{ll}{Virtual Method Table memory layout}{VMTMem} \hline +\begin{FPCltable}{ll}{Virtual Method Table memory layout}{VMTMem} \hline Offset & What \\ \hline +0 & Size of object type data \\ +4 & Minus the size of object type data. Enables determining of valid VMT @@ -1560,14 +1597,14 @@ pointers. \\ +12 & Pointers to the virtual methods. \\ ... & \\ \hline -\end{FPKltable} +\end{FPCltable} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Generated code %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Generated code} \label{ch:GenCode} -The \fpk compiler relies on the assembler to make object files. It generates +The \fpc compiler relies on the assembler to make object files. It generates just the assembly language file. In the following two sections, we discuss what is generated when you compile a unit or a program. @@ -1575,7 +1612,7 @@ what is generated when you compile a unit or a program. % Units \section{Units} \label{se:Units} -When you compile a unit, the \fpk compiler generates 2 files : +When you compile a unit, the \fpc compiler generates 2 files : \begin{enumerate} \item A unit description file (with extension \file{.ppu}). \item An assembly language file (with extension \file{.s}). @@ -1614,7 +1651,7 @@ the unit description file and the object file. You can also provide a C header file to go with the object file. In that case, your unit can be used by someone who wishes to write his programs in -C. However, you must make this header file yourself since the \fpk compiler +C. However, you must make this header file yourself since the \fpc compiler doesn't make one for you. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1656,7 +1693,7 @@ set up the stack. Then it calls the main program. \section{What is it about ?} \label{se:WhatisMMXabout} -\fpk supports the new MMX (Multi-Media extensions) +\fpc supports the new MMX (Multi-Media extensions) instructions of Intel processors. The idea of MMX is to process multiple data with one instruction, for example the processor can add simultaneously 4 words. To implement this efficiently, the @@ -1711,6 +1748,32 @@ want to use them, you have simple turn the switch saturation on: Here is an example: \begin{verbatim} +Program SaturationDemo; +{ + example for saturation, scales data (for example audio) + with 1.5 with rounding to negative infinity +} + +var + audio1 : tmmxword; + +const + helpdata1 : tmmxword = ($c000,$c000,$c000,$c000); + helpdata2 : tmmxword = ($8000,$8000,$8000,$8000); + +begin + { audio1 contains four 16 bit audio samples } +{$mmx+} + { convert it to $8000 is defined as zero, multiply data with 0.75 } + audio1:=tmmxfixed16(audio1+helpdata2)*tmmxfixed(helpdata1); +{$saturation+} + { avoid overflows (all values>$7fff becomes $ffff) } + audio1:=(audio1+helpdata2)-helpdata2; +{$saturation-} + { now mupltily with 2 and change to integer } + audio1:=(audio1 shl 1)-helpdata2; +{$mmx-} +end. \end{verbatim} \section{Restrictions of MMX support} @@ -1727,7 +1790,7 @@ MMX operations and before using floating point operations, you have to call the routine \var{EMMS} of the \var{MMX} unit. This routine restores the FPU registers. -\em{Careful:} The compiler doesn't warn, if you mix floating point and +{\em careful:} The compiler doesn't warn, if you mix floating point and MMX operations, so be careful. The MMX instructions are optimized for multi media (what else?). @@ -1779,7 +1842,7 @@ procedure. % The 32-bit model \section{The 32-bit model.} \label{se:ThirtytwoBit} -The \fpk Pascal compiler issues 32-bit code. This has several consequences: +The \fpc Pascal compiler issues 32-bit code. This has several consequences: \begin{itemize} \item You need a i386 or higher processor to run the generated code. The compiler functions on a 286 when you compile it using Turbo Pascal, @@ -1797,14 +1860,14 @@ constructs and functions are obsolete. The following is a list of functions which shouldn't be used anymore: \begin{description} \item [Seg()] : Returned the segment of a memory address. Since segments have -no more meaning, zero is returned in the \fpk run-time library implementation of +no more meaning, zero is returned in the \fpc run-time library implementation of \var{Seg}. \item [Ofs()] : Returned the offset of a memory address. Since segments have -no more meaning, the complete address is returned in the \fpk implementation +no more meaning, the complete address is returned in the \fpc implementation of this function. This has as a consequence that the return type is \var{Longint} instead of \var{Word}. \item [Cseg(), Dseg()] : Returned, respectively, the code and data segments -of your program. This returns zero in the \fpk implementation of the +of your program. This returns zero in the \fpc implementation of the system unit, since both code and data are in the same memory space. \item [Ptr] accepted a segment and offset from an address, and would return a pointer to this address. This has been changed in the run-time library. @@ -1812,12 +1875,13 @@ Standard it returns now simply the offset. If you want to retain the old functionality, you can recompile the run-time library with the \var{DoMapping} symbol defined. This will restore the Turbo Pascal behaviour. -\item [memw and mem] these arrays gave access to the \dos memory. \fpk -supports them, but they are mapped onto 32-bit flat memory space. +\item [memw and mem] these arrays gave access to the \dos memory. \fpc +supports them, they are mapped into \dos memory space. You need the +\var{GO32} unit for this. \end{description} You shouldn't use these functions, since they are very non-portable, they're -specific to \dos and the ix86 processor. The \fpk compiler is designed to be +specific to \dos and the ix86 processor. The \fpc compiler is designed to be portable to other platforms, so you should keep your code as portable as possible, and not system specific. That is, unless you're writing some driver units, of course. @@ -1848,7 +1912,7 @@ instruction). \end{enumerate} The resulting stack frame upon entering looks as in \seet{StackFrame}. -\begin{FPKltable}{llc}{Stack frame when calling a procedure}{StackFrame} +\begin{FPCltable}{llc}{Stack frame when calling a procedure}{StackFrame} \hline Offset & What is stored & Optional ? \\ \hline +x & parameters & Yes \\ @@ -1856,7 +1920,7 @@ Offset & What is stored & Optional ? \\ \hline +8 & self & Yes \\ +4 & Frame pointer of parent procedure & Yes \\ +0 & Return address & No\\ \hline -\end{FPKltable} +\end{FPCltable} The stack is cleared with the \var{ret} I386 instruction, meaning that the size of all pushed parameters is limited to 64K. @@ -1865,19 +1929,15 @@ The stack size is unlimited for all supported platforms. On the \var{GO32V2} platform, the minimum guaranteed stack is 128Kb, but this can be set with the \var{-Ctxxx} compiler switch. -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% The Heap -\section{The heap} -\label{se:Heap} The heap is used to store all dynamic variables, and to store class instances. The interface to the heap is the same as in Turbo Pascal, -although the effects are maybe not the same. On top of that, the \fpk +although the effects are maybe not the same. On top of that, the \fpc run-time library has some extra possibilities, not available in Turbo Pascal. These extra possibilities are explained in the next subsections. % The heap grows \subsection{The heap grows} -\fpk supports the \var{HeapEerror} procedural variable. If this variable is +\fpc supports the \var{HeapEerror} procedural variable. If this variable is non-nil, then it is called in case you try to allocate memory, and the heap is full. By default, \var{HeapError} points to the \var{GrowHeap} function, which tries to increase the heap. @@ -2000,6 +2060,62 @@ ReleaseTempHeap; ... \end{verbatim} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Accessing DOS memory under the GO32 extender +\section{Accessing \dos memory under the Go32 extender} +\label{se:AccessingDosMemory} + +Because \fpc is a 32 bit compiler, and uses a \dos extender, accessing DOS +memory isn't trivial. What follows is an attempt to an explanation of how to +access and use \dos or real mode memory\footnote{Thanks to an explanation of +Thomas schatzl (E-mail:\var{tom\_at\_work@geocities.com}).}. + +In {\em Proteced Mode}, memory is accessed through {\em Selectors} and +{\em Offsets}. You can think of Selectors as the protected mode +equivalents of segments. + +In \fpc, a pointer is an offset into the \var{DS} selector, which points to +the Data of your program. + +To access the (real mode) \dos memory, somehow you need a selector that +points to the \dos memory. +The \file{GO32} unit provides you with such a selector: The +\var{DosMemSelector} variable, as it is conveniently called. + +You can also allocate memory in \dos's memory space, using the +\var{global\_dos\_alloc} function of the \file{GO32} unit. +This function will allocate memory in a place where \dos sees it. + +As an example, here is a function that returns memory in real mode \dos and +returns a selector:offset pair for it. +\begin{verbatim} +procedure dosalloc(var selector : word; + var segment : word; + size : longint); + +var result : longint; + +begin + result := global_dos_alloc(size); + selector := word(result); + segment := word(result shr 16); +end; +\end{verbatim} +(you need to free this memory using the \var{global\_dos\_free} function.) + +You can access any place in memory using a selector. You can get a selector +using the \var{allocate\_ldt\_descriptor} function, and then let this selector +point to the physical memory you want using the +\var{set\_segment\_base\_address} function, and set its length using +\var{set\_segment\_limit} function. +You can manipulate the memory pointed to by the selector using the functions +of the GO32 unit. For instance with the \var{seg\_fillchar} function. +After using the selector, you must free it again using the +\var{free\_ldt\_selector} function. + +More information on all this can be found in the \unitsref, the chapter on +the \file{GO32} unit. + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Appendices %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -2029,7 +2145,7 @@ generate the unit file, etc. The complete layout can be found in when the compiler changes. The current and up-to-date header definition can be found in the \file{files.pas} source file of the compiler. Look in this file for the \var{unitheader} constant declaration. -\begin{FPKltable}{ll}{Unit header structure.}{UnitHeader} \hline +\begin{FPCltable}{ll}{Unit header structure.}{UnitHeader} \hline Byte & What is stored \\ \hline 0..3 & The letters 'PPU' in upper case. This acts as a check. \\ 4..6 & The unit format as a 3 letter sequence : e.g. '0','1,'2' for format @@ -2040,7 +2156,7 @@ Byte & What is stored \\ \hline 11..14 & Checksum (as a longint). \\ 15,16 & unused (equal to 255). \\ 17..20 & Marks start of unit file. \\ \hline -\end{FPKltable} +\end{FPCltable} After the header, in the second part, first the list of all source files for the unit is written. Each name is written as a direct copy of the string in memory, i.e. a length bytes, and then all characters of the string. This @@ -2060,7 +2176,7 @@ determines the kind of definition that follows. then follows, as a series of bytes, a type-dependent description of the definition. The exact byte order for each type can be found in \seet{DefDef} -\begin{FPKltable}{lccl}{Description of definition fields}{DefDef} \\hline +\begin{FPCltable}{lccl}{Description of definition fields}{DefDef} \\hline Type & Start byte & Size & Stored fields \\ \hline\hline Pointer & 3 & 4 & Reference to the type pointer points to. \\ \hline Base type & 2 & 9 & @@ -2121,7 +2237,7 @@ set & 20 & 5 & 4-byte reference to set element type. \\ 1 byte flag. \end{tabular} \\ \hline \hline -\end{FPKltable} +\end{FPCltable} This list of definitions is again terminated with a \var{\$ff} byte marker. After that, a list of symbols is given, together with a reference to a @@ -2276,16 +2392,107 @@ 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} -\item When optimizing for speed (\var{-OG}) or size (\var{-Og}), a choice is +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 +speed, according to the Cyrix developers FAQ. + \item When optimizing for speed (\var{-OG}) 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. -\item Maximum optimization (\var{-Ox}) avoid creation of stack frames if +used, as well as the reloading optimizer. +\item Maximum optimization (\var{-Ox}) avoids creation of stack frames if they aren't required, and unnecessary loading of registers is avoided as much as possible. (buggy at the moment (version 0.99.0). -\item For the future, a reloading optimizer is planned. -\end{enumerate} +\item Uncertain optimizations (\var{-Oz}): With this switch, the reloading +optimizer (enabled with \var{-Oa}) can be forced into making uncertain +optimizations. + +You can enable uncertain optimizations only in certain cases, +otherwise you will produce a bug; the following technical description +tells you when to use them: +\begin{quote} +% Jonas's own words.. +\em +If uncertain optimizations are enabled, the reloading optimizer assumes +that +\begin{itemize} +\item If something is written to a local/global register or a +procedure/function parameter, this value doesn't overwrite the value to +which a pointer points. +\item If something is written to memory pointed to by a pointer variable, +this value doesn't overwrite the value of a local/global variable or a +procedure/function parameter. +\end{itemize} +% end of quote +\end{quote} +The practical upshot of this is that you cannot use the uncertain +optimizations if you access any local or global variables through pointers. In +theory, this includes \var{Var} parameters, but it is all right +if you don't both read the variable once through its \var{Var} reference +and then read it using it's name. + +The following example will produce bad code when you switch on +uncertain optimizations: +\begin{verbatim} +Var temp: Longint; + +Procedure Foo(Var Bar: Longint); +Begin + If (Bar = temp) + Then + Begin + Inc(Bar); + If (Bar <> temp) then Writeln('bug!') + End +End; + +Begin + Foo(Temp); +End. +\end{verbatim} +The reason it produces bad code is because you access the global variable +\var{Temp} both through its name \var{Temp} and through a pointer, in this +case using the \var{Bar} variable parameter, which is nothing but a pointer +to \var{Temp} in the above code. + +On the other hand, you can use the uncertain optimizations if +you access global/local variables or parameters through pointers, +and {\em only} access them through this pointer\footnote{ +You can use multiple pointers to point to the same variable as well, that +doesn't matter.}. + +For example: +\begin{verbatim} +Type TMyRec = Record + a, b: Longint; + End; + PMyRec = ^TMyRec; + + + TMyRecArray = Array [1..100000] of TMyRec; + PMyRecArray = ^TMyRecArray; + +Var MyRecArrayPtr: PMyRecArray; + MyRecPtr: PMyRec; + Counter: Longint; + +Begin + New(MyRecArrayPtr); + For Counter := 1 to 100000 Do + Begin + MyRecPtr := @MyRecArrayPtr^[Counter]; + MyRecPtr^.a := Counter; + MyRecPtr^.b := Counter div 2; + End; +End. +\end{verbatim} +Will produce correct code, because the global variable \var{MyRecArrayPtr} +is not accessed directly, but through a pointer (\var{MyRecPtr} in this +case). + +In conclusion, one could say that you can use uncertain optimizations {\em +only} when you know what you're doing. +\end{enumerate} \end{document} diff --git a/docs/ref.tex b/docs/ref.tex index 9bf29f3886..26ac78799c 100644 --- a/docs/ref.tex +++ b/docs/ref.tex @@ -25,8 +25,8 @@ \usepackage{a4} \usepackage{makeidx} \usepackage{html} -\latex{\usepackage{fpk}} -\html{\input{fpk-html.tex}} +\latex{\usepackage{fpc}} +\html{\input{fpc-html.tex}} \makeindex % % start of document. @@ -48,10 +48,10 @@ This document describes all constants, types, variables, functions and procedures as they are declared in the system unit. -Furthermore, it describes all pascal constructs supported by \fpk, and lists +Furthermore, it describes all pascal constructs supported by \fpc, and lists all supported data types. It does not, however, give a detailed explanation of the pascal language. The aim is to list which Pascal constructs are -supported, and to show where the \fpk implementation differs from the +supported, and to show where the \fpc implementation differs from the Turbo Pascal implementation. Throughout this document, we will refer to functions, types and variables @@ -78,20 +78,20 @@ manual section. % The Pascal language % \chapter{Supported Pascal language constructs} -In this chapter we describe the pascal constructs supported by \fpk, as well +In this chapter we describe the pascal constructs supported by \fpc, as well as the supported data types. This is not intended as an introduction to the Pascal language, although all language constructs will be covered. The main goal is to explain what is -supported by \fpk, and where the Free implementation differs from the Turbo +supported by \fpc, and where the Free implementation differs from the Turbo Pascal one. \section{Data types} -\fpk supports the same data types as Turbo Pascal, with some extensions from +\fpc supports the same data types as Turbo Pascal, with some extensions from Delphi. \subsection{Integer types} -The integer types predefined in \fpk are listed in \seet{integers}. +The integer types predefined in \fpc are listed in \seet{integers}. -\begin{FPKltable}{lcr}{Predefined integer types}{integers} +\begin{FPCltable}{lcr}{Predefined integer types}{integers} Type & Range & Size in bytes \\ \hline Byte & 0 .. 255 & 1 \\ Shortint & -127 .. 127 & 1\\ @@ -99,33 +99,33 @@ Integer & -32768 .. 32767 & 2 \\ Word & 0 .. 65535 & 2 \\ Longint & -2147483648 .. 2147483648 & 4\\ Cardinal\footnote{The cardinal type support is buggy until version 0.9.3} & 0..4294967296 & 4 \\ \hline -\end{FPKltable} +\end{FPCltable} -\fpk does automatic type conversion in expressions where different kinds of +\fpc does automatic type conversion in expressions where different kinds of integer types are used. -\fpk supports hexadecimal format the same way as Turbo Pascal does. To +\fpc supports hexadecimal format the same way as Turbo Pascal does. To specify a constant value in hexadecimal format, prepend it with a dollar sign (\var{\$}). Thus, the hexadecimal \var{\$FF} equals 255 decimal. -In addition to the support for hexadecimal notation, \fpk also supports +In addition to the support for hexadecimal notation, \fpc also supports binary notation. You can specify a binary number by preceding it with a percent sign (\var{\%}). Thus, \var{255} can be specified in binary notation as \var{\%11111111}. \subsection{Real types} -\fpk uses the math coprocessor (or an emulation) for al its floating-point +\fpc uses the math coprocessor (or an emulation) for al its floating-point calculations. The native type for the coprocessor is \var{Double}. Other than that, all Turbo Pascal real types are supported. They're listed in \seet{Reals}. - \begin{FPKltable}{lccr}{Supported Real types}{Reals} + \begin{FPCltable}{lccr}{Supported Real types}{Reals} Type & Range & Significant digits & Size\footnote{In Turbo Pascal.} \\ \hline Real & 2.9E-39 .. 1.7E38 & 11-12 & 6 \\ Single & 1.5E-45 .. 3.4E38 & 7-8 & 4 \\ 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 \\ -\end{FPKltable} +\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. From version 0.9.3, the @@ -134,7 +134,7 @@ Turbo Pascal. The \seef{SizeOf} function is your friend here. \subsection{Character types} \subsubsection{Char} -\fpk supports the type \var{Char}. A \var{Char} is exactly 1 byte in +\fpc supports the type \var{Char}. A \var{Char} is exactly 1 byte in size, and contains one character. You can specify a character constant by enclosing the character in single @@ -153,7 +153,7 @@ successively, thus \var{''''} represents the single quote character. \subsubsection{Strings} -\fpk supports the \var{String} type as it is defined in Turbo Pascal. +\fpc supports the \var{String} type as it is defined in Turbo Pascal. To declare a variable as a string, use the following declaration: \begin{verbatim} Var @@ -162,7 +162,7 @@ Var This will declare \var{S} as a variable of type \var{String}, with maximum length \var{Size}. \var{Size} can be any value from \var{1} to \var{255}. -\fpk reserves \var{Size+1} bytes for the string \var{S}, and in the zeroeth +\fpc reserves \var{Size+1} bytes for the string \var{S}, and in the zeroeth element of the string (\var{S[0]}) it will store the length of the variable. If you don't specify the size of the string, \var{255} is taken as a @@ -187,7 +187,7 @@ between them. Strings can not be substracted, however. \subsubsection{PChar} -\fpk supports the Delphi implementation of the \var{PChar} type. \var{PChar} +\fpc supports the Delphi implementation of the \var{PChar} type. \var{PChar} is defined as a pointer to a \var{Char} type, but allows additional operations. @@ -196,7 +196,7 @@ C-style null-terminated string, i.e. a variable of type \var{PChar} is a pointer that points to an array of type \var{Char}, which is ended by a null-character (\var{\#0}). -\fpk supports initializing of \var{PChar} typed constants, or a direct +\fpc supports initializing of \var{PChar} typed constants, or a direct assignment. For example, the following pieces of code are equivalent: \begin{CodEx} @@ -255,7 +255,7 @@ However, it is possible to do some pointer arithmetic. You can use the operators \var{+} and \var{-} to do operations on \var{PChar} pointers. In \seet{PCharMath}, \var{P} and \var{Q} are of type \var{PChar}, and \var{I} is of type \var{Longint}. -\begin{FPKltable}{lr}{\var{PChar} pointer arithmetic}{PCharMath} +\begin{FPCltable}{lr}{\var{PChar} pointer arithmetic}{PCharMath} Operation & Result \\ \hline \var{P + I} & Adds \var{I} to the address pointed to by \var{P}. \\ \var{I + P} & Adds \var{I} to the address pointed to by \var{P}. \\ @@ -263,10 +263,10 @@ Operation & Result \\ \hline \var{P - Q} & Returns, as an integer, the distance between 2 addresses \\ & (or the number of characters between \var{P} and \var{Q}) \\ \hline -\end{FPKltable} +\end{FPCltable} \subsection{Booleans} -\fpk supports the \var{Boolean} type, with its two pre-defined possible +\fpc supports the \var{Boolean} type, with its two pre-defined possible values \var{True} and \var{False}. These are the only two values that can be assigned to a \var{Boolean} type. Of course, any expression that resolves to a \var{boolean} value, can also be assigned to a boolean type. @@ -280,7 +280,7 @@ assignments: \end{verbatim} Boolean expressions are also used in conditions. -{\em Remark:} In \fpk, boolean expressions are always evaluated in such a +{\em Remark:} In \fpc, boolean expressions are always evaluated in such a way that when the result is known, the rest of the expression will no longer be evaluated (Called short-cut evaluation). In the following example, the function \var{Func} will never be called, which may have strange side-effects. @@ -292,13 +292,13 @@ be called, which may have strange side-effects. Here \var{Func} is a function which returns a \var{Boolean} type. \subsection{Arrays} -\fpk supports arrays as in Turbo Pascal, except that packed arrays are not +\fpc supports arrays as in Turbo Pascal, except that packed arrays are not supported. Multi-dimensional arrays are also supported. \subsection{Pointers} -\fpk supports the use of pointers. A variable of the type \var{Pointer} +\fpc supports the use of pointers. A variable of the type \var{Pointer} contains an address in memory, where the data of another variable may be stored. @@ -326,7 +326,7 @@ In this example, \var{BP} {\em is a pointer to} a \var{Buffer} type; while \var{ and \var{BP} only takes 4 bytes of memory (enough to keep an adress in memory). -{\em Remark:} \fpk treats pointers much the same way as C does. This means +{\em Remark:} \fpc treats pointers much the same way as C does. This means that you can treat a pointer to some type as being an array of this type. The pointer then points to the zeroeth element of this array. Thus the following pointer declaration @@ -354,10 +354,10 @@ begin end. \end{verbatim} \end{CodEx} -\fpk doesn't support pointer arithmetic as C does, however. +\fpc doesn't support pointer arithmetic as C does, however. \subsection{Procedural types} -\fpk has support for procedural types, although it differs from the Turbo +\fpc has support for procedural types, although it differs from the Turbo Pascal implementation of them. The type declaration remains the same. The two following examples are valid @@ -383,11 +383,11 @@ 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 \fpk it is required. +when assigning a procedural type variable, whereas in \fpc it is required. \subsection{Records} -\fpk supports records. The prototype type definition of a record is: +\fpc supports records. The prototype type definition of a record is: \begin{verbatim} Type RecType = Record @@ -451,7 +451,7 @@ And this is as expected. In \var{Trec1}, each of the elements \var{A} and \var{B} takes 2 bytes of memory, and in \var{Trec1}, \var{A} takes only 1 byte of memory. -As from version 0.9.3 (a developers' version), \fpk supports also the +As from version 0.9.3 (a developers' version), \fpc supports also the 'packed record', this is a record where all the elements are byte-aligned. Thus the two following declarations are equivalent: @@ -474,7 +474,7 @@ Note the \var{\{\$PACKRECORDS 2\}} after the first declaration ! \subsection{Set types} -\fpk supports the set types as in Turbo Pascal. The prototype of a set +\fpc supports the set types as in Turbo Pascal. The prototype of a set declaration is: \begin{verbatim} SetType = Set of TargetType; @@ -495,12 +495,12 @@ Given this set declaration, the follwing assignment is legal: WeekDays := [ Mon, Tue, Wed, Thu, Fri]; \end{verbatim} The operators for manipulations of sets are listed in \seet{SetOps}. -\begin{FPKltable}{lr}{Set Manipulation operators}{SetOps} +\begin{FPCltable}{lr}{Set Manipulation operators}{SetOps} Operation & Operator \\ \hline Union & + \\ Difference & - \\ Intersection & * \\ \hline -\end{FPKltable} +\end{FPCltable} You can compare two sets with the \var{<>} and \var{=} operators, but not (yet) with the \var{<} and \var{>} operators. @@ -511,8 +511,8 @@ processing and decreases program size. \subsection{Enumeration types} -Enumeration types are supported in \fpk. On top of the Turbo Pascal -implementation, \fpk allows the following C-style extension of the +Enumeration types are supported in \fpc. On top of the Turbo Pascal +implementation, \fpc allows the following C-style extension of the enumeration type. \begin{verbatim} Type @@ -536,7 +536,7 @@ error. \section{Constants} -Just as in Turbo Pascal, \fpk supports both normal and typed constants. +Just as in Turbo Pascal, \fpc supports both normal and typed constants. \subsection{Ordinary constants} Ordinary constants declarations are no different from the TP implementation. You can only declare constants of the following types: \var{Ordinal types}, @@ -611,11 +611,11 @@ The order of the fields in a constant record needs to be the same as in the type otherwise you'll get a compile-time error. \section{Objects} -\fpk supports object oriented programming. In fact, part of the compiler is +\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 \fpk. +object oriented programming in \fpc. -\fpk supports 2 programming models for object-oriented programming. +\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. @@ -666,11 +666,11 @@ TObj = Object [(ParentObjectType)] You can repeat as many \var{private} and \var{public} blocks as you want. \var{Method}s are normal function or procedure declarations. -As can be seen in the prototype object declaration, \fpk supports +As can be seen in the prototype object declaration, \fpc supports constructors and destructors. You are responsible for calling the destructor and constructor explicitly when using objects. -\fpk supports also the extended syntax of the \var{New} and \var{Dispose} +\fpc supports also the extended syntax of the \var{New} and \var{Dispose} procedures. In case you want to allocate a dynamic varible of an object type, you can specify the constructor's name in the call to \var{New}. The \var{New} is implemented as a function which returns a pointer to the @@ -757,15 +757,15 @@ So, to initialize an instance of some class, you do the following : ClassVar:=ClassType.ConstructorName; \end{verbatim} -{\em Remark :} \fpk doesn't support the concept of properties yet. +{\em Remark :} \fpc doesn't support the concept of properties yet. \section{Statements controlling program flow.} \subsection{Assignments} -In addition to the standard Pascal assignment operator (\var{:=}), \fpk +In addition to the standard Pascal assignment operator (\var{:=}), \fpc supports some c-style constructions. All available constructs are listed in \seet{assignments}. -\begin{FPKltable}{lr}{Allowed C constructs in \fpk}{assignments} +\begin{FPCltable}{lr}{Allowed C constructs in \fpc}{assignments} Assignment & Result \\ \hline a += b & Adds \var{b} to \var{a}, and stores the result in \var{a}.\\ a -= b & Substracts \var{b} from \var{a}, and stores the result in @@ -774,14 +774,14 @@ a *= b & Multiplies \var{a} with \var{b}, and stores the result in \var{a}. \\ a /= b & Divides \var{a} through \var{b}, and stores the result in \var{a}. \\ \hline -\end{FPKltable} +\end{FPCltable} For these connstructs to work, you should specify the \var{-Sc} command-line switch. {\em Remark:} These constructions are just for typing convenience, they don't generate different code. -\fpk also supports typed assignments. This means that an assignment +\fpc also supports typed assignments. This means that an assignment statement has a definite type, and hence can be assigned to another variable. The type of the assignment \var{a:=b} is the type of \var{a} (or, in this case, of \var{b}), and this can be assigned to another @@ -797,7 +797,7 @@ For this construct to be allowed, it is necessary to specify the \var{-Sa4} switch on the command line. \subsection{The \var{Case} statement} -\fpk supports the \var{case} statement. Its prototype is +\fpc supports the \var{case} statement. Its prototype is \begin{verbatim} Case Pivot of Label1 : Statement1; @@ -816,7 +816,7 @@ The statements \var{Statement1} etc., can be compound statements (i.e. a \var{begin..End} block). {\em Remark:} Contrary to Turbo Pascal, duplicate case labels are not -allowed in \fpk, so the following code will generate an error when +allowed in \fpc, so the following code will generate an error when compiling: \begin{verbatim} @@ -842,7 +842,7 @@ Else Statement2 end; \end{verbatim} -You needed to do the following in \fpk : +You needed to do the following in \fpc : \begin{verbatim} case Pivot of ... @@ -856,7 +856,7 @@ end; 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} -\fpk supports the \var{For} loop construction. The prototypes are: +\fpc supports the \var{For} loop construction. The prototypes are: \begin{verbatim} For Counter:=Lowerbound to Upperbound Do Statement; @@ -868,7 +868,7 @@ For Counter:=Upperbound downto Lowerbound Do Statement; \var{Lowerbound} is larger than \var{Upperbound} then \var{Statement} will never be executed. \subsection{The \var{Goto} statement} -\fpk supports the \var{goto} jump statement. Its prototype is +\fpc supports the \var{goto} jump statement. Its prototype is \begin{verbatim} var @@ -968,7 +968,7 @@ Last statement doesn't need to be followed by a semicolon, although it is allowed. \section{Using functions and procedures} -\fpk supports the use of functions and procedures, but with some extras: +\fpc supports the use of functions and procedures, but with some extras: Function overloading is supported, as well as \var{Const} parameters and open arrays. @@ -1002,7 +1002,7 @@ generated. \subsection{\var{Const} parameters} In addition to \var{var} parameters and normal parameters (call by value, -call by reference), \fpk also supports \var{Const} parameters. You can +call by reference), \fpc also supports \var{Const} parameters. You can specify a \var{Const} parameter as follows: \begin{verbatim} Function Name (Const S: Type_Of_S) : ResultType @@ -1015,7 +1015,7 @@ The main use for this is reducing the stack size, hence improving performance. \subsection{Open array parameters} -\fpk supports the passing of open arrays, i.e. You can declare a procedure +\fpc supports the passing of open arrays, i.e. You can declare a procedure with an array of unspecified length as a parameter, as in Delphi. The prototype declaration for open array parameters is: @@ -1032,19 +1032,19 @@ are also declared with open arrays as parameters, {\em not} to functions or procedures which accept arrays of fixed length. \section{Using assembler in your code} -\fpk supports the use of assembler in your code, but not inline +\fpc supports the use of assembler in your code, but not inline assembler. assembly functions (i.e. functions declared with the \var{Assembler} keyword) are supported as of version 0.9.7. {\em Remark :} -\fpk issues AT\&T assembly language, as understood by most +\fpc issues AT\&T assembly language, as understood by most unix assemblers (most notably : GNU \var{as}). Intel assembler syntax is available as of version 0.9.8 but the Intel support isn't complete in the sense that it is converted to AT\&T syntax, and some constructions aren't supported by the conversion mechanism (see \progref for more information about this). Therefore all examples of assembly language will be given in AT\&T syntax, -as it is the 'native' assembly from \fpk. +as it is the 'native' assembly from \fpc. The following is an example of assembler inclusion in your code. \begin{verbatim} @@ -1068,7 +1068,7 @@ Contrary to Turbo Pascal, it isn't possible (yet) to reference variables by their names in the assembler parts of your code. \section{Modifiers} -\fpk doesn't support all Turbo Pascal modifiers, but +\fpc doesn't support all Turbo Pascal modifiers, but does support a number of additional modifiers. They are used mainly for assembler and reference to C object files. @@ -1137,9 +1137,9 @@ function must be exactly the same. \subsection{Export} Sometimes you must provide a callback function for a C library, or you want -your routines to be callable from a C program. Since \fpk and C use +your routines to be callable from a C program. Since \fpc and C use different calling schemes for functions and procedures\footnote{More -techically: In C the calling procedure must clear the stack. In \fpk, the +techically: In C the calling procedure must clear the stack. In \fpc, the subroutine clears the stack.}, the compiler must be told to generate code that can be called from a C routine. This is where the \var{Export} modifier comes in. Contrary to the other modifiers, it must be specified separately, @@ -1153,7 +1153,7 @@ end; \end{verbatim} The square brackets around the modifier are not allowed in this case. -{\em Remark:} You cannot call an exported function from within \fpk programs. +{\em Remark:} You cannot call an exported function from within \fpc programs. If you try to do so, the compiler will complain when compiling your source code. @@ -1171,20 +1171,20 @@ begin RealDoSomething; end; \end{verbatim} -In this example, from your \fpk code, you can call the \var{RealDoSomething} +In this example, from your \fpc code, you can call the \var{RealDoSomething} procedure. If someone wants to link to your code from a C program, he can call the \var{DoSomething} procedure. Both calls will have the same effect. {\em Remark:} -as of version 0.9.8, \fpk supports the Delphi \var{cdecl} modifier. +as of version 0.9.8, \fpc supports the Delphi \var{cdecl} modifier. This modifier works in the same way as the \var{export} modifier. More information about these modifiers can be found in the \progref, in the section on the calling mechanism and the chapter on linking. \subsection{StdCall} -As of version 0.9.8, \fpk supports the Delphi \var{stdcall} modifier. -This modifier does actually nothing, since the \fpk compiler by default +As of version 0.9.8, \fpc supports the Delphi \var{stdcall} modifier. +This modifier does actually nothing, since the \fpc compiler by default pushes parameters from right to left on the stack, which is what the modifier does under Delphi (which pushes parameters on the stack from left to right). @@ -1236,21 +1236,21 @@ Where \var{'register'} is one of \var{'EAX',EBX',ECX','EDX'} etc. \subsection{Unsupported Turbo Pascal modifiers} -The modifiers that exist in Turbo pascal, but aren't supported by \fpk, are +The modifiers that exist in Turbo pascal, but aren't supported by \fpc, are listed in \seet{Modifs}. -\begin{FPKltable}{lr}{Unsupported modifiers}{Modifs} +\begin{FPCltable}{lr}{Unsupported modifiers}{Modifs} Modifier & Why not supported ? \\ \hline -Near & \fpk is a 32-bit compiler.\\ -Far & \fpk is a 32-bit compiler. \\ +Near & \fpc is a 32-bit compiler.\\ +Far & \fpc is a 32-bit compiler. \\ External & Replaced by \var{C} modifier. \\ \hline -\end{FPKltable} +\end{FPCltable} % % System unit reference guide. % \chapter{Reference : The system unit} -The system unit contains the standard supported functions of \fpk. It is the +The system unit contains the standard supported functions of \fpc. It is the same for all platforms. Basically it is the same as the system unit provided with Borland or Turbo Pascal. @@ -1319,7 +1319,7 @@ var stackbottom : longint; loweststack : longint; \end{verbatim} -The variables \var{ExitProc}, \var{exitcode} are used in the \fpk exit +The variables \var{ExitProc}, \var{exitcode} are used in the \fpc exit scheme. It works similarly to the on in Turbo Pascal: When a program halts (be it through the call of the \var{Halt} function or @@ -1475,8 +1475,8 @@ empty string is returned.} \input{refex/ex12.tex} \Function{CSeg}{Word} -{\var{CSeg} returns the Code segment register. In \fpk, it returns always a -zero, since \fpk is a 32 bit compiler.} +{\var{CSeg} returns the Code segment register. In \fpc, it returns always a +zero, since \fpc is a 32 bit compiler.} {None.} {\seef{DSeg}, \seef{Seg}, \seef{Ofs}, \seef{Ptr}} @@ -1512,8 +1512,8 @@ heap.} \input{refex/ex16.tex} \Function{DSeg}{Word} -{\var{DSeg} returns the data segment register. In \fpk, it returns always a -zero, since \fpk is a 32 bit compiler.} +{\var{DSeg} returns the data segment register. In \fpc, it returns always a +zero, since \fpc is a 32 bit compiler.} {None.} {\seef{CSeg}, \seef{Seg}, \seef{Ofs}, \seef{Ptr}} @@ -1862,8 +1862,8 @@ For an example, see \seep{Dispose}. \function{Ofs}{Var X}{Longint} {\var{Ofs} returns the offset of the address of a variable. -This function is only supported for compatibility. In \fpk, it -returns always the complete address of the variable, since \fpk is a 32 bit +This function is only supported for compatibility. In \fpc, it +returns always the complete address of the variable, since \fpc is a 32 bit compiler. } {None.} @@ -1928,7 +1928,7 @@ The search is case-sensitive. {\var{Ptr} returns a pointer, pointing to the address specified by segment{Sel} and offset \var{Off}. -{\em Remark 1:} In the 32-bit flat-memory model supported by \fpk, this +{\em Remark 1:} In the 32-bit flat-memory model supported by \fpc, this function is obsolete.} {\em Remark 2:} The returned address is simply the offset. If you recompile @@ -1952,7 +1952,7 @@ If the argument \var{L} is omitted, a real number between 0 and 1 is returned. \input{refex/ex49.tex} \Procedure{Randomize} -{\var{Randomize} initializes the random number generator of \fpk, by giving +{\var{Randomize} initializes the random number generator of \fpc, by giving a value to \var{Randseed}, calculated with the system clock. } {None.} @@ -2116,8 +2116,8 @@ If the parameter \var{F} is omitted, standard \var{Input} is assumed.} \function{Seg}{Var X}{Longint} {\var{Seg} returns the segment of the address of a variable. -This function is only supported for compatibility. In \fpk, it -returns always 0, since \fpk is a 32 bit compiler, segments have no meaning. +This function is only supported for compatibility. In \fpc, it +returns always 0, since \fpc is a 32 bit compiler, segments have no meaning. } {None.} {\seef{DSeg}, \seef{CSeg}, \seef{Ofs}, \seef{Ptr}} diff --git a/docs/refex/foot.tex b/docs/refex/foot.tex index 83788a402a..4b6c233a40 100644 --- a/docs/refex/foot.tex +++ b/docs/refex/foot.tex @@ -1,2 +1,2 @@ \end{verbatim} -\end{FPKList} \ No newline at end of file +\end{FPCList} \ No newline at end of file diff --git a/docs/refex/head.tex b/docs/refex/head.tex index b2ed5b6603..2699f37d16 100644 --- a/docs/refex/head.tex +++ b/docs/refex/head.tex @@ -1,3 +1,3 @@ -\begin{FPKList} +\begin{FPCList} \item[Example] \begin{verbatim} diff --git a/docs/sockex/foot.tex b/docs/sockex/foot.tex index 83788a402a..4b6c233a40 100644 --- a/docs/sockex/foot.tex +++ b/docs/sockex/foot.tex @@ -1,2 +1,2 @@ \end{verbatim} -\end{FPKList} \ No newline at end of file +\end{FPCList} \ No newline at end of file diff --git a/docs/sockex/head.tex b/docs/sockex/head.tex index b2ed5b6603..2699f37d16 100644 --- a/docs/sockex/head.tex +++ b/docs/sockex/head.tex @@ -1,3 +1,3 @@ -\begin{FPKList} +\begin{FPCList} \item[Example] \begin{verbatim} diff --git a/docs/stringex/foot.tex b/docs/stringex/foot.tex index 83788a402a..4b6c233a40 100644 --- a/docs/stringex/foot.tex +++ b/docs/stringex/foot.tex @@ -1,2 +1,2 @@ \end{verbatim} -\end{FPKList} \ No newline at end of file +\end{FPCList} \ No newline at end of file diff --git a/docs/stringex/head.tex b/docs/stringex/head.tex index b2ed5b6603..2699f37d16 100644 --- a/docs/stringex/head.tex +++ b/docs/stringex/head.tex @@ -1,3 +1,3 @@ -\begin{FPKList} +\begin{FPCList} \item[Example] \begin{verbatim} diff --git a/docs/strings.tex b/docs/strings.tex index 4cbc0f2665..416b2ef1bc 100644 --- a/docs/strings.tex +++ b/docs/strings.tex @@ -20,7 +20,7 @@ % \chapter{The STRINGS unit.} This chapter describes the \var{STRINGS} unit for -\fpk. +\fpc. Since the unit only provides some procedures and functions, there is only one section, which gives the declarations of these functions, together diff --git a/docs/units.tex b/docs/units.tex index 873235377e..59fe075384 100644 --- a/docs/units.tex +++ b/docs/units.tex @@ -27,8 +27,8 @@ \usepackage{a4} \usepackage{makeidx} \usepackage{html} -\latex{\usepackage{fpk}} -\html{\input{fpk-html.tex}} +\latex{\usepackage{fpc}} +\html{\input{fpc-html.tex}} \makeindex % @@ -46,7 +46,7 @@ \section*{About this guide} This document describes all constants, types, variables, functions and -procedures as they are declared in the units that come standard with \fpk. +procedures as they are declared in the units that come standard with \fpc. Throughout this document, we will refer to functions, types and variables with \var{typewriter} font. Functions and procedures gave their own diff --git a/docs/user.tex b/docs/user.tex index 1f445fbe9e..cefaae45dc 100644 --- a/docs/user.tex +++ b/docs/user.tex @@ -23,32 +23,17 @@ \usepackage{html} \makeindex \latex{\usepackage{multicol}} -\latex{\usepackage{fpkman}} -\html{\input{fpk-html.tex}} -% define the version number here, and not in the fpk.sty !!! -\newcommand{\fpkversion}{0.9.5} +\latex{\usepackage{fpcman}} +\html{\input{fpc-html.tex}} \newcommand{\remark}[1]{\par$\rightarrow$\textbf{#1}\par} -% define many-used references. -%\newcommand{\progref}{\htmladdnormallink{Programmer's guide}{../prog/prog.html}\ } -%\newcommand{\refref}{\htmladdnormallink{Reference guide}{../ref/ref.html}\ } -%\newcommand{\seecrt}{\htmladdnormallink{CRT}{../crt/crt.html}} -%\newcommand{\seelinux}{\htmladdnormallink{Linux}{../linux/linux.html}} -%\newcommand{\seestrings}{\htmladdnormallink{strings}{../strings/strings.html}} -%\newcommand{\seedos}{\htmladdnormallink{DOS}{../dos/dos.html}} -%\newcommand{\seegetopts}{\htmladdnormallink{getopts}{../getopts/getopts.html}} -%\newcommand{\seeobjects}{\htmladdnormallink{objects}{../objects/objects.html}} -%\newcommand{\seegraph}{\htmladdnormallink{graph}{../graph/graph.html}} -%\newcommand{\seeprinter}{\htmladdnormallink{printer}{../printer/printer.html}} -%\newcommand{\seego}{\htmladdnormallink{GO32}{../go32/go32.html}} -% \newcommand{\olabel}[1]{\label{option:#1}} % We should change this to something better. See \seef etc. \newcommand{\seeo}[1]{See \ref{option:#1}} \begin{document} -\title{Free Pascal :\\ User's manual} -\docdescription{User's manual for \fpk, version \fpkversion} -\docversion{1.0} -\date{July 1997} +\title{Free Pascal :\\ Users' manual} +\docdescription{Users' manual for \fpc, version \fpcversion} +\docversion{1.2} +\date{March 1998} \author{Micha\"el Van Canneyt\\Florian Kl\"ampfl} \maketitle \tableofcontents @@ -60,8 +45,8 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % About this document \section{About this document} -This is the user's manual for \fpk . It describes the installation and use of -the \fpk compiler on the different supported platforms. +This is the user's manual for \fpc . It describes the installation and use of +the \fpc compiler on the different supported platforms. It does not attempt to give an exhaustive list of all supported commands, nor a definition of the Pascal language. Look at the \refref for these things. @@ -81,7 +66,7 @@ The \file{README} files are, in case of conflict with this manual, %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % About the compiler \section{About the compiler} -\fpk is a 32-bit compiler for the i386 processor\footnote{Work is being done +\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: \begin{itemize} \item \dos @@ -90,7 +75,7 @@ on a port to ALPHA Architecture}. Currently, it supports 2 operating systems: and work is in progress to port it to other platforms (notably, \ostwo and \windowsnt). -\fpk is designed to be, as much as possible, source compatible with +\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), but it also enhances these languages with elements like function overloading. And, unlike these ancestors, it supports multiple platforms. @@ -99,9 +84,9 @@ It also differs from them in the sense that you cannot use compiled units from one system for the other. Also, at the time of writing, there is no Integrated Development Environment -(IDE) available for \fpk. This gap will, hopefully, be filled in the future. +(IDE) available for \fpc. This gap will, hopefully, be filled in the future. -\fpk consists of three parts : +\fpc consists of three parts : \begin{enumerate} \item The compiler program itself. \item The Run-Time Library (RTL). @@ -123,11 +108,11 @@ you can obtain more information on the Internet, on the following addresses: on the \linux port of the compiler. It contains also useful mail addresses and links to other places. \item \htmladdnormallink{http://www.brain.uni-freiburg.de/\~klaus/fpk-pas} -{http://www.brain.uni-freiburg.de/~klaus/fpk-pas} is the main \fpk information site. +{http://www.brain.uni-freiburg.de/~klaus/fpc-pas} is the main \fpc information site. It also contains the instructions for inscribing to the \textit{mailing-list}, another useful source of information. \end{itemize} -Both places can be used to download the \fpk distribution, although you can +Both places can be used to download the \fpc distribution, although you can probably find them on other places also. Finally, if you think something should be added to this manual @@ -142,21 +127,21 @@ Let's get on with something useful. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Installing the compiler} +\label{ch:Installation} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Before Installation : Requirements \section{Before Installation : Requirements} % -% - % System requirements +% \subsection{System requirements} The compiler needs at least the following hardware: \begin{enumerate} \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 4 Mb of free memory. Under \dos, if you use DPMI memory management, +\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. \item At least 500 Kb. free disk space. \end{enumerate} @@ -179,12 +164,12 @@ Under \linux you need to have the following programs installed : \item Optionally (but highly recommended) : \gnu \file{make}. For easy recompiling of the compiler and Run-Time Library, this is needed. \end{enumerate} -Other than that, \fpk should run on almost any \linux system. +Other than that, \fpc should run on almost any I386 \linux system. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Installing the compiler. \section{Installing the compiler.} -The installation of \fpk is easy, but is platform-dependent. +The installation of \fpc is easy, but is platform-dependent. We discuss the process for each platform separately. @@ -194,7 +179,7 @@ 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 \fpk. They come as zip +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 installation program \file{INSTALL.EXE}. You must run this program to install the compiler. It allows you to select: @@ -205,8 +190,8 @@ not, do you want Free Vision etc.) \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 \fpk. The installation program doesn't modify the -\file{AUTOEXEC.BAT}, since many people (including the authors of \fpk) +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} @@ -214,8 +199,8 @@ file, like this : \begin{verbatim} CALL C:\PP\SET_PP.BAT \end{verbatim} -(This is assuming that you installed \fpk in the default location.) -In order to run \fpk from any directory on your system, you must extend +(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 @@ -227,11 +212,11 @@ choose, It should look something like this : If you want to use the graphic drivers you must modify the environment variable \var{GO32}. Instructions for doing this can be found -in the documentation of the Graph unit, at the InitGraph procedure. +in the documentation of the Graph unit, at the \var{InitGraph} procedure. \subsubsection{Optional Installation: The coprocessor emulation} For people who have an older CPU type, without math coprocessor (i387) -it is necessary to install a coprocessor emulation, since \fpk uses the +it is necessary to install a coprocessor emulation, since \fpc uses the coprocessor to do all floating point operations. The installation of the coprocessor emulation is handled by the @@ -244,75 +229,79 @@ the \verb|SET_PP.BAT| file, as follows: SET GO32=emu C:\PP\DRIVERS\EMU387 \end{verbatim} - % -% - % Installing under Linux +% \subsection{Installing under Linux} \subsubsection{Mandatory installation steps.} -The \linux distribution of \fpk comes in two flavors: +The \linux distribution of \fpc comes in three forms: \begin{itemize} -\item an \file{aout} version, and -\item an \file{ELF} version. +\item a \file{tar.gz} version, +\item a \file{.rpm} (Red Hat Package Manager) version, and +\item a \file{.deb} (debian) version. \end{itemize} -If you don't know which of these flavors you must use, contact you system -administrator, and he will tell you. When that doesn't get you further, try -the \file{ELF} distribution. \file{aout} systems are outdated, and may not be -supported any more in the future. +All of these packages contain a \var{ELF} version of the compiler binaries and +units. the older \var{aout} binaries are no longer distributed, although you +still can use the comiler on an \var{aout} system if you recompile it. -Both flavors are shipped in \file{tar} archive files. -This means that you should untar them, in some directory where you have -write permission, using the following command: +If you use the \file{.rpm} format, installation is limited to \begin{verbatim} -tar -xvf fpk.tar +rpm -i fpc-pascal-XXX.rpm \end{verbatim} -We supposed here that you downloaded the file \file{fpk.tar} somewhere -from the Internet. +(\var{XXX} is the version number of the \file{.rpm} file) -When the files are untarred, you will be left with more archive files, and -two install programs: an installation shell script, and a X-windows -installation program. Both have the same functionality. -To install \fpk, all that you need to do now is give the following command: +If you use debian, installation is limited to +\begin{verbatim} +??? +\end{verbatim} + +When downloading the \var{.tar} file, installation is more interactive: + +This means that you should first untar the file, in some directory where +you have write permission, using the following command: +\begin{verbatim} +tar -xvf fpc.tar +\end{verbatim} +We supposed here that you downloaded the file \file{fpc.tar} somewhere +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. +To install \fpc, all that you need to do now is give the following command: \begin{verbatim} ./install.sh \end{verbatim} -Or, if you have the XForms libraries, you can start the X-Windows based -program. -\begin{verbatim} -./fpkinstall -\end{verbatim} And then you must answer some questions. They're very simple, they're -concerned with 2 things : +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). \end{enumerate} -If you run the installation program/script as \var{root}, you can just accept all installation +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, as it will attempt to create the directories you specify. In principle, you can install it wherever you want, though. -Whatever the installation program you used, -at the end of installation, the installation program will generate a -configuration file for the \fpk compiler which reflects the settings +At the end of installation, the installation program will generate a +configuration file for the \fpc compiler which reflects the settings that you chose. It will install this file in the \file{/etc} directory, (if -you are not installing as \var{root}, this will fail, and in the +you are not installing as \var{root}, this will fail), and in the directory where you installed the libraries. -If you want the \fpk compiler to use this configuration file, it must be +If you want the \fpc compiler to use this configuration file, it must be present in \file{/etc}, or you can set the environment variable \var{PPC\_CONFIG\_PATH}. Under \file{csh}, you can do this by adding a \begin{verbatim} -setenv PPC_CONFIG_PATH /usr/lib/ppc/0.9.1 +setenv PPC_CONFIG_PATH /usr/lib/ppc/0.99.1 \end{verbatim} 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 \fpk +You may wish to set some environment variables. The \linux version of \fpc recognizes the following variables : \begin{itemize} \item \verb|PPC_EXEC_PATH| contains the directory where '\file{as}' and @@ -329,8 +318,8 @@ built at the end of the installation process, except for the \verb|PPC_CONFIG_PATH| variable, which you must set if you didn't install things in the default places. \subsubsection{finally} -Also distributed in \fpk is a README file. It contains the latest -instructions for installing \fpk, and should always be read first. +Also distributed in \fpc is a README file. It contains the latest +instructions for installing \fpc, and should always be read first. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -339,7 +328,7 @@ instructions for installing \fpk, and should always be read first. After the installation is completed and the environment variables are set as described above, your first program can be compiled. -Included in the \fpk distribution are some demonstration programs, +Included in the \fpc distribution are some demonstration programs, showing what the compiler can do. You can test if the compiler functions correctly by trying to compile these programs. @@ -351,12 +340,9 @@ The compiler is called \end{itemize} To compile a program (e.g \verb|demo\hello.pp|) simply type : \begin{verbatim} - ppc386 -a hello + ppc386 hello \end{verbatim} -at the command prompt. The option -a is needed currently to call -the external assembler. -This needed option will disappear when the the internal assembler works stable. -but at the moment it is a mandatory option. +at the command prompt. 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} @@ -378,6 +364,8 @@ be switched off by setting the \file{GO32} environment variable. % Usage %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Compiler usage} +\label{ch:Usage} + Here we describe the essentials to compile a program and a unit. We also describe how to make a stand-alone executable of the compiled program under \dos. For more advanced uses of the compiler, @@ -417,13 +405,11 @@ anything else. Under \dos, additional processing is required. See the section on creating an executable. -You will notice that there are also other files in your directory, with -extensions \file{.o} and \file{.s}. These contain, respectively, -the assembler sources and the object files for your program. You can -safely delete the assembler file, you don't need it any -more\footnote{One day this will be done automatically.}. 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 +You will notice that there is also anothe 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 remove it. @@ -453,22 +439,16 @@ So don't delete them. If you want to distribute the unit, you must provide both the \file{.ppu} and \file{.o} file. One is useless without the other. -The file containing the assembler (extension \file{.s}) can safely be -deleted. You don't need it anymore. - - %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Creating an executable for GO32V1, PMODE/DJ targets -\section{Creating an executable for GO32V1, PMODE/DJ targets} +\section{Creating an executable for GO32V1 and PMODE/DJ targets} This section applies only to \dos users. \linux users can skip this section (unless they're cross-compiling) - % -% - % GO32V1 +% \subsection{GO32V1} When compiling under \dos, GO32V2 is the default target. However, if you use go32V1 (using the \var{-TDOS} switch), the @@ -507,7 +487,7 @@ command prompt, type : \begin{verbatim} COPY /B GO32.EXE+PROG PROG.EXE \end{verbatim} -(assuming \fpk created a file called \file{PROG}, of course.) +(assuming \fpc created a file called \file{PROG}, of course.) This becomes then a stand-alone executable for \dos, which doesn't need the \file{GO32.EXE} on the machine where it should run. \end{enumerate} @@ -517,7 +497,7 @@ This becomes then a stand-alone executable for \dos, which doesn't need the % PMODE/DJ \subsection{PMODE/DJ} -You can also use the PMODE/DJ extender to run your \fpk applications. +You can also use the PMODE/DJ extender to run your \fpc applications. To make an executable which works with the PMODE extender, you can simply create an GO32V2 executable (the default), and then convert it to a PMODE executable with the following two extra commands: @@ -564,8 +544,7 @@ 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. Under \linux, you can set the \var{-k-s} option, which does -the same. +automatically. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Problems @@ -619,6 +598,8 @@ If you want to use the compiler with \var{DPMI} you must have at least % Configuration. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Compiler configuration} +\label{ch:CompilerConfiguration} + The output of the compiler can be controlled in many ways. This can be done essentially in two distinct ways: \begin{itemize} @@ -642,18 +623,19 @@ isn't under \dos. The available options are listed by category: % +% General options % -% General options \subsection{General options} \begin{description} \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[-i] This option tells the compiler to print the copyright information. \olabel{i} -\item[-l] This option tells the compiler to print the \fpk logo on standard -output. It also gives you the \fpk version number. +\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} @@ -662,24 +644,15 @@ output. It also gives you the \fpk version number. \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} % -% - % Options for getting feedback +% \subsection{Options for getting feedback} \begin{description} -\item[-qxx] This option tells the compiler to print on stdout some -information on what it is doing. xx can be one of the following: -\olabel{q} -\begin{itemize} -\item \textbf{x is empty} : Be quiet. Don't output anything -\item \textbf{-} : Give some information. -\item \textbf{--} : Give a lot of information. -\end{itemize} -This is an obsolete option, and is kept only for backwards -compatibility. It may disappear in the future.\\ \item[-vxxx] Be verbose. \var{xxx} is a combination of the following : \olabel{v} \begin{itemize} @@ -687,6 +660,7 @@ compatibility. It may disappear in the future.\\ \item \var{i} : Tells the compiler to show some general information. \item \var{w} : Tells the compiler to issue warnings. \item \var{n} : Tells the compiler to issue notes. +\item \var{h} : Tells the compiler to issue hints. \item \var{l} : Tells the compiler to show the line numbers as it processes a file. Numbers are shown per 100. \item \var{u} : Tells the compiler to print the names of the files it opens. @@ -698,18 +672,16 @@ functions as it is processing them. 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) +\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. \end{itemize} -\item[-w] When this option is specified, the compiler issues warning. To -turn off warnings, specify \var{-w-}\\ -This option is obsolete. and is kept only for backwards compatibility. It -may disappear in the future. -\olabel{w} \end{description} % -% - % Options concerning files and directories +% \subsection{Options concerning files and directories} \begin{description} \item [-exxx] (\linux only) \file{xxx} specifies the directory where the @@ -722,9 +694,20 @@ the file in \file{xxx}. \item [-Fgxxx] (\linux only) \file{xxx} specifies the path where the compiler can find the \gnu C library. \olabel{Fg} +\item [-Fixxx] adds \var{xxx} to the path where the compiler searches for +its include files. +\olabel{Fi} +\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. \olabel{Fr} +\item [-Fuxxx] Idem as \var{-Up}. +\olabel{Fu} +\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.. \item [-Upxxx] \olabel{Up} Tells the compiler to add \file{xxx} to the path where to find units. \\ By default, the compiler only searches for units in the current directory @@ -736,9 +719,8 @@ compiler also to look in the directory \file{xxx}. \subsection{Options controlling the kind of output.} for more information on these options, see also \progref \begin{description} -\item [-a] \olabel{a} Tells the compiler to generate an assembler source file, and to -call an external assembler (\file{as}) to assemble this file. The file will -not be deleted. +\item [-a] \olabel{a} Tells the compiler not to delete the assembler file. +This also counts for the (possibly) generated batch script. \item [-Axxx] \olabel{A}specifies what kind of assembler should be generated . Here \var{xxx} is one of the following : \begin{itemize} @@ -746,17 +728,23 @@ not be deleted. \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{wasm} : An assembler file for the Microsoft/Borland/Watcom assembler. +\item \textbf{masm} : An assembler file for the Microsoft/Borland/Watcom 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 [-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 [-Ct] \olabel{Ct} generate stack checking code. \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 of the following values : \begin{description} @@ -764,6 +752,7 @@ of the following values : \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 @@ -772,8 +761,13 @@ of the following values : \end{description} The exact effect of these effects can be found in the appendices of 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 [-s] \olabel{s} Tells the compiler not to call the assembler and linker. -You must specify also \var{-a} if you specify this. +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 +executable. \item[-Txxx] \olabel{T}Specifies the target operating system. \var{xxx} can be one of the following: \begin{itemize} @@ -783,13 +777,16 @@ the following: \item \textbf{WIN32} : Windows 32 bit (this is still under development). \item \textbf{GO32V2} : \dos and version 2 of the DJ DELORIE extender. \end{itemize} +\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} can be one of the following: \begin{itemize} -\item \textbf{e} : (\linux only) Create an \file{ELF} executable (default). +% \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 \fpk to another operating system. +you start to port \fpc to another operating system. \item \textbf{s} : (\dos only) Strip the symbols from the executable. \end{itemize} \end{description} @@ -897,18 +894,18 @@ In short, the \var{\#define} keywords act as conditionals. \chapter{Porting Turbo Pascal Code} -\fpk was designed to resemble Turbo Pascal as closely as possible. There -are, of course, restrictions. Some of these are due to the fact that \fpk is -a 32-bit compiler. Other restrictions result from the fact that \fpk works +\fpc was designed to resemble Turbo Pascal as closely as possible. There +are, of course, restrictions. Some of these are due to the fact that \fpc is +a 32-bit compiler. Other restrictions result from the fact that \fpc works 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 -\fpk. To a large extent, the constructs defined by Turbo Pascal are +\fpc. To a large extent, the constructs defined by Turbo Pascal are supported. In the following sections we will list the Turbo Pascal constructs which are -not supported in \fpk, and we will list in what ways \fpk extends the Turbo +not supported in \fpc, and we will list in what ways \fpc extends the Turbo Pascal language. @@ -916,11 +913,11 @@ Pascal language. % Things that will not work \section{Things that will not work} Here we give a list of things which are defined/allowed in Turbo Pascal, but -which are not supported by \fpk. Where possible, we indicate the reason. +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 -\fpk. (however, \seeo{So}) +\fpc. (however, \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 @@ -930,15 +927,15 @@ access are not available. This is due to the operating system. Under 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. \item The reserved words \var{FAR, NEAR} are ignored. This is -because \fpk is a 32 bit compiler, so they're obsolete. +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 \fpk is \var{AT\&T} -assembler syntax. This is mainly because \fpk uses \gnu \var{as}. +\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 Turbo Vision is not available. \item The 'overlay' unit is not available. It also isn't necessary, since -\fpk is a 32 bit compiler, so program size shouldn't be a point. +\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. @@ -951,7 +948,7 @@ list of all reserved words.) %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Things which are extra \section{Things which are extra} -Here we give a list of things which are possible in \fpk, but which +Here we give a list of things which are possible in \fpc, but which didn't exist in Turbo Pascal or Delphi. \begin{enumerate} \item There are more reserved words. (see appendix \ref{ch:reserved} for a @@ -999,7 +996,7 @@ begin end; end; \end{verbatim} -\item \fpk supports function overloading. That is, you can define many +\item \fpc supports function overloading. That is, you can define many functions with the same name, but with different arguments. For example: \begin{verbatim} procedure DoSomething (a : longint); @@ -1045,12 +1042,12 @@ When you compile a program with the \var{-So} switch, the compiler will attempt to mimic the Turbo Pascal compiler in the following ways: \begin{itemize} \item Assigning a procedural variable doesn't require a @ operator. One of -the differences between Turbo Pascal and \fpk is that the latter requires +the differences between Turbo Pascal and \fpc is that the latter requires you to specify an address operator when assigning a value to a procedural variable. In Turbo Pascal compatibility mode, this is not required. \item Procedure overloading is disabled. \item Forward defined procedures don't need the full parameter list when -they are defined. Due to the procedure overloading feature of \fpk, you must +they are defined. Due to the procedure overloading feature of \fpc, you must always specify the parameter list of a function when you define it, even when it was declared earlier with \var{Forward}. In Turbo Pascal compatibility mode, there is no function overloading, hence you can omit the @@ -1080,8 +1077,8 @@ begin end; \end{verbatim} In Turbo Pascal compatibility mode, the function will be called recursively -when the \var{writeln} statement is processed. In \fpk, the function result -will be printed. In order to call the function recusively under \fpk, you +when the \var{writeln} statement is processed. In \fpc, the function result +will be printed. In order to call the function recusively under \fpc, you need to implement it as follows : \begin{verbatim} Function expr : Longint; @@ -1105,7 +1102,7 @@ this text is processed too. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Utilities and units that come with Free Pascal} -Besides the compiler and the Run-Time Library, \fpk comes with some utility +Besides the compiler and the Run-Time Library, \fpc comes with some utility programs and units. Here we list these programs and units. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1113,7 +1110,7 @@ programs and units. Here we list these programs and units. \section{Supplied programs} \begin{itemize} -\item \file{dumppu} is a program which shows the contents of a \fpk unit. It +\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 \begin{verbatim} @@ -1122,7 +1119,7 @@ compiled, you can just issue the following command to display the contents of the \file{foo.ppu} unit. \item Also distributed with Free Pascal comes a series of demonstration programs. These programs have no other purpose than demonstrating the capabilities of -\fpk. They are located in the \file{demo} directory of the sources. +\fpc. They are located in the \file{demo} directory of the sources. \item All example programs of the documentation are available. Check out the directories that end on \file{ex} in the documentation sources. There you wll find all example sources. @@ -1132,7 +1129,7 @@ wll find all example sources. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Supplied units \section{Supplied units} -Here we list the units that come with the \fpk distribution. Since there is +Here we list the units that come with the \fpc distribution. Since there is a difference in the supplied units per operating system, we list them separately per system. @@ -1204,12 +1201,14 @@ It also supports long options. \chapter{Debugging your Programs} -\fpk supports debug information for the \gnu debugger \var{gdb}. +\fpc supports debug information for the \gnu debugger \var{gdb}. This chapter describes shortly how to use this feature. It doesn't attempt to describe completely the \gnu debugger, however. For more information on the workings of the \gnu debugger, see the \var{gdb} users' guide. +\fpc also suports \var{gprof}, the \gnu profiler, see section \ref{se:gprof} +for more information on profiling. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Compiling your program with debugger support @@ -1307,11 +1306,39 @@ read or written. for more information, see the \var{gdb} users' guide, or use the \var{'help'} function in \var{gdb}. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Using gprof +\section{Support for \var{gprof}, the \gnu profiler} +\label{se:gprof} + +You can compile your programs with profiling support. for this, you just +have to use the compiler switch \var{-pg}. The compiler wil insert the +necessary stuff for profiling. + +When you have done this, you can run your program uder the gnu profiler, +\var{gprof}, as follows : +\begin{verbatim} +gprog yourexe +\end{verbatim} +Where \file{yourexe} is the name of your executable. + +You may want to capture the outpus of the profiler in a file, since it can +be quite a lot, as follows: +\begin{verbatim} +gprog yourexe >gprof.out +\end{verbatim} + +For more information on the \gnu profiler \var{gprof}, see its manual. + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % CGI. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{CGI programming in Free Pascal} +\label{ch:CGIProgramming} + In these days of heavy WWW traffic on the Internet, CGI scripts have become an important topic in computer programming. While CGI programming can be done with almost any tool you wish, most languages aren't designed for it. @@ -1325,7 +1352,7 @@ complex programming. The basic RTL routines in principle are enough to get the job done, but you can create, with relatively little effort, some units which can be used as a base for more complex CGI programming. -That's why, in this chapter, we will discuss the basics of CGI in \fpk. +That's why, in this chapter, we will discuss the basics of CGI in \fpc. In the subsequent, we will assume that the server for which the programs are created, are based upon the NCSA \var{httpd} WWW server, as the examples will be based upon the NCSA method of CGI programming\footnote{... and it's @@ -1453,10 +1480,10 @@ this may be needed. If your form uses the \var{GET} method of passing it's data, the CGI script needs to read the \var{QUERY\_STRING} environment variable to get it's data. Since this variable can, and probably will, be more than 255 characters long, -you will not be able to use normal string methods, present in pascal. \fpk +you will not be able to use normal string methods, present in pascal. \fpc implements the \var{pchar} type, which is a pointer to a null-terminated array of characters. -And, fortunately, \fpk has a +And, fortunately, \fpc has a \seestrings\ unit, which eases the use of the \var{pchar} type. @@ -1547,13 +1574,13 @@ You may have noticed the following unorthodox call : \begin{verbatim} inc(longint(p)); \end{verbatim} -\fpk doesn't give you pointer arithmetic as in C. However, \var{longints} and +\fpc doesn't give you pointer arithmetic as in C. However, \var{longints} and \var{pointers} have the same length (namely 4 bytes). Doing a type-cast to a \var{longint} allows you to do arithmetic on the \var{pointer}. Note however, that this is a non-portable call. This may work on the I386 processor, but not on a ALPHA processor (where a pointer is 8 bytes long). -This will be remedied in future releases of \fpk. +This will be remedied in future releases of \fpc. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1581,7 +1608,7 @@ And that's all there is to it ! % I'm under Windows, what now ? \section{I'm under Windows, what now ?} Under Windows the system of writing CGI scripts is totally different. If you -use \fpk under Windows then you also should be able to do CGI programming, +use \fpc under Windows then you also should be able to do CGI programming, but the above instructions will not work. If some kind soul is willing to write a section on CGI programming under @@ -1597,105 +1624,103 @@ Windows, I'd be willing to include it here. The following is alphabetical listing of all command-line options, as generated by the compiler: \begin{verbatim} -PPC386 [options] [options] - + switch option on, - off - with * marked options have no effect - with ! marked options are only partial implemented - -a the compiler doesn't delete the generated assembler file - -B build ++ switch option on, - off + -a the compiler doesn''t delete the generated assembler file + -B+ build -C code generation options - * -Ca - * -Ce - - -Chxxxx xxxx bytes heap - (must be less than 67107840 und greater than 1023 - -Ci IO-checking - -Co check overflow of integer operations - -Cr range checking - -Csxxxx stack size (only OS/2) - - -dxxx defines the symbol xxx - -D controlls the generation of DEF file (only OS/2) - -Ddxxxx xxxx is the description - -Do generate DEF file - -Dw PM application - -exxxx xxxx path to executables (only LINUX) - -g generate debugger informations - -F set file names and pathes - -Fexxxx redirect error output to xxxx - -Fgxxxx xxxxx search path for the GNU C lib (LINUX only) - -Frxxxx xxxxx search path for the error message file (only LINUX) + -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 + -d defines the symbol + -e set path to executables + -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 + -LD german + -LE english -l write logo -i information - -Ixxx adds xxx to include path -n don't read the default config file - -oxxx change the name of the executable produced to xxx - -q- write information when compiling (obsolete, see -v) + -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 - -Sa semantic check of expressions - a higher level includes the lower - -Sa0 only ANSI pascal expressions are allowed - -Sa1 functions results havn't to be assigned to variables - -Sa2 @-operator returns typed pointer - -Sa4 assigment results are typed (allows a:=b:=0) - -Sa9 allows expressions with no side effect - -Sc supports operators like C (*=,+=,/= and -=) - -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 the name of constructors must be init - the name of destructors must be done - -St allows static keyword in objects + -S2 switch some Delphi 2 extension on + -Sa semantic check of expressions (higher level includes lower) + -Sa4 assigment results are typed (allows a:=b:=0) + -Sa9 allows expressions with no side effect + -Sc supports operators like C (*=,+=,/= and -=) + -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 -s don't call assembler and linker (only with -a) - -T target operating system - -TDOS DOS extender by DJ Delorie - -TOS2 OS/2 2.x - -TLINUX Linux - ! -TWin32 Windows 32 Bit - -TGO32V2 version 2 of DJ Delorie DOS extender - -uxxx undefines the symbol xxx + -T Target operating system + -TDOS DOS extender by DJ Delorie + -TOS2 OS/2 2.x + -TLINUX Linux + -TWin32 Windows 32 Bit + -TGO32V2 version 2 of DJ Delorie DOS extender + -u undefines the symbol -U unit options - -Un don't check the unit name - -Us compile a system unit - -Upxxxx adds xxxx to the unit path - -vxxx Be verbose. xxx is a combination of the following letters : - e : Show errors (default) i : Show general info - w : Show warnings l : Show linenumbers - u : Show used files t : Show tried files - p : Show compiled procedures c : Show conditionals - d : Show debug info m : Show defined macros - -w- turns warnings off (Obsolete, see -v) + -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 + -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 + n : Show notes t : Show tried files + h : Show hints m : Show defined macros + i : Show general info p : Show compiled procedures + l : Show linenumbers c : Show conditionals + a : Show everything 0 : Show nothing (except errors) -X executable options - -Xc link with the c library - -Xe create ELF executable + -Xc link with the c library + -Xs strip all symbols from executable 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 + -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 -R assembler reading style - -Ratt read AT&T style assembler - -Rintel read Intel style assembler - -Rdirect copy assembler text directly to assembler file + -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 - -O2 optimize for Pentium II (tm) - -O3 optimize for i386 - -O4 optimize for i486 - -O5 optimize for Pentium (tm) - -O6 optimizations for PentiumPro (tm) - -h,-? shows this help + -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) + \end{verbatim} @@ -1802,6 +1827,14 @@ xor %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Compiler error messages} +\label{ch:ErrorMessages} +This appendix is meant to list all the compiler errors. the list of compiler +errors is fairly complete, the assembler errors are less complete. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Compiler errors. +\section{Compiler errors} +The following is a list of general compiler errors. \begin{description} \item [unexpected end of file] this typically happens in on of the following cases : @@ -1817,6 +1850,9 @@ The identifier was already declared in the current scope. \item [syntax error:] An error against the Turbo Pascal language was encountered. This happens typically when an illegal character is found in the sources file. +\item [Parser - syntax error] +An error against the Turbo Pascal language was encountered. This happens +typically when an illegal character is found in the sources file. \item [out of memory] The compiler doesn't have enough memory to compile your program. There are several remedies for this: @@ -1835,21 +1871,21 @@ scope where it's defined. An illegal character was encountered in the input file. \item [source too long] The compiler cannot cope with source files longer than (???) -\item [INLINE not supported (use option -Si for C++ styled inlining)] +\item [procedure type INLINE not supported] You tried to compile a program with C++ style inlining, and forgot to specify the \var{-Si} option (\seeo{Si}). The compiler doesn't support C++ styled inlining by default. -\item [NEAR ignored] +\item [procedure type NEAR ignored] This is a warning. \var{NEAR} is a construct for 8 or 16 bit programs. Since the compile generates 32 bit programs, it ignores this directive. -\item [FAR ignored] +\item [procedure type FAR ignored] This is a warning. \var{FAR} is a construct for 8 or 16 bit programs. Since the compile generates 32 bit programs, it ignores this directive. \item [INTERRUPT ignored] Interrupt procedures aren't possible on operating systems, other than DOS, it isn't allowed to take over an interrupt at the user level. (versions older than 0.9.2 didn't have \var{INTERRUPT} support. -\item [private methods can't be VIRTUAL] +\item [private methods shouldn't be VIRTUAL] You declared a method in the private part of a object (class) as \var{virtual}. This is not allowed. Private methods cannot be overridden anyway. @@ -1878,19 +1914,16 @@ incompatible with the parameters in the function or procedure definition. \item [statement expected] \item [illegal integer constant] - +You made an exression which isn't an integer, and the compiler expects the +result to be an integer. \item [illegal expression] \item [expression too complicated - FPU stack overflow] Your expression is too long for the compiler. You should try dividing the construct over multiple assignments. -\item [CONTINUE not possible] +\item [CONTINUE not allowed] You're trying to use \var{continue} outside a loop construction. -\item [BREAK not possible] +\item [BREAK not allowed] You're trying to use \var{break} outside a loop construction. -\item [exception handling needed to compile this (command line -Se)] -Older (less than 0.6.6) versions of \fpk only. Your statement needs exception handling. -Exception handling isn't supported by default in the compiler. -Use the \var{-Se} option to turn on exception handling.% (\seeo{Se}) \item [illegal qualifier] One of the following is appending : \begin{itemize} @@ -1898,30 +1931,36 @@ One of the following is appending : \item You're indexing a variable that is not an array. \item You're dereferencing a variable that is not a pointer. \end{itemize} -\item [illegal count variable] The type of a \var{for} loop must be ordinal. - -\item [ordinal type expected] +\item [illegal counter variable] +The type of a \var{for} loop must be ordinal. +\item [ordinal value expected] The expression must be of ordinal type (i.e. maximum a Longint) \item [high range limit < low range limit] You are declaring a subrange, and the lower limit is higher than the high limit of the range. -\item [illegal unit identifier] +\item [illegal unit name] The name of the unit doesn't match the file name. \item [unknown format of unit file] The unit the compiler is trying to read is corrupted, or generated with a newer version of the compiler. -\item [error when reading unit] +\item [Reading PPU-File] +The unit the compiler is trying to read is corrupted, or generated with a +newer version of the compiler. +\item [Invalid PPU-File entry] The unit the compiler is trying to read is corrupted, or generated with a newer version of the compiler. \item [circular unit use] Two units are using each other in the interface part. This is only allowed in the implementation part. \item [too many units] -\fpk has a limit of 1024 units in a program. You can change this behavior +\fpc has a limit of 1024 units in a program. You can change this behavior by changing the \var{maxunits} constant in the \file{files.pas} file of the compiler, and recompiling the compiler. \item [illegal char constant] +The compiler expects a character constant, but finds something else. \item [overloaded identifier isn't a function identifier] +The compiler encountered a symbol with the same name a s an overloaded +function, but it isn't a function it can overload. \item [overloaded functions have the same parameter list] You're declaring overloaded functions, but with the same parameter list. Overloaded function must have at least 1 different parameter in their @@ -1934,8 +1973,6 @@ You're calling overloaded functions with a parameter that doesn't correspond to any of the declared function parameter lists. e.g. when you have declared a function with parameters \var{word} and \var{longint}, and then you call it with a parameter which is of type \var{integer}. -\item [exception handling not used, however needed by function] -This message is no longer used. \item [forward declaration not solved:] This can happen in two cases: \begin{itemize} @@ -1945,7 +1982,7 @@ with a \var{forward} directive, but do not implement it. block. \end{itemize} \item [input file not found] -\fpk cannot find the program or unit source file, or the included file isn't +\fpc cannot find the program or unit source file, or the included file isn't found. \item [function header doesn't match the forward declaration] You declared the function in the \var{interface} part, or with the @@ -1965,10 +2002,8 @@ You want to include (i.e \var{\{\$i file\}}) which the compiler doesn't find. Check if the filename is correct. \item [record or class type expected] The variable or expression isn't of the type \var{record} or \var{class}. -\item [not found:] -An unknown symbol was encountered. \item [only values can be jumped over in enumeration types] -\fpk allows enumeration constructions as in C. Given the following +\fpc allows enumeration constructions as in C. Given the following declaration two declarations: \begin{verbatim} type a = (A_A,A_B,A_E=:6,A_UAS:=200); @@ -1985,7 +2020,7 @@ you're compiling now. (see the option \var{-T} \seeo{T}). You cannot declare a constant of type class or object. \item [duplicate case label] You are specifying the same label 2 times in a \var{case} statement. -\item [range check error while Eva luting constants] +\item [range check error while evaluating constants] The constants are out of their allowed range. \item [illegal type conversion] When doing a type-cast, you must take care that the sizes of the variable and @@ -1995,7 +2030,7 @@ The variable of expression isn't of the type \var{class}. \item [functions variables of overloaded functions are not allowed] You are trying to assign an overloaded function to a procedural variable. This isn't allowed. -\item [can't open assembler output file] +\item [can't create assembler file] The assembler output file cannot be opened. This can have many causes, but 'disk full' is a reasonable guess. \item [string length must be a value from 1 to 255] @@ -2017,10 +2052,11 @@ constructor of the class. \item [file types must be var parameters] You cannot specify files as value parameters, i.e. they must always be declared \var{var} parameters. -\item [string constant exceeds line end] -You forgot probably to include the closing ' in a string. +\item [string exceeds line] +You forgot probably to include the closing ' in a string, so it occupies +multiple lines. \item [illegal version of the unit:] -This unit was compiled with an earlier version of \fpk. +This unit was compiled with an earlier version of \fpc. \item [illegal floating point constant] \item [destructors can't have parameters] You are declaring a destructor with a parameter list. Destructor methods @@ -2048,7 +2084,7 @@ If you declare overloaded virtual methods in a class, then they should either all support exceptions, or none. You cannot mix them. \item [EXPORT declared functions can't be called] You are trying to call a procedure you declared as \var{export}. Due to the -different calling scheme of \fpk and C, you cannot call such a function from +different calling scheme of \fpc and C, you cannot call such a function from within your Pascal program. \item [EXPORT declared functions can't be nested] You cannot declare a function or procedure within a function or procedure @@ -2056,14 +2092,13 @@ that was declared as an export procedure. \item [methods can't be EXPORTed] You cannot declare a procedure that is a method for an object as \var{export}ed. That is, you methods cannot be called from a C program. -\item [SELF is allowed in methods only] +\item [SELF is only allowed in methods] You are trying to use the \var{self} parameter outside an object's method. Only methods get passed the \var{self} parameters. \item [call by var parameters have to match exactly] When calling a function declared with \var{var} parameters, the variables in the function call must be of exactly the same type. There is no automatic type conversion. -\item [type identifiers are not allowed in this context] \item [class identifier expected] The variable isn't of type \var{class}. \item [class isn't a super class of the current class] @@ -2071,9 +2106,6 @@ When calling inherited methods, you are trying to call a method of a strange class. You can only call an inherited method of a parent class. \item [methods can be only in other methods called direct with type identifier of the class] A construction like \var{sometype.somemethod} is only allowed in a method. -\item [illegal INHERITED: class has no super class] -You specified an \var{INHERITED} keyword in a method of a class which has no -parent class, i.e. which isn't derived from another class. \item [illegal type: pointer to class expected] You specified an illegal type. \item [possible illegal call of constructor or destructor (doesn't match to this context)] @@ -2091,9 +2123,9 @@ does not exist. When using the extended syntax of \var{dispose}, you must specify the destructor method of the class you are trying to dispose of. The procedure you specified is not a destructor. - -\item [assembler: illegal constant] -\item [illegal type declaration of set elements] +\item [type conflict between set elements] +There is at least one set element which is of the wrong type, i.e. not of +the set type. \item [illegal expression in set constructor] \item [type conflict between set elements] You are specifying elements of a different type for a set. @@ -2101,7 +2133,7 @@ You are specifying elements of a different type for a set. \item [expression type must be class or record type] The expression isn't of type class or record. \item [the operator / isn't defined for integer, the result will be real, use DIV instead] -When using the '/' operator in \fpk the result will be of type real, when +When using the '/' operator in \fpc the result will be of type real, when used with integers. \item [can't write PPU file] There is a problem when writing to the unit file. @@ -2141,7 +2173,7 @@ An error occurred when assembling. This can have many causes. This is a warning. The identifier was declared (locally or globally) but wasn't used (locally or globally). \item [functions with void return value can't return any value] -In \fpk, you can specify a return value for a function when using +In \fpc, you can specify a return value for a function when using the \var{exit} statement. This error occurs when you try to do this with a procedure. Procedures cannot return a value. \item [Hmmm..., this code can't be much efficient] @@ -2160,7 +2192,7 @@ but there is no corresponding declaration in the interface part of the unit. \item [It's not possible to overload this operator] You are trying to overload an operator which cannot be overloaded. \item [Abstract methods can't be called direct] -\fpk understands the \var{abstract} keyword. +\fpc understands the \var{abstract} keyword. \item [the mix of CLASSES and OBJECTS are not allowed] You cannot use \var{object} and \var{class} intertwined. \item [macro buffer overflow while reading or expanding a macro] @@ -2221,7 +2253,7 @@ raise exceptions in an \var{except} block. \end{description} \chapter{Run time errors} -The \fpk Run-tim library generates the following errors at run-time +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} @@ -2309,7 +2341,7 @@ 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 \fpk provides a growing heap, i.e. the heap will +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. @@ -2340,4 +2372,346 @@ 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.} + +This section lists the errors that are generated by the inline assembler reader. +They are {\em not} the messages of the assembler itself. + +% General assembler errors. +\subsection{General assembler errors} +\begin{description} +\item [Divide by zero in asm evaluator] +This fatal error is reported when a constant assembler expressions +does a division by zero. + +\item [Evaluator stack overflow, Evaluator stack underflow] +These fatal errors are reported when a constant assembler expression +is too big to evaluate by the constant parser. Try reducing the +number of terms. + +\item [Invalid numeric format in asm evaluator] +This fatal error is reported when a non-numeric value is detected +by the constant parser. Normally this error should never occur. + +\item [Invalid Operator in asm evaluator] +This fatal error is reported when a mathematical operator is detected +by the constant parser. Normally this error should never occur. + +\item [Unknown error in asm evaluator] +This fatal error is reported when an internal error is detected +by the constant parser. Normally this error should never occur. + +\item [Invalid numeric value] +This warning is emitted when a conversion from octal,binary or hexadecimal +to decimal is outside of the supported range. + +\item [Escape sequence ignored] +This error is emitted when a non ANSI C escape sequence is detected in +a C string. + +\item [Asm syntax error - Prefix not found] +This occurs when trying to use a non-valid prefix instruction + +\item [Asm syntax error - Trying to add more than one prefix] +This occurs when you try to add more than one prefix instruction + +\item [Asm syntax error - Opcode not found] +You have tried to use an unsupported or unknown opcode + +\item [Constant value out of bounds] +This error is reported when the constant parser determines that the +value you are using is out of bounds, either with the opcode or with +the constant declaration used. + +\item [Non-label pattern contains @] +This only applied to the m68k and Intel styled assembler, this is reported +when you try to use a non-label identifier with a '@' prefix. +\item [Internal error in Findtype()] +\item [Internal Error in ConcatOpcode()] +\item [Internal Errror converting binary] +\item [Internal Errror converting hexadecimal] +\item [Internal Errror converting octal] +\item [Internal Error in BuildScaling()] +\item [Internal Error in BuildConstant()] +\item [internal error in BuildReference()] +\item [internal error in HandleExtend()] +\item [Internal error in ConcatLabeledInstr()] +\label{InternalError} +These errors should never occur, if they do then you have found +a new bug in the assembler parsers. Please contact one of the +developers. +\item [Opcode not in table, operands not checked] +This warning only occurs when compiling the system unit, or related +files. No checking is performed on the operands of the opcodes. + +\item [@CODE and @DATA not supported] +This Turbo Pascal construct is not supported. +\item [SEG and OFFSET not supported] +This Turbo Pascal construct is not supported. +\item [Modulo not supported] +Modulo constant operation is not supported. +\item [Floating point binary representation ignored] +\item [Floating point hexadecimal representation ignored] +\item [Floating point octal representation ignored] +These warnings occur when a floating point constant are declared in +a base other then decimal. No conversion can be done on these formats. +You should use a decimal representation instead. +\item [Identifier supposed external] +This warning occurs when a symbol is not found in the symolb table, it +is therefore considered external. +\item [Functions with void return value can't return any value in asm code] +Only routines with a return value can have a return value set. + +\item [Error in binary constant] +\item [Error in octal constant] +\item [Error in hexadecimal constant] +\item [Error in integer constant] +\label{ErrorConst} +These errors are reported when you tried using an invalid constant expression, +or that the value is out of range. + +\item [Invalid labeled opcode] +\item [Asm syntax error - error in reference] +\item [Invalid Opcode] +\item [Invalid combination of opcode and operands] +\item [Invalid size in reference] +\item [Invalid middle sized operand] +\item [Invalid three operand opcode] +\item [Assembler syntax error] +\item [Invalid operand type] +You tried using an invalid combination of opcode and operands, check the syntax +and if you are sure it is correct, please contact one of the developers. + +\item [Unknown identifier] +The identifier you are trying to access does not exist, or is not within the +current scope. + +\item [Trying to define an index register more than once] +\item [Trying to define a segment register twice] +\item [Trying to define a base register twice] +You are trying to define an index/segment register more then once. + +\item [Invalid field specifier] +The record or object field you are trying to access does not exist, or +is incorrect. + +\item [Invalid scaling factor] +\item [Invalid scaling value] +\item [Scaling value only allowed with index] +Allowed scaling values are 1,2,4 or 8. + + +\item [Cannot use SELF outside a method] +You are trying to access the SELF identifier for objects outside a method. + + +\item [Invalid combination of prefix and opcode] +This opcode cannot be prefixed by this instruction + +\item [Invalid combination of override and opcode] +This opcode cannot be overriden by this combination + +\item [Too many operands on line] +At most three operand instructions exist on the m68k, and i386, you +are probably trying to use an invalid syntax for this opcode. + +\item [Duplicate local symbol] +You are trying to redefine a local symbol, such as a local label. + +\item [Unknown label identifer] +\item [Undefined local symbol] +\item [local symbol not found inside asm statement] +This label does not seem to have been defined in the current scope + + +\item [Assemble node syntax error] +\item [Not a directive or local symbol] +The assembler statement is invalid, or you are not using a recognized +directive. + +\end{description} + +% I386 specific errors +\subsection{I386 specific errors} + +\begin{description} +\item [repeat prefix and a segment override on <= i386 may result in errors if an interrupt occurs] +A problem with interrupts and a prefix instruction may occur and may cause +false results on 386 and earlier computers. + +\item [Fwait can cause emulation problems with emu387] +This warning is reported when using the FWAIT instruction, it can +cause emulation problems on systems which use the em387.dxe emulator. + +\item [You need GNU as version >= 2.81 to compile this MMX code] +MMX assembler code can only be compiled using GAS v2.8.1 or later. + +\item [NEAR ignored] +\item [FAR ignored] +\label{FarIgnored} +\var{NEAR} and \var{FAR} are ignored in the intel assemblers, but are still accepted +for compatiblity with the 16-bit code model. + +\item [Invalid size for MOVSX/MOVZX] + +\item [16-bit base in 32-bit segment] +\item [16-bit index in 32-bit segment] +16-bit addressing is not supported, you must use 32-bit addressing. + + +\item [Constant reference not allowed] +It is not allowed to try to address a constant memory address in protected +mode. + +\item [Segment overrides not supported] +Intel style (eg: rep ds stosb) segment overrides are not support by +the assembler parser. + +\item [Expressions of the form [sreg:reg...] are currently not supported] +To access a memory operand in a different segment, you should use the +sreg:[reg...] snytax instead of [sreg:reg...] + +\item [Size suffix and destination register do not match] +In intel AT\&T syntax, you are using a register size which does +not concord with the operand size specified. + +\item [Invalid assembler syntax. No ref with brackets] +\item [ Trying to use a negative index register ] +\item [ Local symbols not allowed as references ] +\item [ Invalid operand in bracket expression ] +\item [ Invalid symbol name: ] +\item [ Invalid Reference syntax ] +\item [ Invalid string as opcode operand: ] +\item [ Null label references are not allowed ] +\item [ Using a defined name as a local label ] +\item [ Invalid constant symbol ] +\item [ Invalid constant expression ] +\item [ / at beginning of line not allowed ] +\item [ NOR not supported ] +\item [ Invalid floating point register name ] +\item [ Invalid floating point constant: ] +\item [ Asm syntax error - Should start with bracket ] +\item [ Asm syntax error - register: ] +\item [ Asm syntax error - in opcode operand ] +\item [ Invalid String expression ] +\item [ Constant expression out of bounds ] +\item [ Invalid or missing opcode ] +\item [ Invalid real constant expression ] +\item [ Parenthesis are not allowed ] +\item [ Invalid Reference ] +\item [ Cannot use \_\_SELF outside a method ] +\item [ Cannot use \_\_OLDEBP outside a nested procedure ] +\item [ Invalid segment override expression ] +\item [ Strings not allowed as constants ] +\item [ Switching sections is not allowed in an assembler block ] +\item [ Invalid global definition ] +\item [ Line separator expected ] +\item [ Invalid local common definition ] +\item [ Invalid global common definition ] +\item [ assembler code not returned to text ] +\item [ invalid opcode size ] +\item [ Invalid character: < ] +\item [ Invalid character: > ] +\item [ Unsupported opcode ] +\item [ Invalid suffix for intel assembler ] +\item [ Extended not supported in this mode ] +\item [ Comp not supported in this mode ] +\item [ Invalid Operand: ] +\item [ Override operator not supported ] +\end{description} + +% m68k specific errors +\subsection{m68k specific errors.} +\begin{description} +\item [Increment and Decrement mode not allowed together] +You are trying to use dec/inc mode together. + +\item [Invalid Register list in movem/fmovem] +The register list is invalid, normally a range of registers should +be separated by - and individual registers should be separated by +a slash. +\item [Invalid Register list for opcode] +\item [68020+ mode required to assemble] +\end{description} + + +\chapter{The Floating Point Coprocessor emulator} + +In this appendix we note some caveats when using the floating point +emulator on GO32V2 systems. Under GO32V1 systems, all is as described in +the installation section. + +{\em Q: I don't have an 80387. How do I compile and run floating point + programs under GO32V2? + + Q: What shall I install on a target machine which lacks hardware + floating-point support? +} + +{\em A :} + Programs which use floating point computations and could be run on + machines without an 80387 should be allowed to dynamically load the +\file{emu387.dxe} + file at run-time if needed. To do this you must link the \var{emu387} unit to your + exectuable program, for example: + +\begin{verbatim} + Program MyFloat; + + Uses emu387; + + var + r: real; + Begin + r:=1.0; + WriteLn(r); + end. +\end{verbatim} + + \var{Emu387} takes care of loading the dynamic emulation point library. + + You should always add emulation when you distribute floating-point + programs. + + A few users reported that the emulation won't work for them unless + they explicitly tell \var{DJGPP} there is no \var{x87} hardware, like this: + +\begin{verbatim} + set 387=N + set emu387=c:/djgpp/bin/emu387.dxe +\end{verbatim} + + There is an alternative FP emulator called WMEMU. It mimics a real + coprocessor more closely. + + {\em WARNING:} We strongly suggest that you use WMEMU as FPU emulator, since + \file{emu387.dxe} does not emulate all the instructions which are used by the + Run-Time Libary such as \var{FWAIT}. + + +{\em Q: I have an 80387 emulator installed in my AUTOEXEC.BAT, but + DJGPP-compiled floating point programs still doesn't work. Why? +} + + +{\em A :} DJGPP switches the CPU to protected mode, and the information + needed to emulate the 80387 is different. Not to mention that the + exceptions never get to the real-mode handler. You must use emulators + which are designed for DJGPP. Apart of emu387 and WMEMU, the only + other emulator known to work with DJGPP is Q87 from QuickWare. Q87 is + shareware and is available from the QuickWare Web site. + + +{\em Q: I run DJGPP in an \ostwo DOS box, and I'm told that \ostwo will install + its own emulator library if the CPU has no FPU, and will transparently + execute FPU instructions. So why won't DJGPP run floating-point code + under \ostwo on my machine? +} + +{\em A} : \ostwo installs an emulator for native \ostwo images, but does not + provide FPU emulation for DOS sessions. + \end{document}