Scripts to Compile and Link Applications


Up: Linking and running programs Next: Using Shared Libraries Previous: Linking and running programs

The mpich implementation provides four commands for compiling and linking C (mpicc), C++ (mpiCC), Fortran 77 (mpif77), and Fortran 90 (mpif90) programs.

In addition, the following special options are supported:

-mpilog
Build version that generates MPE log files.
-mpitrace
Build version that generates traces.
-mpianim
Build version that generates real-time animation.
-show
Show the commands that would be used without actually running them.

Use these commands just like the usual C, Fortran 77, C++, or Fortran compilers. For example,
    mpicc -c foo.c  
    mpif77 -c foo.f 
    mpiCC -c foo.C 
    mpif90 -c foo.f 
and
    mpicc -o foo foo.o 
    mpif77 -o foo foo.o 
    mpiCC -o foo foo.o 
    mpif90 -o foo foo.o 
Commands for the linker may include additional libraries. For example, to use routines from the C math library library, use
    mpicc -o foo foo.o -lm 
Combining compilation and linking in a single command, as shown here,
    mpicc -o foo foo.c 
    mpif77 -o foo foo.f 
    mpiCC -o foo foo.C 
    mpif90 -o foo foo.f 
may also be used.

Note that while the suffixes .c for C programs and .f for Fortran-77 programs are standard, there is no consensus for the suffixes for C++ and Fortran-90 programs. The ones shown here are accepted by many but not all systems. Mpich tries to determine the accepted suffixes, but may not always be able to.

You can override the choice of compiler by specifying the environment variable MPICH_CC, MPICH_F77, MPICH_CCC, or MPICH_F90. However, be warned that this will work only if the alternate compiler is compatible with the default one (by compatible, we mean that is uses the same sizes for all datatypes and layouts, and generates object code that can be used with the mpich libraries). If you wish to override the linker, use the environment variables MPICH_CLINKER, MPICH_F77LINKER, MPICH_CCLINKER, or MPICH_F90LINKER.



Up: Linking and running programs Next: Using Shared Libraries Previous: Linking and running programs


Using Shared Libraries


Up: Scripts to Compile and Link Applications Next: Fortran 90 and the MPI module Previous: Scripts to Compile and Link Applications

Shared libraries can help reduce the size of an executable. This is particularly valuable on clusters of workstations, where the executable must normally be copied over a network to each machine that is to execute the parallel program. However, there are some practical problems in using shared libraries; this section discusses some of them and how to solve most of those problems. Currently, shared libraries are not supported from C++.

In order to build shared libraries for mpich, you must have configured and built mpich with the --enable-sharedlib option. Because each Unix system and in fact each compiler uses a different and often incompatible set of options for creating shared objects and libraries, mpich may not be able to determine the correct options. Currently, mpich understands Solaris, GNU gcc (on most platforms, including LINUX and Solaris), and IRIX. Information on building shared libraries on other platforms should be sent to mpi-bugs@mcs.anl.gov.

Once the shared libraries are built, you must tell the mpich compilation and linking commands to use shared libraries (the reason that shared libraries are not the default will become clear below). You can do this either with the command line option -shlib or by setting the environment variable MPICH_USE_SHLIB to yes. For example,

    mpicc -o cpi -shlib cpi.c 
or
    setenv MPICH_USE_SHLIB yes 
    mpicc -o cpi cpi.c 
Using the environment variable MPICH_USE_SHLIB allows you to control whether shared libraries are used without changing the compilation commands; this can be very useful for projects that use makefiles.

Running a program built with shared libraries can be tricky. Some (most?) systems do not remember where the shared library was found when the executable was linked! Instead, they depend on finding the shared library in either a default location (such as /lib) or in a directory specified by an environment variable such as LD_LIBRARY_PATH or by a command line argument such as -R or -rpath (more on this below). The mpich configure tests for this and will report whether an executable built with shared libraries remembers the location of the libraries. It also attemps to use a compiler command line argument to force the executable to remember the location of the shared library.

If you need to set an environment variable to indicate where the mpich shared libraries are, you need to ensure that both the process that you run mpirun from and any processes that mpirun starts gets the enviroment variable. The easiest way to do this is to set the environment variable within your .cshrc (for csh or tcsh users) or .profile (for sh and ksh users) file.

However, setting the environment variable within your startup scripts can cause problems if you use several different systems. For example, you may have a single .cshrc file that you use with both an SGI (IRIX) and Solaris system. You do not want to set the LD_LIBRARY_PATH to point the SGI at the Solaris version of the mpich shared libraries*. Instead, you would like to set the environment variable before running mpirun:


    setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/usr/local/mpich/lib/shared 
    mpirun -np 4 cpi 
Unfortunately, this won't always work. Depending on the method that mpirun and mpich use to start the processes, the environment variable may not be sent to the new process. This will cause the program to fail with a message like


    ld.so.1: /home/me/cpi: fatal: libpmpich.so.1.0: open failed: No such  
    file or directory 
    Killed 
There are various solutions to this problem; each of them depends on the particular mpich device (e.g., ch_p4) that you are using, and those solutions are discussed in the appropriate section within Section Special features of different systems .

An alternative to using LD_LIBRARY_PATH and the secure server is to add an option to the link command that provides the path to use in searching for shared libraries. Unfortunately, the option that you would like is ``append this directory to the search path'' (such as you get with -L). Instead, many compilers provide only ``replace the search path with this path.''* For example, some compilers allow -Rpath:path:...:path to specify a replacement path. Thus, if both mpich and the user provide library search paths with -R, one of the search paths will be lost. Eventually, mpicc and friends can check for -R options and create a unified version, but they currently do not do this. You can, however, provide a complete search path yourself if your compiler supports an option such as -R.

The preceeding may sound like a lot of effort to go to, and in some ways it is. For large clusters, however, the effort will be worth it: programs will start faster and more reliably, because there is less network and file system traffic.



Up: Scripts to Compile and Link Applications Next: Fortran 90 and the MPI module Previous: Scripts to Compile and Link Applications


Fortran 90 and the MPI module


Up: Scripts to Compile and Link Applications Next: Compiling and Linking without the Scripts Previous: Using Shared Libraries

When mpich was configured, the installation process normally looks for a Fortran 90 compiler, and if it finds one, builds two different versions of an MPI module. One module includes only the MPI routines that do not take ``choice'' arguments; the other includes all MPI routines. A choice argument is an argument that can take any datatype; typically, these are the buffers in MPI communication routines such as MPI_Send and MPI_Recv. The two different modules can be accessed with the -nochoice and -choice option to mpif90 respectively. The choice version of the module supports a limited set of datatypes (numeric scalars and numeric one- and two-dimensional arrays). This is an experimental feature; please send mail to mpi-bugs@mcs.anl.gov if you have any trouble. Neither of these modules offer full ``extended Fortran support'' as defined in the MPI-2 standard.



Up: Scripts to Compile and Link Applications Next: Compiling and Linking without the Scripts Previous: Using Shared Libraries