II - Commands
CONFIGURE(1) MATE Commands CONFIGURE(1)
NAME
configure - configuration script to compile and install MATE.
SYNOPSIS
./configure --with-mpi=MPI_PATH
[--prefix=INSTALL_DIR]
[--build-dir=BUILD_DIR]
[--build-jobs=JOBS_NUMBER]
[--force]
[--help]
DESCRIPTION
configure is used to set the installation environment before using the
make command to build MATE. It performs the following tasks:
1 Define the path where MATE and its dependencies (ROSE, Boost,
Tarragon) are going to be built. This path needs to have
with at least 5Gb of free space prior to compilation.
2 Verify that the MPI library binary and include paths exist.
3 Determine which version of Boost to use depending on the current gcc
version.
4 Verify that some of the tool dependencies used by MATE or ROSE can be
executed.
Except for --with-mpi, none of the options for configure are mandatory,
and a default value is used for them, in case they are not specified.
OPTIONS
These options are used to choose the information displayed by ps.
The output may differ by personality.
--with-mpi=MPI_PATH
Specifies where the MPI library to use is installed. Configure will look
for and execute MPI_PATH/bin/mpicxx command, and verify that the file
MPI_PATH/include/mpi.h exists. This MPI library will be used by MATE
to compile and link the translated source files.
--prefix=INSTALL_PATH
Specifies where MATE and its dependencies will be installed. INSTALL_PATH
needs to have at least 1Gb of free space at the moment of installation.
Default value: $PWD/bin
--build-dir=BUILD_PATH
Specifies where MATE and its dependencies will be downloaded and built.
BUILD_PATH needs to have at least 1Gb of free space at the moment
of installation.
Default value: $PWD/build
--build-jobs=JOBS_NUMBER
Specifies how many jobs will be used to build MATE and its dependencies.
The recommended value for this parameter is the number of CPU cores in the
computer used to compile. Compilation times for MATE's dependencies vary
greatly depending on this value. For example:
ROSE's Compilation time for 1 job: ~4 hours.
ROSE's Compilation time for 16 jobs: ~30 minutes.
Default value: 1
--force
Forces the current gcc/boost version to be used. For a list of MATE
compatible compiler/boost versions see the COMPATIBILITY section.
--help
Displays a help message.
EXAMPLES
Simple configuration example:
./configure --with-mpi=/opt/mpich2
Simple configuration example with recommended simultaneous job number:
./configure --with-mpi=/opt/mpich2 --build-jobs=16
Configuration with different filesystems for build/installation:
./configure --with-mpi=/opt/mpich2 --build-jobs=16 --build-dir=/big-filesystem/mate-build --prefix=/usr/bin/mate
Display help message:
./configure --help
MAKE COMMANDS
After the configuration script was been executed without errors, the user can compile
and install MATE using the following make commands:
make
Compiles MATE and its dependencies. Creates the --build-dir path to download and compile
dependencies. If dependencies are already installed, it does not re-build them.
make install
Installs MATE in the directory specified with the --prefix option.
make check
Compiles and executes all tests included in the tests/ folder. It is recommended that this
command is executed after installing MATE to verify that it runs correctly.
make clean
Cleans MATE's compilation files, but does not uninstall it from the installation directory.
COMPATIBILITY
The following combinations of gcc/boost have been tested, and the correct
combination is chosen from the gcc version being used. Automatic fixes to ROSE
installation are applied in some cases:
gcc 4.4.*: boost 1.50
gcc 4.5.*: boost 1.47 + fixEDGbuild.sh (*)
gcc 4.6.0: boost 1.47 + fixEDGbuild.sh (*)
gcc 4.6.*: boost 1.53 + fixEDGbuild.sh (*)
gcc 4.7.*: boost 1.53
gcc 4.8.*: boost 1.53
gcc 4.9.*: boost 1.53 + fixEDGbuild.sh + fixgcc49x.sh (*) (**)
Using gcc for compilation of MATE and its dependencies is mandatory since
the ROSE compiler infrastructure can only be compiled with gcc.
There are no restrictions on which MPI library can be used for MATE, although
the majority of tests have been performed using MPICH.
(*) The script fixEDGbuild.sh is automatically used to select the correct
version of EDG binaries compatible with the current gcc version used
to compile ROSE.
(**) The script fixgcc49x.sh is automatically used to allow ROSE use gcc 4.9.*
DEPENDENCIES
All MATE's dependencies are automatically downloaded (except for Tarragon,
which is included in MATE's source code) and compiled by the installation
script.
Some dependencies require that some GNU programs are already installed
in the system. MATE's configuration script does not check for all of these
sub-dependencies, but an error message informing which programs are missing
will be displayed by the dependency's own configure script.
ROSE Compiler Infrastructure.
The ROSE Compiler Infrastructure is downloaded and compiled automatically
during installation. MATE uses ROSE for code translation. It may take several
minutes to compile ROSE using multiple simultaneous jobs, and up to four hours
using a single job.
Tarragon Runtime System.
TRS's source code is included in the MATE release. MATE uses the TRS
for task generation and communication.
Boost C++ Libraries.
Boost is downloaded and compiled automatically during installation.
MATE uses Boost to support ROSE.
MATE-TRANSLATE(1) MATE Commands MATE-TRANSLATE(1)
NAME
mate-translate - Translates MATE-annotated source code.
SYNOPSIS
mate-translate files [-Idir...] [-Dmacro[=defn]...] [gcc_flags] [--mate-verbose]
DESCRIPTION
mate-translate takes a set of input C/C++ files containing MPI functions and
#mate pragma annotations and outputs a single C++ file containing a semantically
equivalent latency-tolerant version of the input program.
OPTIONS
These options are used to specify source files and pre-compilation flags to
mate-translate.
files
Specifies the source C/C++ files to be translated by MATE. It is
recommended that all the project's source files are indicated here.
See the INPUT section for more details.
-Idir...
Specifies include directories for header files (.h, .hpp).
-Dmacro[=defn]...
Specifies definitions and macros. MATE's preprocessor will apply
these definitions in the translated code permanently.
gcc-flags
Allows specifying additional gcc flags required for compilation that
are necessary for translation.
--mate-verbose
Allows visualizing the progress of the MATE during its different translation
stages. It also provides further details when an unexpected error occurs.
INPUT
The list of file(s) specified in the files must satisfy the
following requirements:
- One and only one of the source files specified must contain a full
definition of the main function:
int main(int, char**);
- At least one of the files must contain MPI code, reachable from the main
function.
- All input files must follow MATE's annotation syntax. MPI control and
collective communication functions do not need to be annotated. All MPI
peer to peer communications need to be enclosed in their corresponding
MATE overlap/receive/send regions. See the SUPPORTED MPI FUNCTIONS
section for more information.
The full specification of MATE's annotation syntax can be found at:
mate.ucsd.edu/usage.html#syntax
OUTPUT
If translation is successful, mate-translate will output a single
C++ code file with the same name as the source file containing the main
function, and an added prefix. For example:
INPUT = main.c aux1.c aux2.c
OUTPUT = mate_main.cpp
The output file will containg a Tarragon-compatible class definition that
is used by Tarragon to execute in a data-driven form. This class semantically
represents the original main() function plus inlined functions containing MPI
functions.
MATE will inline (i.e. replace a function call statement with the whole
function being called) all functions that call, or contain calls, to other
functions containing MPI calls. This is done in a recursive fashion.
The resulting MATE generated file contains all the communication semantics
used by the original program. No other functions (i.e. those who do not contain
MPI calls inside their definitions or in subsequent function calls) are inlined.
To compile a translated project you only need to replace the original source file
containing the main() function with the translated file. You also need to use
mate-cxx for compilation. For example:
Original compilation line:
mpicc main.c aux1.c aux2.c -o my_program
MATE compilation line (including translation step):
mate-translate main.c aux1.c aux2.c
mate-cxx mate_main.cpp aux1.c aux2.c -o mate_my_program
EXAMPLES
Single file translation:
mate-translate main.c
Multiple file translation:
mate-translate main.c aux1.c aux2.c
Multiple file translation with include directories:
mate-translate main.c aux1.c aux2.c -I/usr/include
Multiple file translation with include directories and definitions:
mate-translate main.c aux1.c aux2.c -I/usr/include -Dvalue=100
KNOWN LIMITATIONS
- When we translate MPI processes into tasks that runs as threads,
we change the memory model of our program. In particular, global
variables (i.e. declared outside the scope of any function) will
become shared, result in interactions among tasks does not occur in
the original MPI program. This is a general issue with all task based
systems, and each has their own solution. Our interim solution is to
place such globals in a C struct and to pass the struct as actual
paramters to functions that use global state.
- Multi-line Macro definitions are not supported.
- Communicator splitting operations are not supported currently.
MATE-CXX(1) MATE Commands MATE-CXX(1)
NAME
mate-cxx - Compiler/Linker for MATE translated programs.
SYNOPSIS
mate-cxx files [mpicxx_flags]
DESCRIPTION
mate-cxx is an alias for the mpicxx command specified by the user during
MATE's configuration. It adds additional flags, includes, and linked libraries
that are necessary for the MATE translated code to compile, and to link with
the MATE Runtime System.
When mate-cxx is executed, all its arguments are redirected to mpicxx but
with the addition of MATE specific arguments.
OPTIONS
These options are used to specify source files and mpicxx flags to mate-cxx.
files
Specifies the source C/C++ files to be compiled/linked.
mpicxx-flags
Allows specifying additional mpicxx flags used by the original
program to compile/link.
EXAMPLES
Single file compilation and linking:
mate-cxx mate_main.cpp -o mate_myprog
Multiple file compilation and linking:
mate-cxx mate_main.cpp aux1.c aux2.c -o mate_myprog
Multiple file compilation and linking in separate stages:
mate-cxx -c mate_main.cpp
mate-cxx -c aux1.c
mate-cxx -c aux2.c
mate-cxx mate_main.o aux1.o aux2.o -o mate_myprog
Multiple file compilation and linking in separate stages
with include directories, definitions, additional libraries, and flags:
mate-cxx -c mate_main.cpp -Dvalue=100 -O2
mate-cxx -c aux1.c -I/usr/include -O2
mate-cxx -c aux2.c -O2
mate-cxx mate_main.o aux1.o aux2.o -o mate_myprog -L/user/lib -lm
EXECUTION
MATE-translated programs should be executed with the following syntax:
srun -n PROCESSES mate_program --mate-threads WORKERS --mate-tasks MATE_TASKS [--verbose]
PROCESSES
Indicates the number of MATE processes to be instanciated by the SLURM/MPI/UPC launcher.
The recommended value for this argument is the total number of NUMA domains in the exeuction
domain. For example, if the run uses 16 nodes, with 2 NUMA domains each, the value for
PROCESSES should be 32.
--mate-threads WORKERS
The number specified in WORKERS indicated how many MATE workers
(kernel level threads) will be created for every MATE process.
Each worker will be mapped to a single and distinct processor core. MATE guarantees
that no thread/core migration will occur during execution.
The recommended value is for this argument the number of cores in each separate NUMA domain.
For example, if the current machine has 2 processors with 8 cores each, the
best configuration is to run 2 MATE processes per node and 8 MATE threads per worker.
More information about this can be found in the MULTINODE EXECUTION section.
Indicating more workers than cores available in the machine will result in
performance degradation:
--mate-tasks MATE_TASKS
MATE_TASKS indicates the amount of MATE tasks to be created.
From the user program's point of view, the MATE Tasks are equivalent to MPI tasks.
However, this parameter allows MATE to execute more tasks than cores in the node,
allowing virtualized executions.
--verbose
This flag will enable Tarragon to print information about the current execution:
- CPU and NUMA related information.
- Global and node-local worker count and IDs.
- Global and node-local task count and IDs.
- Worker-Core affinity.
- Task-worker affinity.
- Individual Task finalization order.