Thank you for your interest in SuperWaba.
If you don't know where to start, here are some tips:

1. SuperWaba can run in two locations: in the device (currently in
Palm OS from 2.0 to up and some Windows CE/PocketPC models), using
a bytecode interpreter, and on the desktop, using the Sun JDK
or a Java-enabled browser for this.

2a. PALM OS: The VM part that needs to be installed in the Palm OS device
consists of three files:
    . SuperWaba.pdb: contains the classes available in superwaba/classes/*
    . SuperWaba.prc: contains the Java bytecode interpreter
    . SWNatives.prc: contains the implementation for the native methods
    (E.G.: Graphics.drawLine)
    Please make sure you have read the bin/palm/__installation_instructions.txt

2b. WINDOWS CE: The VM part that needs to be installed in the Windows CE/PocketPC is:
    . SuperWaba.pdb (same as above)
    . SuperWaba.exe: same of SuperWaba.prc plus SWNatives.prc.
    Please make sure you have read the bin/ce/__installation_instructions.txt

3. When running the software in the desktop, you'll need a JDK (1.2.x
recommended but also compatible with 1.1.x and 1.3.x).

4. There are some examples in the superwaba/examples directories.
Please take a look at them. In each of those directories, there are also two
files: make.bat and rundemo.bat. The make.bat searches for a installed JDK
and compiles the example. The rundemo.bat runs the example in the desktop as
a Java application. You can easily customize them by changing the name of
the variable "appname" to match the name of your application. Note that those
bat files may not run correctly on Windows < NT. To make them run ok, search for
all that use errorlevel and change: "%errorlevel%"=="0" to "%errorlevel%"==""
(http://support.microsoft.com/default.aspx?scid=KB;en-us;137857&)

5. A User Interface tutorial, a Library (JNI) and an Input/Output
tutorial are available for sale at  www.superwaba.org.
Everybody says that they are well worth the price. Buying it helps this open-source
project survive.

6. Daniel Tauschke has created a free IDE for SuperWaba: MobileCreator. It
simplifies a lot of the creation and building of SuperWaba programs. You can get
it at http://www.tauschke.com/

6a. There is also a great tool that lets you create user interfaces. You
can even use it in your Palm. See /superwaba/examples/apps/GuiBuilder.

7. When you create a SuperWaba application (i.e. HelloPalm.java), you
must create two files: HelloPalm.pdb and HelloPalm.prc/exe. The pdb will contain
the  HelloPalm.class file, among with any bitmap or class that HelloPalm
uses. The prc/exe will contain the application version and icon, among other
things. To create the pdb, use the utility superwaba/bin/Warp. To create the prc/exe,
use superwaba/bin/ExeGen. In the bin directory
there's an Instructions.txt file with all command line options. Once again, the
make.bat file simplifies the process by compiling your program
and executing both utilities.

8. If you have questions, point your newsgroup reader to
news://news.falch.net/pilot.programmer.waba and ask questions there. But, PLEASE,
download all messages first and do a search on them. Your question may have
already been answered, and you'll save your time and the time of people at
the newsgroup. (Make sure you have downloaded all messages: there are more
than 15000). Also, be sure to read the faq at the SuperWaba site.

9. When running your application on POSE, don't forget to turn off some settings
in "Settings/Debugging":  >>
  . Hardware Register Access
  . Proscribed Function Call
  . Screen Access

10. DON'T use the Jikes compiler with SuperWaba.

11. Install SuperWaba at its default location: <root>/superwaba. This way,
all bat files will work correctly. After you became a master in SW, then you
may change the location.

12. Remember: your device only has 16Mhz. It will never be equal to your
    1000Mhz desktop computer. Code optimization is always welcome. Take
    a look at this also: http://patrick.net/jpt/. And buy the optimization
    tricks tutorial

Below you see some ways of how to set up some famous IDEs to run and debug
SuperWaba programs as applets or applications in the desktop. After you
debug it, you can generate the necessary files with Warp/Exegen and deploy
it to the device.

----------------------------------------------------------------------
NetBeans or Forte - Thanks to Jean Rissoto, Ed. J Szalajeski and Vince Nguyen

In NetBeans (or Forte)
    . Click the Tools menu, select Options and go to the Debugging and Execution
      folder:

    . Expand the folder

    . Select the "Execution Types" icon  (looks like 2 arrows) and expand the tree.

    . Right Click your mouse on the root of the Execution Types, and select New..
      External Execution Name the Type ExteralSuperWaba

    . Right Click the ExteralSuperWaba Item  just created, from the
      context menu select Properties, and change the External Process to
      -cp {filesystems} waba.applet.Applet /datapath . /x 10 /y 10 /scale 2 /bpp 8 {classname}

Select the Debugger Types,tree.
    . Expand the tree

    . Right Click your mouse and select new Default Debugger
      Name it DefaultSuperWaba

    . Right Click the DefaultSuperWaba just created, from the context menu
      select Properties

    . Change the External Process Argument to
       {classic}{debuggerOptions} -Djava.compiler=NONE {q}{bootclasspathSwitch}{bootclasspath}{q}
       -classpath {q}{filesystems}{q} waba.applet.Applet /datapath . /x 10 /y 10 /scale 2 /bpp 8 {main}

      (please note: you are only adding waba.applet.Applet to the default)

    . Close the options menu,

In the filesystem Explorer
    . unmount all jar file netbeans add by default

    . mount Sun's source jar file for the rt.jar  (src.jar) otherwise you will not be able to debug

    . mount the directory where SuperWaba classes are:  This allows stepping through the SW source code
       . X:\superwaba\classes

    . An alternative is to mount only the SuperWaba.jar file (superwaba.jar), and not directly step
      into the SW libraries.

    . mount your own jar files or java files

Project settings:
    . Select your project's mount directory in the filesystem explorer,
     (the directory with your source files)

    . Right Click your main class file, select properties from the context menu

    . Select the Execution Tab,

    . Change the Compiler to Internal Compilation

    . Change the Debugger to DefaultSuperWaba
      (your item created above should be in the drop down combo box)

    . Change the executor to ExternalSuperWaba

    . The arguments can be adjusted from this property page too.

    (Recommended, arguments)

    -Arguments: /dataPath j:\\apps\\my\\donnees /x 10 /y 160 /bpp 8
    /scale 2
     j:\apps\my .... is the path to the datas of my app...
    /x 10 /y 160 /bpp 8 /scale see explanations below at end of text.
-----------------------------------------------------------------------
Tested for JBuilder 6 Personal and Pro only

1) Create a new project
    1.a) Select the menu "File"->"New Project"
    1.b) Set the Name of the project: for this example, "SWTest"
            will be the name of the project:

2) Create/Add a "Lib":
    2.a) Right click on SWTest.jpx
    2.b) Select Paths
    2.c) Select Required Libraries
    2.d) Select Add -> New (1st time only)
    2.e) Set Name to SWLib (for instance), then Select Add
    2.f) Select superwaba.jar (...superwaba\bin\xplat\superwaba.jar)
    2.g) Select your new Lib (SWLib) and select OK
    2.h) you're back to the "Path" tab of the project properties window.

3) Select your Lib again and click on Edit. You will get the Configure Lib
    window.
4) Select Source -> Add and select your ... \superwaba\classes
    folder
5) You can also set the "documentation" path.
6) Select OK to close the Configure Lib window and the project properties
    window

Now, you need to modify the following only for SuperWaba and restore
it after for a regular project.

7) Select, from the menu bar, Tools->Configure JDKs
8) Add and move to the top the following paths (in this order, from the top
    to the "bottom"):
    8.a) ... \superwaba\classes
    8.b) ...\superwaba\bin\xplat\superwaba.jar
    8.c) ... \
9) You can add the last 2 paths to the source and doc paths too by
    selecting the available tabs

10) Select OK to close this Configure JDKs window.

You're done and ready to do everything you need now. The trick is that you
have to execute/debug the waba.applet.Applet class with the Name of your
main window  subclass as the application parameters. Be sure to run/debug
waba.applet.Applet as an application and not as an applet:

Put a breakpoint on the first line of your onStart method and launch Debug.
It will stop where you did set your breakpoint. If you don't do that, you will
debug waba.applet.Applet, which is probably not what you want to do.
-----------------------------------------------------------------------
Visual Cafe (3.1)

1. menu File/New project. Choose "empty project".
2. menu Project/Options.
   Project tab:
   . Release type: "debug".
   . Project type: "Application"
   . Main class: "waba.applet.Applet
   . program arguments: <your_app_name>
   Directories Tab:
   . add in this order
     . <visualCafe_directory>\java\Lib\classes.zip
     . /superwaba/classes
     . <your_project_directory>
   . uncheck "Append classpath"
   . uncheck "Auto-generate classpath"
3. press ok.
4. drag your .java project files to the project pane.
5. menu Project/Build Application
6. set your breakpoints
7. menu Project/Run in Debugger

   Note: when you change the Project release type for "final", you must set
again the paths.
-----------------------------------------------------------------------
Linux - Thanks to Christopher C. Stump

Establishing a SuperWaba development environment under Linux is a rather easy task. All the tools necessary for SuperWaba development are available in the SuperWaba SDK which can be downloaded from www.superwaba.org. Once the package is obtained, it needs to be unzipped.

#Unzip the package
[command prompt]$ unzip superWabaSDK.zip

Once the SDK is extracted, it needs to be placed in a useful location .  We will assume the environment is being established for a single user, in which case anywhere in the user's home directory is acceptable.

#Move SDK to home locale
[command prompt]$ mv superWabaSDK ~/any location

Once the SDK is in its desired location one must set the Java classpath environment variable to include the new library. In a single user environment, a personal start-up script can be used for this purpose, such as ~/.bash_profile which is provided by any Linux system that gives its users a Bash shell by default. You can temporarily define the classpath variable in a shell, but it is much more useful to define it permanently in the above file. In any case, the following must be defined somewhere on the system:

CLASSPATH="{full path to the SDK}/superwaba/classes:{full path to SDK}/superwaba/bin:."

The classes directory holds the SuperWaba class files. The bin directory holds tools that will be used during compilation. If a classpath variable is already defined on the system, then the above path can be appended to the variable with the same syntax. Also, note the last ':.', this is necessary to include the current working directory in the classpath. Without this addition, compilation will fail. In order for the new classpath variable to take effect, the shell or X window environment being worked in must be exited and the system logged back into.

With the SuperWaba SDK in place and the classpath properly defined, one can begin developing SuperWaba applications. We will assume the reader has already written a SuperWaba program called MySuperWabaApp.java .  In order to test/run this program either on a Palm OS device or POSE, we must transform the .java source code into a Palm OS executable .prc file. This can be accomplished in a few easy steps:

#Change to the directory with the SuperWaba source
[command prompt]$ cd {path to SuperWaba source}

#Compile source
[command prompt]$ javac MySuperWabaApp.java

#Run Warp on the newly created .class files
[command prompt]$ java Warp c MySuperWabaApp MySuperWabaApp.class

#Run Exegen on the .class files
[command prompt]$ java Exegen MySuperWabaApp MySuperWabaApp MySuperWabaApp

Warp is a java program found in {full path to SDK}/superwaba/bin. Warp's purpose is to create the .pdb files used by Palm OS applications and the .wrp files used by Windows CE devices. We are only concerned with the .pdb file. The first argument to Warp, c, tells the program to create a .pdb file. The second argument is the name of the to-be-created .pdb file, and the third argument is all of the .class program files.

Exegen is a java program that can also be found in same directory as Warp. Exegen's purpose is to create the .prc file, which is the SuperWaba program in Palm OS executable form. The first argument to Exegen is the name of the to-be-created .prc file. The second argument is the name of the main source code file. The third argument is the name of the .wrp file.

If the above steps were successful, then a ready-to-use/test Palm OS application should be in the current directory. There should be files called MySuperWabaApp.prc and MySuperWabaApp.pdb . Both of these files, along with the SuperWaba virtual machine files, must be installed on a Palm unit or POSE in order to run the application. The SuperWaba virtual machine files can be found in {full path to the SDK}/superwaba/ .  Of course, the above command line arguments can be tedious to type over and over again while developing. Therefore, it is much nicer to place all of the commands in a simple shell script, like this Bash script, so everything can be easily run in sequence with a single command:

#Invoke shell script to handle SuperWaba app creation
[command prompt]$ ./superwaba_maker.sh
-----------------------------------------------------------------------
Eclipse 2.1 - created by Guilherme Campos Hazan and Deluan

To create the SuperWaba base project:

1. Open menu File/New/Project/Java/Java Project. Click next.
2. Project name: SuperWaba. Uncheck "use default" and select <sw_root>/superwaba/classes
3. Click next. Press yes when asking to create project now.
4. The "java settings" panel will appear. In the "source" tab, click in the + to open the "source folders" tree
5. Double-click on "Exclusion filter". Add "java/lang". This will avoid potential conflicts.
6. Click finish. Ignore the problems found.
7. In the package explorer, right click the "SuperWaba" project and select properties.
8. On "java compiler", select "use project settings" and change the "static members accessed through non-static reference" to "ignore".
9. Click "javadoc location". Click "browse" and select the superwaba/doc directory.
10. click 10 to build the project again. That's it! This will be the base project of all your SuperWaba projects.

To create your own project

1. Open menu File/New/Project/Java/Java Project. Click next.
2. Choose a name and select its default location.
3. Click next. Press yes when asking to create project now.
4. The "java settings" panel will appear. Click "Projects". Select the "SuperWaba" project as the "required project"
5. Click finish.
6. Click menu Run/Run...
7. double click "Java Application". Change the name to whatever you want.
8. In the "Main" tab:
   . Project: click browse and select your project name
   . Main class: type "waba.applet.Applet"
9. In the "Arguments" tab:
   . program arguments: type your app name (E.g.: "MyMainWin")
10. Be sure that the tab "Classpath" has your project name + SuperWaba
11. Click "Run".

Thats it! You're now able to debug your projects in Eclipse!

-----------------------------------------------------------------------
Microsoft Visual J++
1. Put SW classes in the first position in the classpath. E.g. if your classpath is <code>SET CLASSPATH = C:\jdk1.2.2</code> now becomes <code>SET CLASSPATH=C:\SuperWaba\classes;C:\jdk1.2.2</code>
2. Open in Visual J++: File &gt; New Project &gt; Console Aplication
3. OK now you can start to write code.
4. To run, test and debug, go to Project &gt; &quot;app&quot; Properties... Launch TAB, check Radio Button &quot;Custom&quot;
5. Set program: JVIEW.EXE and arguments: waba.applet.Applet &quot;ARGS&quot; &quot;yourclass&quot; (where ARGS are the arguments to pass to SuperWaba Applet and &quot;yourclass&quot; is the name of you main class. E.g.: waba.applet.Applet /scale 1 firstScreen)
6. Now Tab Output Format: uncheck Enable Packaging

PS (added by Fredie Oliveira): CLASSPATH environment variable is lost when J++ IDE  calls JView. This problem is reported by Microsoft in article "PRB: Environment Variables Are Lost When Running from VJ6 IDE" (Q215413).
To solve the problem, follow all steps in SW faq and add the CLASSPATH env variable contents in registry key: HKLM\SOFTWARE\Microsoft\Java VM\Classpath. Eg.: HKLM\SOFTWARE\Microsoft\Java VM\Classpath = %systemroot%\java\classes;.;c:\superwaba\classes;c:\j2sdk1.4.1_01\lib\tools.jar.

-----------------------------------------------------------------------
GENERAL SETTINGS

To be able to do the setup in any IDE, you must do as described:
1. Add to the classpath your project directory
2. Add to the classpath "superwaba/classes" path or
"superwaba/bin/xplat/superwaba.jar" file. Maybe you'll need to recompile
the classes or remake the jar file if you're not using JDK 1.2.2, that is
the jdk used to deploy SuperWaba.
3. set the main class as "waba.applet.Applet"
4. set the program arguments to your class name with full package
specification. For example, to run the Welcome application as an applet, set
the command line to "waba.ui.Welcome"
-----------------------------------------------------------------------
Optional arguments to waba.applet.Applet (when running it as application),
in any order and case insensitive:
. /x <x>
. /y <y>
. /w <width>
. /h <height>
. /uiStyle <WinCE_or_PalmOS>
. /bpp <bitsPerPixel_2_4_or_8>
. /scale <scale_1_to_4>
. /dataPath <path>
. /useSonyFonts
. /t title of the application window
. /cmdLine <the rest of arguments are passed to the app as the commandline>
. class name must always be the last argument
Note: The dataPath is used to set where the catalog and images are stored
Note2: In version 2.0beta4, appPath was changed to dataPath to make more
sense, but appPath is still used for backwards compatibility

Important note: if you want to emulate a Sony 320x320 device, use the following parameters:
  rundemo /w 320 /h 320 /scale 1 /useSonyFonts /bpp 8

To emulate a Windows CE or Pocket PC device with 240, 480 or 640 horizontal resolution, use:
  rundemo /w 240_or_480_or_640 /h 320_or_anything /scale 1 /bpp 8