alpha version

Welcome to the Ameba project. Port your MIDlets to others platforms (Nokia, Siemens, Motorola, Samsung etc.) fast and easily. Debug, build, deploy and backup with one command. Save your time!

TABLE OF CONTENTS
What is Ameba?
General overview
Quick tour: step by step example
Benefits
Installation
AmebaEngine
Ameba scripts environment
Glossary
Last words

What is Ameba?

Ameba was created to help port MIDlets from one platform to another. Because the differences between phones are getting bigger and bigger, I've ended up with many versions (18+) of the same MIDlet for various phones. The idea is to write the source code only once and change only the code that is specific to some phone. The easiest way was to add the #define statement, just like in C. In general AmebaEngine is simply preprocessor similar to the one from C/C++. However it has some more features and sometimes the syntax is shorter. In addition to AmebaEngine there is a complete script environment, that helps to manage the code, versions etc.

It's main purpose is to make developing, maintaining and debugging MIDlets faster, easier and as automatic as possible. The main feature is to have only one source code and have it compiled for many platforms (Nokia, Siemens, Samsung, Motorola etc.). Thanks to mechanism of including different files it is easy to have multi language MIDlets.

Ameba's key features:
- one source code: many platforms,
- internationalization,
- easier debug,
- smaller and faster code,
- complete environment for building, running and deploying midlets,
- project history,
- directory structure helps to keep the project clean,
- auto backup,
- integration with emulators,
- integration with IDE (gel),
- empty project templates,
- extendible - add your own features,
- fast,
- free!

General overview

Project management is done via Ameba scripts. First step is to create a new project. The developer works with only one source code (reference version). This source is not a valid Java code (it will not compile) and consists of code for all the platforms. This is achieved via special keywords like #define, #if, #include etc. Later to produce valid source code for a given platform appropriate script has to be invoked. All scripts (make, build, run, deploy, backup) to handle the project are in the "scripts" directory. They are all in perl, thus work on Win32 and Linux.

Quick Tour: step by step example

To show all the most important features and basic usage, we shall create new project using simple template, add new platform and compile it. For this example we will assume that Ameba is properly installed in C:\ameba. Suggested place for all the projects is in "/projects" directory in ameba's main directory.

1. Create a new project

c:\ameba\projects\ameba create project MyGame

This command will produce in the current directory a new directory called "MyGame". Inside there is a whole structure of subdirectories. Each has its purpose as listed below:

Directory structure inside a target's directory:

At this moment a whole set of directories, scripts and files is created. Below is the list of major files:

2. Create new targets

Default template which was used has 4 targets: nokia s40 en, nokia s40 pl, nokia s30 en, nokia s30 pl. Of cource that is not enough and we want another target: nokia s60 in english and polish. So we need to create 2 more targets.

c:\ameba\projects\MyGame\ameba create target nokia s60 en

c:\ameba\projects\MyGame\ameba create target nokia s60 pl

At this point 2 new directories appear: nokia_s60_en and nokia_s60_pl. Both have the same subdirectory structure as for other targets. At this point we can have a look at the source code.

3. The source code

File: config.jh 

//
// target platform configuration
// note: 
// #pragma xxx yyy 
// is needed for AmebaEngine and additionally works as
// #define __yyy___ 1
//
#pragma platform NOKIA
#pragma type S40
#pragma lang EN

// include correct language pack
#if defined(__EN__)
	#include "l_en.jh"
#elif defined(__PL__)
	#include "l_pl.jh"
#endif

When AmebaEngine starts transforming files it first reads the config.jh file to look for the 3 pragmas: "platform", "type" and "lang". Any extra defines are evaluated. Below the target pragmas there is conditional including of file "l_en.jh" or "l_pl.jh". These files contain text for MIDlet in english and polish. Because these 3 pragmas also add new defines they can be already used. As showed in the comment at the begining of the config.jh file, new defines have special format. __yyy__ where yyy is the value of pragma so here we can have __EN__ or __PL__ and this is used to include appropriate file. Below are those two files.

TIP: if you want your #define to be present in all your files put it in the config.jh file.

File: l_en.jh

//<
//< english language pack
//<
#define L_EXIT "Exit"
#define L_HELLO_WORLD "Hello World!"

File: l_pl.jh

//<
//< polish language pack
//<
#define L_EXIT "Wyjście"
#define L_HELLO_WORLD "Witaj świecie!"

File: MyGame.java

/*
 * Powered by AmebaEngine v __AMEBA_VERSION__
 * File processed on: __DATE__
 *
 * File created on: Wed Apr 28 08:40:16 2004
 * File: MyGame.java
 */
import javax.microedition.midlet.*;
import javax.microedtion.lcdui.*;

/**
 * @author (your name)
 * @date Wed Apr 28 08:40:16 2004
 */
public class MyGame extends MIDlet implements CommandListener {

	Command iCmdExit;
	TextBox iText;

	public MyGame() {
		iCmdExit = new Command(L_EXIT, Command.EXIT, 1);
		iText = new TextBox("MyGame", L_HELLO_WORLD, 20, TextField.ANY);
		iText.addCommand(iCmdExit);
		iText.setCommandListener(this);
	}


	protected void startApp() {
		Display.getDisplay(this).setCurrent(iText);
	}


	protected void pauseApp() {
		// empty
	}


	protected void destroyApp() {
		// empty
	}


	public void commandAction(Command aCmd, Displayable aDisp) {
		if (aCmd == iCmdExit) {
			destroyApp(false);
			notifyDestroyed();
		}
	}
}

These 4 files is the complete reference source code for the MyGame MIDlet. In the MyGame() constructor there are those defines from langugage files: L_EXIT and L_HELLO_WORLD. Now how to change the reference version into valid source code?

3. Make valid Java source code

The "scripts" directory in the project main directory contains several files used to make your source code.

As you can see all scripts are in perl so should work the same on win32 and linux platforms. Lets have a look at one of the scripts for example "makedef.pl".

File: makedef.pl

#!/usr/bin/perl
# 
# file     : makedef.pl
# gen date : Wed Apr 28 10:19:37 2004
# ameba    : 1.0.1-pre-alpha
# mod      : a_update module version: 1.0.4
# 
system("java -classpath G:/hmml/ameba/bin/AmebaEngine/classes AmebaEngine 
             -inputdir C:/ameba/projects/MyGame/ref 
             -config C:/ameba/projects/MyGame/ref/config.jh 
             -basedir C:/ameba/projects/MyGame 
             -input MyGame.java ");

system(" * ameba make def  >> C:/ameba/projects/MyGame/ameba.history");

Benefits

There are many benefits if Ameba is used. The most important is faster development, much easier debug. Read sections below to learn more about the major benefits.

Installation

Ameba needs Perl to work! For win32 platforms I suggest ActiveState ActivePerl http://www.activestate.com. I use version 5.8.
After putting Ameba in a destination directory (in this example we assume that ameba is in c:\ameba) two more steps have to be made:

1. Setting AMEBA_HOME environment variable.

set AMEBA_HOME=c:\ameba

2. Adding bin directory to PATH

set path=%path%;c:\ameba\bin

Later you can check if everything is OK by running check script.

ameba_install.pl

AmebaEngine

AmebaEngine is the core of Ameba. This is the program that transforms reference version of source code and produces valid java source code. AmebaEngine can be used as a stand alone program. However it is intended to be used with Ameba, which is generating scripts to run AmebaEngine (they can be quite complex).

Ameba scripts environment

Ameba *is* platform independant - Java + perl is a good solution. However to have everything working the way I want some scripts are platform dependant. These are in to versions: with extension (bat) for win32 platform and without for linux (ex. 'ameba.bat' for win32 and 'ameba' for linux).

Glossary

Reference version of source code - This is the source code the developer writes with all the AmebaEngine's directives like "#define" etc. and is used by AmebaEngine to produce valid Java source code.
AmebaEngine - the transforming engine, uses reference source code and produces valid Java source code
Ameba - Whole project including all scripts, AmebaEngine, documentation and additional tools

Last words

This project is under constant development. When ever I feel I need some feature and I have time I try to implement it. The most recent version is available in CVS, and from time to time whole package will be prepared.
very final words: portions of Ameba developed on P133!