These are frequently asked questions and answers for
Guarana 1.0: Carnival edition

Introduction
------------

Q1. What is guarana?

A1. Guarana is the name of an Amazonian bush tree, as well as its
    fruit, that contains lots of caffeine.  There's a very tasty
    soft-drink made from this fruit; if you ever come to Brazil, ask
    for a bottle of Guarana, you'll love it.  Richard Stallman did!
    Really!

    Guarana powder is commonly used as an ingredient to hot drinks
    that people have in order to stay awake for the whole Carnival
    holiday.  In Brazil, that's serious business: it's four days long!

    This all is to say that Guarana is a good replacement for Java :-)

Q2. No, I mean, what is Guarana, with capital `G'?  This piece of
    software I've just downloaded!

A2. Guarana is the name of a reflexive architecture we have created,
    that allows multiple meta-objects to be combined to define the
    meta-level behavior for an object.

    Some of its unique characteristics are the hierarchical
    organization of meta-objects and the preoccupation with security
    of both base-level and meta-level objects.

    Please read the technical report that describes Guarana for more
    details (it's available from my home page), and fell free to
    e-mail me if you have any doubts.

Q3. Who are `we' and `I'?
    When I write `we', I refer to the people who have created Guarana,
    namely:

	- Alexandre Oliva <oliva@dcc.unicamp.br> (that's me! :-)
	    Computer Science MSc student.  I work on computational
	    reflection, and I'm particularly interested in
	    fault-tolerant distributed systems.

	- Islene Calciolari Garcia <islene@dcc.unicamp.br>
	    Computer Science MSc student.  She works with distributed
	    systems, in particular, global snapshots algorithms.
	    In her spare time, she's my fiancee.  :-)

	- Luiz Eduardo Buzato <buzato@dcc.unicamp.br>
	    He's our advisor, which means he's the one to be blamed. :-)
	    He's a full-time professor at the Institute of Computing
	    of the State University of Campinas, SP, Brazil.  He's got
	    his PhD at Newcastle, UK.

Q4. So why would I want to use Guarana?

A4. Because we worked a lot to make it good for you! :-)

    Seriously, computational reflection is a powerful technique that
    allows one to implement management requirements, such as
    persistence, distribution, replication, fault-tolerance and
    concurrency control, just to mention a few, in a transparent way,
    that is, one doesn't have to modify the application code in order
    to add these features.

    Guarana was made so that the implementation of these features can
    be reused across several applications, *even if you don't have
    their source code*.  Furthermore, in Guarana, you can dynamically
    enable or disable these features, for selected objects.

Q5. Is Guarana 100% Java?

A5. No.  Although we haven't modified the Java Programming Language at
    all, we have modified a Java interpreter to provide for
    interception of operations such as method and constructor
    invocation, field and array element access, synchronization
    operations and object creation.

    It might have been possible to implement Guarana in 100% Java, but
    it would involve pre-processing class files with a custom
    ClassLoader.  Even standard Java classes would have to be
    preprocessed, which is unportable anyway.  In the beginning, we
    have actually tried to do that, but we haven't tried hard enough.
    Modifying the interpreter was much easier.

Q6. Why did you choose to modify Kaffe?

A6. Because it is Free Software!

    Furthermore, I don't have access to the sources of any other
    implementation of the Java Virtual Machine.  In particular, I'm
    not a source code licensee of Sun's JDK, and I really don't want
    to, since I like and support the Free Software concept, and
    working on JDK would forbid me from working on Kaffe or other Free
    JVMs.

    Anyway, if you do have access to JDK sources, and you'd like to
    implement Guarana on it, I'd be glad to lend you a hand.

Q7. Can I use Guarana with other programming languages?

A7. Certainly.  There's nothing in the reflexive architecture of
    Guarana that ties it to Java.  It was designed to be a
    language-independent reflexive architecture.  Java was chosen for
    the first implementation because of its simplicity and
    portability.

    I should note, however, that we don't currently have plans to
    implement Guarana for other programming languages.  If you decide
    to do so, please tell me.

Q8. Can I use concepts of Guarana on other reflexive platforms?

A8. Of course!  I couldn't prevent you from doing that, anyway!

    In fact, Guarana was originally intended to be an extension to
    existing reflexive architectures.  It has grown to a complete
    reflexive architecture, but you can easily borrow some of its
    concepts, such as meta-object composition and meta-configuration
    propagation to other reflexive architectures.

Q9. Do I have to modify my application source code to use Guarana?

A9. Not at all.  Your application code doesn't have to be modified,
    and you don't even need the source code of your application in
    order to make it reflexive.  In fact, we support the idea that you
    *shouldn't* modify the base-level code because of reflection,
    otherwise the separation of concerns between the functional (base)
    level and the management (meta) level is broken.


Installing and Running Guarana
------------------------------

Q1. How do I install Guarana?

A1. First, you should have downloaded the distribution file of
    Guarana.  It contains a file named README.  You don't have to read
    it, actually, it just says Guarana is Free Software and such.
    Instead, you should read the FAQ, which is this file you're
    reading already.

    Decompress the Guarana tarball into a temporary directory.
    Then, download kaffe 0.9.2 and the javasoft.com package into the
    guarana directory.  These tar files used to be available from
    ftp://ftp.kaffe.org/pub/kaffe.  If it ever disappears from there,
    there will be a copy of it available from my home page.

    From inside directory guarana-1.0, run `make'.  This will
    decompress the kaffe packages and apply the patch file that
    modifies kaffe so that it supports Guarana.  You may need GNU
    patch, if your system lacks a patch utility, or if it can't handle
    the patch file.

    Ok, now you're ready to build: enter the kaffe-0.9.2 directory,
    configure, make and make install, as you used to do with kaffe.

Q2. What if it doesn't build?

A2. I have tested it myself on Sparc Solaris 2.5 and 2.6, and on
    RedHat Linux i386 4.0 and 5.0, with both engines (jit and intrp).

    There's a bug in gcc 2.8.0 and egcs 1.0.1 on Linux/x86 that causes
    it to miscompile function BR_unicamp_Guarana_Guarana_deliver() in
    Guarana.c; it is fixed in the latest snapshot of egcs, so I hope
    it will be fixed in release 1.0.2, and in gcc 2.8.1.

    I also tried to build kaffe+guarana on RedHat Linux alpha 5.0,
    IRIX 6.3, IRIX 5.2 and SunOS 4.1.3.  It won't build on the first
    two due to portability problems regarding the argument list saving
    mechanism I decided to use.  It won't build on IRIX 5.2 because of
    some stack ABI incompatibility in threads.s (kaffe 0.9.2 wouldn't
    build on it either).  On SunOS 4.1.3, it will build, but it won't
    run because of some shared library issue that shouldn't be hard to
    fix.  I won't delay the release just because of that.

Q3. How hard is it to port Guarana to other platforms?

A3. Well, I should confess I've used one particularly dirty and very
    unportable trick to get a working prototype as soon as possible.

    It depends.  The main portability problem has to do with the way I
    store argument lists.  Assigning to va_arg()s is non-portable, but
    I used it anyway.  This may be changed to a more portable
    mechanism in the future, but you may try to port it now.

    Take a look at the end of kaffe/kaffevm/classMethod.[hc], you may
    have to override some of the #defines there.  Add the necessary
    definitions to md.[hc] in the appropriate config directory.
    Contributions are welcome. :-)

Q4. How do I run Guarana?

A4. Just like you invoked kaffe.  There isn't a separate executable
    program; the interpreter is 

    Well, actually, you need to modify the CLASSPATH so that the
    guarana shared library is loaded (unless you're not using shared
    libraries) and the guarana jar file is included.

    The easies way is to make sure your environment contains all the
    definitions listed in file ENVIRONMENT, which should be created by
    `configure'.

    I myself prefer to use shell-scripts that will set up my
    environment and invoke kaffe for me.  I don't understand why kaffe
    doesn't do it itself...

    Just save the script below in same directory in your PATH, fix the
    definition of variable prefix, name the script `kaffe' and make it
    executable.  You may also create hard-links or copies of this file
    with names such as jar, javac, kaffeh, etc.

#!/bin/sh
prefix=<insert the kaffe installation prefix here>
# follow soft links
file=$0
while [ -h $file ]; do
  newfile=`ls -l $file | sed s/'.* -> '//`
  case "$newfile" in
  /*) file="$newfile";;
  *) file="`dirname "$file"`/$newfile";;
  esac
done
# redirect 3>&1 for verbose run
[ -t 3 ] || exec 3>/dev/null
name=`basename $file`
CLASSPATH=${CLASSPATH-.}:$prefix/share/kaffe/classes.zip:$prefix/lib/libguarana.so:$prefix/share/kaffe/guarana.jar
export CLASSPATH
echo setting CLASSPATH="$CLASSPATH" >&3
LD_LIBRARY_PATH=$prefix/lib${LD_LIBRARY_PATH+:$LD_LIBRARY_PATH}
export LD_LIBRARY_PATH
echo setting LD_LIBRARY_PATH="$LD_LIBRARY_PATH" >&3
PATH=$prefix/bin${PATH+:$PATH}
export PATH
echo setting PATH="$PATH" >&3
echo running ${DEBUG} $name "$@" >&3
# set DEBUG=gdb for debugging
exec ${DEBUG} $name "$@"

Q5. Is there any sample code available?

A5. Yes.  After you apply the guarana patch, you should find a rather
    complicated example in directory
    packages/guarana.unicamp.br/sample.  It shows most of the
    single-meta-object functionality of Guarana.  Composing
    meta-objects is left as an exercise for the reader.

Q6. What if I have any doubts about Guarana?

A6. Please e-mail me, I'd be pleased to lend you a hand, and to
    try to improve the existing documentation.

Q7. What if I Guarana doesn't work as I expected?

A7. Maybe your expectations were incorrect.  :-)

    Sometimes, Guarana does more than we'd expect it to do.  

    On the other hand, you may have found a bug.  Please send me a
    detailed bug report.  Code snippets and stack traces are welcome.

Q8. Is there anything else I should know?

A8. Yes.  You should read the paper that describes the Reflexive
    Architecture of Guarana (it is available from my home page).
    Additionally, the API of Guarana is worth having on-line; you may
    rebuild it from the sources: just run `make docs' in directory
    packages/guarana.unicamp.br/APIguarana/classes/src.  If you, for
    any reason, modify the Java part of the source code of Guarana,
    run `make depend' in the `src' directory once.  After that,
    running `make' should be enough.  After rebuilding the sources,
    you may wish to `make jar' in directory APIguarana, then `make
    stubs' in APIguarana/lib.

Q9. Why is it so much slower than kaffe?

A9. Basically, because it is a quick and dirty proof-of-pudding
    implementation.  I've got lots of plan on how to improve
    performance, but I've got a MSc Thesis to finish. :-)

    Here's a list of points may considerably improve the performance
    of Guarana:

    - instead of checking, for each operation, whether an object is
      associated with a meta-object or not, a modified dispatch table
      could be set up, so that non-reflexive operations do not incur
      into any additional cost.

    - reification of method invocations have to parse the method
      signature several times.  A good way to improve this situation
      would be to modify the argument list reification and dispatching
      mechanisms.  With the JIT engine, we could generate a custom
      function per method that would load arguments from registers and
      stack and store them in a memory region, and another function
      that would load back registers and stack from memory and call
      the actual method.  With the INTRP engine, we could simply copy
      stack slots.

* Java is a trademark of Sun Microsystems, Inc.