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 a compiler system.

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-${VERSION}'

directory.  The ${VERSION} represents the version of MCPP such as 2.6.4

or 2.7.1.

The configure script searches for compilers by name of 'cc' ('c++') and

'gcc' ('g++') according to the path list set in the environment variable

$PATH.  So, if you use compilers named like 'gcc-4.3.0' and 'g++-4.3.0',

you have to specify them by CC and CXX environment variables, or link

them to 'gcc' and 'g++', prior to do configure.  If you use a pair of

compilers other than the one first found in the path list, you have to

change the $PATH such as:

    export PATH=/my/gcc/bin:$PATH

The setting should be kept the same while you do 'configure' and 'make'.

Do not specify a compiler by CC or CXX variable with any directory part,

even in an absolute path, when it is not the first one found in the

$PATH, because $PATH influences everything of configure.

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 by

name of 'mcpp'.  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 make command.  The same can be said on GCC-specific-build.  Also, you

can use "CFLAGS+='-ggdb -O0'" option to debug mcpp by gdb.

'make install' of compiler-independent-build installs a few documents as

well as the executable.  This is for the convenience of making a binary

package.

Note that on Linux, Mac OS X, CygWIN and MinGW, 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 line of commands 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.

The prefix directory is automatocally set from the path of GCC: for

example, '/usr/local' of '/usr/local/bin/gcc'.  If you specify --prefix

option for configure and it conflicts with the GCC path, the --prefix

option will be ignored.  '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/

SYSTEM/VERSION).  This is the directory where cc1 (cpp0), which is

called by gcc, is located.  'make install' saves GCC / cc1, cc1plus

(cpp0) 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).  In addition, it generates

some GCC-version-dependent header files under 'mcpp-gcc*' directory in

compiler-specific include directory.

2.2.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.)  You can use any version of testsuite from GCC V.2.95.*

to V.4.2.*.

Also, 'configure' needs an option to specify the directory where GCC /

testsuite is located, as:

    ${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, and applies

required settings according to whether GCC is V.2.* or V.3.*-4.*.  When

the name of the gcc command is not 'gcc', for example 'gcc-4.1.2' or

'powerpc-apple-darwin9-gcc-4.0.1', 'make check' links 'gcc' to that name

temporarily, because GCC testsuite expects literal 'gcc' for the name.

Then, the testsuite will be executed.  Usually, 'make check' would be

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.

Depending on the location of ${gcc-source} directory, you should do

'sudo make check' instead of 'make check'.  In this case, make sure that

gcc is the same between root and the current user.

The testsuite edition of Validation Suite can also be applied to cc1,

cc1plus (cpp0) of GCC V.2.95 and later, not only for MCPP.  (Refer cpp-

test.html 3.2.3).

2.2.1.3. make uninstall

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

The header files in mcpp-gcc* directory will be deleted, too.  The

settings of gcc and cc1, cc1plus (cpp0) 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 should 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 GCC-specific-MCPP manually.  Also you should do 'make

uninstall; make distclean' even before updating configure or Makefile.in,

when you update MCPP.

2.2.2. When the compiler system is Apple-GCC on Mac OS X

Although Mac OS X is one of the UNIX-like systems, it has some

peculiarities such as "framework" directories.  Its system compiler is a

GCC with many extensions added by Apple.  Moreover, since the appearance

of Intel-Mac, both of the compiler system for x86 and the compiler

system for powerpc, one is a native compiler and the other is a cross

compiler, begun to co-exist in a same machine.  And even a so-called

"universal binary", which is a bundle of binaries for x86 and powerpc,

hence is able to work on either machine, has become popular.  The

structure of compiler systems is rather complex.

To install MCPP for this complex system, the command sequence of 2.2.1

is not sufficient.  Here, I explain the case of Mac OS X / Apple-GCCs

apart from other UNIX.  I am using Mac OS X Leopard on Intel-Mac, so I

take the examples of the system.  If you use Powerpc-Mac, read the

section below swapping 'i686' and 'powerpc'.  On Tiger, read 'darwin9'

as 'darwin8'.

Apple provides GCC 4.0.1, and also provides GCC 3.3 as an addition.  I

explain only GCC 4.0.1, and omit GCC 3.3, because it has not been

properly compiled at least on Leopard.

2.2.2.1. Native compiler versus cross compiler

It is simple to compile and install MCPP for a native compiler, i.e. for

x86 on Intel-Mac.  The command sequence in 2.2.1 is sufficient for it.

Making of MCPP with a cross compiler, however, is not so easy.

Generally, the configure script of MCPP does not support cross compiling,

because it contains a few tests to be compiled and executed.  A binary

for a target environment cannot be run on a build environment usually.

If we test the build environment instead, the results are not

necessarily the same with the target.

Nevertheless, on Mac OS X, we can exceptionally configure cross-

compiling for different CPUs in most cases.  First, Intel-Mac

automatically executes a ppc binary with an emulator.  Second, if the

build environment and the target differ only in CPU and its related

settings, and OS, its version and GCC's version are all the same between

them, we can substitute most of the tests of the target with that of the

build.

On Intel-Mac, for a compiler-independent-build, you should specify the C

compiler (the name of compiler driver) and C++ compiler by the

environment-variables CC and CXX.  There are many gccs and g++s in /usr/

bin of Mac OS X.  In Mac OS X Leopard on Intel-Mac, powerpc-apple-

darwin9-gcc-4.0.1 and powerpc-apple-darwin9-g++-4.0.1 are the C compiler

and the C++ compiler for powerpc.  (Actually, all the gccs and g++s in

/usr/bin are universal binaries of i386 and ppc.) In addition, you

should specify the target system by --target option.  In this case, you

should use the compiler's name removing '-gcc-4.0.1', i.e. powerpc-apple-

darwin9.  This is the configure command to make compiler-independent-

build:

    ${mcpp-dir}/configure --target=powerpc-apple-darwin9    \

            CC=powerpc-apple-darwin9-gcc-4.0.1      \

            CXX=powerpc-apple-darwin9-g++-4.0.1

On the other hand, ppc-Mac cannot execute an x86 binary, so you cannot

make the compiler-independent-build with this method.  Instead, you can

cross-compile it manually, using the difference file and mac_osx.mak.

See mcpp-porting.html#3.1.4 and #3.11, if needed.  You can also make a

universal binary on ppc-Mac with its native compiler using the configure,

as explained in the next section.

To make a GCC-specific-build, you should specify the C compiler by

--with-target-cc= option instead of CC and CXX as: (the configure deduce

the name of C++ compiler from the name of C compiler, replacing 'gcc'

with 'g++'.)

    ${mcpp-dir}/configure --target=powerpc-apple-darwin9    \

            --with-target-cc=powerpc-apple-darwin9-gcc-4.0.1    \

            --enable-replace-cpp

This configuration does not contain any running test of the target, so

it can be used on ppc-Mac too, changing 'powerpc' with 'i686'.

When the version of the default native compiler (gcc and g++) greatly

differs from that of the cross compiler specified by --with-target-cc=

option, you should specify a native compiler of a version as close as

possible to the target by the environment-variables CC and CXX.  The

compiler specified by CC (CXX) is to be used to build MCPP, while the

compiler specified by --with-target-cc= is the target compiler into

which MCPP is installed.

The cross compiler differs from the native compiler in libexec directory,

compiler-specific include directory and predefined macros.  The

configure with these options appropriately sets them.  These options

should be used for configure, not for make command.

Note that a cross compiler itself runs on a host system, so does a

compiler-specific-build MCPP installed "to a cross compiler".  On the

other hand, a compiler-independent-build MCPP compiled "with a cross

compiler" runs on a target system.  Also note that both of the GCC-

specific-build for the native compiler and for the cross compiler are

compiled by the native compiler, therefore, if you install both, you

should first install the one for the cross compiler.

2.2.2.2. Making a universal binary

To make a universal binary, specify the CPUs by -arch options and add

them to the 'make' command as "CFLAGS+='-arch i386 -arch ppc'".  The

valid CPU types are 'i386', 'x86_64', 'ppc' and 'ppc64'.  For example,

this command generates a bundled binary for 4 CPU types.

    make CFLAGS+='-arch i386 -arch x86_64 -arch ppc -arch ppc64'

The configure needs no special option for universal binary, it needs

only options for non-universal binary, if any.

GCC has '-isysroot DIR' or '--sysroot=DIR' options, which change root of

system include directories to DIR.  These options are not limited to Mac

OS, but are commonly used on Mac OS to compile a universal binary in

order to widen compatibility with older version of Mac OS.  For example,

if '-isysroot /Developer/SDKs/MacOSX10.4u.sdk' is specified, /usr/

include becomes /Developer/SDKs/MacOSX10.4u.sdk/usr/include.  This is an

example to compile a universal binary compatible with Mac OS X 10.4

(Tiger) on 10.5 (Leopard).  When you use this option in making MCPP, you

should also specify the version of SDK by -mmacosx-version-min= option.

Any universal binary of MCPP can be generated with a combination of the

above configure options and these make options, on either of compiler-

independent-build or GCC-specific-build, and on either of native

compiler or cross compiler.  This example shows the sequence to generate

a universal binary of compiler-independent-build compatible with Tiger

for i386 and ppc.  (Actually, you should write the '*' in one line.)

    ${mcpp-dir}/configure

    make CFLAGS+='-isysroot /Developer/SDKs/MacOSX10.4u.sdk     \

            -mmacosx-version-min=10.4 -arch i386 -arch ppc'

    sudo make install

2.2.3. 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, Mac OS X, CygWIN and MinGW 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.3.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.3.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.3.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.4. 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.

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 have to 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 should 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 should 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.

November, 2008

Kiyoshi Matsui <kmatsui@t3.rim.or.jp>