The University of Arizona / Computer Science / UAScience

Installing the MPD Programming Language

http://www.cs.arizona.edu/mpd

Gregg Townsend
Department of Computer Science
The University of Arizona
January 20, 2004

General Notes

The MPD Programming Language runs under several different Unix systems including Linux, Solaris, Irix, and Digital Unix. A list is included in the Systems file in the main directory.

The MPD system is in the public domain and you may use and distribute it as you wish. We ask that you retain credits referencing the University of Arizona and that you identify any changes you make.

We can't provide a warranty with MPD; it's up to you to determine its suitability and reliability for your needs. We would like to hear of any problems you encounter but we cannot promise a timely correction.

System Components

The MPD system consists of several components. mpd and mpdl are the key programs used directly by an MPD programmer. The MPD runtime system is loaded implicitly by mpdl. Supplemental tools, example programs, and documentation are also provided.

mpd is the compiler proper. It translates an MPD program into a C program and then calls the C compiler to produce object code.

mpdl is the MPD linker. It generates tiny C files of configuration information and invokes the C compiler to combine these with object files and the runtime library. The end product is an executable program.

mpdx is an executive program that supervises "distributed" MPD programs: those that use create vm(). It is not called explicitly but is forked automatically by the runtime system.

mpdm assists in the construction of complex programs by inspecting MPD source code and automatically creating a correct make description file.

mpdprof reads a trace file produced during the execution of an MPD program and produces a report of event counts by line number or an annotated listing showing the counts.

The library contains resources, globals, and externals that can be linked with MPD programs. It includes an option processor and interfaces to X Windows and to the XTANGO animation package.

mpdv runs verification tests to check that the MPD system is functioning correctly. mpdvi installs new verification tests. These programs are part of the installation process and are not used by MPD programmers.

Directory Structure

Important files in the main directory include:

README

General release information and last minute notes. READ THIS FILE!

Systems

Detailed system-specific information. READ THIS, TOO.

Configuration

File paths and other miscellaneous configuration data.

Makefile

The master file of make directives for building MPD.

There are also several source code files and other files used in the build process.

Subdirectories of the main directory are:

mpd

Source code for mpd, the MPD compiler.

mpdl

Source code for mpdl, the MPD linker.

rts

Source code for the MPD runtime system, including mpdx.

library

Source code for the MPD library routines.

csw

Platform-specific runtime code for context switching.

multi

Platform-specific runtime code for multiprocessing support.

mpdm

Source code for mpdm, the Makefile builder.

mpdprof

Source code for mpdprof, the profiler.

mpdv

Source code for mpdv and mpdvi, the verification tools.

links

A collection of symbolic links pointing to locations where the executables are built. This directory can be put in a search path to assist in testing.

vsuite

A suite of verification programs used by mpdv. Most are simple and artificial, but some useful MPD examples are in vsuite/examples.

man

Individual man pages for the various programs in the MPD system.

doc

Additional documentation in HTML form.

Configuring the MPD System

Before you build MPD, you must decide where to install it. Pathnames are embedded in the binaries so that (for example) mpd can call mpdl and mpdl can find the runtime library. Five directories must be specified: one for the commands, one for hidden files such as the runtime library, and three for the man pages. All of the installed files have names beginning with mpd.

If you plan to install MPD as a local utility you might choose distinct directories such as /usr/local/bin, /usr/local/lib/mpd, and then /usr/man/manl for all the man pages. Alternatively, everything can be collected in a single directory such as /usr/mpd/bin or /home/yourname/bin. Do not use any existing directories within the MPD distribution, but you can safely create a new bin subdirectory under the main directory.

If the directories you have chosen do not now exist, you must create them manually. The installation process does not create new directories.

To configure the system, edit the file Configuration in the main directory. Change the MPDSRC definition to reflect the path of the main directory. Define installation directories as described above for MPDCMD, MPDLIB, MAN1, MAN3, and MAN5. All directories must be absolute paths (beginning with '/'), and no comments may appear on the definition lines.

If the X window system is installed, set XINCL to the parent directory of the X11 include directory. Usually, that is /usr/include or /usr/X11R6/include. On a Sun running OpenWindows, set XINCL to /usr/openwin/include. If X is not installed, set XINCL to be empty.

If you wish to use the animation interface provided in the library, you must first obtain and install the XTANGO package from Georgia Tech. At this writing it is available by anonymous FTP from the /pub/people/stasko directory on ftp.cc.gatech.edu. Then define XTANGO as the name of the XTANGO include directory.

A few other values can also be configured in the main Makefile. MANEXT defines the file extension for installed man pages. The xxPATH definitions define the location of the C compiler and other utilities called from within MPD commands, but do not affect the building of MPD. The CFLAGS definition sets compilation options for use while building MPD.

Some operating systems require additional changes to Configuration and/or Makefile. See the section in the Systems file describing your particular operating system.

Configuring for MultiMPD on Solaris

A multithreaded version of MPD, called MultiMPD, provides true concurrency on a multiprocessor Sun SPARC system. If you have a multiple-CPU Solaris system, you can configure MultiMPD. (MultiMPD also runs fine on uniprocessors, so it a single configuration suffices for a mixed environment.)

To configure MultiMPD on Solaris, edit the main Makefile and define

MULTI=solaris

Edit the Configuration file and define

LIBR=-lthread

Building and Testing

To build the MPD system, simply type

make

in the main directory. This builds all the components of the MPD system within the MPD directory structure, altering nothing outside the structure.

If you later need to change the configuration information, do so and again type make. This sort of rebuild goes relatively quickly because only a few files need to be recompiled.

After building the system, check that it is functional by entering

mpdv/mpdv -v quick

to run the "quick" set of MPD tests. This prints some environmental information and then runs a small set of tests. -v causes each verification directive to be echoed. The "quick" tests may actually take a few minutes, even on a fast machine; quick/jumble, in particular, has grown to over 500 lines of MPD and is compiled and executed twice.

No error messages are expected. If "expected 0, got 1 from $RSHPATH" appears for the quick/vm test, it indicates a problem running the rsh (or remsh) program. This is discussed below under Configuring Virtual Machines.

It is not necessary to complete the installation to manually test the newly built system. If you put the links subdirectory in your search path, you can compile MPD programs by running mpd and mpdl with the -e option. This causes them to load libraries and other files from within the source directory instead of from the ultimate, installed locations.

Installing the System

After the system has been built and verified, it must be installed in its ultimate destination as configured above. Type

make install

to copy the commands, man pages, and support files.

To verify a correct installation, type

mpdv/mpdv -v -p quick

to run the same tests as before, but using the installed files.

Configuring Virtual Machines

At this point, a complete MPD system has been built and installed. Without further reconfiguration, however, remote virtual machines may not work properly. This reconfiguration was deferred until now in order to have a working MPD system as a testbed. If you don't have a network of machines or don't need to use create vm() on n, you can skip this section. If you're building MPD on an Intel Paragon, you should also skip this section.

When a program creates a virtual machine and specifies a host machine on which to place it, MPD uses a remote shell to run the program on the remote host. The remote shell program is rsh(1) on most systems or remsh(1) on some System V derived Unixes. Set the RSHPATH definition in the Configuration file to name the correct program. Under Solaris 2, use /bin/rsh.

Verify that rsh or remsh is working by entering

rsh 'hostname' date

If necessary, substitute remsh for rsh and/or uname -n for hostname. If this doesn't print the date, there is a configuration problem outside of MPD; seek local assistance.

The name of the executable file passed to rsh is the same for all remote hosts and is controlled by an mpdmap file. This contains patterns for matching the program's filename and corresponding templates for generating the remote filename for rsh. The format of mpdmap is described in its man page, man/mpdmap.5.

If your network provides transparent access to remote disks, it should be possible to make remote execution work automatically by specifying templates that generate host-independent filenames. The mpdmap.az file in the main directory is an example of how this is done at Arizona.

Without remote disk access, users of multiple virtual machines will need to manually copy their programs to the remote hosts (e.g., using rcp or rdist) before beginning execution. The configuration in mpdmap controls where the programs must be placed, so a simple and straightforward method is desirable. One way to do this is to generate a path relative to the user's home directory. For example, if mpdmap contains the line

sequoia:/usr?/*/** ~$2/$3

then when a program /usr3/username/path is run on host sequoia, MPD expects to find copies of the executable in ~username/path on remote machines.

Edit mpdmap in the main directory and set up a configuration appropriate to your local situation. Refer to the mpdmap man page for a detailed description of the format, and use the Arizona configuration as a starting point and an example.

Make sure that your search path includes the directory where you just installed mpd, and type rehash if your shell requires it. Go into the vsuite/examples/misc/remote subdirectory and type

mpd remote.mpd

to compile a test program. Set the environment variable MPDMAP to the absolute pathname of the new mpdmap file.

Begin with a simple test by typing

a.out

to run the program with no arguments. It should simply tell you the local hostname; this verifies that mpdx is accessible, and that the location of a.out matches one of the patterns in mpdmap. Then try giving the local hostname as an explicit argument; this verifies that the generated filename works on the present host.

Now add other hostnames as command arguments; if remote execution fails (perhaps as expected), then the diagnostics from rsh give the file name attempted. Copy a.out into other directories, and onto other hosts if necessary. Run it from various locations with various hostname arguments. Run it using absolute and relative paths. Try to test any special cases used in the mpdmap file.

When you are satisfied with the configuration in mpdmap, return to the main directory and type

make install

to reinstall the system including the revised mpdmap file.

Cleaning Up

After the system has been installed, nothing within the MPD directory structure is needed to build or run MPD programs. The structure can be backed up on tape and removed from the disk.

If you wish to keep the source code online, type

make clean

to remove executables and intermediate files from the build process. Warning: the cleanup process is a bit aggressive, and it removes all files within the directory structure that satisfy certain tests. If you have created files of your own within the structure, and you wish to preserve them, it would be prudent to first copy them elsewhere.

The Full Verification Suite

The mpdv/mpdv quick command, noted above, runs just a small subset -- the quick subdirectory -- of the MPD verification suite. That should be sufficient to verify correct installation of an unmodified MPD system.

The full set of over 400 tests can be exercised by running mpdv/mpdv with no additional parameters. Most platforms exhibit a few failures; see the Systems file for details.

Porting to Other Systems

It is possible to port MPD to other system architectures besides those presently supported; some assembly language programming is required. 32-bit Unix systems with conventional memory models are most easily accommodated. See the documentation for porting the SR language; MPD is ported in a similar manner.

Feedback

Please let us know of any problems you encounter so that we can continue to improve MPD. Our electronic mail address is sr-project@cs.arizona.edu. To address any problems, we'll need to know what computer and operating system you are using, and what version of MPD. Because of limited resources we can't promise to fix every problem, but we appreciate all comments and acknowledge all mail.