From 2a07cce2ebb61fbe8c2d696dd430eb876b1674b5 Mon Sep 17 00:00:00 2001 From: michael Date: Mon, 24 Jan 2000 07:02:50 +0000 Subject: [PATCH] + Some more explanations. Options corrected --- docs/user.tex | 268 +++++++++++++++++++++++++++++++++++--------------- 1 file changed, 188 insertions(+), 80 deletions(-) diff --git a/docs/user.tex b/docs/user.tex index c281e4cbec..471fd2ffaf 100644 --- a/docs/user.tex +++ b/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 set stack size to -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 defines the symbol -e 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 set exe/unit output path to -Fi adds to include path -Fl adds to library path + -FL uses as dynamic linker -Fo adds to object path -Fr load error message file -Fu adds to unit path @@ -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 change the name of the executable produced to - -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 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 compiler stops after the 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 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 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 Set Image base to Hexadecimal 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