diff --git a/docs/prog.tex b/docs/prog.tex index aad7c8a267..9cf33c9114 100644 --- a/docs/prog.tex +++ b/docs/prog.tex @@ -4438,7 +4438,7 @@ construct a \file{Makefile} from it. any previously existing \file{Makefile} will be erased. % Makefile.fpc format. -\section{Format of the \file{Makefile.fpc} configuration file} +\section{Format of the configuration file} This section describes the rules that can be present in the file that is fed to \file{fpcmake}. @@ -4554,9 +4554,10 @@ Specifies whether the installation rules will be shown. By default this is Specifies whether the \file{Makefile} objects will be shown, i.e. a list of all units and programs that will be built by \file{make}. \end{description} + \subsection{Install} Contains instructions for installation of your units and programs. The -following keywods are recognized: +following keywords are recognized: \begin{description} \item[dirprefix] is the directory below wchich all installs are done. This corresponds to the \var{--prefix} argument to \gnu \file{configure}. @@ -4581,8 +4582,9 @@ one library. library is needed. This will make sure that the path to the GCC library is inserted in the library search path. \item[needotherlib] -a boolean value that tells the makefile that other library directories will -be needed. +(\linux only) a boolean value that tells the makefile that it should add +all library directories from the \file{ld.so.conf} file to the compiler +command-line. \end{description} \subsection{Packages} @@ -4756,13 +4758,12 @@ file \file{gnuutils.zip} on the \fpc FTP site. The following programs are optionally needed if you use some special targets. Which ones you need are controlled by the settings in the \var{tools} section. - \begin{description} \item[cmp] a \dos and \windowsnt file comparer. Used if \var{toolcmp} is \var{True}. \item[diff] a file comparer. Used if \var{tooldiff} is \var{True}. \item[ppdep] the ppdep depency lister. Used if \var{toolppdep} is \var{True}. Distributed with \fpc. -\item[ppfiles] the ppufiles unit file depency lister. Used if \var{toolppufiles} +\item[ppufiles] the ppufiles unit file dependency lister. Used if \var{toolppufiles} is \var{True}. Distributed with \fpc. \item[ppumove] the \fpc unit mover. Used if \var{toolppumove} is \var{True}. Distributed with \fpc. @@ -4771,27 +4772,28 @@ Distributed with \fpc. \item[zip] the zip archiver program. Used if \var{toolzip} is \var{True}. \end{description} All of these can also be found on the \fpc FTP site for \dos and \windowsnt. +\file{ppdep,ppufiles} and \file{ppumove} are distributed with the \fpc +compiler. -\section{Variables used by \file{makefile.fpc}} +% +\section{Variables that affect the generated makefile} +The makefile generated by \file{fpcmake} contains a lot of variables. +Some of them are set in the makefile itself, others can be set and are taken +into account when set. -Many variables affect the behaviour of the makefile. The variables can be -split in several groups: -\begin{description} -\item[Required environment variables] -\item[Command-line directory variables] -\item[Internal directory variables] -\item[Target variables] -\item[Compiler command-line variables] -\item[Internal Compiler command-line variables] -\end{description} -Each group will be discussed separately in the subsequent. +These variables can be split in several groups: +\begin{itemize} +\item Environment variables. +\item Directory variables. +\item Compiler command-line variables. +\end{itemize} +Each group will be discussed separately. -\subsection{Required environment variables} +\subsection{Environment variables} -In principle, \var{fcmake} doesn't expect any environment variable to be set. -Optionally, you can set the variable -\var{FPCMAKEINI} which should contain the name of a file with the basic -rules that fpcmake will generate. +In principle, \var{fpcmake} doesn't expect any environment variable to be set. +Optionally, you can set the variable \var{FPCMAKEINI} which should contain +the name of a file with the basic rules that \file{fpcmake} will generate. By default, \file{fpcmake} has a compiled-in copy of \file{fpcmake.ini}, which contains the basic rules, so there should be no need to set this variable. @@ -4799,96 +4801,23 @@ You can set it however, if you wish to change the way in which fpcmake works and creates rules. The initial \file{fpcmake.ini} file can be found in the \file{utils} source -package on the \fpc web site. - -\subsection{Command-line Directory variables} +package on the \fpc ftp site. +\subsection{Directory variables} The first set of variables controls the directories that are recognised in the makefile. They should not be set in the \file{Makefile.fpc} file, but can be specified on the commandline. - - \begin{description} - \item[INCDIR] this is a list of directories, separated by spaces, that will be added as include directories to the compiler command-line. Each directory in the list is prepended with \var{-I} and added to the compiler options. - \item[LIBDIR] is a list of library paths, separated by spaces. Each directory in the list is prepended with \var{-Fl} and added to the compiler options. - \item[OBJDIR] is a list of object file directories, separated by spaces, that is added to the object files path, i.e. Each directory in the list is prepended with \var{-Fo}. - -\end{description} - -\subsection{Internal Directory variables} - -These variables specify directories that are absolutely needed by -the makefile to function. - -\begin{description} -\item[NEEDINCDIR] is a space-separated list of library paths. Each -directory in the list is prepended with \var{-Fl} and added to the -compiler options. -\item[NEEDLIBDIR] is a space-separated list of library paths. Each -directory in the list is -prepended with \var{-Fl} and added to the compiler options. -\item[NEEDOBJDIR] is a list of object file directories, separated by - spaces. Each directory in the list is prepended with \var{-Fo} and -added to the compiler options. -\item[NEEDUNITDIR] is a list of unit directories, separated by spaces. -Each directory in the list is prepended with \var{-Fu} and is added to the -compiler options. -\item[OSINC] this is a space-separated list of OS-dependent directories -that will be added as include directories to the compiler command line. -\item[OTHERLIBDIR] is a list of library paths, separated by spaces. Each -directory in the list is prepended with \var{-Fl} and added to the -compiler options. This variable is meant to be set in the \file{Makefile.fpc} -\item[PROCINC] is a space-separated list of processor-dependent directories -that will be added as include directories to the compiler command-line. -\item[RTL] If \var{RTLDIR} is not set, \var{RTL} is used to construct -\var{RTLDIR}, after which \var{RTLDIR} is added to the compiler unit -path, with \var{-Fu} prepended. If \var{RTLDIR} is not set, it is set - to \mvar{RTL}/\mvar{OS\_TARGET}. -\item[RTLDIR] Directory where the \var{RTL} unit sources are. -If \var{RTLDIR} is not set, it is set to \mvar{RTL}/\mvar{OS\_TARGET}. \\ -If \var{RTL} is also not set, it is set to \mvar{FPCDIR}\var{/rtl/}\mvar{OS\_TARGET}. -\item[TARGETDIR] If set, this directory is added as the output directory of -the compiler, where all units and executables are written, i.e. it gets -\var{-FE} prepended. -\item[TARGETUNITDIR] If set, this directory is added as the output directory of -the compiler, where all units and executables are written, i.e. it gets -\var{-FU} prepended. -\item[UNIT] If \var{UNITDIR} is not set, \var{UNIT} is used to construct -\var{UNITDIR}. \var{UNITDIR} is added to the compiler unit path, with \var{-Fu} -prepended. -\item[UNITDIR] Directory where the \var{RTL} compiled units are. -If \var{UNITDIR} is not set, it is set to \mvar{UNIT}/\mvar{OS\_TARGET}. \\ -If \var{UNIT} is also not set, it is set to \mvar{FPCDIR}\var{/rtl/}\mvar{OS\_TARGET}. -\end{description} - -\subsection{Target variables} - -The second set of variables controls the targets that are constructed -by the makefile. They are created by FPCMAKE, so you can use them in your rules, -but you shouldn't assign values to them yourself. - -\begin{description} -\item[EXEOBJECTS] This is a list of executable names that will be compiled. -the makefile appends \mvar{EXEEXT} to these names. -\item[LOADEROBJECTS] is a list of space-separated names that identify -loaders to be compiled. This is mainly used in the compiler's RTL sources. -\item[UNITOBJECTS] This is a list of unit names that will be compiled. The -makefile appends \mvar{PPUEXT} to each of these names to form the unit file -name. The sourcename is formed by adding \mvar{PASEXT}. -\item[ZIPNAME] is the name of the archive that will be created by the -makefile. -\item[ZIPTARGET] is the target that is built before the archive is made. -this target is built first. If successful, the zip archive will be made. \end{description} \subsection{Compiler command-line variables } @@ -4903,7 +4832,118 @@ of \var{OPT} is simply added to the compiler command-line. compiler. They do not get \var{-d} prepended. \end{description} -\subsection{Internal Compiler command-line variables} +\section{Variables set by \file{fpcmake}} + +All of the following variables are only set by \file{fpcmake}, if +they aren't already defined. This means that you can override them by +setting them on the make commandline, or setting them in the \var{presettings} +section. But most of them are correctly determined by the generated +\file{Makefile} or set by your settings in the configuration file. + +The following sets of variables are defined: +\begin{itemize} +\item Directory variables. +\item Program names. +\item File extensions. +\item Target files. +\end{itemize} +Each of these sets is discussed in the subsequent: + +\subsection{Directory variables} + +The following directories are defined by the makefile: + +\begin{description} +\item[BASEDIR] is set to the current directory if the \file{pwd} command is +available. If not, it is set to '.'. + +\item[BASEINSTALLDIR] is the base for all directories where units are +installed. By default, On \linux, this is set to +\mvar{PREFIXINSTALLDIR}\var{/lib/fpc/}\mvar{RELEASEVER}.\\ On other systems, +it is set to \mvar{PREFIXINSTALLDIR}. You can also set it with the +\var{basedir} variable in the \var{Install} section. + +\item[BININSTALLDIR] is set to \mvar{BASEINSTALLDIR}/\var{bin} on \linux, +and\\ \mvar{BASEINSTALLDIR}/\var{bin}/\mvar{OS\_TARGET} on other systems. +This is the place where binaries are installed. + +\item[GCCLIBDIR] (\linux only) is set to the directory where \file{libgcc.a} +is. If \var{needgcclib} is set to \var{True} in the \var{Libs} section, then +this directory is added to the compiler commandline with \var{-Fl}. + +\item[LIBINSTALLDIR] is set to \mvar{BASEINSTALLDIR} on \linux,\\ + and \mvar{BASEINSTALLDIR}/\var{lib} on other systems. + +\item[NEEDINCDIR] is a space-separated list of library paths. Each +directory in the list is prepended with \var{-Fl} and added to the +compiler options. Set by the \var{incdir} keyword in the \var{Dirs} section. + +\item[NEEDLIBDIR] is a space-separated list of library paths. Each +directory in the list is +prepended with \var{-Fl} and added to the compiler options. +Set by the \var{libdir} keyword in the \var{Dirs} section. + +\item[NEEDOBJDIR] is a list of object file directories, separated by + spaces. Each directory in the list is prepended with \var{-Fo} and +added to the compiler options. +Set by the \var{objdir} keyword in the \var{Dirs} section. + +\item[NEEDUNITDIR] is a list of unit directories, separated by spaces. +Each directory in the list is prepended with \var{-Fu} and is added to the +compiler options. +Set by the \var{unitdir} keyword in the \var{Dirs} section. + +\item[TARGETDIR] This directory is added as the output directory of +the compiler, where all units and executables are written, i.e. it gets +\var{-FE} prepended. It is set by the \var{targtdir} keyword in the +\var{Dirs} section. + +\item[TARGETUNITDIR] If set, this directory is added as the output directory of +the compiler, where all units and executables are written, i.e. it gets +\var{-FU} prepended.It is set by the \var{targtdir} keyword in the +\var{Dirs} section. + +\item[PREFIXINSTALLDIR] is set to \file{/usr} on \linux, \file{/pp} on \dos +or \windowsnt. Set by the \var{dirprefix} keyword in the \var{Install} +section. + +\item[UNITINSTALLDIR] is where units will be installed. This is set to\\ +\mvar{BASEINSTALLDIR}/\mvar{UNITPREFIX} \\ +on \linux. On other systems, it is set to \\ +\mvar{BASEINSTALLDIR}/\mvar{UNITPREFIX}/\mvar{OS\_TARGET}. +\end{description} + +\subsection{Target variables} + +The second set of variables controls the targets that are constructed +by the makefile. They are created by \file{fpcmake}, so you can use +them in your rules, but you shouldn't assign values to them yourself. + +\begin{description} +\item[EXEOBJECTS] This is a list of executable names that will be compiled. +the makefile appends \mvar{EXEEXT} to these names. It is set by the +\var{programs} keyword in the \var{Targets} section. + +\item[LOADEROBJECTS] is a list of space-separated names that identify +loaders to be compiled. This is mainly used in the compiler's RTL sources. +It is set by the \var{loaders} keyword in the \var{Targets} section. + +\item[UNITOBJECTS] This is a list of unit names that will be compiled. The +makefile appends \mvar{PPUEXT} to each of these names to form the unit file +name. The sourcename is formed by adding \mvar{PASEXT}. +It is set by the \var{units} keyword in the \var{Targets} section. + +\item[ZIPNAME] is the name of the archive that will be created by the +makefile. +It is set by the \var{zipname} keyword in the \var{Zip} section. + +\item[ZIPTARGET] is the target that is built before the archive is made. +this target is built first. If successful, the zip archive will be made. +It is set by the \var{ziptarget} keyword in the \var{Zip} section. + +\end{description} + +\subsection{Compiler command-line variables} The following variables control the compiler command-line: \begin{description} @@ -4914,86 +4954,27 @@ command line. This is determined by the Makefile itself. \item[CPU\_TARGET] the target CPU type is added as a define to the compiler command line. This is determined by the Makefile itself. -\item[LIBNAME] if smartlinking is requested (i.e. \var{SMARTLINK} is set to -\var{YES}), this is the name of the static library to produce. Don't add -\var{lib} to this, the compiler will do that. +\item[LIBNAME] if a shared library is requested this is the name of the +shared library to produce. Don't add \var{lib} to this, the compiler will +do that. +It is set by the \var{libname} keyword in the \var{Libs} section. \item[NEEDGCCLIB] if this variable is defined, then the path to \file{libgcc} is added to the library path. +It is set by the \var{needgcclib} keyword in the \var{Libs} section. \item[NEEDOTHERLIB] (\linux only) If this is defined, then the makefile will append all directories that appear in \var{/etc/ld.so.conf} to the library path. +It is set by the \var{needotherlib} keyword in the \var{Libs} section. \item[OS\_TARGET] What platform you want to compile for. Added to the compiler command-line with a \var{-T} prepended. -\item[SMARTLINK] if \var{SMARTLINK} is set to \var{YES} then the compiler -will output smartlinked units if \var{LIBTYPE} is not set to \var{shared}. +%\item[SMARTLINK] if \var{SMARTLINK} is set to \var{YES} then the compiler +%will output smartlinked units if \var{LIBTYPE} is not set to \var{shared}. \end{description} -\section{Variables set by \file{fpcmake}} - -All of the following variables are only set by \file{fpcmake}, if -they aren't already defined. This means that you can override them by -setting them on the make command line, or setting them in the \var{presettings} -section. But most of them are correctly determined by the generated -\file{Makefile}. -The following sets of variables are defined: -\begin{description} -\item[Directory variables] -\item[Program names] -\item[File extensions] -item[Target files] -\end{description} -Each of these sets is discussed in the subsequent: -\subsection{Directory variables} - -The following directories are defined by the makefile: - -\begin{description} -\item[BASEDIR] is set to the current directory if the \file{pwd} command is -available. If not, it is set to '.'. - -\item[BASEINSTALLDIR] is the base for all directories where units are -installed. On \linux, this is set to -\mvar{PREFIXINSTALLDIR}\var{/lib/fpc/}\mvar{RELEASEVER}.\\ On other systems, -it is set to \mvar{PREFIXINSTALLDIR} - -\item[BININSTALLDIR] is set to \mvar{BASEINSTALLDIR}/\var{bin} on \linux, -and\\ -\mvar{BASEINSTALLDIR}/\var{bin}/\mvar{OS\_TARGET} on other systems. This is -the place where binaries are installed. - -\item[GCCLIBDIR] (\linux only) is set to the directory where \file{libgcc.a} -is. - -\item[LIBINSTALLDIR] is set to \mvar{BASEINSTALLDIR} on \linux,\\ - and \mvar{BASEINSTALLDIR}/\var{lib} on other systems. - -\item[OTHERLIBDIR] (\linux only) is set to the full set of paths in \file{/etc/ld.so.conf} - -\item[PREFIXINSTALLDIR] is set to \file{/usr} on \linux, \file{/pp} on \dos -or \windowsnt. - -\item[SHARED\_LIBINSTALLDIR] is where shared libraries are -installed. This equals \mvar{PREFIXINSTALLDIR}/\var{lib} on \linux, and -\var{SHARED\_UNITINSTALLDIR} on other systems. - -\item[SHARED\_UNITINSTALLDIR] is where units from libraries are -installed. This equals \mvar{UNITINSTALLDIR}/\var{shared} - -\item[STATIC\_LIBINSTALLDIR] is where static libraries will be -installed. By default, it equals \mvar{STATIC\_UNITINSTALLDIR}. - -\item[STATIC\_UNITINSTALLDIR] is where static, smartlinked units will be -installed. It equals \mvar{UNITINSTALLDIR}/\var{static}. - -\item[UNITINSTALLDIR] is where units will be installed. This is set to\\ -\mvar{BASEINSTALLDIR}/\mvar{UNITPREFIX} \\ -on \linux. On other systems, it is set to \\ -\mvar{BASEINSTALLDIR}/\mvar{UNITPREFIX}/\mvar{OS\_TARGET}. -\end{description} \subsection{Program names} @@ -5056,7 +5037,6 @@ the first \var{UNITOBJECTS} files. \subsection{Target files} The following variables are defined to make targets and rules easier: - \begin{description} \item[COMPILER] is the complete compiler commandline, with all options added, after all \file{Makefile} variables have been examined. @@ -5067,14 +5047,14 @@ makefile. by the makefile. \item[LOADEROFILES] is a list of object files that will be made from the loader assembler files. This is mainly for use in the compiler's RTL sources. -\item[UNITFILES] a list of unit files that will be made. This is just +\item[UNITPPUFILES] a list of unit files that will be made. This is just the list of unit objects, with the correct unit extension appended. \item[UNITOFILES] a list of unit object files that will be made. This is just the list of unit objects, with the correct object file extension appended. \end{description} -\section{Rules and targets created by \file{makefile.fpc}} +\section{Rules and targets created by \file{fpcmake}} The \var{makefile.fpc} defines a series of targets, which can be called by your own targets. They have names that resemble default names (such as @@ -5098,8 +5078,8 @@ loaders. If \var{DEFAULTUNITS} is defined, executables are excluded from the targets. \item[fpc\_exes] target to make all executables in \var{EXEOBJECTS}. \item[fpc\_loaders] target to make all files in \var{LOADEROBJECTS}. -\item[fpc\_sharedlib] target that makes all units as dynamic libraries. -\item[fpc\_staticlib] target that makes all units as smartlinked units. +\item[fpc\_shared] target that makes all units as dynamic libraries. +\item[fpc\_smart] target that makes all units as smartlinked units. \item[fpc\_units] target to make all units in \var{UNITOBJECTS}. \end{description} @@ -5108,8 +5088,6 @@ targets. The following cleaning targets are defined: \begin{description} \item[fpc\_clean] cleans all files that result when \var{fpc\_all} was made. -\item[fpc\_libsclean] is the same as \var{fpc\_clean}, but also removes any -shared or dynamic libraries that may have been built. \item[fpc\_cleanall] is the same as both previous target commands, but also deletes all object, unit and assembler files that are present. \end{description} @@ -5118,14 +5096,13 @@ deletes all object, unit and assembler files that are present. The following archiving targets are defined: \begin{description} -\item[fpc\_zipinstalladd] will add to a (possibibly existing) archive file (it's -name is taken from \mvar{ZIPNAME}. -\item[fpc\_zipinstall] is the same, only the archive is cleared first. +\item[fpc\_zipinstall] will create an archive file (it's +name is taken from \mvar{ZIPNAME}) from the compiled units. +\item[fpc\_zipsourceinstall] will create an archive file (it's +name is taken from \mvar{ZIPNAME}), from the sources. \end{description} The zip is made uzing the \var{ZIPEXE} program. Under \linux, a \file{.tar.gz} file is created. - - \subsection{Informative rules} The following targets produce information about the makefile: