These are frequently asked questions and answers for
Guarana 1.5: Braziling Patroness 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 PhD 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 PhD student.  She works with distributed systems, in
particular, consistent 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 hardq, 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 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 Kaffe
OpenVM 1.0b2, the new release that includes an 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 with LD="ld -n32" (Kaffe 1.0* only)
    - SunOS 4.1.3/sparc, JIT and intrp --with-staticlib and a patch to
add `#include <sys/types>' to `libraries/clib/awt/X/imgjpeg.c'.  I
hope this patch will soon be installed in the CVS tree of Kaffe.

    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.

    I haven't tested other platforms.

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 to support the MOP of Guarana 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 a
sensitive performance impact, 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, lots of
objects have to be created and garbage collected, etc.  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.
