+ Initial implementation of man page by Marco Van De Voort

docs/ppc386.1

@@ -0,0 +1,415 @@
+.TH ppc386 1 "30 may 1999" FPC "Free Pascal Compiler"
+.SH NAME
+ppc386 \- Free Pascal Compiler (FPC) binary, name derived from Portable Pascal Compiler
+
+.SH SYNOPSIS
+
+.B "ppc386 [options] [sourcefile]"
+.BR
+
+.SH DESCRIPTION
+This binary is the main binary of the
+.I Free Pascal Compiler (FPC)
+which is a
+.I Turbo Pascal
+and
+.I Delphi (2.0) compatible
+standalone (non GCC frontend) multitarget Pascal compiler.
+.PP
+The compiler uses
+.BR LD (1)
+and can use
+.BR AS (1) (see parameter \-Aas, but also has its own binary object writer.
+.PP
+The current main targets are
+.I Go32V2
+(Dos DJGPP extender),
+.I Linux,
+.I OS/2
+and
+.I Win32.
+The other targets (M68K compilers for Atari and Amiga) are based on older
+versions of the compiler.
+.PP
+This manpage is meant for quick\-reference only. FPC comes with a great (600+ pages)
+manual, which is updated constantly, while this man page can be out of date.
+
+.SH Usage
+
+The compilation proces is started by typing
+.I ppc386
+followed by a sourcefile name (normally with .pas or .pp extension). Before processing the actual processing of the source file,
+.BR ppc386.cfg (5)
+the configuration file of the compiler is read which contains the location of the
+RTL, other packages (API, FCL, FreeVision), and optionally default values for some
+switches. See the separate manpage of
+.BR ppc386.cfg (5)
+for more information.
+
+.SH Options
+
+.PP
+General options
+
+.IP \fI\-h\fP
+if you specify this option, the compiler outputs a list of all options,
+and exits after that.
+.IP \fI\-?\fP
+idem as \-h, but waiting after every screenfull for the enter key.
+.IP \fI\-i\fP
+This option tells the compiler to print the copyright information.
+   You can give it an option, as -ixxx} where "xxx" can be one of the
+following:
+.RS
+.IP \fID\fP
+Returns the compiler date.
+.IP \fIV\fP
+Returns the compiler version.
+.IP \fISO\fP
+Returns the compiler OS.
+.IP \fISP\fP
+Returns the compiler processor.
+.IP \fITO\fP
+Returns the target OS.
+.IP \fITP\fP
+Returns the target Processor.
+.RE
+.IP \fI-l\fP
+This option tells the compiler to print the
+.I FPC
+logo on standard output. It also gives you the
+.I FPC
+version number.
+.IP \fI-n\fP
+Tells the compiler not to read the configuration file
+.BR ppc386.cfg (5)
+
+.PP
+Options for getting feedback
+.IP \fI-vxxx\fP
+Be verbose. "xxx" is a combination of the following:
+.RS
+.IP \fIe\fP
+Tells the compiler to show only errors. This option is on by default.
+.IP \fIi\fP
+Tells the compiler to show some general information.
+.IP \fIw\fP
+Tells the compiler to issue warnings.
+.IP \fIn\fP
+Tells the compiler to issue notes.
+.IP \fIh\fP
+Tells the compiler to issue hints.
+.IP \fIl\fP
+Tells the compiler to show the line numbers as it processes a
+file. Numbers are shown per 100.
+.IP \fIu\fP
+Tells the compiler to print the names of the files it opens.
+.IP \fIt\fP
+Tells the compiler to print the names of the files it tries
+to open.
+.IP \fIp\fP
+Tells the compiler to print the names of procedures and
+functions as it is processing them.
+.IP \fIc\fP
+Tells the compiler to warn you when it processes a
+conditional.
+.IP \fIm\fP
+Tells the compiler to write which macros are defined.
+.IP \fId\fP
+Tells the compiler to write other debugging info.
+.IP \fIa\fP
+Tells the compiler to write all possible info. (this is the
+same as specifying all options)
+.IP \fI0\fP
+Tells the compiler to write no messages. This is useful when
+you want to override the default setting in the configuration file.
+.IP \fIb\fP
+Tells the compiler to show all procedure declarations if an
+overloaded function error occurs.
+.IP \fIx\fP
+Tells the compiler to output some executable info (for Win32
+platform only).
+.IP \fIr\fP
+Rhide/GCC compatibility mode: formats the error differently, so they
+are understood by RHIDE.
+.RE
+.PP
+Options concerning files and directories
+.IP \fI-exxx\fP
+"xxx" specifies the directory where thc ompiler can find the executables
+as (the assembler) and ld (the compiler).
+
+.IP \fI-FD\fP
+same as
+.I -e.
+.IP \fI-Fexxx\fP
+This option tells the compiler to write errors, etc. to
+the file "xxx".
+.IP \fI-Fgxxx\fP
+(linux only, obsolete) "xxx" specifies the path where the compiler
+can find the
+.I GNU C
+library. This is superseded by the
+.I -Fl
+option.
+.IP \fI-Fixxx\fP
+adds "xxx" to the path where the compiler searches for
+its include files.
+.IP \fI-Flxxx\fP
+Adds "xxx" to the library searching path, and is passe to the linker.
+
+.IP \fI-FLxxx\fP
+( Linux only) Tells the compiler to use "xxx" as the
+dynamic linker. Default this is /lib/ld-linux.so.2, or
+lib/ld-linux.so.1, depending on which one is found.
+.IP \fI-Foxxx\fP
+Adds "xxx" to the object file path. This path is used
+when looking for files that need to be linked in.
+.IP \fI-Frxxx\fP
+"xxx" specifies the file which contain the compiler
+messages. Default the compiler ahs built-in messages. Specifying this option
+will override the default messages.
+.IP \fI-Fuxxx\fP
+Idem as
+.I -Up
+Add "xxx" to the object path.
+.IP \fI-FUxxx\fP
+Tells the compiler to write units in directory "xxx" instead of the current
+directory.
+.IP \fI-Ixxx\fP
+Add "xxx" to the include file search path.
+This path is used when looking for include files.
+.IP \fI-P\fP
+uses pipes instead of files when assembling. This may speed up
+the compiler on OS/2 and Linux. Only with assemblers (such as
+.I GNU AS
+that support piping..
+.IP \fI-Upxxx\fP
+Tells the compiler to add "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 "xxx."
+
+.PP Options controlling the kind of output
+for more information on these options, see also the programmers manual.
+.IP \fI-a\fP
+Tells the compiler not to delete the assembler file.
+This also counts for the (possibly) generated batch script.
+.IP \fI-al\fP
+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.
+.IP \fI-Axxx\fP
+specifies what kind of assembler should be generated . Here
+"xxx" is one of the following :
+.RS
+.IP \fIAS\fP
+A unix .o (object) file, using
+.I GNU AS
+.IP \fInasmcoff\fP
+a coff file using the
+.I nasm
+assembler.
+.IP \fInasmelf\fP
+a ELF32 file (LINUX only) using the
+.I nasm
+assembler.
+.IP \fInasmonj\fP
+a obj file  using the
+.I nasm
+assembler.
+.IP \fImasm\fP
+An obj file using the Microsoft
+.I masm
+assembler.
+.IP \fItasm\fP
+An obj file using the Borland
+.I tasm
+assembler.
+.RE
+
+.IP \fI-CD\fP
+Create dynamic library.
+.IP \fI-Chxxx\fP
+Reserves "xxx" bytes heap. "xxx" shoul be between 1024 and 67107840.
+.IP \fI-Ci\fP
+Generate Input/Output checking code.
+.IP \fI-Cn\fP
+Omit the linking stage.
+.IP \fI-Co\fP
+Generate Integer overflow checking code.
+.IP \fI-Cr\fP
+Generate Range checking code.
+.IP \fI-Csxxx\fP
+Set stack size to "xxx".
+.IP \fI-CS\fP
+Create static library.
+.IP \fI-Ct\fP
+generate stack checking code.
+.IP \fI-Cx\fP
+Use smartlinking when compiling and linking units.
+.IP \fI-dxxx\fP
+Define the symbol name "xxx". This can be used
+to conditionally compile parts of your code.
+
+
+
+.IP \fI-E\fP
+Same as -Cn.
+.IP \fI-g\fP
+Generate debugging information for debugging with
+.I GDB
+
+.IP \fI-gg\fP
+idem as -g.
+.IP \fI-gd\fP
+generate debugging info for dbx.
+.IP \fI-gh\fP
+use the heaptrc unit (see the units part of the FPC manual).
+.IP \fI-Oxxx\fP
+optimize the compiler's output; "xxx" can have one
+of the following values :
+.RS
+.IP \fIg\fP
+optimize for size, try to generate smaller code.
+.IP \fIG\fP
+optimize for time, try to generate faster code (default).
+.IP \fIr\fP
+keep certain variables in registers (experimental, use with caution).
+.IP \fIu\fP
+uncertain optimizations
+.IP \fI1\fP
+Level 1 optimizations (quick optimizations).
+.IP \fI2\fP
+Level 2 optimizations (-O1 plus some slower optimizations).
+.IP \fI3\fP
+Level 3 optimizations (-O2 plus -Ou).
+.IP \fIPn\fP
+Specify processor : n can be one of
+.RS
+.IP \fI1\fP
+optimize for 386/486
+.IP \fI2\fP
+optimize for Pentium/PentiumMMX (tm)
+.IP \fI3\fP
+optimizations for PentiumPro / P-II / Cyrix 6x86 / K6 (tm)
+.RE
+
+The exact effect of these effects can be found in the programmers part of the manual.
+.RE
+.IP \fI-oxxx\fP
+Tells the compiler to use "xxx" as the name of the output
+file (executable). Only with programs.
+.IP \fI-pg\fP
+Generate profiler code for gprof.
+.IP \fI-s\fP
+Tells the compiler not to call the assembler and linker.
+Instead, the compiler writes a script, PPAS.BAT under DOS, or
+ppas.sh under Linux, which can then be executed to produce an
+executable.
+.IP \fI-Txxx\fP
+Specifies the target operating system. "xxx" can be one of the following:
+.RS
+.IP \fIGO32V1\fP
+DOS and version 1 of the DJ DELORIE extender (no longer maintained).
+.IP \fIGO32V2\fP
+DOS and version 2 of the DJ DELORIE extender.
+.IP \fILINUX\fP
+Linux.
+.IP \fIOS2\fP
+OS/2 (2.x) (this is still under development).
+.IP \fIWIN32\fP
+Windows 32 bit.
+.RE
+.IP \fI-uxxx\fP
+undefine the symbol "xxx". This is the opposite
+of the -d option.
+.IP \fI-uxxx\fP
+Undefine symbol "xxx".
+.IP \fI-Xx\fP
+Executable options. These tell the compiler what
+kind of executable should be generated. the parameter "x"
+can be one of the following:
+.RS
+.IP \fIc\fP
+(Linux only) Link with the C library. You should only use this when
+you start to port \fpc to another operating system.
+.IP \fID\fP
+Link with dynamic libraries (defines the FPC_LINK_DYNAMIC symbol)
+.IP \fIs\fP
+Strip the symbols from the executable.
+.IP \fIS\fP
+Link with static libraries (defines th FPC_LINK_STATIC symbol)
+.RE
+
+.PP
+Options concerning the sources (language options)
+for more information on these options, see also Programmers Manual
+.IP \fI-Rxxx\fP
+Specifies what assembler you use in your "asm" assembler code
+blocks. Here "xxx" is one of the following:
+.RS
+.IP \fIatt\fP
+Asm blocks contain AT&T assembler.
+.IP \fIintel\fP
+Asm blocks contain Intel assembler.
+.IP \fIdirect\fP
+Asm blocks should be copied as-is in the assembler
+file.
+.RE
+.IP \fI-S2\fP
+Switch on Delphi 2 extensions.
+.IP \fI-Sc\fP
+Support C-style operators, i.e. *=, +=, /= and -=.
+.IP \fI-Sd\fP
+tells the compiler to dispose asmlists. This uses less memory,
+but is slower.
+.IP \fI-Se\fP
+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,
+the compiler will stop after the first error.
+.IP \fI-Sg\fP
+Support the label and goto commands.
+.IP \fI-Si\fP
+Support C++ style INLINE.
+.IP \fI-Sm\fP
+Support C-style macros.
+.IP \fI-So\fP
+Try to be Borland TP 7.0 compatible (no function
+overloading etc.).
+.IP \fI-Sp\fP
+Try to be
+.I GPC (GNU Pascal Compiler)
+compatible.
+.IP \fI-Ss\fP
+The name of constructors must be "init", and the
+name of destructors should be "done".
+.IP \fI-St\fP
+Allow the "static" keyword in objects.
+.IP \fI-Un\fP
+Do not check the unit name. Normally, the unit name
+is the same as the filename. This option allows both to be different.
+.IP \fI-Us\fP
+Compile a system unit. This option causes the
+compiler to define only some very basic types.
+
+.SH Acknowledgements
+
+The manual (on which the manpage is based) was mainly written by Michael van Canneyt.
+.PP
+Questions/corrections can be mailed to fpc\[email protected]
+.PP
+Also thanks to the rest of the FPC development team.
+
+.SH SEE ALSO
+.BR  ppc386.cfg (5)
+.BR  ppdep (1)
+.BR  ppudump (1)
+.BR  ppumove (1)
+.BR  ptop (1)
+.BR  h2pas (1)
+.BR  ld (1)
+.BR  as (1)
+