Platform Requirements ===================== Currently Jupiter VM only works on Linux on x86 platforms. Software Requirements ===================== Download and install the following sofware packages: For jupiter: - Python 1.5.2 (www.python.org) - GNU gcc 2.95.3 (gcc.gnu.org) - SUN jdk 1.3.1 (sun.java.com) Note: the release compiles with gcc 3.0.2 and gcc 3.1 too. However we found both not to optimize code as well as gcc 2.95.3. We also used other jdk versions (1.1.8 and 1.2.2), but we recommend 1.3.1. Newer versions of Python should work. We have not tested them. For classpath: See the "INSTALL" file in the classpath directory for a list of the required software. You will have to untar the "runtime.tar.gz" file (see below) and look into the "classpath/classpath-0.03/classpath" directory. This are the requirements for the GNU classpath we distribute with Jupiter. You will need the software listed for building the Java bytecode and the JNI native libraries as well. We used the gcc 3.0.2 (gcc.gnu.org) compiler. - Perl 5 - GNU autoconf 2.52 (www.gnu.org/software/autoconf) - GNU automake 1.5 (www.gnu.org/software/automake) - GNU libtool 1.4.2 (www.gnu.org/software/libtool) - GNU GCJ 3.0.2+ (GNU gcc 3.0.2) There are also some packages that are not always necessary: - gcjh from GCJ 2.96+ (you can use the one in GNU gcc 3.0.2) - GTK+ 1.2.x - libart_lgpl 2.1.0 - gdk-pixbuf (Only needed if you want to compile the native library) For GNU gcc: - GNU libtool 1.3.5 (www.gnu.org/software/libtool) Please read this whole INSTALL file before continuing since there are some forward references on how to proceed for some steps. Files ===== Obtain the following files from: http://www.eecg.utoronto.ca/jupiter jupiterjvm.tar.gz runtime.tar.gz Untar them in the same directory with the following command. Each of the files will create its own directory structure. tar -zxvf jupiterjvm.tar.gz tar -zxvf runtime.tar.gz Note: in the following settings $JUPITER_VM refers to the directory where you untarred the application files. Making GNU gcc ============== These are the options you will need to enable when compiling GNU gcc. Use GNU libtool 1.3.5. GNU libtool 1.4.2 (the required version for Classpath) fails with this version of GNU gcc. GNU gcc 2.95.3 and 3.0.2 configuration: ./configure --enable-threads=posix --enable-languages=c,c++,java --enable-libgcj You can use the --prefix option to locate this package in another directory (recommended). Making Classpath ================ The first installation step is to configure the Classpath runtime libraries. Unless you modify these classes, you will need to do this only once. Install and configure the required software for GNU Classpath (see above). Remember to add the respective executable files in your execution path. Tips for non-standard automake installations -------------------------------------------- If you install automake in a non-standard directory (through the --prefix option) you will have to follow these steps: cd to the directory where you installed GNU libtool 1.4.2 directory cd share/aclocal cp libtool.m4 file to the directory where you installed GNU automake 1.5, subdirectory shared/aclocal For example: cp libtool-1.4.2/share/aclocal/libtool.m4 automake-1.5/share/aclocal/ Also, you will have to copy the files "gtk.m4", "libart.m4" and "glib.m4" from its installation directory For example: cp /usr/share/aclocal/gtk.m4 automake-1.5/share/aclocal/ cp /usr/share/aclocal/libart.m4 automake-1.5/share/aclocal/ cp /usr/share/aclocal/glib.m4 automake-1.5/share/aclocal/ Once all the necessary packages are installed and configured type: cd $JUPITER_VM/classpath/classpath-0.03 There you will find some scripts for compiling and installing Classpath with the settings used by Jupiter. Edit the following files: config.sh make.sh In the PATH line, change the executable path to GNU gcc 3.0.2 to the directory where you installed the compiler. This will be useful later when GNU gcc 2.95.3 will become the default for compiling Jupiter. After you edit the files, execute: ./config.sh ./make.sh ./install.sh The installation script will pick the appropriate runtime directory for Jupiter. Making Codegen ============== cd to $JUPITER_VM/codegen and type: make clean && make You can use either gcc 2.95.3 or gcc 3.0.2 with this component. Environment settings ==================== Set the following environment variables in your profile. If your shell is bash, you must edit .bash_profile, if you use csh you must add them to .cshrc The examples are given for bash shell. Note: $PROFILE_OUTPUT is the directory where you would like to have the profiling information stored (when enabled). For the example, we assume that you have $CLASSPATH set. Environment variables --------------------- export JAVAC=javac export JUPITER_CLASSPATH=$JUPITER_VM/runtime:.:$CLASSPATH export JUPITER_PROFILE=$PROFILE_OUTPUT/prof.raw export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$JUPITER_VM/runtime PATH ---- The following programs must be in the path: - Python 1.5.2 - GNU gcc 2.95.3 - jdk 1.3.1 compiler (javac) - $JUPITER_VM/codegen - $JUPITER_VM/jupiter - $JUPITER_VM/jupiter/top $JUPITER_VM/codegen is a needed component for compiling jupiter. $JUPITER_VM/jupiter and $JUPITER_VM/jupiter/top must be included if you want to be able to run jupiter from any directory. The debug version of jupiter is stored in $JUPITER_VM/jupiter/top, the optimized version of jupiter in $JUPITER_VM/jupiter. Making Jupiter ============== cd to $JUPITER_VM/jupiter and type: make clean && make This will create a simple, unoptimized version of Jupiter which will include level 3 debug information (-ggdb3). It is a good idea to run the regression tests afterwards. For that purpose execute the following command: make regress After running the regression tests, you must execute: make clean && make to clean up all the extra information set in the executable during the regression test. Compilation commands ==================== This is a short list of other ways to compile Jupiter: Standard debug version: ----------------------- make Fast version: ------------- make quick Regression tests: ----------------- make regress Regression tests with fast jupiter version: ------------------------------------------- make qregress Standard debug version with profiler enabled: --------------------------------------------- make profile Fast version with profiler enabled: ----------------------------------- make qprofile Compilation cleaning: --------------------- make clean It is recommended that you execute "make clean" before using any of the previous options. Executable names ================ When jupiter is compiled in its debug version, its executable is called "jupiter" and it is located in $JUPITER_VM/jupiter/top. However, when the fast version is made, the executable is called "qjupiter" (which stands for quick jupiter) and it is located in $JUPITER_VM/jupiter. Running the project =================== Jupiter can be run like any other virtual machine. Currently there are no command line options that will change its behaviour. For example, to run the Test.class java class you should type: jupiter Test or qjupiter Test depending on the Jupiter version you compiled. End === If you want, you can remove the files you downloaded. There is a copy of the INSTALL and README files inside the "jupiter" directory. rm jupiterjvm.tar.gz rm runtime.tar.gz Using another compiler version ============================== When compiling with another compiler version, make sure you recompile all the following components: - codegen - boehm garbage collector - classpath - jupiter