This file explains how to generate a preprocessor for the particular
compiler system by compiling the MCPP source.  For further details,
please refer to mcpp-porting.txt.

1. configure and make

To compile MCPP, the configure script can be used on UNIX-like systems
and CygWIN.  In the mcpp-2.5 directory, if you type the commands as:

    ./configure; make; make install

the executable program will be generated and installed.

To strip the executable, do 'make install-strip' instead of
'make install'.  To install the documents and the validation suite, do

    make install-data

The documents and the validation suite will get deleted, if you do

    make uninstall-data

By 'make', MCPP executable is generated as the following name.

    mcpp_std    : Standard conformant specification.

Furthermore, if you do 'configure' with the option '--enable-maintainer-
mode' and do 'make', the following will also get generated.

    mcpp_prestd : Specification for pre-C90 (i.e. K&R 1st).

Please refer to mcpp-manual.txt for the behavior specifications.

However, depending on the compiler systems, it may not be compiled or
installed properly if some of the options are not specified.

1.1  When the compiler system is GNU C.

1.1.1 configure and make

When the compiler system is GNU C, the appropriate settings will be set
by the 'configure' without any options.  After doing './configure', do
'make'.  The 'make' should be done in the mcpp-2.5 directory, which is
the parent directory, not in the 'src' directory.

1.1.2 make install

The 'make install' command installs into the normal program directory (e.
g. /usr/bin or /usr/local/bin) and also, into the compiler's directory
(e.g. /usr/libexec or /usr/lib/gcc-lib/i686-pc-linux-gnu/VERSION).  In
the former, MCPP can be run independently as a normal command, but this
is not called from gcc.  The latter is the directory where cpp (cc1),
which is called by gcc, is located.  In the latter installation, if you
do 'configure' with the option '--enable-maintainer-mode',
'make install' saves GNU C / cpp0 (cc1) and setups gcc appropriately to
call mcpp_std.  This setting is different depending on GNU C being V.2.*,
V.3.0 - 3.2 or V.3.3 - 3.4.  (Refer section 3.9.5 and 3.9.7 of mcpp-
manual.txt).

1.1.3 make check

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

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

    ./configure --with-gcc-testsuite-dir=DIR --enable-maintainer-mode

If the directory where GNU C 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 GNU C / testsuite.  After the
required settings are applied according to whether GNU C is V.2.* or V.3.
*, 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_std unless
mcpp_std is called from gcc.  Due to this, the option '--enable-
maintainer-mode' is also required.

The testsuite edition of Validation Suite can also be applied to cpp0
(cc1) of GNU C V.2.9x and V.3.*, not only for MCPP.  (Refer cpp-test.txt
section 2.2.3).

1.1.4 make uninstall

When you run 'make uninstall', the executables of MCPP will get deleted.

If you have done 'configure' with the option '--enable-maintainer-mode',
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 run
beforehand.  This is because the configure must check GNU C, not MCPP.

1.2 When the compiler system is not GNU C.

When the compiler system is not GNU C, 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 GNU C, because the author is using GNU C on
Linux, FreeBSD or CygWIN systems, and so the information is collected by
the configure.  However, as he does not know any compiler-systems on
Unix other than GNU C, he does not even know what or how it needs to be
checked by the configure, let alone the porting.

In compiler systems other than GNU C on Unix systems, please compile
with the following procedures.

1.2.1 configure by specifying options

At first, do 'configure' by specifying some options.  When running

    ./configure --help

some options should be displayed.  By these options, specify the
predefined macros of the compiler system and the C++ unique include
directory.

1.2.2 Do 'make; make install' and run as a stand-alone preprocessor.

When doing 'make; make install', mcpp_std become able to be run as a
normal command.  However in this state, you cannot use it as a
preprocessor of the compiler system.

1.2.3 "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.  (Refer mcpp-porting.txt 4.2).

1.2.4  Re-configure by adding options

Once porting of source is completed, after 'make uninstall', re-
configure by adding the option --libexecdir=DIR.  This 'DIR' is the
directory where the preprocessor called by the compiler driver will be
located.

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

1.3  The limitations of the configure

In the compilation of MCPP, the specifications of the target systems
(the compiler systems which will be using MCPP as a preprocessor) must
be understood in detail.  At the same time the compiler systems doing
the compile 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.

2. 'make' on the DOS/Windows compiler systems

Since all compiler systems on DOS/Windows other than CygWIN are not
subject to the 'configure', they need the modification of the source 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.

Please change the newline code of files for DOS/Windows systems
beforehand.

2.1 Applying a patch

The difference files and makefiles for various compiler systems are
available in the directory named 'noconfig'.  The source of MCPP is
defaulted to FreeBSD / GNU C 3.4 setting.  The difference files are used
in order to modify this source for the target 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 DOS/Windows as it has
been ported.

2.2  Modifying nonconfig.H and Makefile if required

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

Also, if the directory of the compiler system is different from the
default settings of the Makefile, then modify the line.

If the target system and the compiling system are different, nonconfig.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.

2.3  make and make install

Now, you can do 'make' and 'make install' successfully to the already
ported systems.  (For Visual C++, use 'nmake' instead of 'make').

In Visual C++ .net, 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.txt 2.10)

2.4  Test

GNU C / testsuite cannot be used in DOS/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.txt 2.2.2).

If you re-compile MCPP with the "pre-preprocess" functionality of MCPP,
by using MCPP itself as a preprocessor, you should be able to check if
it has been ported successfully for the compiler system.  (Refer mcpp-
porting.txt 3.7)

3. Compile on Plan 9

For the compiling on Plan 9, please see mcpp-porting.txt 3.1.8, 3.7.1.

4. Please send me the information for porting.

To be able to port to the compiler-systems which have not been supported
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 GNU C.  I would like to work on
configure.ac.

5. Validation Suite

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

March, 2005
Kiyoshi Matsui <kmatsui@t3.rim.or.jp>