These are frequently asked questions and answers for
Guarana 1.4.1: Brazilian Independence Day edition

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

Q.  What is guarana?

A.  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 :-)

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

A.  Guarana is the name of a reflective architecture we have created,
    that allows multiple meta-objects to be combined to define the
    meta-level behavior for an object, which improves code reuse.

    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
    send e-mail to the Guarana mailing-list if you have any doubts.

Q.  Who are `we' and `I'?

A.  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.

Q.  So why would I want to use Guarana?

A.  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.

Q.  Is Guarana 100% Java?

A.  No.  Although we haven't modified the Java Programming Language,
    we have had to modify the 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 is impossible to implement Guarana in 100% Java.  We have tried 
    really hard to do that, but we ended up proving it was
    impossible.  A paper describing the problems we have encountered
    is underway.

Q.  Why did you choose to modify Kaffe?

A.  Because it is Free Software, and it is the most portable existing
    Java Virtual Machine!  What could have been a better choice?

    Furthermore, I didn't have access to the sources of any other
    implementation of the Java Virtual Machine when I started (now
    there's Japhar, the GNU JVM).  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.

Q.  Can I use Guarana with other programming languages?

A.  Certainly.  There's nothing in the reflective architecture of
    Guarana that ties it to Java.  It was designed to be a
    language-independent reflective 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.

Q.  Can I use concepts of Guarana on other reflective platforms?

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

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

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

A.  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 reflective.  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
------------------------------

Q.  How do I install Guarana?

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

    Decompress the Guarana tarball into a temporary directory.
    Then, download one of the Kaffe snapshots recommended for use with
    Guarana; they should be available wherever you downloaded Guarana
    from.

    This release of Guarana is compatible with both the latest
    snapshot of Kaffe 0.10.1 ---the old release that does not support
    AWT and depends on Sun's implementation of the Java Core
    Library---, and with recent snapshots of Kaffe OpenVM 1.0.b1, the
    new release that includes an almost complete implementation of the
    Core Library, and reintroduces support to AWT.

    From inside the Guarana directory, run either `make' or `make
    old', depending on which version of Kaffe you have downloaded.
    If you have already downloaded them into a different directory,
    just specify `KAFFE_TGZDIR=/that/directory' when you run make.
    This will decompress the Kaffe snapshot and apply a 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.

    You may try to use this release of Guarana with newer releases or
    snapshots of Kaffe.  Some newer snapshots of Kaffe tested with
    Guarana may be available in the home page of Guarana.  In
    this case, you must uncompress it yourself, then specify
    `KAFFE_DIR=<DIR>', where `<DIR>' is the directory in which the
    sources of Kaffe sources were stored.

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

Q.  What if it doesn't build?

A.  You have probably found out Kaffe hasn't probably been ported to
    your platform yet.  Note that there was a major change in the
    platform-specific interface of Kaffe from release 0.9 to 0.10, so
    some formerly-supported platforms may have become unsupported
    again.

    Guarana was built and tested on the following platforms:

	- Solaris 2.5/sparc, JIT and intrp
	- Solaris 2.6/sparc, JIT and intrp
	- RedHat Linux 4.0/x86, JIT and intrp
	- RedHat Linux 5.0/x86, JIT and intrp
	- IRIX 6.3/mips, intrp only (but not release 0.10.1)
	- SunOS 4.1.3/sparc, JIT and intrp --with-staticlib

    On SunOS 4.1.3, Kaffe with dynamic libraries would build but
    not run.  It is a known problem of Kaffe on the dynamic linker of
    SunOS 4.1.3, that is reported to be fixed in SunOS 4.1.4.
    Building --with-staticlib is a possible work-around.

    On IRIX 5.2, Kaffe intrp would build but not run because Kaffe
    only supports the n32 ABI, not supported by IRIX 5.2.

    On RedHat Linux 5.1/alpha, Kaffe would not build due to compile
    errors.

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

A.  Since Guarana is not platform-specific at all, it is as portable
    as Kaffe itself.

Q.  How do I run Guarana?

A.  Just like you invoked Kaffe, i.e., run `kaffe' in order to start
    any Java program, `javac' to start the Java compiler, etc.
    `guarana' and `guaranac' are copies of, respectively, `kaffe' and
    `javac', for your convenience, but that's all.

Q.  Is there any sample code available?

A.  Yes, there is a directory called `sample' that contains plenty of
    examples.  The ones in the root directory are just simple examples
    for testing Guarana; in `tutorial-src', you should find all the
    sources for the Guarana Tutorial, a paper to be published soon; a
    preview version of this document should be available at the time
    of this release.  In directory `performance', you'll find a
    program that times several operations, that was used to collect
    data for the paper The Implementation of Guarana, to be published
    soon as well.

    Most examples are based on class MetaLogger, contained in the
    `tutorial-src', so you'd better add this directory to the
    CLASSPATH.  In order to compile all sample sources, just type
    `make' in the source directory.

    Note that you can use this MetaLogger to start any Java
    application in logging mode: check the documentation of
    MetaLogger.main for usage.

Q.  What if I have any doubts about Guarana?

A.  Subscribe to the Guarana mailing-list (send e-mail to
    guarana-subscribe@makelist.com), then post your question to
    guarana@makelist.com.  There is a mailing-list archive at
    <URL:http://www.findmail.com/listsaver/guarana>, if you'd rather
    check for common questions before posting.

    Note that the list will only accept posts from subscribers, in
    order to avoid spamming.

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

A.  Maybe your expectations were incorrect.  :-)

    Sometimes, Guarana does more than we'd expect it to do, because we 
    don't know enough about the internals of the class/object we're
    reflecting upon, or we just couldn't foresee its behavior.

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

Q.  Is there anything else I should know?

A.  Yes.  You should read the paper that describes the Reflective
    Architecture of Guarana (it is available from my home page).  You
    may also find the Guarana Tutorial useful.  Additionally, the API
    of Guarana is worth having on-line; you may rebuild it from the
    sources: just run `make doc' in directory src.  If you, for any
    reason, modify the Java part of the source code of Guarana, run
    `make' in the `src' directory.  After rebuilding the sources, you
    may wish to `make jar' and `make stubs' in directory
    kaffe-<version>/kaffe/kaffevm/guarana.

Q.  Why is Guarana slower than Kaffe?

A.  Why do you think it is?  Did you really measure its performance
    with real-world applications?

    My performance tests, with ``real-world'' applications such as
    compiling and running `HelloWorldApp' have indicated that the
    interception code inserted for Guarana support produces a
    *negligible* impact on performance on the interpreter engine.
    (Actual figures can be found in ``The Implementation of Guarana'',
    available from the home-page of Guarana)

    The JIT engine, particularly the JIT compiler itself, exhibits an
    sensitive performance drop, because some bytecodes now produce
    much more complex machine-code.  However, what seems an
    unacceptable performance impact for short-running test programs,
    turns out to be only about 20%, on average, for long-running ones.

    Of course, all this assumes no use of reflection at all.  When you
    introduce meta-objects, even do-nothing ones, performance drops
    down a lot, because interception of operations has to take
    place. But then, isn't intercepting operations what reflection is
    all about?

    Anyway, we've still got plans on how to make the small
    performance impact yet smaller; ``The Implementation of Guarana''
    describes some future optimizations.


* Java is a trademark of Sun Microsystems, Inc.
