Implementation of the Aardappel programming language
Java Other
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
projects
src
LICENSE.md
aarded.bat
aarded.sh
build.xml
readme.txt

readme.txt

Aardappel Programming Environment, July 2000.

User Manual

Wouter van Oortmerssen


Installation
============
The Aardappel Editor is written in Java, and the compiler generates
Java applications so you will need a Java SDK or JRE installed on your
system (a Java enabled browser won't do). Get it from:

http://java.sun.com/jdk/

To install AardEd itself simply unzip it to any place you like (with
directories). If you have Java correctly installed you should be able
to run AardEd using the included aarded.bat (windows) or aarded.sh
(any unix) scripts. You may need to modify these to use "javaw" or
"jre" instead of "java", depending on what kind of Java you have
installed.


Using AardEd
============
Note well: this text is there to provide all practical information not
included in my thesis, as such it does not explain the language. To be
able to use AardEd sensibly you are advised to read atleast chapters 3
and 6 of my thesis, available from:

http://strlen.com/aardappel/

A few sample Aardappel projects have been included with AardEd that
you can load, browse through, and execute, to get a feel for the
system. Use "open" from the project menu and go to the "projects"
folder in the top directory. Load "project.ap" from any of its
subdirectories. "factorial" or "qsort" are good starting points.

To create your own project, simply create a new directory below the
projects dir (or anywhere else) and use "new" from the project menu to
save a "project.ap" file there. Then add new bags & modules to your
project and edit them. To save, use "save all" from the menu, which
saves all bags & modules and your project file. Quitting and
restarting AardEd will automatically load the last project you were
working on.


Editing programs
================
Again, most should become appearent from what is in the thesis and
some experimenting, but here are some general hints & tips to get
started.

The best way to create any tree is drag and drop: start at the root
and drag/replace children as you go. If you drag trees from another
rule they will be copied, if you drag them from pattern to expression
part you will create a placeholder. If you want to copy something
from another window, use copy & paste.

An alternative method to create trees is typing the name of the
root atom in the string widget at the top of the window. If it's
an existing tree with rules for it, Aarded will fill in the
children for you. To add children to a tree, use the the right
mouse button menu (ctrl-A).


Creating your own icons
=======================
You can associate a graphical representation with any atom you use in
your programs.  Simply create the picture in a paint program, save it
in gif format using transparent background if applicable, and put it
the "atomimages" subdirectory under <name>.gif, where <name> is equal
to the atom you want replaced (for operator symbols use their ascii
value). AardEd will automatically scan these pictures when it starts
up and render your atoms accordingly.

Similarly if certain icons confuse you, all that you need to do is
remove them from that directory (currently the only icons I made are
some operators, "lambda", and a couple for the qsort example).


Running an Aardappel program separate from AardEd
=================================================
To give compiled Aardappel programs to other people without
the environment, simply create a zip or jar that includes
the following files:

CompiledAardappel.class
AardappelRuntime*.class
r/*.class

and maybe a script file that runs

java CompiledAardappel

CompiledAardappel.class is simply the last compiled expression, so
make sure you select "compile standalone" on the appropriate top level
expression / bag before you copy these files.


Distributing programs over a network
====================================
To set up a machine as a server that can help out in Aardappel
computations, it needs to have a copy of these files:

AardappelRuntime*.class
r/*.class

AardEd uses RMI to communicate with the servers, so you need to have
"rmiregistry" running. This should be part of any Java installation.

You can then launch the server as follows:

java r/AardappelServer localhost

If everything went ok, this will then tell you that it is ready to
participate in computations. On your client machine you can now run
your Aardappel program as standalone and specify the ip addresses /
names of any servers on the command line:

java CompiledAardappel server1 server2 ...

if everything went ok your program should now run distributed over all
available servers and the client!

You can also start distributed computations directly from AardEd, but
depending on the way your system is set up there may be problems with
that. The infrastructure for it is in place, look at the source for
Compiler.compile() if you are interested.

In most cases the above is too simple to be true, and trying to run a
distributed computation out of the box will result in various obscure
security exceptions being thrown. RMI is subject to the
RMISecurityManager, which under Java 1.2 or greater gets its
permissions from the java policy files (they don't exist on 1.1, so it
should be much easier to run the distributed runtime system on that),
which in most default installations don't allow enough for the runtime
system to work.

To fix this requires you fiddle with the policy files in your Java
installation. You can take the lazy route and put something like
(replace <path> with where you installed AardEd):

grant codeBase "file://<path>/aarded/-" {
	permission java.security.AllPermission;
};

at the top of java.policy (depending on your system, the one in
jre/lib/security, or you can create one in your home directory or in
the aarded directory, in which case you may need to point to it from
the java.security file). Alternatively you can read up on Java
security and try to grant permissions more precisely :)


Not implemented functions
=========================
from the menu: "deploy" (use compile standalone in the treeview
editors instead).


Source code
===========
This release comes with full sourcecode, which you can browse out of
mere interest or enhance yourself.

One of the first thing you may want to add if you intend to write some
Aardappel programs are more builtin functions: the basic ones are
there but there are bound to be ones missing. To do this, add a
function to the existing ones in AardappelRuntime.java, like:

public static Rval builtin_rule_myfunction_2(Rval a, Rval b) { ... };

(the 2 is the number of arguments). Then in the constructor in
Compiler.java add a line like:

builtin("myfunction",2);

Now you can use trees with root atom "myfunction" and two children and
have this function evaluated instead. Look at other builtin functions
to see how to access an Rval. Caveat: if you add functions that have
side effects you will have to use AardappelServer.marshall() to make
sure they are executed on the client, if you want them to behave
correctly in a distributed program (look at "plot" for how to do
this).

General guide to the source code files:

the runtime system consists of AardappelRuntime.java + all the files
in the "r" package, most of which implement various runtime
representations of Aardappel values. Most interesting is the bag,
which implements Linda (see RbagTS.java)

The project editor is in Mainwin.java and Project.java, and the
graphical editor is in Treeview.java, all the subclasses of Code.java
(Atom/Int/Bag/Tree/Rules), and the various *info.java classes.

The compiler is in Compiler.java, Codegen.java (a generic interface to
the jas package) and Sym.java (contains the functionality for
compiling all rules with a certain root atom).

most code should prove to be easily modifyable and maintainable.


Future versions, legality status etc.
=====================================
I would like to improve AardEd, especially now it finally got
somewhere: all raw functionality is in, but it could do with a lot of
improvements. I can't make any promises however, since I have taken on
a quite demanding job, so don't come bug me for new releases or fixes
of certain problems.

Program & source are released under the Apache license v2. If you make
an improved version of AardEd I would love to hear about it.


Wouter van Oortmerssen