This is a draft for reimplementing the compiler framework in pkgsrc.

= Introduction =

There are many compilers and related programs. Pkgsrc provides the
packages with a uniform environment in which the following variables are
set during the build. Additionally, some wrappers are created for each
of the programs, with the names in parentheses.

TRADITIONAL_CPP	(traditional-cpp)
	A traditional C preprocessor that can also be used for
	processing files other than C source code. For example,
	editors/emacs needs such a program to preprocess Makefiles.

CPP (cpp)
	A C preprocessor
CC (cc, gcc)
	A C compiler
C89 (c89)
	An ISO C90 compiler
C99 (c99)
	An ISO C99 compiler

CXXCPP (c++cpp)
	A C++ preprocessor
CXX (c++, CC, g++)
	A C++ compiler

F77 (f77, g77)
	A Fortran 77 compiler
F90 (f90)
	A Fortran 90 compiler
F95 (f95)
	A Fortran 95 compiler

AS (as)
	An assembler without preprocessor

LD (ld)
	A linker

= Selecting the compilers =

The user-settable variable PKGSRC_COMPILER contains a list of compilers
that should be used in that order. The package-settable variable
USE_LANGUAGES contains the languages that are needed by the package.
Based on these variables, the wrappers are created. The selection takes
place in two phases.

In phase one, all selected compilers are queried for their capabilities.

In phase two, the capabilities and dependencies are known, and the
wrapper programs are created from this information.

= Querying for capabilities =

In the first phase, for each compiler in PKGSRC_COMPILERS, the file
${compiler}-def.mk is loaded. This file contains the definition of the
compiler's capabilities.

The definition file starts by adding the compiler to the global list of
available compilers (_COMPILERS). Each compiler has a unique name which
is used as parameter for all variable names of that definition.

<programlisting>
    _COMPILERS+=    sunpro
</programlisting>

Each compiler defines a <quote>base directory</quote>, in which the
compiler is installed. There are two variables involved here: one is
user-settable and has the form ${NAME}_BASEDIR. The other
(_COMPILER_BASEDIR.*) is internal.

<programlisting>
    _COMPILER_BASEDIR.sunpro=       ${SUNPRO_BASE}
</programlisting>

The next definitions are only necessary if they deviate from the default
values, which can be seen in mk/compiler2/def.mk.

<programlisting>
    _COMPILER.sunpro.traditional-cpp= ${SUNPRO_TRADCPP}
    _COMPILER.sunpro.cpp=           ${SUNPRO_BASE}/bin/cc
    _COMPILER_PRE_ARGS.sunpro.cpp=  -E
    _COMPILER.sunpro.cc=            ${SUNPRO_BASE}/bin/cc
    _COMPILER.sunpro.c89=           ${SUNPRO_BASE}/bin/c89
    _COMPILER.sunpro.c99=           ${SUNPRO_BASE}/bin/c99
    ...

    _COMPILER.gcc2.c89=             ${GCC2_BASEDIR}/bin/gcc
    _COMPILER_PRE_ARGS.gcc2.c89=    -std=c89
    ...
</programlisting>

Pkgsrc can also handle compiler wrappers like ccache, distcc or f2c.
They are defined as above but need some additional variables. The
_COMPILER_NEEDS variable specifies what kind of compiler is needed for
implementing this compiler.

<programlisting>
    _COMPILER_NEEDS.f2c.f77=        cc
    _COMPILER_NEEDS.distcc.cc=      cc
    _COMPILER_NEEDS.distcc.c++ =    c++
</programlisting>

For example, if a package has set USE_LANGUAGES to "f77" and
PKGSRC_COMPILER  to "f2c gcc4", the compiler wrapper framework will see
that it needs an f77 compiler. The first one it finds is f2c. Then it
will notice that it needs a cc and continues its search with the gcc4
definition. Luckily, that compiler has set _COMPILER.gcc4.cc, so
everything is fine.