A single directory (which has subdirectories) contains all the files related to Athapascan-0. Normally this directory is /usr/local or /usr/local/ath0b, which must be stored in the shell environment variable A0HOMEDIR. A file a0setup.csh, contained in the bin subdirectory of A0HOMEDIR, sets all the shell environment variables necessaries to compile, link and run programs with Athapascan-0, as well as Athapascan-0 itself.
The currently systems supported by Athapascan-0 are:
Be sure to have installed in your system the threads and MPI packages necessary to compile Athapascan-0. After expanding the tarfile, a directory called ath0b is created with the following contents:
To compile Athapascan-0 itself, the user must execute make being inside the directory ath0b. It generates the bin/a0setup.csh file and fills the directories include, lib and bin, with the installation files, which are the include files, the libraries generated by the compilation and the binary utilities.
To install the libraries in your system, execute make install. It will copy the contets of the include, lib and bin directories to the installation directory. Nevertheless, Athapascan-0 can be used uninstalled, in the same directory it was compiled.
In the doc directory you can find all the documents and manuals (like this, for example). They are supplied in LaTeX source. Postscript versions can be obtained by executing make in the doc directory. There is also a program which converts the LaTeX files into html, to be read with you preferred navigator.
Usually, after having compiled all libraries of Athapascan-0, one can make a copy of it to make available to all user in the system. Though, there is no need to copy all the sources of Athapascan-0 for that. Athapascan-0 comes with an installation procedure, activated by make install in the main directory. It copies only the needed files generated in include, lib and bin directories to the destination directory (chosen with configure).
The examples directory contains some example programs for Athapascan-0. To compile them, use make. Don't forget to run the bin/a0setup.csh file before.
There are also subdirectories for every Athapascan-0 layer (look at src directory), with little test programs. They can be compiled with make all.
To use Athapascan-0, at least two variables must be previously set: A0HOMEDIR and A0TYPE. Files a0setup.csh (for C-shell) and a0setup.sh (for Bourne-shell) set those variables and the PATH variable to find the MPI and Athapascan-0executables. To set all the variables needed, execute:
prompt% source ..../ath0b/bin/a0setup.csh
To compile an Athapascan-0 program, the user must execute the C compiler, passing all the needed options. There is a makefile in the file pointed by the variable A0MAKEFILE which can be used to compile and link any simple Athapascan-0 program. For example, to compile a program called toto.c:
prompt% make -f ${A0MAKEFILE} toto
Athapascan-0 supplies two front-end scripts, to compile and link Athapascan-0 programs, namely a0cc and a0ld. Their usage is the same as the regular MPI compiler of your system (mpcc with IBM MPI, hcc with LAM/MPI, mpicc with MPI-CH). They add all needed options and execute the system configured compiler. The option -v can be used to inspect the commands issued by those scripts.
prompt% a0cc -BLABLA -c -o file1.o file1.c prompt% a0cc -FOOBAR -c -o file2.o file2.c prompt% a0ld -OPTION -o myprog file1.o file2.o file3.o
As a0cc and a0ld are just front-ends to a C compiler and linker, all the options passed to both are passed to the back-end compiler and linker. For example, to see which compiler is executed and its options, one can use the -v option, as follows:
prompt% a0cc -c -v emamp.c ================a0cc output================ hcc -c -I/users/navajo3/pasin/a0/sparc.lam.sol2/include -DA0_TSOL2 -DA0_LAM -c -v examp.c ================system output================ "examp.c", line 45: warning: Function has no return statement : examp
There are some options interpreted by a0cc and a0ld themselves, not passed to the back-end. They are:
To compile and link complex programs, which require several objects or libraries, the user must build a makefile. Suppose you have 3 source files, which must be compiled with different compiler options, and linked together at the end. File file1.c needs options -BLABLA, file file2.c needs -FOOBAR and file file3.c needs no options. The option -OPTION mut be passed to the linker. The lines that follow are a makefile for such 3-file example.
include $(A0MAKEFILE) file1.o: file1.c $(CC) $(CCFLAGS) -BLABLA -o file1.o file1.c file2.o: file2.c $(CC) $(CCFLAGS) -FOOBAR -o file2.o file2.c # make knows how to make file3.o, since it has no special options myprog: file1.o file2.o file3.o $(LD) $(LDFLAGS) -OPTION -o myprog file1.o file2.o file3.o
In the bin directory, the user can find a0run, which executes an Athapascan-0 program using the configured MPI. The a0run command understands the following options:
For example, to run program fubar in three nodes, with parameters myfile and 34 passed to the program's argv[1] and argv[2], use:
prompt% a0run fubar -a0n 3 myfile 34
An Athapascan-0 program can be also started as any MPI program in the system. For more information, refer to the MPI manual of your system. On SP2 systems, check poe, on LAM/MPI or MPI-CH systems, check mpirun.
The Athapascan-0 runtime library extracts itself some of the parameters passed to the executable program. All the parameters not extracted by Athapascan-0 will be passed in the program main() function arguments argv[]. The currently recognized Athapascan-0 arguments are:
Very few systems for parallel and threaded programs debugging exist. Athapascan-0 programs can be degugged with regular debuggers, using a special startup. The debugger to be used should at least be capable to attach to a running process.
To run an Athapascan-0 program with a debugger, start the program with the -a0stop option. It will cause the program to stop in the call of a0Init() on all nodes. One debugger should be started for every node to be debugged.
Some debuggers allow the user to debug many Unix processes at the same time. If all nodes can be run in the same physical computer, one single debugger can be started. See your MPI manual to learn how to run all nodes in a single computer.
Some MPI implementations run every node in a different physical machine, so, the debugger must be remotely started manually on that machines too. A hostfiles, with a list of machines in which the parallel program must run, can be useful in that moment. See your MPI manual to learn how to use hostfiles.
After starting all the necessary debuggers, attach every one to the Unix processes corresponding to the nodes. Starting Athapascan-0 with the option -a0verbose, the physical machines and process identifiers of all nodes are echoed. Having attached all the processes, they will be blocked in the a0Init() function call.
To continue the execution, the user must run a0cont in the same directory where the node 0 is running. All nodes will return from the call of a0Init() and all debuggers can take control of it.