Setting up the Eclipse IDE build environment:
=============================================

Prerequisites:
--------------

Install Java J2SE JDK >= 1.5.0
Install WTK 1         >= 1.04           (for MIDP1 version)
Install WTK 2         >= 2.2            (for MIDP2 version)
Install WTK Nokia Series 40             (for Nokia version)
Install Antenna       >= 0.9.14
Install Proguard      >= 3.6
Install Eclipse       >= 3.2.0

It might work with earlier versions than those listed, but at least
the listed versions worked for me. Eclipse MUST be version 3.2.0 or
higher. If you are not planning to compile all of the MIDP1, MIDP2 and
Nokia versions, the corresponding WTK can be omitted.

The JDK "bin" directory must be in the command path, specifically the
"jar" command.


Installing derived files:
-------------------------

Some files necessary for compiling this project can only be generated
from the "Makefile build environment" (described later in this document).
If you are unable to generate these files, there is a compressed tar
archive named "derived.tgz" containing the derived files. It is important
that this archive is extracted into the same directory as the archive
itself is located in, so that the extracted files end up in the correct
subdirectories. In Windows, this can be achieved by running an archiving
program such as WinZip. In Linux, you can use the following command:

  $ tar zxf derived.tgz


Starting Eclipse:
-----------------

Now, start Eclipse. The following descriptions refer to Eclipse menus
and dialogs. When referring to <this directory>, I mean the main
project directory, the one containing this file. An important point
(especially if you are installing in Windows) is that this directory
should not contain spaces, so it cannot be located in e.g. "Documents
and Settings".


Optionally create a new Eclipse workspace:
------------------------------------------

(Useful if you are working with other projects with Eclipse.)

File > Switch Workspace...
  Workspace: [<this directory>/.eclipse]                    (e.g.)
  click [OK]
  click [Workbench]


Settings path variables before importing the projects:
------------------------------------------------------

Window > Preferences...
  General > Workspace > Linked Resources
    click [New...]
      Name:     [MAIN               ]
      Location: [<this directory>   ]
      click [OK]
  Java > Build Path > Classpath Variables
    click [New...]
      Name:     [WTK_1              ]
      Path:     [<path to WTK 1>    ]
      click [OK]
    click [New...]
      Name:     [WTK_2              ]
      Path:     [<path to WTK 2>    ]
      click [OK]
    click [New...]
      Name:     [WTK_N              ]
      Path:     [<path to WTK Nokia>]
      click [OK]
  click [OK]

(The <path to WTK Nokia> is the directory in the Nokia WTK containing
the subdirectories "lib" and "bin". In my case this was a directory
named ".../Devices/Nokia_Series_40_MIDP_Concept_SDK_Beta_0_3")


Importing projects:
-------------------

(For some reason, it does not work for me to import the CalcApplet
project in the first import, so I have to import it separately, after
the others.)

File > Import...
  General > Existing Projects into Workspace
  click [Next]
  (*) Select root directory: [<this directory>]
  Projects:
    [x] Calc                            (the MIDP1 version)
    [ ] CalcApplet                      (the Applet demo application)
    [x] CalcMIDP2                       (the MIDP2 version)
    [x] CalcNokia                       (the Nokia version)
  click [Finish]
File > Import...
  General > Existing Projects into Workspace
  click [Next]
  (*) Select root directory: [<this directory>]
  Projects:
    [x] CalcApplet
  click [Finish]

All projects are using the same "main" source directory, so warnings
and errors will be listed four times each unless you set up a filter
(using the small, inconspicuous button with three arrows on it).

(Some times, you can get error messages (and a small red cross) on the
"main" source directory. In that case, simply delete the project,
check the MAIN path variable, and try to import the project again.)


Setting up and executing the Ant build tasks:
---------------------------------------------

Calc.jar:

Package Explorer > Calc > build.xml, right click, Run As > Ant Build...
  Classpath tab, select "User Entries", click [Add External JARs]
    find and add your Antenna jar, e.g. antenna-bin-0.9.14.jar
    find and add your Proguard jar, e.g. proguard-3.6.jar
  Properties tab
    uncheck "Use global properties as specified in the Ant runtime preferences"
    click [Add Property]
      Name:     [wtk.home           ]
      Value:    [<path to WTK 1>    ]
  click [Run]

After the Ant build tasks have been set up, you can run them directly
with Run As > Ant Build.


CalcMIDP2.jar:

Package Explorer > CalcMIDP2 > build.xml, right click, Run As > Ant Build...
  Classpath tab, select "User Entries", click [Add External JARs]
    find and add your Antenna jar, e.g. antenna-bin-0.9.14.jar
    find and add your Proguard jar, e.g. proguard-3.6.jar
  Properties tab
    uncheck "Use global properties as specified in the Ant runtime preferences"
    click [Add Property]
      Name:     [wtk.home           ]
      Value:    [<path to WTK 2>    ]
  click [Run]


CalcNokia.jar:

Package Explorer > CalcNokia > build.xml, right click, Run As > Ant Build...
  Classpath tab, select "User Entries", click [Add External JARs]
    find and add your Antenna jar, e.g. antenna-bin-0.9.14.jar
    find and add your Proguard jar, e.g. proguard-3.6.jar
  Properties tab
    uncheck "Use global properties as specified in the Ant runtime preferences"
    click [Add Property]
      Name:     [wtk.home           ]
      Value:    [<path to WTK Nokia>]
  click [Run]


CalcApplet.jar:

Package Explorer > CalcApplet > build.xml, right click, Run As > Ant Build
  (should work directly if there are no other errors)


CalcApplet.jar, running:

Package Explorer > CalcApplet > CalcApplet.html, right click, Run As > Run...
  Double-click "Java Applet"
  Classpath tab, select "User Entries", click [Add External JARs]
    find and add "<this directory>/applet/target/CalcApplet.jar"
    select the CalcApplet.jar and move it to the top of "User Entries"
  Applet: [midpcalc.CalcApplet]
  click [Run]



Setting up the Makefile build environment:
==========================================

Prerequisites:
--------------

Prerequisites for the Makefile build environment are more restrictive, if you
expect things to work "out of the box" without any need to modify the
Makefile, which contains many direct paths to where things are expected to be.
It will probably only work in Linux.

                                        Location:
GNU bash                                /bin/sh
GNU Make                                ${PATH}/make
GCC                                     ${PATH}/gcc, ${PATH}/cpp
Ant                                     ${PATH}/ant
Java J2SE JDK         >= 1.5.0          ${PATH}/javac
WTK 1                 == 1.04           ../../WTK104
WTK 2                 == 2.2            ../../WTK2.2
WTK Nokia Series 40   == 2.2            ../../WTK104/lib/classes.zip
Antenna               == 0.9.14         ../../WTK104/lib/antenna-bin-0.9.14.jar
Proguard              == 3.6            ../../WTK104/lib/proguard-3.6.jar
Real.java             >= 1.09           ../real-java/Real.jpp

It might work with earlier versions than those listed, but at least
the listed versions worked for me.

Locations where some of the specified software can be downloaded from:

Java J2SE JDK         http://java.sun.com        (Java Development Kit)
WTK 1                 http://java.sun.com        (J2ME Wireless Toolkit)
WTK 2                 http://java.sun.com        (J2ME Wireless Toolkit)
WTK Nokia             http://forum.nokia.com     (J2ME Wireless Toolkit)
Ant                   http://ant.apache.org      (Java build tool)
Proguard              http://proguard.sf.net     (Obfuscator)
Antenna               http://antenna.sf.net      (MIDP Ant tasks)
Real.java             http://real-java.sf.net    (Floatint point library)


Building:
---------

  $ cd <this directory>
  $ make


Development Guidelines
======================

If you want to contribute to the development, I want you to consider the
following guidelines first:

1) Make it compact: Many phones and also many WAP gateways have a limit of
   64kB for the jar file containing an application. (After version 3.00, 
   we don't care any more.)

2) Don't break compatibility: If you are making a fix to get the program
   running on a different hardware, make sure that the code still works on all
   the hardware that it is already working on, and not just the new hardware.

3) To avoid conflicts arising from concurrent modification by two independent
   developers, try to make the least impact on the code: Unless there is a
   very good reason for it, do not change or refactor large portions of the
   code simultaneously.  Exempt from this rule are large changes that actually
   decrease the size of the application, and code changes that do not change
   the compiled result, such as adding comments and renaming identifiers to
   increase clarity.

3b) Don't change indenting: The current code uses a BSD-like brace style with 4
   spaces of indentation for subblocks. Under no circumstances change the
   indentation or brace style of large portions of the code using your own
   prefferred indentation. Under no circumstances insert TAB characters in the
   code or replace all occurrances of X consecutive spaces with one TAB.

3c) Always do "cvs diff <file>" before committing. You need to see what you
   have done to be able to make a good commit comment. If you accidently
   changed indentation, inserted TAB's or switched CR/LF mode on the entire
   file it will show in the diff and you may be able to save face in time.
   The smaller the diff, the better.

4) LEARN CVS. CVS is a useful tool that enables several people to develop on
   the same project simultaneously. If you are a member of the delveoper team,
   your contribution will only be accepted in the form of CVS commits, so
   learn how to use it. The most important rule to avoid confusion: Only
   modify files in a CVS controlled directory, never take files out of the CVS
   directory to modify them.


Regards,
Roar Lauritzsen