General improvement on viewing wide and long slog2 files. This added features needed...
[mpe.git] / INSTALL
1                       MPE (Multi-Processing Environment)
2                       ----------------------------------
3
4                           Version 2.4.6. March, 2008
5
6                     Mathematics and Computer Science Division
7                            Argonne National Laboratory
8
9 II. CONFIGURATION
10 -----------------
11
12 MPE can be configured and installed as an extension to most MPI standard
13 -compliant MPI implementations, e.g. MPICH-2, MPICH, LAM/MPI, Open/MPI,
14 SGI's MPI, HP-UX's MPI and IBM's MPI.  It has been integrated seamlessly
15 into MPICH and MPICH-2 distributions, so MPE will be installed automatically
16 during MPICH-X's installation process.  
17
18
19
20 II. a)  Configuration Model
21 ---------------------------
22
23 MPE is designed to be used as an extension to an existing MPI implementation,
24 so its configuration model assumes a general MPI development environment.  
25 Here are the major variables that MPE configure reads, all can be read 
26 through environment variables or as variables as part of configure command.
27 Some has --enable-xxx counterparts that can be read through configure command.
28
29 CC          : C compiler used to create serial executable,
30               e.g. xlc on BG/P MPI.
31 CFLAGS      : compiler flags for CC.
32
33 MPI_CC      : C compiler for MPI program, e.g. mpixlc_r for BG/P MPI,
34               or mpicc from MPICHx, Open-MPI, or LAM-MPI.  Setting MPI_CC
35               to MPI wrapper means no need to set MPI_INC and MPI_LIBS. 
36 MPI_CFLAGS  : MPI C compiler flags to compile MPI program.
37
38 F77         : Fortran compiler used to create serial executable,
39               e.g. xlf on BG/P MPI.
40 FFLAGS      : compiler flags for F77.
41
42 MPI_F77     : Fortran compiler for MPI program, e.g. mpixlf77_r for BG/P MPI,
43               or mpif77 from MPICHx, Open-MPI, or LAM-MPI. Setting MPI_F77 to
44               MPI wrapper means no need to set MPI_INC and MPI_LIBS.
45 MPI_FFLAGS  : MPI Fortran compiler flags to compile MPI Fortran program.
46
47 MPI_INC     : MPI include path prefixed with -I. It specifies MPI header files
48               location, where mpi.h and mpif.h are located, e.g.
49               -I/pkgs/MPI/include. This flag will be added to MPI_CFLAGS and
50               MPI_FFLAGS, i.e. the MPI include path can be explicitly set in
51               MPI_CFLAGS and MPI_FFLAGS without setting MPI_INC. 
52 MPI_LIBS    : MPI library flags with -L and -l. It specifies the location of
53               the MPI libraries. The flags contains library path prefixed with
54               -L and MPI libraries name prefixed with -l, e.g. -L/opt/MPI/lib
55               -lpmpich -lmpich.
56 F2CMPI_LIBS : compiler's library flag for Fortran to C MPI profiling wrapper
57               library, e.g. "-lfmpich" when MPI_CC=mpicc & MPI_F77=mpif77
58               for MPICH.
59
60 MPERUN      : MPI application launch command. This variable is necessary only
61               if user wants to run "make check", "make installcheck-all" or
62               "$sbindir/mpecheckinstall -run" and the default MPERUN value,
63               "$bindir/mpiexec -n 4", is not correct.  This variable does
64               not launch the process manager if it is required to run
65               the MPI application.  Therefore, user needs to make sure that
66               the MPI runtime environment has been set up correctly before
67               invoking "make check", "make installcheck-all" or
68               "$sbindir/mpecheckinstall -run".
69
70 It is recommended that user set these variables through configure command,
71 e.g mpe2/configure CC=xlc_r F77=xlf_r MPI_CC=mpixlc_r MPI_F77=mpixlf77_r.
72 In some MPI implementations, like HP-UX's, MPI_CC and MPI_F77 may have
73 been reserved for use by the MPI implementation, use the configure options,
74 --enable-xxx, to set MPI_CC and MPI_F77 instead.
75
76 For those who require Cross-Compilation support, please refer to the
77 INSTALL.cross file.
78
79
80 II. b)  Build Options and Features
81 ----------------------------------
82
83 MPE's configure is written using autoconf 2, and supports VPATH style install  
84 process.  It means the actual source directory and the building directory
85 can be in 2 different locations.  This allows the same source directory to be
86 used to build multiple versions of MPE with different options and still won't 
87 mess up the original source.  It is highly recommended that user should do a 
88 VPATH build.  Also MPE involves several different independent packages, in 
89 order to create a tightly integrated environment for user, it is recommended 
90 that user should do a "make install" to install the MPE in a separate directory
91 after the build is done.  The benefit is that all utility programs will be in
92 bin/, all libraries will be in lib/ and all graphic tools will be nicely 
93 organized in share/ ...  Finally, to test if the MPE installation is working
94 correctly, user is urged to do "make installcheck" or the demanding test
95 "make installcheck-all MPERUN='<path_to_mpiexec> -n 4'" in the build directory.
96
97 There are 2 types of configure options.
98
99         1)  MPI implementation and User options
100         2)  Generic configure flags supplied by autoconf 2
101
102 For a list of flags/switches for type 1 (not type 2) in MPE, do
103 "<mpe2>/configure --help=recursive".
104
105 For a more concise list of command line arguments like
106 --with-xxx and --enable-xxx, do
107 "<mpe2>/configure --help=recursive | grep "^--" | sort - | uniq"
108
109 The following is not a complete list but some of the more important ones.
110 Generic flags:
111 --prefix=INSTALL_DIR            Specifies the final install directory for 
112                                 "make install".  All libraries, utility
113                                 programs, graphic programs and examples
114                                 are installed in a standard directory
115                                 structure without files created in the
116                                 building process.
117
118 --x-includes=X_INC              Specifies the directory where X include
119                                 files are located.  This is used when
120                                 configure has trouble in locating X in
121                                 user system.
122
123 --x-libraries=X_LIBS            Specifies the directory where X libraries
124                                 are located.  This is used when configure
125                                 has trouble in locating X in user system.
126         
127
128 MPI implementation Options:
129 Besides the following command line options, the serial C and Fortran compilers
130 can be specified through typical environment variables CC and F77.
131
132 --with-mpicc=MPI_CC             Specify MPI C compiler to generate parallel
133                                 executable, e.g. mpcc for AIX.  This can be
134                                 specified through environmental parameter
135                                 MPI_CC.
136
137 --with-mpif77=MPI_F77           Specify MPI F77 compiler to generate parallel
138                                 executable, e.g. mpxlf for AIX.  This can be
139                                 specified through environmental parameter
140                                 MPI_F77.
141
142 --with-mpiinc=MPI_INC           Specify compiler's include flag for MPI 
143                                 include directory,
144                                 e.g. "-I/pkgs/MPI/include" for mpi.h 
145
146 --with-mpilibs=MPI_LIBS         Specify compiler's library flag for MPI 
147                                 libraries,
148                                 e.g. "-L/pkgs/MPI/lib -lpmpich -lmpich"
149
150 --enable-f77                    Enable the compilation of routines that 
151                                 require a Fortran compiler.  If configuring 
152                                 with MPICH, the configure in the top-level 
153                                 MPICH directory will choose the appropriate 
154                                 value for you.  However, it can be overridden.
155                                 The default is yes, --enable-f77.
156
157 --enable-f2cmpilib              Enable the building of MPE's internal Fortran 
158                                 to C MPI wrapper library.  The default is yes,
159                                 --enable-f2cmpilib
160
161 --with-f2cmpilibs=F2CMPI_LIBS   Specify compiler's library flags for Fortran
162                                 to C MPI wrapper library.  Using this option 
163                                 will force --disable-f2cmpilib.
164                                 e.g. "-lfmpich" when configuring MPE for MPICH
165
166 Other User Options:
167 --enable-echo                   Turn on strong echoing.  The default is no,
168                                 --disable-echo.
169
170 --with-mpelibname=MPE_LIBNAME   Specify the MPE library name instead of the 
171                                 default 'mpe'.  e.g. if MPE_LIBNAME="MPE",
172                                 then the libraries generated will be libMPE.a,
173                                 liblMPE.a, libtMPE.a, libaMPE.a and
174                                 libMPE_f2cmpi.a.  This option is necessary
175                                 when configuring MPE for a existing and older
176                                 version of MPICH which has MPE installed.
177
178 --enable-misc                   build MPE miscellaneous routines, e.g.
179                                 MPE_Errors_xxx(), MPE_Seq_xxx(),
180                                 MPE_xxxTags() and MPE_GetHostName()....
181                                 The default enable=yes.
182
183 --enable-logging                build MPE logging routines related to
184                                 CLOG-2, e.g.  MPE_Log_xxx()...
185                                 The default enable=yes.
186
187 --enable-wrappers               build various MPI wrapper libraries.
188                                 MPI logging library, liblmpe.a;
189                                 MPI tracing library, libtmpe.a;
190                                 Fortran to C MPI library, libmpe_f2cmpi.a.
191
192 --enable-graphics               build MPE graphics routines.  If disabled
193                                 then the MPE routines that make use of X11
194                                 graphics will NOT be built.  This is
195                                 appropriate for systems that either do not
196                                 have the X11 include files or that do not
197                                 support X11 graphics.  The default enable=yes.
198
199 --enable-collchk                bild MPI Collective and Datatype
200                                 checking library, libmpe_collchk.a
201
202 --enable-slog2[=build]          Configure all the SLOG-2 tools.
203                                 --enable-slog2 without any argument will
204                                 use the prebuilt jar files.
205                                 --enable-slog2=build will rebuild all the
206                                 jar files from the source code.
207                                 The default is enable=yes.
208
209 --with-java=JAVA_HOME           Specify the path of the top-level directory 
210                                 of the Java, j2sdk, installation.  If this 
211                                 option or --with-java2 is not given, 
212                                 slog2sdk configure will try to locate j2sdk
213                                 for you to build slog2 related tools. 
214
215 --with-java2=JAVA_HOME          Specify the path of the top-level directory
216                                 of the Java, j2sdk, installation.  If this
217                                 option or --with-java2 is not given, 
218                                 slog2sdk configure will try to locate j2sdk
219                                 for you to build slog2 related tools. 
220
221 In order to achieve maximum performance benefit, it is recommended to
222 use latest Java 2, i.e. JDK-1.4.x to build Jumpshot-4. 
223
224
225
226
227 III. INSTALLATION INSTRUCTIONS
228 -------------------------------  
229
230 As noted earlier, the MPE library can be installed as part of the MPICH
231 configure or as an extension of an existing MPI implementation.  Below are
232 instructions and examples for typical installation of MPE on popular MPI 
233 implementations. 
234
235
236
237 III. a)  Configuring as part of the MPICH-X configure
238 -----------------------------------------------------
239
240 The configure in the MPICH directory will try to determine the necessary 
241 information and pass it to the MPE configure.  If no options are given, 
242 the MPE will automatically be configured by default.  However, the user 
243 can provide extra configuration information to MPE through old MPICH-1 
244 configure with the following options:
245
246         -mpe_opts=MPE_OPTS
247
248 where MPE_OPTS is one or more of the choices in section II.  Multiple
249 instances of -mpe_opts are allowed to specify different options for 
250 the MPE configure.
251
252 The MPICH-2 configure works seamlessly with MPE's, so MPE configure
253 options can be passed down from MPICH-2 _without_ -mpe_opts.
254
255
256 III. b) Configuring as part of an existing MPI implementation
257 -------------------------------------------------------------
258
259 The following are some examples for configuring MPE for an existing
260 MPI implementation.
261
262 For SGI MPI, e.g. denali.mcs.anl.gov, do the following for default ABI, -n32
263
264     setenv MAKE gmake
265     ${MPE_SRC_DIR}/configure --with-mpilibs=-lmpi \
266                              --with-java=/usr/java-1.1.6/usr/java
267     make
268     make install PREFIX=${MPE_INSTALL_DIR}
269     make installcheck PREFIX=${MPE_INSTALL_DIR}
270
271 for 64 bits ABI, either set CC="cc -64" and F77="f77 -64" or add options
272 CFLAGS=-64 and FFLAGS=-64 to the configure options.
273
274
275 For IBM MPI, e.g. quad.mcs.anl.gov, do
276
277     setenv MPI_CC mpcc
278     setenv MPI_F77 mpxlf
279     ${MPE_SRC_DIR}/configure --with-java=/homes/chan/pkgs/java/J1.1.8
280     make
281     make install PREFIX=${MPE_INSTALL_DIR}
282     make installcheck PREFIX=${MPE_INSTALL_DIR}
283
284
285 For SUN MPI CLuster Tools 7 and older versions, do
286
287     setenv MPI_CC mpcc
288     setenv MPI_F77 mpf90
289     ${MPE_SRC_DIR}/configure --with-mpilibs="-L${MPI_LIB_DIR} -lmpi"
290     make
291     make install PREFIX=${MPE_INSTALL_DIR}
292     make installcheck PREFIX=${MPE_INSTALL_DIR}
293
294     without -L${MPI_LIB_DIR} in --with-mpilibs, mpe2 configure may fail.
295
296
297 For HP-UX's MPI implementation,
298
299     ${MPE_SRC_DIR}/configure --with-mpicc=mpicc \
300                              --with-mpif77=mpif77 \
301                              --with-flib_path_leader="-Wl,-L"
302     make
303     make install PREFIX=${MPE_INSTALL_DIR}
304     make installcheck PREFIX=${MPE_INSTALL_DIR}
305
306 If MPE's Fortran support on HP-UX's MPI is NOT working, try using
307 HP-UX's libfmpi.a if it is there.  Here is the configure options.
308
309     ${MPE_SRC_DIR}/configure --with-mpicc=mpicc \
310                              --with-mpif77=mpif77 \
311                              --with-flib_path_leader="-Wl,-L" \
312                              --with-f2cmpilibs=-lfmpi
313     make
314     make install PREFIX=${MPE_INSTALL_DIR}
315     make installcheck PREFIX=${MPE_INSTALL_DIR}
316
317 note: configure option --with-flib_path_leader="-Wl,-L" may not needed.
318
319
320 For LAM/MPI implementation, do
321
322     setenv MPI_CC ${LAM_INSTALL_DIR}/bin/mpicc
323     setenv MPI_F77 ${LAM_INSTALL_DIR}/bin/mpif77
324     ${MPE_SRC_DIR}/configure --with-mpilibs="-L${LAM_INSTALL_DIR}/lib -lpmpi" \
325                              --with-java=/sandbox/jdk1.3.1
326     make
327     make install PREFIX=${MPE_INSTALL_DIR}
328     make installcheck PREFIX=${MPE_INSTALL_DIR}
329
330     optional tests:
331     "launch the process manager": e.g. lamboot.
332     make installcheck-all PREFIX=${MPE_INSTALL_DIR} \
333                           MPERUN="<path_to_mpirun> -np 4"
334
335 Using MPE with LAM for fortran MPI program is not working until recently.  
336 Configure options listed above enable MPE's internal Fortran to C MPI library.
337 To use LAM's Fortran to C MPI library in LAM 6.3.3 or later, liblamf77mpi.a, 
338 do
339
340     setenv MPI_CC ${LAM_INSTALL_DIR}/bin/mpicc
341     setenv MPI_F77 ${LAM_INSTALL_DIR}/bin/mpif77
342     ${MPE_SRC_DIR}/configure --with-mpilibs="-L${LAM_INSTALL_DIR}/lib -lpmpi" \
343                              --with-f2cmpilibs=-llamf77mpi \
344                              --with-java2=/sandbox/jdk1.3.1
345     make
346     make install PREFIX=${MPE_INSTALL_DIR}
347     make installcheck PREFIX=${MPE_INSTALL_DIR}
348
349 LAM 6.5.6 to 6.5.9 has a bug on autoconf variable, WORDS_BIGENDIAN, that
350 interferes with MPE's configure in the correct detection of endianiness
351 of the machine, e.g. enabling byte swapping on little endian machine,
352 e.g. intel box.  For details, see
353
354 http://www.lam-mpi.org/MailArchives/lam/2002/09/4893.php
355 http://www.lam-mpi.org/MailArchives/lam/2002/09/4894.php
356 http://www.lam-mpi.org/MailArchives/lam/2002/09/4895.php
357 http://www.lam-mpi.org/MailArchives/lam/2002/09/4896.php
358
359 Preferred Solution: Upgrade to newer version of LAM.
360          Or
361 Temporary Solution: Hand edit src/logging/mpe_logging_conf.h to define
362                     correct WORDS_BIGENDIAN.
363
364 LAM 7.0 or later has included libpmpi.a into libmpi.a, so --with-mpilibs
365 may not be needed.
366
367 LAM 7.1.2b23 or older has a bug on MPI_*_c2f( MPI_*_NULL ) that causes
368 seg. fault, see
369 http://www.lam-mpi.org/MailArchives/lam/2005/08/11073.php
370 So fortran LAM/MPI program that uses Isend/Irecv cannot use libmpe_f2cmpi.a,
371 (the reason is that MPI_Wait on the request from Isend/Irecv returns
372 MPI_REQUEST_NULL which could not be translated by MPI_Request_c2f() in
373 libmpe_f2cmpi.a)
374
375 Preferred Solution: Upgrade to newer version of LAM, 7.1.2b24 or later
376          Or
377 Temporary Solution: Configured with --with-f2cmpilibs=-llamf77mpi. 
378
379
380 For OpenMPI, do
381
382     ${MPE_SRC_DIR}/configure MPI_CC=${OPENMPI_INSTALL_DIR}/bin/mpicc \
383                              CC=<C_COMPILER_used_to_build_OpenMPI> \
384                              MPI_F77=${OPENMPI_INSTALL_DIR}/bin/mpif77 \
385                              F77=<FORTRAN_COMPILER_used_to_build_OpenMPI> \
386                              --with-java2=/usr/local/j2sdk-1.4.2
387                              --prefix=<MPE_INSTALL_DIR>
388     make
389     make install
390     make installcheck
391     make installcheck-all MPERUN="${OPENMPI_INSTALL_DIR}/bin/mpiexec -n 4"
392
393 OpenMPI-1.0 does not instantiate MPI_F_STATUS(ES)_IGNORE, so fortran program
394 may not be able to use MPI_STATUS(ES)_IGNORE with OpenMPI+MPE.
395
396 See http://www.open-mpi.org/community/lists/users/2005/11/0380.php
397
398
399 For prebuilt version of MPICH-1: Since old MPICH-1 comes with an older version
400 of MPE.  The MPI wrappers that come with MPICH-1 searches old MPE headers
401 and link with old MPE libraries first.  To avoid using incompatible MPE
402 headers and libraries, MPE2 should be built with native compilers used in
403 MPI wrappers (i.e. setting CC and F77 but NOT MPI_CC and MPI_F77) and use
404 MPI_INC to specify MPI include path and MPI_LIBS to specify the MPI libraries.
405 e.g. on NCSA's Turing Mac cluster, configuing MPE2 for mpich-gm (which is
406 based on mpich-1.2.6):
407
408     ${MPE_SRC_DIR}/configure CC=cc F77="xlf90 -qnocommon -qextname -qfixed=72" \
409                              MPI_INC=-I/turing/software/mpich-gm/include       \
410                              MPI_LIBS="-Wl,-multiply_defined,suppress          \
411                                        -Wl,-u,_gmpi_macosx_malloc_hack         \
412                                        -L/turing/software/mpich-gm/lib         \
413                                        -lpmpich -lmpich -lpmpich -lmpich       \
414                                        -L/turing/software/lib -lgm -lpthread"  \
415                              --disable-safePMPI                                \
416                              --prefix=<MPE_INSTALL_DIR>
417     make
418     make install
419     make installcheck
420     make installcheck-all MPERUN="/turing/software/mpich-gm/bin/mpirun -n 4" 
421
422 MPE2 is careful in arranging its include files and libraries flags
423 during compilation, i.e. MPE2's include path is always searched before MPI's
424 and MPE's library path comes before MPI's, so to avoid conflicting headers
425 and libraries from older MPE installation.
426  
427 For prebuilt version of MPICH-1.1.2 or MPICH-1.2.0, e.g. donner, do
428
429     setenv MPI_CC ${MPICH_INSTALL_DIR}/bin/mpicc
430     setenv MPI_F77 ${MPICH_INSTALL_DIR}/bin/mpif77
431     ${MPE_SRC_DIR}/configure  --with-f2cmpilibs=-lfmpich \
432                               --with-mpelibname=newMPE \
433                               --with-java=/sandbox/j2sdk1.4.2
434     make
435     make install PREFIX=${MPE_INSTALL_DIR}
436     make installcheck PREFIX=${MPE_INSTALL_DIR}
437
438 It is important to use the configure option --with-mpelibname to specify a 
439 different MPE library name than the default "mpe" when configuring MPE for
440 older MPICH.  Without this option, the linkage tests in MPE would most likely
441 use the old MPE libraries in the MPICH instead of the newly built MPE 
442 libraries in resolving the MPE symbols.  Also the option --with-f2cmpilibs
443 forces MPE to use the Fortran to C MPI wrapper library in previous
444 version of MPICH.  Not using --with-f2cmpilibs would cause MPE to use
445 its own Fortran to C MPI profiling wrapper library. 
446
447
448 For BlueGene/Light's MPI implementation: If the compilers are set up correctly
449
450     ${MPE_SRC_DIR}/configure                                               \
451     MPI_CC=blrts_xlc MPI_F77=blrts_xlf CC=xlc F77=xlf                      \
452     MPI_INC="-I/bgl/BlueLight/ppcfloor/bglsys/include"                     \
453     MPI_LIBS="-L/bgl/BlueLight/ppcfloor/bglsys/lib                         \
454              -lmpich.rts -lmsglayer.rts -lrts.rts -ldevices.rts -lc"       \
455     CFLAGS=-O3 FFLAGS=-O3                                                  \
456     --with-java=/usr/lib/IBMJava2/jre                                      \
457     --disable-misc --disable-graphics --disable-sample --disable-rlog
458
459 i.e. make sure that blrts_xlc uses the same xlc as listed in CC, the same
460      applies to blrts_xlf.
461
462 If the above does not work, try the following:
463
464 for older XL compilers, do
465
466     ${MPE_SRC_DIR}/configure                                               \
467     MPI_CC="/opt/ibmcmp/vac/7.0/bin/xlc                                    \
468            -F /etc/opt/ibmcmp/vac/7.0/blrts-vac.cfg"                       \
469     MPI_F77="/opt/ibmcmp/xlf/9.1/bin/xlf                                   \
470            -F /etc/opt/ibmcmp/xlf/9.1/blrts-xlf.cfg"                       \
471     CC="/opt/ibmcmp/vac/7.0/bin/xlc -F /etc/opt/ibmcmp/vac/7.0/vac.cfg"    \
472     F77="/opt/ibmcmp/xlf/9.1/bin/xlf -F /etc/opt/ibmcmp/xlf/9.1/xlf.cfg"   \
473     MPI_INC="-I/bgl/BlueLight/ppcfloor/bglsys/include"                     \
474     MPI_LIBS="-L/bgl/BlueLight/ppcfloor/bglsys/lib                         \
475              -lmpich.rts -lmsglayer.rts -lrts.rts -ldevices.rts -lc"       \
476     --with-java=/usr/lib/IBMJava2/jre                                      \
477     --disable-misc --disable-graphics --disable-sample --disable-rlog      \
478     CFLAGS=-O3 FFLAGS=-O3  
479
480 For newer XL compilers, do
481
482     ${MPE_SRC_DIR}/configure                                               \
483     CC="/soft/apps/ibmcmp-20050414/vac/7.0/bin/xlc                         \
484        -F /soft/apps/ibmcmp-20050414/etc/opt/ibmcmp/vac/7.0/vac.cfg"       \
485     F77="/soft/apps/ibmcmp-20050414/xlf/9.1/bin/xlf                        \
486         -F /soft/apps/ibmcmp-20050414/etc/opt/ibmcmp/xlf/9.1/xlf.cfg"      \
487     MPI_CC="/soft/apps/ibmcmp-20050414/vac/7.0/bin/xlc -F                  \
488         /soft/apps/ibmcmp-20050414/etc/opt/ibmcmp/vac/7.0/blrts-vac.cfg"   \
489     MPI_F77="/soft/apps/ibmcmp-20050414/xlf/9.1/bin/xlf -F                 \
490         /soft/apps/ibmcmp-20050414/etc/opt/ibmcmp/xlf/9.1/blrts-xlf.cfg"   \
491     MPI_INC="-I/bgl/BlueLight/DRV100_2005-050311PM/ppc/bglsys/include"     \
492     MPI_LIBS="-L/bgl/BlueLight/DRV100_2005-050311PM/ppc/bglsys/lib         \
493              -lmpich.rts -lmsglayer.rts -lrts.rts -ldevices.rts -lc"       \
494     CFLAGS=-O3 FFLAGS=-O3                                                  \
495     --with-java=/usr/lib/IBMJava2/jre                                      \
496     --disable-misc --disable-graphics --disable-sample --disable-rlog
497
498 Preferred approach: MPI_INC and MPI_LIBS should be included in some kind of
499 mpicc/mpif77 scripts, e.g. mpicc_ibm(or mpxlc) and mpif77_ibm(or mpxlf)
500 wrappers
501
502      ${MPE_SRC_DIR}/configure                                              \
503      MPI_CC=/home/chan/bin/mpicc_ibm                                       \
504      MPI_F77=/home/chan/bin/mpif77_ibm                                     \
505      CC=/opt/ibmcmp/vac/7.0/bin/xlc                                        \
506      F77=/opt/ibmcmp/xlf/9.1/bin/xlf                                       \
507      --with-java=/usr/lib/IBMJava2/jre                                     \
508      --disable-misc --disable-graphics --disable-sample --disable-rlog
509
510 After the successful configure, do make and make install.
511
512      make
513      make install PREFIX=${MPE_INSTALL_DIR}
514
515
516 For older MacOSX's MPICH2 which is built with gcc and gfortran:
517
518     ${MPE_SRC_DIR}/configure MPI_CC=${MPICH2_INSTALL_DIR}/bin/mpicc      \
519                              MPI_F77=${MPICH2_INSTALL_DIR}/bin/mpif77    \
520                              CC=gcc F77=gfortran                         \
521                              MPI_LIBS="  -lSystemStubs -lSystem -ldl"    \
522                              --prefix=<MPE_INSTALL_DIR>
523     make
524     make install
525     make installcheck
526     make installcheck-all MPERUN="${MPICH2_INSTALL_DIR}/bin/mpiexec -n 4"
527
528 where MPI_LIBS="  -lSystemStubs -lSystem -ldl" is needed to get fortran
529 program to link correctly if the mpif77 does not have the linking flags.
530 This seems to be necessary for some older gcc/gfortran combination on MaxOSX.
531
532
533 III. c) Miscellaneous Info about the Build System.
534 --------------------------------------------------
535
536 3 extra variables, MPE_COPTS, MPE_FOPTS, and MPE_LDOPTS, are included in 
537 almost all of MPE's Makefiles to mimic the usage of CFLAGS, FFLAGS and LDFLAGS.
538    MPE_COPTS  is the CFLAGS equivalent,
539    MPE_FOPTS  is the FFLAGS equivalent,
540    MPE_LDOPTS is the LDFLAGS equivalent.
541 These variables are not set in configures and Makefiles.  So it allows
542 end-user to quickly set one of this variables in Makefile through environment
543 variable without rerun configure.  For instance, if user forgets to set
544 CFLAGS=-g in configuring MPE, one can do "make MPE_COPTS=-g" instead and 
545 this can be done selectively in any subpackages.