REAL 5.0 Installation Manual
S. Keshav
Cornell University
skeshav@cs.cornell.edu
 
August 13th 1997 

0. Prologue

Here is a paraphrase from Norman Wilson's introduction to the Research 10th edition of UNIX that just about sums up my attitude to REAL:

I desire to stay out of the software support business; I have enough of that keeping my own system running. I’m interested in sharing the system with colleagues; I’m not set up to support customers.

 This system is not packaged for novices. It is assumed that anyone who gets a copy is self-sufficient and can read our manuals and the source code to resolve confusions and problems.

 OK, its not that bad. There is a mailing list of REAL users where you can ask questions (real@minnie.cs.adfa.oz.au). I monitor this list and usually answer questions posted there within a day or two. But do not expect hand holding.

1. Introduction
This manual provides guidelines for installing REAL. The table below summarizes the systems on which I know REAL will run. Your mileage may vary.
 
Processor OS Comments
MC68000 SunOS Haven’t tested this for a while, but should work.
SPARC SunOS Works ‘out of the box.’
SPARC Solaris (SunOS 5.0) Works ‘out of the box.’
MIPS IRIX 4.0.5 Should work ‘out of the box.’ I have not tested on IRIX 5.3
MIPS Ultrix Should work, but I have not tested this.
Alpha OSF (Digital Unix) Works ‘out of the box.’
x86 FreeBSD/NetBSD Should work ‘out of the box.’
x86 Linux May require some fiddling. 
x86 Windows NT/95 Won’t work (yet). 
Vax BSD 4.3 Works ‘out of the box.’ (does anyone still have these?)
2. Steps in the Installation
 I will assume that you have a copy of the compressed tar file on a disk with a reasonable amount of space (at least 5MB).

Step 1

Create the REAL root directory. Move the compressed tar file to this directory. Then, uncompress and untar the file.

[uncompress | gunzip] REAL5.0.tar.[Z|gz]

tar xvf REAL5.0.tar

You are now ready to configure and make the system. All instructions that follow use filenames relative to this root directory.

Step 2

Change directory to sim/src. Edit file state.S to extract the assembly code corresponding to your machine, and save it in a file called state.s.

Step 3

Customize the makefiles for your system. You have to edit three makefiles.

    1. If you are on an SGI machine running IRIX 5.2 or greater uncomment line 121 in the file src/Makefile.SH (this will make nest.a into a shared source library instead of an archive).
    2. Edit sim/makefile beginning at 101 (see comments there for more instructions)
    1. Edit sim/kernel/makefile at line 48 if you are running Solaris
Step 4

If you are running IRIX 5.2 or greater, you will need to tell the system about the location of the shared library. The command is:

    setenv LD_LIBRARY_PATH ../src
 

Step 5

You are now ready to configure the system. Change directory to src and type

Configure This will fire up an interactive configuration manager that will ask you several questions about your system, and will figure out many things by itself. If it completes successfully, it will build the simulate binary. If so, skip to Step 6.

It is possible the Configure will not work correctly. For example, Configure runs a test that creates archives of length zero and this can cause a core dump on some machines. To avoid this, you should comment out the commands that are causing problems, and determine the defaults manually. It helps to have a Unix guru handy.

At one point, Configure will ask you to do a shell escape to edit config.sh. Here, type in

![favorite-editor] config.sh You will find a file that looks like this:

#!/bin/sh

# config.sh

# This file was produced by running the Configure script.

 

d_eunice='undef'
eunicefix=':'
define='define'
expr='/bin/expr'
sed='/bin/sed'
echo='/bin/echo'
cat='/bin/cat'
rm='/bin/rm'
tr='/bin/tr'
sort='/bin/sort'
grep='/bin/grep'
test='test'
contains='grep'
cpp='/lib/cpp'
cppminus=''
d_charsprf='define'
d_voidsig='define'
libc='/lib/libc.a'
n='-n'
c=''
package='REAL4.0'
spitshell='cat'
shsharp='true'
sharpbang='#!'
startsh='#!/bin/sh'
voidflags='7'
defvoidused='1'
d_getopt='define'
d_itimer='define'
d_systime='/usr/include/sys/time.h'
d_memset='define'
d_bstring='define'
d_psignal='define'
d_rename='define'
d_rusage='define'
d_server='undef'
d_sigvec='define'
d_sigvectr='undef'
d_socket='define'
d_oldsock='undef'
socketlib=''
sockethdr=''
inc=''
lib=''
lintlib=''
mkdep='/lib/cpp -M'
orderlib='false'
ranlib='/usr/bin/ranlib'
stackdir='-1'
d_cckr='-cckr'
CONFIG=true
 
You have to edit this file to make sure that it describes your system accurately. This is not easy, and unfortunately there is not much I can do to help you with it. Your only consolation is that you will almost surely not have to change anything. I recommend that you just try building the system and only come back to this step if it really blows up on you.

I will now describe the variable names in the file, and you will need to determine if their values are appropriate for your system. In general, the convention used for variable names is that d_XXX means that a #define for XXX will be created in the configuration file nest.h. Command names stand for the particular flavor of command used by your system.

The file starts off with `d_eunice', which is defined if you have a eunice system (I've never seen this system myself)

This is followed by definitions for the location of useful commands such as sed, echo, cat, rm, and tr. Modify them if necessary.

`contains' should be your flavor of grep.

`cpp' should be set to your C preprocessor. The Configure script automatically tries cpp, cc -E

`cppminus' is the default flag that you need to give to cpp.

`d_charsprf' is set if sprintf() is of type char.

`d_voidsig' is set if your system defines signal() to be of type (void).

The definition for `libc' is critical, and defines where your C library is.If you have more than one library, then this might be wrong. For example, in UMIPS, it will be set to the SysV library /usr/lib/libc.a, and you actually should have /bsd43/usr/lib/libc.a.

`spitshell' is the command to print data into a file.

`shsharp' is true if `#' can comment out things in your version of shell.

`voidflags' is explained when you do Configure.

Now there are some defines that explore the limits of your operating system. The meanings of these defines are in the file sim/src/nest.h.SH. Take a minute to make sure that they are correct.

`socketlib' is the library that has socket code, if libc.a doesn't. (Solaris has it in libsocket)

`sockethdr' is the place where include files for sockets are kept if they are non-standard.

`mkdep' is the command that will generate makedepends for you. Usually this is /lib/cpp -M, but if that doesn't work, you may have to use /bsd43/bin/cc -M.

`orderlib' is true if the archive command creates unordered libraries.

`ranlib' is the command you need to use to create random libraries (set to `:' if it isn't needed, then the command becomes a comment).

`stackdir' is the direction the stack grows in, 1 is up, -1 is down.

Finally, CONFIG is set to indicate that you have run config.sh.

 After you have edited config.sh, you should return to the Configure session. Configure will now extract some files. Files that end with a .SH suffix are shell scripts that contain shell variables set by config.sh. Configure runs config.sh to set these variables, then runs the .SH file. This creates a file where the appropriate variables have been substituted. For example, if Configure determines that the C preprocessor, cpp, should be called as /usr/lib/cpp -, then the shell variable `cpp' will be set to `/usr/lib/cpp', and the variable `cppminus' to `-'. Suppose Makefile needs to invoke the preprocessor in one of its targets. Then Makefile.SH has an entry of the form `$cpp $cppminus filename'. When Makefile is extracted, the correct invocation is automatically generated (write once, run anywhere code :-)

Next, Configure will do a makedepend for you. This step consists of editing Makefile to automatically add include file dependencies. The `depend' target in Makefile spawns a small ed script that edits Makefile to delete the end of the file, and to append dependencies generated by $mkdep.

Finally, Configure will make the nest.a library as well as the REAL simulator binary (which is called 'simulate'). Ignore any warnings about non-portablity of the code.

If Configure stops in the make nest.a step, simply type make nest.a after fixing whatever problem arose. Then cd ../sim, and type "make depend; make final".

Step 6

In some cases, when you try to run the simulator, it will crash with an error message: `ADDRESS NOT FOUND!' This means that the file FUNC_TABLE has not been properly created. This file is created by the nm command in the `final' target of sim/sim/makefile, using the file nm.awk. It should look like

<hex address <function name The function name should not be prepended by underscores. If there are underscores, change the makefile to use nm2.awk instead of nm1.awk (or the other way around). Since `nm' implementations produce widely varying output, you may need to modify both the nm parameters and the awk file to get things to work.

Step 7

You are now ready to begin simulations. The REAL User manual and Programmers manual should help you get started. Good luck !