$Id: INSTALL,v 1.25 2006/02/25 16:24:39 morsiani Exp morsiani $ *** uMPS Installation Instructions To install uMPS, just untar the the distribution tar file into any directory. For example: mkdir /usr/local cp uMPS.1.23-RC1.tar.gz /usr/local/ cd /usr/local gunzip uMPS.1.23-RC1.tar.gz tar xvf uMPS.1.23-RC1.tar This will create three directories below the main directory: umps/ support/ example/ They contain respectively: -------------------------------------------------------------------------------- umps/ : The simulator sources Before compiling the simulator one should edit the options at the beginning of the Makefile in this directory. Essentially, one needs to select the architecture class one is performing the installation on: Set the HOST option to one of: LINUX, FreeBSD, PPC, or SUN. Additionally, if one is performing a FreeBSD installation there is one other edit change to make. The same is true for PPC installations. After making the appropriate edit changes to the Makefile, uMPS should be compiled with: make When compilation ends, the umps, umps-mkdev, umps-elf2mps, and umps-objdump executables have been built. To run any of these executables the LD_LIBRARY_PATH must be set to include the path to XForms library needed by uMPS. If you use tcsh: setenv LD_LIBRARY_PATH /usr/local/uMPS.1.23-RC1/umps/FORMS If you use bash: export LD_LIBRARY_PATH=/usr/local/uMPS.1.23-RC1/umps/FORMS Under FreeBSD, you may have also have to add /usr/compat/linux/lib to LD_LIBRARY_PATH A short explanation: The MIPS architecture supports both big-endian as well as little-endian processing. The uMPS simulator will take on the endian-ness of its host architecture. This is why the instructions for building the cross-compiler development tools are different depending on the architecture of the installation machine. Furthermore, the primary edit change in the Makefile is to specify the architecture of the installation machine. Unfortunately, there are some library differences between architectures. uMPS uses the ELF compatability and FORMS libraries. A version of these libraries are included in the distribution. While these included libraries do not work under FreeBSD, the standard system ELF and FORMS libraries included with FreeBSD do - hence the other edit change in the Makefile for FreeBSD installations. In some cases (e.g. Mac OS X; PPC installation) it is necessary to recreate the included ELF and FORMS libraries. To do so one downloads the libelf source and follows the installation directions. Instead of performing a complete installation of libelf one can simply un-tar the distribution, cd into the libelf-0.8.6 directory and run: ./configure make Then instead of running "make install" simply copy the created header (*.h) and library (libelf.a) files (found inthe lib/ subdirectory) into /usr/local/uMPS.1.23-RC1/umps/ELF/ as needed. The same steps may need to be performed for the libforms library found in the FORMS subdirectory. Alternative to making the library in a private directory and then copying the appropriate files into the FORMS subdirectory, is to make and install this library in /usr/local and then configure the installation like the FreeBSD installation - to use the "standard" libforms library instead of a local one. For this library and associated header files one uses the xforms source. (Note: One needs to have libjpeg installed in order to configure and make libforms.) -------------------------------------------------------------------------------- support/ : Some support files, and system ROMs The support files can only be created after the uMPS simulator has been built. Furthermore, the support files are architecture (big-endian vs. little-endian) specific. It is therefore recommended that one perform the following steps after cd'ing into the support directory and editing the options at the beginning of the Makefile in this directory: make distclean make To insure that one has the correct support files for the architecture one is installing on. The uMPS simulator will run correctly only if instructed on the position of some support files. This may be achieved by specifying their position in a umpsrc file. The umpsrc file is searched: In the current directory (./.umpsrc) In the user home directory ($HOME/.umpsrc) In a system-wide configuration file (/etc/umpsrc) The search stops at the first file found. A umpsrc.sample file is located in support/ directory. -------------------------------------------------------------------------------- examples/ : Classical "Hello World" examples for the uMPS simulator Each example program prints a message on terminal 0 (or printer 0) and ends. They have been included to show how the Makefile, MIPS cross-compiler and umps commands should be used to build executable code for the uMPS virtual machine. These examples have already been cross-compiled (little-endian architecture) to let you test the simulator without installing the cross-compiler kit. *.umps files represent uMPS simulated devices. See the README file in the examples/ directory for more information regarding the example programs and how to test/run them.