+ new man page with fpc.cfg description

install/man/man5/fpc.cfg.5

@@ -0,0 +1,285 @@
+.TH fpc.cfg 5 "23 november 2001" FPC "FPC configuration file"
+.SH NAME
+fpc.cfg \- Free Pascal Compiler (FPC) configuration file, name derived from Free Pascal Compiler.
+
+.SH DESCRIPTION
+This is the main configuration file of the
+.I Free Pascal Compiler (FPC)
+.PP
+All commandline options of the compiler (described in
+.BR ppc386 (1)
+) can be specified in fpc.cfg
+
+When the configuration file is found, it is read, and the lines
+it contains are treated like you typed them on the command line see
+.BR ppc386 (1)
+with some extra condtional possibilities.
+
+.SH SYNTAX
+
+You can specify comments in the configuration file with the # sign.
+Everything from the # on will be ignored, unless it is one of the keywords (see below).
+
+The compiler looks for the fpc.cfg file in the following places :
+.PP
+\	\fI\- Under Linux and unix\fP
+.br
+\	\	\- The current directory.
+.br
+\	\	\- Home directory, looks for .fpc.cfg
+.br
+\	\	\- The directory specified in the environment
+.br
+\	\	     variable PPC\_CONFIG\_PATH, and if it's not
+.br
+\	\	     set under /etc.
+.PP
+\	\fI- Under all other OSes:\fP
+.br
+\	\	\- The current directory.
+.br
+\	\	\- The directory specified in the environment
+.br
+\	\	     variable  PPC\_CONFIG\_PATH.
+.br
+\	\	\- The directory where the compiler binary is.
+.br
+
+.PP
+When the compiler has finished reading the configuration file, it continues
+to treat the command line options.
+
+One of the command\-line options allows you to specify a second configuration
+file: Specifying \@foo on the command line will use file foo instead of fpc.cfg
+and read further options from there. When the compiler has finished reading
+this file, it continues to process the command line.
+
+The configuration file allows some kind of preprocessing. It understands the
+following directives, which you should place on the first column of a line :
+.PP
+
+\	#IFDEF
+.br
+\	#IFNDEF
+.br
+\	#ELSE
+.br
+\	#ENDIF
+.br
+\	#DEFINE
+.br
+\	#UNDEF
+.br
+\	#WRITE
+.br
+\	#INCLUDE
+.br
+\	#SECTION
+.br
+They work the same way as their $...  directive counterparts in Pascal: 
+
+.IP \fI#IFDEF\fP
+.RS
+.IP \fISyntax\fP
+#IFDEF name
+
+Lines following #IFDEF are skipped read if the keyword "name"
+following it is not defined.
+
+They are read until the keywords #ELSE or #ENDIF are
+encountered, after which normal processing is resumed.
+
+.IP \fIExample\fP
+#IFDEF VER0_99_12
+.br
+\-Fu/usr/lib/fpc/0.99.12/rtl
+.br
+#ENDIF
+.br
+.PP
+In the above example, /usr/lib/fpc/0.99.12/rtl will be added to
+the path if you're compiling with version 0.99.12 of the compiler.
+.RE
+
+.IP \fI#IFNDEF\fP
+.RS
+.IP \fISyntax\fP
+#IFNDEF name
+
+Lines following #IFDEF are skipped read if the keyword "name"
+following it is defined.
+
+They are read until the keywords #ELSE or #ENDIF are
+encountered, after which normal processing is resumed.
+
+.IP \fIExample\fP
+#IFNDEF VER0_99_12
+.br
+-Fu/usr/lib/fpc/0.99.13/rtl
+.br
+#ENDIF
+.PP
+In the above example, /usr/lib/fpc/0.99.13/rtl will be added to
+the path if you're NOT compiling with version 0.99.12 of the compiler.
+.RE
+.IP \fI#ELSE\fP
+.RS
+.IP \fISyntax\fP
+#ELSE
+
+#ELSE can be specified after a #IFDEF or #IFNDEF
+directive as an alternative.
+Lines following #ELSE are skipped read if the preceding #IFDEF
+#IFNDEF was accepted.
+
+They are skipped until the keyword #ENDIF is
+encountered, after which normal processing is resumed.
+
+.IP \fIExample\fP
+
+#IFDEF VER0_99_12
+.br
+-Fu/usr/lib/fpc/0.99.12/rtl
+.br
+#ELSE
+.br
+-Fu/usr/lib/fpc/0.99.13/rtl
+.br
+#ENDIF
+.br
+.PP
+In the above example, /usr/lib/fpc/0.99.12/rtl will be added to
+the path if you're compiling with version 0.99.12 of the compiler,
+otherwise /usr/lib/fpc/0.99.13/rtl will be added to the path.
+.RE
+.IP \fI#ENDIF\fP
+.RS
+.IP \fISyntax\fP
+#ENDIF
+.PP
+#ENDIF marks the end of a block that started with #IF(N)DEF,
+possibly with an #ELSE between it.
+.RE
+
+.IP \fI#DEFINE\fP
+.RS
+.IP \fISyntax\fP
+#DEFINE name
+.PP
+#DEFINE defines a new keyword. This has the same effect as a
+"\-dname"  command\-line option.
+.RE
+
+.IP \fI#UNDEF\fP
+.RS
+.IP \fISyntax\fP
+#UNDEF name
+
+#UNDEF un-defines a keyword if it existed.
+This has the same effect as a "-uname" command-line option.
+.RE
+
+.IP \fI#WRITE\fP
+.RS
+.IP \fISyntax\fP
+#WRITE Message Text
+
+#WRITE writes "Message Text" to the screen.
+This can be useful to display warnings if certain options are set.
+
+.IP \fIExample\fP
+#IFDEF DEBUG
+.br
+#WRITE Setting debugging ON...
+.br
+-g
+.br
+#ENDIF
+.br
+
+.PP
+if "DEBUG is defined, this will produce a line
+
+Setting debugging ON...
+
+and will then switch on debugging information in the compiler.
+.RE
+
+.IP \fI#INCLUDE\fP
+.RS
+.IP \fISyntax\fP
+#INCLUDE filename
+
+#INCLUDE instructs the compiler to read the contents of
+"filename" before continuing to process options in the current file.
+
+This can be useful if you want to have a particular configuration file
+for a project (or, under Unix like systems (such as Linux), in 
+your home directory), but  still want to have the global options that are 
+set in a global configuration file.
+
+.IP \fIExample\fP
+#IFDEF LINUX
+.br
+  #INCLUDE /etc/fpc.cfg
+.br
+#ELSE
+.br
+  #IFDEF GO32V2
+.br
+    #INCLUDE c:\\pp\\bin\\fpc.cfg
+.br
+  #ENDIF
+.br
+#ENDIF
+.br
+.PP
+This will include /etc/fpc.cfg if you're on a unix like machine (like linux),
+and will include c:\\pp\\bin\\fpc.cfg on a dos machine.
+.RE
+.IP \fI#SECTION\fP
+.RS
+.IP \fISyntax\fP
+#SECTION name
+
+The #SECTION directive acts as a #IFDEF directive, only
+it doesn't require an #ENDIF directive. the special name COMMON
+always exists, i.e. lines following #SECTION COMMON are always read.
+.RE
+
+.SH Example
+
+A standard block often used in (the Linux version of) fpc.cfg is
+
+-vwhin
+.br
+#IFDEF VER0_99_12
+.br
+ #IFDEF FPC_LINK_STATIC
+.br
+  \-Fu/usr/lib/fpc/0.99.12/rtl/static
+.br
+  \-Fu/usr/lib/fpc/0.99.12/units/static
+.br
+ #ENDIF
+.br
+ #IFDEF FPC_LINK_DYNAMIC
+.br
+  \-Fu/usr/lib/fpc/0.99.12/rtl/shared
+.br
+  \-Fu/usr/lib/fpc/0.99.12/units/shared
+.br
+ #ENDIF
+.br
+ \-Fu/usr/lib/fpc/0.99.12/rtl
+.br
+ \-Fu/usr/lib/fpc/0.99.12/units
+.br
+#ENDIF
+.PP
+The block is copied into the fpc.cfg file for each version you use (normally
+the latest release  and the lastest developpers
+snapshot.
+
+.SH SEE ALSO
+.BR  ppc386 (1)