+ Some more explanations. Options corrected

docs/user.tex

@@ -655,6 +655,23 @@ your source file has uppercase letters in it. Only when the compiler tries to
 recompile the unit, it will not find your source because of the uppercase
 letters.
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Units libraries and smartlinking
+\section{Units, libraries and smartlinking}
+The \fpc compiler supports smartlinking and the creation of libraries.
+However, the default behaviour is to compile each unit into 1 big object
+file, which will be linked as a whole into your program.
+
+Not only is it possible to compile a shared library under \windows and 
+\linux, but also it is possible to take existing units and put them 
+together in 1 static or shared library.
+
+
+begin{}
+
+
+
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % Creating an executable for GO32V1, PMODE/DJ targets
 \section{Creating an executable for GO32V1 and PMODE/DJ targets}
@@ -897,7 +914,7 @@ You can still pass a configuration file with the \var{@} option.
 \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.
+\item \var{u} : Tells the compiler to print information on the units it loads.
 \item \var{t} : Tells the compiler to print the names of the files it tries
 to open.
 \item \var{p} : Tells the compiler to print the names of procedures and
@@ -932,6 +949,11 @@ compiler can find the executables \file{as} (the assembler) and \file{ld}
 \item [-Fexxx] This option tells the compiler to write errors, etc. to
 the file named \file{xxx}.
 \olabel{Fe}
+\item [-FExxx] tells the compiler to write the executable and units in 
+directory \file{xxx} instead of th current directory.
+\olabel{FE}
+\item [-FIxxx] Adds \var{xxx} to the include file search path.
+\olabel{FI}
 \item [-Flxxx] Adds \var{xxx} to the library searching path, and is passed
 to the linker.
 \olabel{Fl}
@@ -939,23 +961,22 @@ to the linker.
 dynamic linker. Default this is \file{/lib/ld-linux.so.2}, or
 \file{/Hlib/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.
+\item[-Foxxx] Adds \file{xxx} to the object file search path. 
+This path is used when looking for files that need to be linked in.
 \olabel{Fo}
 \item [-Frxxx] \file{xxx} specifies the file which contain the compiler
-messages. Default the compiler ahs built-in messages. Specifying this option
+messages. Default the compiler has built-in messages. Specifying this option
 will override the default messages.
 \olabel{Fr}
-\item [-Fuxxx] Add \file{xxx} to the unit path. Units are first searched
-in the current directory. If they are not found there then the compiler searches 
-them in the unit path. You must {\em
-always} supply the unit path to the system unit.
+\item [-Fuxxx] Add \file{xxx} to the unit search path. 
+Units are first searched in the current directory. 
+If they are not found there then the compiler searches them in the unit path. 
+You must {\em always} supply the path to the system unit.
 \olabel{Fu}
 \item [-FUxxx] Tells the compiler to write units in directory \var{xxx}
-instead of the current directory.
+instead of the current directory. It overrides the \var{-FE} option.
 \item [-Ixxx] \olabel{I} Add \file{xxx} to the include file search path.
-This path is used when looking for include files. This option is obsolite,
-use \var{-Fi} instead.
+This option has the same effect as \var{-Fi}.
 \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...
@@ -969,8 +990,7 @@ for more information on these options, see also \progref
 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.
+in the assembler file as comments. 
 \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.
@@ -978,14 +998,17 @@ the code generated bythe compiler.
 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 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}
+\begin{description}
+\item[as] assemble using \gnu as.
+\item[asaout] assemble using \gnu as for aout (Go32v1).
+\item[nasmcoff] coff (Go32v2) file using Nasm.
+\item[nasmelf] elf32 (Linux) file using Nasm.
+\item[nasmobj] object file using Nasm.
+\item[masm] object file using Masm (Microsoft).
+\item[tasm] object file using Tasm (Borland).
+\item[coff] coff object file (Go32v2) using the internal binary object writer.
+\item[pecoff] pecoff object file (Win32) using the internal binary object writer.
+\end{description}
 \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
@@ -1007,10 +1030,9 @@ integer errors, a run-time error will be generated by 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. 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.
+\item [-CX] \olabel{Cx} Create a smartlinked unit when writing a unit.
 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.
@@ -1022,6 +1044,7 @@ to conditionally compile parts of your code.
 \item [-gg] idem as \var{-g}.
 \item [-gd] \olabel{gd} generate debugging info for \file{dbx}.
 \item [-gh] use the heaptrc unit (see \unitsref).
+\item [-gc] generate checks for pointers.
 \item[-Oxxx] \olabel{O} optimize the compiler's output; \var{xxx} can have one
 of the following values :
 \begin{description}
@@ -1056,7 +1079,7 @@ the following:
 \item \textbf{GO32V2} : \dos and version 2 of the DJ DELORIE extender.
 \item \textbf{LINUX} : \linux.
 \item \textbf{OS2} : OS/2 (2.x) using the \var{EMX} extender.
-\item \textbf{WIN32} : Windows 32 bit.
+\item \textbf{WIN32} : \windows 32 bit.
 \end{itemize}
 \item [-uxxx] \olabel{u} undefine the symbol \var{xxx}. This is the opposite
 of the \var{-d} option.
@@ -1072,8 +1095,9 @@ can be one of the following:
 \item \textbf{D} : Link with dynamic libraries (defines the
 \var{FPC\_LINK\_DYNAMIC} symbol)
 \item \textbf{s} : Strip the symbols from the executable.
-\item \textbf{S} : Link with static libraries (defines the
-\var{FPC\_LINK\_STATIC} symbol)
+\item \textbf{S} : Link with static units (defines the \var{FPC\_LINK\_STATIC} symbol)
+\item \textbf{X} : Link with smartlinked units (defines the
+\var{FPC\_LINK\_SMART} symbol)
 \end{itemize}
 \end{description}
 
@@ -1101,10 +1125,11 @@ from \var{-Sd} because some \fpc constructs are still available to you.
 -=}.
 \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,
+\item [-SeN] \olabel{Se} The compiler stops after the N-th error. Normally,
 the compiler tries to continue compiling after an error, until 50 errors are
 reached, or a fatal error is reached, and then it stops. With this switch,
-the compiler will stop after the first error.
+the compiler will stop after the N-th error (if N is omitted, a default of 1 
+is assumed).
 \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
@@ -1592,6 +1617,25 @@ begin
 \item You cannot nest comments.
 \end{itemize}
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% A note about long file names.
+\section{A note on long file names under \dos}
+Under \windows 95 and higher, long filenames are supported. Compiling
+for the win32 target ensures that long filenames are supported in all
+functions that do fie or disk access in any way.
+
+Moreover, \fpc supports the use of long filenames in the system unit and 
+the dos unit also for go32v2 executables. The system unit contains the
+boolean variable \var{LFNsupport}. If it is set to \var{True} then all
+system unit functions and DOS unit functions will use long file names 
+if they are available. This should be so on all versions of Windows,
+with the possible exception of \windows 2000. The system unit will check
+this by calling \dos function \var{71A0h} and checking whether long
+filenames are supported on the \file{C:} drive. 
+
+It is possible to disable the long filename support by setting the
+\var{LFNSupport} variable to \var{False}
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % Utilities.
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -1949,6 +1993,27 @@ will convert the \file{resdemo.rst} file to \file{resdemo.po}.
 More information on the \file{rstconv} utility can be found in the \progref,
 under the chapter about resource strings.
 
+\subsection{fpcmake}
+
+\file{fpcmake} is the \fpc makefile constructor program.
+
+It reads a \file{Makefile.fpc} configuration file and converts it to a 
+\file{Makefile} suitable for reading by GNU \file{make} to compile 
+your projects. It is similar in functionality to GNU \file{autoconf}
+or \file{Imake} for making X projects.
+
+\file{fpcmake} accepts filenames of makefile description files as it's 
+command-line arguments. For each of these files it will create a 
+\file{Makefile} in the same directory where the file is located, 
+overwriting any other existing file.
+
+If no options are given, it just attempts to read the file \file{Makefile.fpc}
+in the current directory and tries to construct a makefile from it.
+any previously existing \file{Makefile} will be erased. 
+
+The format of the \file{fpcmake} configuration file is described in great
+detail in the appendices of the \progref.
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % Supplied units
 \section{Supplied units}
@@ -1956,35 +2021,73 @@ 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. They are documented in the \unitsref.
 
+%
+% Common units
+%
+\subsection{Units common to all platforms}
+The following units are common to all platform; i.e. their workings 
+are guaranteed to be the same on all platforms.
+\begin{itemize}
+\item [getopts] This unit gives you the \gnu \var{getopts} command-line 
+arguments  handling mechanism. It also supports long options.
+\item [mmx] This unit provides support for \var{mmx} extensions in your
+code.
+\item [objects]  This unit provides basic routines for handling objects.
+\item [objpas] is used for Delphi compatibility; you should never load this
+unit explicitly; it is automatically loaded if you request Delphi mode.
+\item [strings] This unit provides basic string handling routines for the 
+\var{pchar} type, comparable to similar routines in standard \var{C} 
+libraries.
+\item[sysutils] is an alternative implementation of the sysutils unit of 
+Delphi.
+\item[typinfo] Provides functions to acces Run-Time Type Information, just
+like Delphi.
+\end{itemize}
+
 %
 % Under DOS
 %
 \subsection{Under DOS}
 \begin{itemize}
-\item [strings] This unit provides basic
-string handling routines for the \var{pchar} type, comparable to similar
-routines in standard \var{C} libraries.
-\item [objects]  This unit provides basic
-routines for handling objects.
-\item [dos] This unit provides basic routines for
-accessing the operating system \dos. It provides almost the same
-functionality as the Turbo Pascal unit.
-\item [printer]  This unit provides all you
-need for rudimentary access to the printer.
-\item [getopts] This unit gives you the
-\gnu \var{getopts} command-line arguments  handling mechanism.
-It also supports long options.
-\item [crt] This unit provides basic screen
-handling routines. It provides the same functionality  as the Turbo Pascal \var{CRT}
+\item [crt] This unit provides basic screen handling routines. 
+It provides the same functionality  as the Turbo Pascal \var{CRT} unit.
+\item [dos] This unit provides basic routines for accessing the operating 
+system \dos. It provides almost the same functionality as the Turbo Pascal 
 unit.
+\item [emu387] This unit provides support for the coprocessor emulator.
+\item [graph] This unit provides basic graphics handling, with routines to 
+draw lines on the screen, display texts etc. It provides the same functions 
+as the Turbo Pascal unit.
+\item [go32] This unit provides access to possibilities of the \var{GO32}
+\dos extender.
+\item [ports] This unit provides access to the ports[] construct of 
+Turbo Pascal.
+\item [printer]  This unit provides all you need for rudimentary access 
+to the printer.
+\end{itemize}
+
+%
+% Under Windows
+%
+\begin{itemize}
+\item [dos] This unit provides basic routines for
+accessing the operating system \dos. It emulates this functionality
+by issuing calls to the Windows operating system.
+\item [crt and wincrt] These units provides basic screen handling routines. 
+They provide the same functionality as the Turbo Pascal \var{CRT} unit.
 \item [graph] This unit provides basic graphics
 handling, with routines to draw lines on the screen, display texts etc. It
 provides the same functions as the Turbo Pascal unit.
-\item [go32] This unit provides access to possibilities of the \var{GO32}
-\dos extender.
-\item [emu387] This unit provides support for the coprocessor emulator.
-\item [mmx] This unit provides support for \var{mmx} extensions in your
-code.
+\item [Windows] This unit provides access to al Win32 API calls. Effort has
+been taken to make sure that it is compatible to the Delphi version of this
+unit, so code for Delphi is easily ported to \fpc.
+\item[opengl] provides access to the low-level opengl functions in \windows.
+\item[winmouse] provides access to the mouse in \windows.
+\item[ole2] provides access to the OLE capabilities of \windows.
+\item[winsock] provides acces to the \windows sockets API Winsock.
+\item[sockets] is a wrapper around winsock that is compatible with the 
+\linux sockets layer. Using this unit ensures that your code will run 
+both on \windows and \linux.
 \end{itemize}
 
 %
@@ -1992,40 +2095,31 @@ code.
 %
 \subsection{Under Linux}
 \begin{itemize}
-\item [strings] This unit provides basic
-string handling routines for the \var{PChar} type, comparable to similar
-routines in standard \var{C} libraries.
-\item [objects] This unit provides basic
-routines for handling objects.
-\item [crt] This unit provides basic screen
-handling routines. It provides the same functionality Turbo Pascal \var{CRT}
-unit. It works on any terminal which supports the \var{vt100} escape
+\item [crt] This unit provides basic screen handling routines. 
+It provides the same functionality Turbo Pascal \var{CRT} unit. 
+It should work on any terminal which supports the \var{vt100} escape
 sequences.
-\item [dos] This unit provides an emulation of the
-same unit under \dos. It is intended primarily for easy porting of Pascal
-programs from \dos to \linux. For good performance, however, it is
-recommended to use the \var{linux} unit.
+\item [dos] This unit provides an emulation of the same unit under \dos. 
+It is intended primarily for easy porting of Pascal programs from \dos 
+to \linux. For good performance, however, it is recommended to use the 
+\var{linux} unit.
 \item [linux] This unit provides access to the
 \linux operating system. It provides most file and I/O handling routines
 that you may need. It implements most of the standard \var{C} library constructs
 that you will find on a Unix system. If you do a lot of disk/file
 operations, the use of this unit is recommended over the one you use under
 Dos.
-\item [printer] This unit provides an
-interface to the standard Unix printing mechanism.
-\item [getopts] This unit gives you the
-\gnu \var{getopts} command-line arguments  handling mechanism.
-It also supports long options.
-\item [mmx] This unit provides support for \var{mmx} extensions in your
-code.
+\item [printer] This unit provides an interface to the standard Unix 
+printing mechanism. It supports printing to file and to any command you
+would like.
 \item [sockets] This unit gives you access to sockets and TCP/IP
 programming.
 \item [graph] Is an implementation of Borlands \file{graph} unit, which
-works on the Linux console. It's implementation is fairly complete, the only
-non-functional things are the fillpatterns and line styles. It uses the
-libvga and libvgagl graphics libraries, so you need these installed for this
-unit to work. Also, programs using this library need to be run as root, or
-setuid  root, and hence are a potential security risk.
+works on the Linux console. It's implementation is as complete as on
+the other platforms (it shares the same code).
+It uses the libvga and libvgagl graphics libraries, so you need these 
+installed for this unit to work. Also, programs using this library need 
+to be run as root, or setuid root, and hence are a potential security risk.
 \item [ports] This implements the various \var{port[]} constructs. These are
 provided for compatibility only, and it is not recommended to use them
 extensively. Programs using this construct must be run as ruit or setuid
@@ -2564,8 +2658,8 @@ put + after a boolean switch option to enable it, - to disable it
            -Cr        range checking
            -Cs<n>     set stack size to <n>
            -Ct        stack checking
-           -CS        create static library
-           -Cx        use smartlinking
+           -CD        create also dynamic library (* doesn't work yet *)
+           -CX        create also smartlinked library
   -d<x>  defines the symbol <x>
   -e<x>  set path to executable
   -E     same as -Cn
@@ -2575,6 +2669,7 @@ put + after a boolean switch option to enable it, - to disable it
            -FE<x>     set exe/unit output path to <x>
            -Fi<x>     adds <x> to include path
            -Fl<x>     adds <x> to library path
+           -FL<x>     uses <x> as dynamic linker
            -Fo<x>     adds <x> to object path
            -Fr<x>     load error message file <x>
            -Fu<x>     adds <x> to unit path
@@ -2583,6 +2678,7 @@ put + after a boolean switch option to enable it, - to disable it
            -gg        use gsym
            -gd        use dbx
            -gh        use heap trace unit
+           -gc        generate checks for pointers
   -i     information
            -iD        return compiler date
            -iV        return compiler version
@@ -2595,12 +2691,13 @@ put + after a boolean switch option to enable it, - to disable it
   -l     write logo
   -n     don't read the default config file
   -o<x>  change the name of the executable produced to <x>
-  -pg    generate profile code for gprof
+  -pg    generate profile code for gprof (defines FPC_PROFILE)
+  -P     use pipes instead of creating temporary assembler files
   -S<x>  syntax options:
            -S2        switch some Delphi 2 extensions on
            -Sc        supports operators like C (*=,+=,/= and -=)
            -Sd        tries to be Delphi compatible
-           -Se        compiler stops after the first error
+           -Se<x>     compiler stops after the <x> errors (default is 1)
            -Sg        allow LABEL and GOTO
            -Sh        Use ansistrings
            -Si        support C++ styled INLINE
@@ -2626,18 +2723,23 @@ put + after a boolean switch option to enable it, - to disable it
                declarations if an error    x : Executable info (Win32 only)
                occurs
   -X     executable options:
-           -XD        link with dynamic libraries (defines FPC_LINK_DYNAMIC)
+           -Xc        link with the c library
            -Xs        strip all symbols from executable
-           -XS        link with static libraries (defines FPC_LINK_STATIC)
+           -XD        try to link dynamic          (defines FPC_LINK_DYNAMIC)
+           -XS        try to link static (default) (defines FPC_LINK_STATIC)
+           -XX        try to link smart            (defines FPC_LINK_SMART)
 
 Processor specific options:
   -A<x>  output format:
-           -Ao        coff file using GNU AS
-           -Anasmcoff coff file using Nasm
+           -Aas       assemble using GNU AS
+           -Aasaout   assemble using GNU AS for aout (Go32v1)
+           -Anasmcoff coff (Go32v2) file using Nasm
            -Anasmelf  elf32 (Linux) file using Nasm
            -Anasmobj  obj file using Nasm
            -Amasm     obj file using Masm (Microsoft)
            -Atasm     obj file using Tasm (Borland)
+           -Acoff     coff (Go32v2) using internal writer
+           -Apecoff   pecoff (Win32) using internal writer
   -R<x>  assembler reading style:
            -Ratt      read AT&T style assembler
            -Rintel    read Intel style assembler
@@ -2660,6 +2762,12 @@ Processor specific options:
            -TLINUX    Linux
            -TOS2      OS/2 2.x
            -TWin32    Windows 32 Bit
+  -WB<x>  Set Image base to Hexadecimal <x> value
+  -WC     Specify console type application
+  -WD     Use DEFFILE to export functions of DLL or EXE
+  -WG     Specify graphic type application
+  -WN     Do not generate relocation code (necessary for debugging)
+  -WR     Generate relocation code
   
   -?     shows this help
   -h     shows this help without waiting