Guest VM can be built using shell scripts or using the Eclipse IDE.
We strongly recommend first checking out and building Maxine, following the
instructions here, to provide
a basic sanity check. Note, be sure to checkout a version compatible with Guest VM as
described here.
Building Guest VM
For instructions on how to develop in Eclipse, see here.
For building from the command line, Guest VM leverages the max script from Maxine,
through a Guest VM specific script guest that resides in the GuestVMNative/bin directory.
Running the guest Script
The only prerequisites for using this script are that you set the following environment variables:
JAVA_HOME - to your JDK 1.6 installation directory
JUNIT4_CP - to the location of a jar file containing JUnit 4.0+
XEN_ROOT - to your Xen installation directory
You can build all or part of of Maxine and Guest VM with the build subcommand of guest. To build everything do as follows:
% bin/guest build
If you have already built Maxine, you can build just the Guest VM projects as follows:
Note that the order is important as each project is compiled separately and there are
dependencies between projects.
Building a Guest VM Image
Before building an image, you should choose the network configuration for the image, since
the default behavior is set at image build time. See here for details.
To build an image you should be cd'ed into the GuestVMNative project directory.
You can then build a Guest VM image as follows (output elided):
% bin/guest image
This script performs the following actions:
builds the Guest VM microkernel (GUK) using gmake
performs a Maxine image build customized for Guest VM
builds the Maxine native (C) code targeted for Guest VM using gmake
builds the GuestVMNative C code using gmake
links all of the above to produce an image that can be run
under Xen using the xm command
The resulting image file is called guestvm.
N.B. After pulling a new version of Maxine or Guest VM it is advisable to
do ./guest build -clean before building an image, to avoid
picking up zombie class files from the previous version which can cause a
build failure.
Building the Maxine Inspector for Guest VM
The Maxine Inspector for Guest VM executes as an user-level
process in one Xen domain while the target Guest VM image runs as
a separate domain. This is similar to the process to process
debugging model of a standard operating system environment however
standard Xen prohibits an unprivileged domain (domU) from accessing
the state of another unprivileged domain. Note also that since
the Inspector is a user-level process and not part of the OS kernel
it also requires special support from the kernel to access the target domain's state.
This support is available under Linux but not Solaris xVM. I.e.,
the Inspector must run in a Linux domain even when running Solaris xVM.
Normally the Inspector assumes that the host and target environments are the
same, i.e., process to process debugging in the same OS. This is not the
case when running the Inspector on Linux debugging a Guest VM domain.
This requires that the low-level libraries for debugger-debuggee communication
be rebuilt for this cross-debugging environment. This code depends
on some additional support in guk that is not built by default,
and must be built on a system that has a built Xen system available.
The additional guk support is in guk/tools/db-front.
% cd $GUESTVM_HOME/guk/tools/db-front
% gmake
%
Then install the resulting library, as the root user:
% sudo gmake install
Now build the GuestVM variant of the Maxine Inspector libraries:
% cd $GUESTVM_HOME/maxine/Native
% gmake TARGETOS=GuestVM tele prototype
It should now be possible to run the Inspector as follows:
% cd $GUESTVM_HOME/guestvm/GuestVMNative
% sudo bin/runins &
Note, since the Inspector can get hung if the target domain becomes unresponsive, we recommend
running it in the background, to retain shell access.
It is advisable to run the Inspector with the same JDK environment that was used to build the Guest VM image being debugged. This can be ensured using the -java option to runins:
% sudo bin/runins -java path_to_java_executable
Note also that the Inspector needs access to the same set of classes as the Guest VM. So, for
non-trivial applications, it will be necessary to specify these with the -cp option.
