+ Updated compiler options

docs/user.tex

@@ -888,7 +888,8 @@ following:
 \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 [-n] Tells the compiler not to read the configuration file.
+\item [-n] Tells the compiler not to read default the configuration file.
+You can still pass a configuration file with the \var{@} option.
 \olabel{n}
 \end{description}
 
@@ -942,18 +943,12 @@ compiler).
 \item [-Fexxx] This option tells the compiler to write errors, etc. to
 the file in \file{xxx}.
 \olabel{Fe}
-\item [-Fgxxx] (\linux only, obsolete) \file{xxx} specifies the path where the compiler
-can find the \gnu C library. This is superseded by the \var{-Fl} option.
-\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[-FLxxx] (\linux only) Tells the compiler to use \file{xxx} as the
 dynamic linker. Default this is \file{/lib/ld-linux.so.2}, or
-\file{lib/ld-linux.so.1}, depending on which one is found.
+\file{lib/ld-linux.so.1}, depending on which one is found first.
 \olabel{FL}
 \item[-Foxxx] Adds \file{xxx} to the object file path. This path is used
 when looking for files that need to be linked in.
@@ -962,52 +957,73 @@ when looking for files that need to be linked in.
 messages. Default the compiler ahs built-in messages. Specifying this option
 will override the default messages.
 \olabel{Fr}
-\item [-Fuxxx] Idem as \var{-Up}: Add \file{xxx} to the object path.
+\item [-Fuxxx] Add \file{xxx} to the unit path. Units are loaded from the
+current directory if they exist, and then in the unit path. You must {\em
+always} supply the unit path to the system unit.
 \olabel{Fu}
 \item [-FUxxx] Tells the compiler to write units in directory \var{xxx}
 instead of the current directory.
 \item [-Ixxx] \olabel{I} Add \file{xxx} to the include file search path.
-This path is used when looking for include files.
+This path is used when looking for include files. This option is obsolite,
+use \var{-Fi} instead.
 \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
-and the directory where the compiler itself resides. This option tells the
-compiler also to look in the directory \file{xxx}.
+\file{as}) that support piping...
 \end{description}
 
 % Options controlling the kind of output.
 \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 not to delete the assembler file.
+\item [-a] \olabel{a} Tells the compiler not to delete the assembler files
+it generates (not when using the internal assembler).
 This also counts for the (possibly) generated batch script.
 \item [-al] \olabel{al} Tells the compiler to include the sourcecode lines
 in the assembler file as comments. This feature is still experimental, and
 should be used with caution.
-\item [-Axxx] \olabel{A}specifies what kind of assembler should be generated . Here
+\item[-ar] \olabel{ar} tells the compiler to list register allocation and 
+release info in the assembler file. This is primarily intended for debugging
+the code generated bythe compiler.
+\item[-at] \olabel{at} tells the compiler to list information about
+temporary allocations and deallocations in the assembler file.
+\item [-Axxx] \olabel{A} specifies what kind of assembler should be generated . Here
 \var{xxx} is one of the following :
 \begin{itemize}
-\item \textbf{o} : A unix .o (object) file, using \gnu \file{as}.
+\item \textbf{o} : A unix coff object file, using the \gnu assembler \file{as}.
 \item \textbf{nasmcoff} : a coff file using the \file{nasm} assembler.
 \item \textbf{nasmelf} : a ELF32 file (\linux only) using the \file{nasm} assembler.
 \item \textbf{nasmonj} : a obj file  using the \file{nasm} assembler.
 \item \textbf{masm} : An obj file using the Microsoft \file{masm} assembler.
 \item \textbf{tasm} : An obj file using the Borland \file{tasm} assembler.
 \end{itemize}
-\item [-CD] Create dynamic library.
+\item[-B] \olabel{B} tells the compiler to re-compile all used units, even
+if the unit sources didn't change since the last compilation.
+\item[-b] \olabel{b} tells the compiler to generate browser info. This information can
+be used by an Integrated Development Environment (IDE) to provide information 
+on classes, objects, procedures, types  and variables in a unit.
+\item[-bl] \olabel{bl} is the same as \var{-b} but also generates
+information about local variables, types and procedures.
+\item [-CD] Create a dynamic library. This is used to transform units into
+dynamically linkable libraries on \linux.
 \item [-Chxxx] \olabel {Ch} Reserves \var{xxx} bytes heap. \var{xxx} should
 be between 1024 and 67107840.
-\item [-Ci] \olabel{Ci} Generate Input/Output checking code.
-\item [-Cn] \olabel{Cn} Omit the linking stage.
-\item [-Co] \olabel{Co} Generate Integer overflow checking code.
-\item [-Cr] \olabel{Cr} Generate Range checking code.
+\item [-Ci] \olabel{Ci} Generate Input/Output checking code. In case some
+input/output code of your program returns an error status, the program will
+exit with a run-time error. Which error is generated depends on the I/O error.
+\item [-Cn] \olabel{Cn} Omit the linking stage. 
+\item [-Co] \olabel{Co} Generate Integer overflow checking code. In case of
+integer errors, a run-time error will be generated by your program.
+\item [-Cr] \olabel{Cr} Generate Range checking code. In case your program
+acesses an array element with an invalid index, or if it increases an
+enumerated type beyond it's scope, a run-time error will be generated.
 \item [-Csxxx] \olabel{Cs} Set stack size to \var{xxx}.
 \item [-CS] \olabel{CS} Create static library.
-\item [-Ct] \olabel{Ct} generate stack checking code.
+\item [-Ct] \olabel{Ct} generate stack checking code. In case your program
+performs a faulty stack operation, a run-rime error will be generated.
 \item [-Cx] \olabel{Cx} Use smartlinking when compiling and linking units.
+smartlinking will only link in the code parts that are actually needed by
+the program. All unused code is left out. This can lead to substantially
+smaller binaries.
 \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}.
@@ -1023,11 +1039,11 @@ of the following values :
 \item[G] optimize for time, try to generate faster code (default).
 \item[r] keep certain variables in registers (experimental, use with
 caution).
-\item[u] uncertain optimizations
+\item[u] Uncertain optimizations
 \item[1] Level 1 optimizations (quick optimizations).
 \item[2] Level 2 optimizations (\var{-O1} plus some slower optimizations).
 \item[3] Level 3 optimizations (\var{-O2} plus \var{-Ou}).
-\item[Pn] Specify processor: \var{n} can be one of
+\item[Pn] (Intel only) Specify processor: \var{n} can be one of
 \begin{description}
 \item[1] optimize for 386/486
 \item[2] optimize for Pentium/PentiumMMX (tm)
@@ -1041,14 +1057,15 @@ file (executable). Only with programs.
 \item [-s] \olabel{s} Tells the compiler not to call the assembler and linker.
 Instead, the compiler writes a script, \file{PPAS.BAT} under \dos, or
 \file{ppas.sh} under \linux, which can then be executed to produce an
-executable.
-\item[-Txxx] \olabel{T}Specifies the target operating system. \var{xxx} can be one of
+executable. This can be used to speed up the compiling process or to debug
+the compiler's output.
+\item[-Txxx] \olabel{T} Specifies the target operating system. \var{xxx} can be one of
 the following:
 \begin{itemize}
 \item \textbf{GO32V1} : \dos and version 1 of the DJ DELORIE extender (no longer maintained).
 \item \textbf{GO32V2} : \dos and version 2 of the DJ DELORIE extender.
 \item \textbf{LINUX} : \linux.
-\item \textbf{OS2} : OS/2 (2.x) (this is still under development).
+\item \textbf{OS2} : OS/2 (2.x) using the \var{EMX} extender.
 \item \textbf{WIN32} : Windows 32 bit.
 \end{itemize}
 \item [-uxxx] \olabel{u} undefine the symbol \var{xxx}. This is the opposite
@@ -1078,24 +1095,33 @@ can be one of the following:
 \subsection{Options concerning the sources (language options)}
 for more information on these options, see also \progref
 \begin{description}
-\item [-Rxxx] \olabel{R} Specifies what assembler you use in your \var{asm} assembler code
-blocks. Here \var{xxx} is one of the following:
+\item [-Rxxx] \olabel{R} Specifies what kind of assembler you use in 
+your \var{asm} assembler code blocks. Here \var{xxx} is one of the following:
 \begin{description}
-\item [att\ ] \var{asm} blocks contain AT\&T assembler.
-\item [intel] \var{asm} blocks contain Intel assembler.
-\item [direct] \var{asm} blocks should be copied as-is in the assembler
+\item [att\ ] \var{asm} blocks contain AT\&T-style  assembler. 
+This is the default style. 
+\item [intel] \var{asm} blocks contain Intel-style assembler.
+\item [direct] \var{asm} blocks should be copied as-is in the assembler,
+only replacing certain variables.
 file.
 \end{description}
-\item [-S2] \olabel{Stwo} Switch on Delphi 2 extensions.
+\item [-S2] \olabel{Stwo} Switch on Delphi 2 extensions.  This is different
+from \var{-Sd} because some \fpc constructs are still available to you.
 \item [-Sc] \olabel{Sc} Support C-style operators, i.e. \var{*=, +=, /= and
 -=}.
-\item [-Sd] tells the compiler to dispose asmlists. This uses less memory,
-but is slower.
+\item [-Sd] Tells the compiler to be Delphi compatible. This is more strict
+than the \var{-S2} option, since some \var{fpc} extensions are switched off.
 \item [-Se] \olabel{Se} The compiler stops after the first error. Normally,
 the compiler tries to continue compiling after an error, until 50 errors are
-reached, or a fatal error is reachd, and then it stops. With this switch,
+reached, or a fatal error is reached, and then it stops. With this switch,
 the compiler will stop after the first error.
-\item [-Sg] \olabel{Sg} Support the \var{label} and \var{goto} commands.
+\item [-Sg] \olabel{Sg} Support the \var{label} and \var{goto} commands. By
+default these are not supported. You must also specify this option if you
+use labels in assembler statements. (if you use the \var{AT\&T} style
+assember)
+\item [-Sh] Use ansistrings by default for strings. If this keyword is
+specified, the compiler will interpret the \var{string} keyword as a
+ansistring. Otherwise it is supposed to be a short strings (TP style).
 \item [-Si] \olabel{Si} Support \var{C++} style INLINE.
 \item [-Sm] \olabel{Sm} Support C-style macros.
 \item [-So] \olabel{So} Try to be Borland TP 7.0 compatible (no function
@@ -1549,7 +1575,7 @@ programs and units. Here we list these programs and units.
 \subsection{ppudump program}
 
 \file{ppudump} is a program which shows the contents of a \fpc unit. It
-is distributed with the compiler you can just issue the following command
+is distributed with the compiler. You can just issue the following command
 \begin{verbatim}
   ppudump [options] foo.ppu
 \end{verbatim}