Chess Sponsors and Researchers who attend reviews
Previous topic  |  This topic  |  Next topic
Previous article  |  This article  |  Next article

Christopher Brooks, 9 Jun 2004

Displaying attached file README.txt: (Back up)

$Id: README.txt,v 1.15 2004/06/02 18:14:50 cxh Exp $

# contents of this directory
README.txt : this file
bin	: scripts for the metroshell and some backend tools
doc	: documents for the Metropolis meta-model and their libraries
examples: Metropolis meta-model examples
lib	: Metropolis meta-model libraries
src	: Metropolis meta-model compiler and backend tools

Metropolis: Design Environment for Heterogeneous Systems
Send questions and bug reports to metro_comp@ic.eecs.berkeley.edu.
See also the Metropolis website: http://www.gigascale.org/metropolis

The Metropolis meta-model compiler
The Metropolis meta-model consists of the frontend and a set of
backend tools.  The frontend parses meta-model files, creates
Abstract Syntax Trees (ASTs), and applies a series of passes on the
ASTs to make resolutions and semantic analysis. A Backend tool
browses and analyzes the ASTs to generate a model appropriate for the
backend. For example, a backend for a simulation tool in a particular
language generates files that describe the meta-model design in the

The meta-model compiler requires Java Development Kit (JDK) and a C
compiler for installation.  The compilation has been tested under the
following environments:

* Linux
 - OS:		Red Hat Linux 7.1, 8.0, 9.0
 - JDK:		Java 1.4 or later
		We use exception chaining, which requires Java 1.4.
		JDK 1.4 under versions of RedHat earlier that RH 8.0
		hung while compiling code in 
		JDK 1.4.2_01 and later seems to work fine
 - C compiler:	gcc 2.96, 3.2.2

* Sun OS
 - OS:		Sun Solaris 2.7, 2.8
 - JDK:		1.4 or later
		We use exception chaining, which requires Java 1.4.
 - C compiler:	gcc 2.95, gcc 3.2.2

* Windows under Cygwin
 - OS		Windows XP
 - JDK		1.4 or later
		We use exception chaining, which requires Java 1.4.
 - C compiler:  gcc 3.3.1
At this time, we do not recommend running Metropolis models 
under Cygwin, but Cygwin can be used to generate the code that
is compiled under Microsoft Visual C.

Note that many of the SystemC regression tests fail under Cygwin.
See doc/coding/cygwin.htm for details.  These failures have
nothing to do with Metropolis, they are problems with Cygwin and

Note that under Cygwin with SystemC-2.0.1 the producers_consumer
example runs but does not produce any output.  We are not sure why,
we suspect a problem with SystemC under Cygwin.
You can install all of Cygwin or else a subset that includes 
make, gcc and other programs.
Such a subset may be found at:

* Windows under Microsoft VisualStudio 6.0 
 - OS		Windows XP
 - JDK		1.4 or later
		We use exception chaining, which requires Java 1.4.
 - C compiler:  Microsoft VisualStudio 6.0 sp4
Note that support for MSVC is incomplete, it is best if you
read doc/coding/msvc.htm, follow the Cygwin installation and 
complete the msvc installation.

Take the following steps for installation. 
1. Install System C 2.0 from http://www.systemc.org in 
either /usr/local/systemc-2.0 or ~/src/systemc-2.0

System C 2.0.1 will work, though we have tested primarily under
System C 2.0.

The following directories are searched for System C installations
in the following order
    1. ~/src/systemc-2.0.1
    2. ~/src/systemc-2.0
    3. /usr/local/systemc-2.0.1

2. Define the METRO environment variable to the location
of the Metropolis directory
For example, under csh, you might do
  % setenv METRO /home/metro

METRO should point to the directory where this file is found.
i.e. the current directory should become $METRO

Note that under Cygwin bash, you should _not_ do
  % METRO=`pwd`
Instead, do
  % METRO=c:/src/metro
This is because under Cygwin bash, `pwd` is likely to return a path
that includes "cygdrive" and Java does not understand the
"cygdrive" notation.

METRO_CLASSPATH can be used to specify a set of directories for top-level
packages at which meta-model designs to be compiled are
located. Multiple directories are separated by the standard path-separator
character for your platform, that is, a colon (:) on Unix systems, or a
semicolon (;) on Windows systems.  It is wise to include $METRO/lib
and $METRO/examples by default.  For example,
   % setenv METRO_CLASSPATH "$METRO/examples:$METRO/lib"
or, in Cygwin bash on Windows:
   % export METRO_CLASSPATH="$METRO/examples;$METRO/lib"
(Note the semicolon).
If nothing is specified, set it as empty:

3. Run configure

This will check for Java and the C/C++ compilers,
read in $METRO/mk/metro.mk.in and generate $METRO/mk/metro.mk

4. Compile:
make >& make.out

A regression test can be performed on some examples included in this 

The regression test can be performed by typing 
    cd $METRO
    make tests

Metroshell can be found at $METRO/bin/metroshell.

It will give a metropolis> prompt, and type help
for available commands and their information.

The metroshell can be used in a batch mode.  To do this, prepare a
file, say myscript, which lists a sequence of metroshell commands, and
then type:
  metroshell -ni myscript
See $METRO/examples/test/shellcmd for an example of the file.

If metroshell commands are put in a file .metroshrc located at the home
directory, these commands are executed in the very beginning when the
metroshell starts up.  This can be used for initialization.  The
following is an example.

% more ~/.metroshrc
# comment: my initial set up for the Java locations
set JDK /usr/java1.3
set java  $JDK/bin/java
set javac $JDK/bin/javac
classpath add ..

Note that one cannot use Unix environment variables in the second
argument of the set command in .metroshrc.

Various backends can be invoked using another shell script
$METRO/bin/metacomp. The basic usage of this script is:

  metacomp [options] source_files

The option "-h" displays the help for the meta-model compiler, including the
complete list of options of the compiler. For example, the options allow the
user to specify the back-end module that will be invoked once the meta-model
file has been parsed.

There is an example at $METRO/examples/test.  README.txt file in the
directory explains the example and how to use the meta-model compiler
and a System C simulation backend tool.

Files written in the meta-model language should be text files with extension
"mmm" (initials for "Metropolis Meta-Model"). The user invoking the compiler
should have enough privileges to READ the source files and CREATE files in 
the same directory where the source files are stored.

Meta-model sources can be organized in packages, in the same way as Java
packages. All source files of a package are stored in a single directory.
Subpackages of a package are stored in a subdirectory of the parent
package, thus creating a directory hierarchy. 

The compiler has to know all the directories where it can find top level
packages (packages with no parent, like "java" in the Java language).
This set of directories, known as the "classpath", can be specified in
the METRO_CLASSPATH environment variable.  Users can list the directories
in the classpath, separated by the standard path-separator character for
their system -- for example, a colon (:) on Unix systems, or a semicolon (;)
on Windows systems.  Some examples of classpath variable (using csh syntax)
would be:

 * If some meta-model packages that we need to use in the compilation are 
   stored in the paths "/hm/mysystem" and "/hm/research", then
   % setenv METRO_CLASSPATH "/hm/mysystem:/hm/research"

 * An example on a Windows platform might be:
   % setenv METRO_CLASSPATH "c:/metro/mysystem;e:/mylibs/sometree"
   (Here each directory specification is prefixed by its drive ID, and is
   separated from other directories in the class path by a semicolon.)

 * No user-defined package is available, then

 * The only package available is in "/usr/local/mmm/pkg", then
   % setenv METRO_CLASSPATH /usr/local/mmm/pkg

If user-defined meta-model packages are not needed in the compilation,
the variable can be defined empty. Remember to use "" to enclose the 
list of paths if you define more than one directory.  One can use the
classpath command of the metroshell to register new paths as
classpaths. These paths are recognized as valid classpaths until the
metroshell is quit.  For example, 
 classpath add /usr/local/mmm/designs /hm/myname/mydesigns
will add the two paths as the classpath.

If you want to add your design as a part of the regression test
executed when "make test" is typed in the current directory, do the

1. In the directory where your design is found, prepare a Makefile
   with a target name "test:" and write a script that you want to
   be executed in the regression test.  See $METRO/examples/test
   for an example.

2. In ./Makefile.common, append the path to the directory of your
   design to the variable TESTDIR.

Previous topic  |  This topic  |  Next topic
Previous article  |  This article  |  Next article
©2002-2018 Chess