paweld/fpc
1
0
Fork 0
mirror of https://gitlab.com/freepascal.org/fpc/source.git synced 2025-04-08 16:28:24 +02:00
Code Issues Packages Projects Releases Wiki Activity

+ Some more explanations. Options corrected

Browse Source
This commit is contained in:
michael 2000-01-24 07:02:50 +00:00
parent 2f9b5b1b2b
commit 2a07cce2eb
1 changed files with 188 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

268
docs/user.tex
View File

@ -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