This file explains how to generate executables by compiling the MCPP
source.  For further details, please refer to mcpp-porting.html.

1. Types of MCPP executables

There are several types of MCPP executable corresponding to its building
methods.  The building methods of MCPP have following two axis:

    1. stand-alone-build vs subroutine-build
    2. compiler-independent-build vs compiler-specific-build

stand-alone-build:  The preprocessor which is invoked as a command.
    Some of this type is invoked by compiler-driver.
subroutine-build:  The preprocessor to be called as a subroutine
    (repeatedly, if required) from other main program.

compiler-independent-build:  The preprocessor which behaves on its own
    not depending on any compiler system.  The invocation options, for
    example, are the same across the compilers with which MCPP is
    compiled.  Although it can preprocess source files, it cannot behave
    as an integrated part of the compiler system.
    While V.2.6 and V.2.6.1 called this as 'stand-alone-build', V.2.6.2
    changed the name according to the creation of subroutine-build.
compiler-specific-build:  The preprocessor to replace (if possible) the
    resident preprocessor of certain compiler system.  It has some
    specifications for the compiler system only and is installed into
    the compiler-system-specific directory.

This document does not explain subroutine-build.  As for it, please
refer to mcpp-porting.html 3.12.  All the explanations below are of
stand-alone-build.

2. Configure and make

To compile MCPP, the configure script can be used on UNIX-like systems
and CygWIN, MinGW.  You can do configure and make in any directory.  In
this document ${mcpp-dir} represents the path of 'mcpp-2.6.4' directory.

2.1. The compiler-independent-build

If you type the commands as:

    ${mcpp-dir}/configure; make; make install

the compiler-independent executable will be generated and installed.
Also a few document files will be installed.

    ${mcpp-dir}/configure --prefix=/usr; make; make install

will install the executable into 'bin' directory in the directory
specified by '--prefix' option.  If this option is omitted, the
directory defaults to '/usr/local'.

'make install' usually requires root privilege, and you can do it by:

    sudo make install

or by first 'su', then 'configure; make; make install'.
On FreeBSD, you'd better to use 'gmake' instead of 'make'.
To strip the executable, do:

    make install-strip

instead of 'make install'.

To uninstall the executable, do:

    make uninstall

If you specify 'DESTDIR=DIR' option with make (un)install, all the files
will be installed under (or uninstalled from) the 'DIR' directory.  For
example,

    make DESTDIR=/tmp/mcpp install

will install mcpp into '/tmp/mcpp/usr/local/bin/', (Non-existent
directories will be generated.  If '--prefix=DIR' option was specified
in configure, '/usr/local' part will be replaced by 'DIR').  This option
is used to make a binary package.

GCC 4.1 or later has the option '-fstack-protector' ('-fstack-protector-
all').  You can enable it by adding 'CFLAGS+=-fstack-protector' option
to configure or make command.  The same can be said on GCC-specific-
build.

Though the Makefile of MCPP had 'install-data' and 'uninstall-data'
targets upto V.2.6.2, these targets were abolished at V.2.6.3, because
copying of documents and Validation Suite to another directory is not
necessary when one installs MCPP from the source.  However, 'make
install' of compiler-independent-build installs the least documents as
well as the executable.  This is for the convenience of making a binary
package.

Note that on Linux and CygWIN the system's standard headers have certain
defects, and some workarounds are necessary for the compiler-independent-
build of MCPP.  See mcpp-manual.html 3.9.9 for this problem.

2.2. The compiler-specific-build

This command will generate a compiler-specific executable and will
install it into the compiler-specific directory.

    ${mcpp-dir}/configure --enable-replace-cpp; make; make install

'make install', 'make install-strip', 'make uninstall' are the same as
compiler-independent-build.  '--prefix' option of configure is also the
same, though this is irrelevant to the installation directory of the
executable.  'DESTDIR' option of make has also no relevance to the
executable's installation.

For the compiler systems other than GCC, however, it may not be compiled
or installed properly if some porting work has not been done beforehand
and if some of the options are not specified with configure.

2.2.1 When the compiler system is GCC.

When the compiler system is GCC, the appropriate settings will be set by
the configure without any options other than '--enable-replace-cpp'.
After configuring, do 'make'.

2.2.1.1. make install

After configuring and 'make', the 'make install' command installs MCPP
into the compiler's directory (e.g. /usr/libexec or /usr/lib/gcc-lib/
i686-pc-linux-gnu/VERSION).  This is the directory where cpp (cc1),
which is called by gcc, is located.  'make install' saves GCC / cpp0
(cc1) and setups gcc and g++ command appropriately to call MCPP.  This
setting is different depending on GCC being V.2.* or V.3.*-4.*. (Refer
section 3.9.5 and 3.9.7 of mcpp-manual.html).

2.1.1.2. make check

In the MCPP Validation Suite, there is an edition which can be used as
testsuite of GCC.  If GCC / testsuite has been installed, 'make check'
can test MCPP using the testsuite edition of Validation Suite.  Because
this edition is to be used as a part of GCC / testsuite, the testsuite
should be installed and ready to execute in advance.  GCC / testsuite is
usually a part of the source code of GCC. (It can be a separate package
in some cases.)

Also, 'configure' needs an option to specify the directory where GCC /
testsuite is located, as below:

    ${mcpp-dir}/configure --with-gcc-testsuite-dir=DIR  \
            --enable-replace-cpp

If the directory where GCC source is located is ${gcc-source}, this
'DIR' should become:

    ${gcc-source}/gcc/testsuite

Configured as above, 'make check' after 'make; make install' copies the
testsuite edition of Validation Suite into GCC / testsuite.  After the
required settings are applied according to whether GCC is V.2.* or V.3.*
-4.*, the testsuite will be executed.  Usually, 'make check' would run
before 'make install' in the normal software, but this order is reversed
in MCPP.  This is because testsuite cannot be applied to MCPP unless
MCPP is called from gcc.  Due to this, the option '--enable-replace-cpp'
is also required.

The testsuite edition of Validation Suite can also be applied to cpp0
(cc1) of GCC V.2.95 and later, not only for MCPP.  (Refer cpp-test.html
section 3.2.3).

2.2.1.3. make uninstall

When you type 'make uninstall', the executables of MCPP will get deleted.
The settings of gcc and cpp0 (cc1) will be reset to the initial state.
When the re-execution of configure is required after completing
'make install' for some reason, 'make uninstall' needs to be done
beforehand.  This is because the configure must check GCC, not MCPP.

If you have done 'make check', the 'make uninstall' will also remove the
testsuite edition of Validation Suite.  If you want to use Validation
Suite for GCC, copy it manually.

The Makefiles generated by configure are necessary to do
'make uninstall', so you should not remove them.  When you do
'make distclean', first do 'make uninstall', because it is a little
troublesome to uninstall MCPP manually.

2.2.2. When the compiler system is not GCC

When the compiler system is not GCC, some options need to be specified
in the configure.  Also, to use MCPP replacing the preprocessor of the
compiler system, the "porting" or adding source code is required.  MCPP
have already been ported to GCC, because the author is using GCC on
Linux, FreeBSD or CygWIN systems, and so the informations can be
collected by the configure.  However, as he does not know any compiler
systems on UNIX-like systems other than GCC, he does not even know what
or how it needs to be checked by the configure, let alone the porting.

For compiler systems other than GCC on UNIX systems, please compile with
the following procedures.

2.2.2.1. Configure by specifying options

First, do configure by specifying some options, for example:

    ${mcpp-dir}/configure --enable-replace-cpp --bindir=DIR \
            --with-cxx-include-dir=CXXDIR   \
            --enable-SYSTEM-STD-macro=_MACRO=val

Specify the directory where the preprocessor, which is called from the
compiler-driver, is located with --bindir, specify the C++ specific
include directory with --with-cxx-include-dir and specify the predefined
macro of the resident preprocessor with --enable-SYSTEM-STD-macro or
other options.

If you type

    ${mcpp-dir}/configure --help

some options will be displayed.

Then, after doing 'make; make install', some work for making mcpp
callable from the compiler driver is required.  Please see the setup on
GCC for how to do this.

2.2.2.2. "Porting" work

To be able to use the MCPP replacing the preprocessor of the compiler
system, it is required to do "porting" work by adding source code.
These are the execution options for the compiler system or the
implementation of #pragma directives.  Especially, when there are some
execution time options which are used frequently but different from MCPP,
they at least need to be implemented.  In order to do that, define the
macro to designate the compiler in configed.H, and write some codes in
system.c. (Refer mcpp-porting.html 4.2).

2.2.2.3. Re-configure by adding an option

Once porting of source is completed, re-configure by adding the option
--with-compiler-name=COMPILER.  'COMPILER' is the macro for the compiler
defined in configed.H.

After 'make; make install' is done successfully, do 'make clean; make'
which recompiles MCPP using the installed MCPP.  If it passes, it can be
said that basic porting has been done successfully.

2.2.3. The limitations of the configure

In the compilation of compiler-specific-build of MCPP, the
specifications of the target system (the compiler system which will use
MCPP as a preprocessor) must be understood in detail.  At the same time
the host system (the compiler system with which MCPP is compiled) need
to be understood.  In case these two are not the same, the source code
of MCPP is written with the settings of both systems separately in the
header file (configed.H).  However, the configure cannot detect both of
them at the same time.  Therefore, it assumes the target system is the
same as the host system.

If these two systems are not the same, Part 2 of the configed.H needs to
be modified.

Cross-compiling is not supported by the configure of MCPP, either.  Some
tests which cannot be executed by the cross-compiler are included as
well.  In case of cross-compiling, the default values will be set, but
this may not work.  In any case, the author himself has never used a
cross-compiler, so he is not sure.

3. 'make' on the Windows compiler systems

Since all compiler systems on Windows other than CygWIN and MinGW are
not subject to the 'configure', they need a bit of modification of the
source in order to do 'make'.  As there are difference files for already
ported systems, a patch can be applied by using them.  The procedure for
the use of the difference files is explained below.

Even the systems subject to the 'configure' can also be controlled in
detail by editing the makefile and header files directly.

3.1. Applying a patch

The difference files and makefiles for various compiler systems are
available in 'noconfig' directory.  The source of MCPP is defaulted to
FreeBSD / GCC 3.4 setting.  The difference files are used in order to
modify this source for the particular compiler systems.  The makefile is
written for using the make command attached to each compiler system.

In the 'src' directory, run as below.  All of the following process
should be done within the 'src' directory.

    patch -c < ..\noconfig\which-compiler.dif
    copy ..\noconfig\which-compiler.mak Makefile

'patch' is a UNIX command, but it can be used in Windows as it has been
ported.  Of course, you can directly edit the noconfig.H file referring
the difference file.

3.2. Modifying noconfig.H and Makefile if required

The settings of various directories in the difference files are based on
the environment of the author, hence you must modify them.

If the version of the compiler system is different from that of the
difference file, modify the header file noconfig.H.  (See noconfig.H
itself and mcpp-porting.html 3.1).  Similarly, if the multi-byte
character for normal use is not Japanese, change the macro definition
MBCHAR in noconfig.H.

Also, define BINDIR in the Makefile to the directory in which mcpp
executable should be installed.  As for the Makefile for Visual C,
remove '#' of this line and make 'install' target effective.

    #install :

3.3. Compiler-independent-build

Now, you can do 'make' and 'make install' successfully for the compiler-
independent executable. (For Visual C, use 'nmake' instead of 'make').

3.4. Compiler-specific-build

To make the compiler-specific-build, rewrite BINDIR in the Makefile to
the directory in which the executables of the compiler system are
located.  Then, rewrite this line in noconfig.H:

    #define COMPILER    INDEPENDENT

Replace 'INDEPENDENT' with the macro to designate the compiler.  Then do
'make' and 'make install'.  'COMPILER' can be overwritten also by make
option, hence the file can be left as it is.  For example, in Visual C,
'nmake COMPLIER=MSC' and 'nmake COMPILER=MSC install' or in Borland C,
'make -DCOMPILER=BORLANDC' and 'make -DCOMPILER=BORLANDC install'.

If the target system and the compiling system are different, noconfig.H
/ Part 1 should be set to the specifications of the target system and
Part 2 should be set for the compiling system.  The Makefile that should
be used is the compiling system's one, and modify the installation
directory to the target system's one.

Since most compiler systems on Windows integrate preprocessor into its
compiler, it is impossible to replace the preprocessor of such a one-
path compiler with MCPP.  To use MCPP, a source program should be first
preprocessed with MCPP and then the output should be passed to the
compiler.  To use MCPP with a one-path compiler, the procedure must be
written in makefile.  For sample procedures, refer to the makefile's
settings used to recompile MCPP using MCPP itself.

In Visual C++, if you create "makefile project" by IDE using the
attached makefile, all the functions of IDE, such as source level debug,
become available. (Refer mcpp-manual.html 2.10)

3.5. Test

On Windows, any include directory is not preset except MinGW/GCC-
specific-build and GygWIN, hence you must specify them by the
environment variable INCLUDE (and CPLUS_INCLUDE, if necessary).

GCC / testsuite cannot be used in Windows, MCPP needs to be checked
directly by preprocessing the test samples in test-t, test-c and test-l
directories.  If you use tool/cpp_test.c, it can test some parts
automatically. (Refer cpp-test.html 3.2.2).

For the compiler-specific-build of MCPP, if you re-compile MCPP with the
"pre-preprocess" functionality of MCPP, by using MCPP itself as the
preprocessor of the compiler system, you can check whether it has been
ported successfully for the compiler system. (Refer mcpp-porting.html 3.
7)

4. Please send me the information for porting.

To port to the compiler systems which have not been ported yet, lots of
information is required.  It will be great to hear from many people.

Please let me know if you know the values for options of the 'configure',
for compiler systems other than GCC.  I would like to work on configure.
ac.

5. Validation Suite

MCPP provides "Validation Suite" which tests and evaluates C/C++
preprocessor comprehensively.  Validation Suite has 265 items and can be
applied to any preprocessor as well as MCPP.  Refer to 3.1 and 3.2 of
cpp-test.html.

May, 2007
Kiyoshi Matsui <kmatsui@t3.rim.or.jp>