The Janos Java NodeOS
---------------------

This software is part of the Janos Project at the University of Utah:

    http://www.cs.utah.edu/flux/janos/

    Send any comments, questions, bugs, or fixes to:
        janos-discuss@flux.cs.utah.edu.  

    (You can subscribe to this and other Janos mailing lists from the
    Janos web page.)

This distribution contains the Janos Java NodeOS Bindings (also
referred to as the 'jnodeos').  The jnodeos is a presentation of the
NodeOS[1] interface in Java.  The core of the source is in the
src/nodeos subdirectory.  There are two "back-ends" in this
implementation, one implemented in pure Java and one which calls on
Moab's NodeOS API.  Compilation defaults to the "pure java" version.

[1] NodeOS Interface Specification at http://www.cs.princeton.edu/nsg/papers/nodeos.ps


Prerequisites:
    GNU make
        On most BSD-based distributions GNU make is installed as
        'gmake'.  Use that.  (The configure script will find it for
        you.)

    A Java Compiler
        Jikes, or a JDK1.3 javac, is required.  No other javac that we
        know of can both initialize our blank final fields and compile
        our code bug-free. Jikes is good for you anyway; if you're not
        using it now, you'll thank us when you start.  We use version
        1.06.  (Though moving to 1.12 would be an improvement.)

        You can get Jikes from:
        http://www10.software.ibm.com/developerworks/opensource/jikes/

        NOTE: The compiler shipped with Kaffe, kjc, has some bugs in
        it that our code tickles.  However, we don't check for this
        bug at configure-time.  There are regression tests that will
        check it, though.

        Older versions of Jikes (e.g., v0.47) do not correctly
        propagate public static final longs into classes that use but
        do not define them.  (E.g., B uses A.longVal).  This only
        affects the debugging infrastructure.  There is no
        configure-time test for this bug.
    
        The configure script will run some minimal tests on your java
        compiler to tell you if it's up to speed.

        Please let us know if you are successful in getting another
        Java compiler to compile the Janos Java NodeOS.


    A Java Virtual Machine
        We use a recent Kaffe CVS snapshot.  JDKs 1.1.x, 1.2.x, and
        1.3 from Sun seem to work fine.  You could probably even run
        on an older 1.0.x JVM, as we use few (if any) of the classes
        introduced in 1.1.  (Though we haven't tested this).

        You can get the latest CVS version of Kaffe from
        http://www.kaffe.org/

Building the Janos Java NodeOS:
    Read the file INSTALL for more details on building the Janos Java
    NodeOS.

    jnodeos has a configure-like script that tries to figure out in
    what ways your system is broken (er... different from ours).
    
    Ideally it works like this:

        cd <jnodeos dir>
        ./configure
        ./build

    If configure cannot find a passable javac, try this:
        ./configure --javac=/path/to/recentjdk/bin/javac

    If you have jikes, but it isn't working, it is probably because
    the classpath is not set correctly.  Try this:
        ./configure --classpath=/path/to/jdk/lib/classes.zip

    You can run configure in another directory if you don't want to
    contaminate the source tree.  All files will be generated in that
    directory.

    The configure scripts will generate a script 'jnodeos' (which will
    also be installed in the bin subdirectory of the install tree).
    This script sets the CLASSPATH environment variable to include the
    necessary Janos Java NodeOS class archives.  It defaults to
    running 'java' as the JVM, though you can override that by setting
    the JAVA environment variable to point to some other JVM.


    Still stuck?  Read the detailed instructions in INSTALL.  Or,
    send a message to janos-discuss@flux.cs.utah.edu.


Testing the Janos Java NodeOS:

  o Hello, World!

    The simplest test is the Janos HelloWorld.  You can run it like
    this:

    cd <jnodeos dir>
    jnodeos edu.utah.janos.nodeos.Main edu.utah.janos.tests.HelloWorld

    You should see some output like:

        Janos Java NodeOS v1.2.0
        Hello, world!
        Shutting down.

    If that doesn't work try:

    sh -x jnodeos edu.utah.janos.nodeos.Main edu.utah.janos.tests.HelloWorld

    to see what might be going wrong.

  o Regression Tests

    The regression tests will provide a quick check that the system is
    really working for you.  To that end a 'check' script is generated
    that runs the basic regression tests.  Again, for more information
    on the regression tests, read the README.testsuite document.

    cd <janos dir>
    ./check


Let us know what you think!
janos-discuss@flux.cs.utah.edu