Building Process

Introduction

GeoGebra is written in Java. Its primary developing editor tool is the Eclipse integrated development environment (IDE). Another option is to use command line tools, namely ant and some Unix specific utilities. In this article we deal with 3 options, but our final focus is on understanding the building process from the source files to deploying a release version of GeoGebra.

It is important, that we must make a difference between 'developer build', 'command line build' and 'official build'.

The first ('developer build') means that we want to add new features to GeoGebra or modify it, probably fix some bugs, then finally commit the changes to the developer repository. This requires the Eclipse IDE. The developer needs a modern workstation on his machine, with a modern operating system (usually Microsoft Windows, but others are also possible, e.g. Linux).

The second one ('command line build') means that we are just about to create GeoGebra for testing purposes, but without a modern IDE. We don't want to use Eclipse and we don't want to allocate a huge amount of resources. We just would like to run GeoGebra and test it, by using only the command line, not more. This is typical for Linux hackers who are primarily not Java developers, but maybe want to play with the software a bit. (However, it is also possible to edit the source code by an alternate editor, e.g. vim, this scenario is not for developing GeoGebra.)

The third one ('official build') means much more: we want to announce the whole program as an official version of GeoGebra. Of course, this scenario is primarily for packagers, and not for normal users.

For developer builds, the first subsections of the SetUp page is a good kickstart to set up Eclipse and start to work on GeoGebra quickly. Usually this means that ant or Unix tools are not required for most developers. For Linux hackers, to create a command line build, the SetUpCommandLine page is suggested to read. For both the Linux hackers and the packagers it is required to have ant installed on their system, and for automation, a Unix-like system is good to have.

Now we assume you already read both pages and know the usual way for compiling GeoGebra. From now on, we go into the details. Our purpose is to understand the building process for 'official build', which is based on the 'command line build', but it has some additional steps as well.

Configuration files used by Eclipse and ant

GeoGebra source comes with predefined Eclipse and ant configuration files. Eclipse will use the .classpath file. ant's main configuration file is build.xml. We use additional XML files for downloading 3rd party libraries (kickstart.xml), create various packages from the JAR files (pack.xml), or create the installers for Windows and Macintosh (installer.xml).

Compilation

Most parts of Java software are usually written in *.java files. At the time of this writing, GeoGebra has more than 3500 Java files. The first step for processing them is that a Java compiler creates *.class files from these *.java files.

Java software can usually use auxilary libraries. GeoGebra also uses such libraries, including the Java runtime library (from Sun Java, version 1.5 or above), and some external libraries as well (see SourcesForUsedLibraries for details). The set of *.class files are a mixture of binary code from GeoGebra itself, the runtime library and the external libraries.

A Java compiler tool is responsible for creating these *.class files. The resulted binary code may be different for various compilers. GeoGebra is known to compile against at least two open source Java compilers: the Eclipse Java compiler (ecj) and the Sun Java Compiler (javac).

On using Eclipse, by default it uses its built-in compiler to create *.class files. This is usually done in the background using low amount of resources, because ecj can work as an incremental compiler. However, it is also possible to use ecj outside of Eclipse, or even without installing Eclipse. For automated builds, we use the ecj JAR package (or the ecj Linux package), but it is also possible to use javac instead. However, the resulted *.class files might have problem later on signing the resulted JAR files in this case. Unfortunately, GeoGebra may have errors in its source code which prevents javac to compile the source code; however, ecj will do the compilation even if errors exist. As a consequence, latest versions of GeoGebra are compiled with ecj by default.

As a result, more than 5500 *.class files will be generated occupying more than 19 MB of disk space.

Eclipse can automatically run GeoGebra by using the *.class files. Selecting geogebra.GeoGebra.java or geogebra.GeoGebra3D.java and click on the "Run" toolbar icon, the application will start. Eclipse only uses the *.class files to start the application, not more.

Cleaning up

Sometimes it may be useful to delete the *.class files. You can initiate it in Eclipse by selecting the Project -> Clean... menu option. Make sure that Project -> Build Automatically is not checked. Another option is to use the ant target "delete-classes" from build.xml.

Automation

Eclipse will automatically recreate the *.class files. For command line builds we have to know how ecj works when it is called from Eclipse. We have to specify the bootclasspath option to inform gcj to use the Sun Java runtime library, and to set the classpath to have all *.jar files in the root directory of the GeoGebra source tree. In addition, jogl.jar and gluegen-rt.jar from the 3D/ directory are also required.

Autogenerating GeoGebra kernel

Some *.java files are missing from the GeoGebra source tree. The reason for that is we have to regenerate some files regularly when the parser for the GeoGebra kernel changes. The parser is written in a *.jj file, and to compile it to *.java we need the javacc application.

Eclipse can do this job by using the eclipse-javacc plugin, but for command line automation of this step, we need an ant target, namely "compile-grammar".

Summary

To create *.class files in Eclipse, we need the eclipse-javacc plugin to generate the missing *.java files for the geogebra/kernel/parser/ directory. Then the built-in Java compiler of Eclipse will do the compilation by using the GeoGebra source, the Sun Java runtime library and the external *.jar files. Now Eclipse can run the application.

To do the same from command line, we need to run the ant targets "delete-classes", "compile-grammar". Next, to use ecj for compilation, we need to use *.jar version of ecj (or a direct executable instead). However now we have all required *.class files, we need an extra step to create *.jar files to run the application.

Compatibility questions

• GeoGebra requires Sun Java runtime for compilation, version 1.5 or above. OpenJDK is incompatible: the xawt/libmawt library is missing.
• Because of many schools still use version 1.5 of Java, we cannot use any features from Sun Java 1.6 or above. The reason for this is that we don't want anyone committing Java 6 code by mistake.

Packaging

End users of GeoGebra can use the application by running it the following ways:

• Running it as a native Java application. From command line it is usually called "java -jar geogebra.jar". GeoGebra consists of a dozen *.jar files, including geogebra.jar as well. Of course, these files can be hidden from the end users (by creating a shortcut icon, for example), but the way of working is the same.
• Using WebStart. This is similar to the first way, but a JNLP file is downloaded first.
• "Applet start". The technology behind is similar, however here some features are not working (e.g. printing, see http://www.geogebra.org/en/wiki/index.php/Unsigned_GeoGebra_Applets for details).
• There are also planned ways to run GeoGebra in the future, e.g. using the GeoGebraMobile GUI (under development yet).

The first 3 ways are similar that all of them need *.jar files to run. These files are created by an ant target, "geogebra", from pack.xml. This is a quite complicated target with many subtargets. (If one wants to run its first step only, "ggb-jar-files", borrowed from build.xml, he or she will get only the ​vanilla version of the JARs. Typically, this step is the last one for the 'command line build' for Linux hackers, but not for the packagers.)

Different sets of *.jar files

Currently the ant machinery is designed to create 5 different sets of the *.jar files. The International GeoGebra Institute owns a private key which is for the official signing for 3 sets. (The other 2 sets are unsigned.)

All sets are copied into the build/ directory.

Set 1: debug/

If the packager has the signing key, this directory will contain a signed version of the 12 *.jar files. These files are mostly for debugging purposes. Their approx. size is 14.7 MB.

Without the signing key, the content of directory is still capable for running it by a Sun Java runtime environment (JRE), version 1.5 or above. (The more recent version you use for JRE, the better user experience you get.) Currently, the sum of sizes of the JAR files are approx. 13.6 MB. This way we can get the vanilla version. (However, a vanilla version can always be created independently by running the 'make-vanilla-jars' script. It (re)creates the parser, (re)creates the classes and creates the *.jar files.)

Set 2: unsigned/unpacked/

This directory will contain the applet version of GeoGebra. The *.jar files are optimized by using the proguard utility. Their approx. size is 8.2 MB.

Set 3: unsigned/packed/

This directory will contain the applet version of GeoGebra (as in Set 2), but zipped (by using the pack200 tool). Because of its size, this is the final version we use at www.geogebra.org for applets. To use it smoothly, some modifications are required in the web server application (Apache) as well. Approx. size is 4.6 MB.

Set 4: unpacked/

Having the signing key, this directory will contain the webstart version of GeoGebra. The vanilla version is optimized first by running proguard, then a repack-jarsigner pair of tools are used. (Note: here the pack.segment.limit=-1 setting must be used in the repack step to avoid SHA1 errors in the signed *.jar files.) Approx. size is 8.4 MB.

Set 5: packed/

Same as Set 4, but a final packaging is done for reducing download speed. (Note: here the pack.segment.limit=-1 setting must be used again.) This is the final version we use at www.geogebra.org for the JNLP files. Approx. size is 4.9 MB.

Summary

This summary shows how the vanilla version is modified to different sets. 's' is for signing, 'r' is for repacking, 'o' is for optimizing, 'p' is for packing, 'v' is for vanilla:

debug/

vs (or v, if no key is present)

unsigned/unpacked/

vo

unsigned/packed/

vop

unpacked/

vors

packed/

vorsp

For example, 'vop' means that the vanilla version is optimized first with proguard, then it is packed with pack200.

External tools and some tweaks

proguard

We use the build.pro file for fine tuning proguard. It is currently defined as a special ant task.

pack200

We use the tools_p200.config file for fine tuning pack200. It is currently defined as a special ant task.

Because of packing multiple files at the same time, instead of calling pack200 a difficult way, we prefer to use the p200ant tool. We modified it to prevent anyone using Java version 1.6 for the packaged JAR files (see ​http://bugs.sun.com/view_bug.do?bug_id=6712743 for details). However, with some tweaks on the GeoGebra source code (putting a dummy class in geogebra_properties.jar), Java 1.6 could still be used. (If someone tries to compile GeoGebra and do the packaging then, he must use the unmodified version of the original p200ant tool.)

jarsigner

It is currently defined as an ant signjar task.

Unfortunately (see ​http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6351684 and ​http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=5078608) this step requires ecj for compilation of the *.class files, because Sun javac creates a few such *.class files which cannot be verified properly. (Probably the inner classes have some problems. However, this problem may be not any longer present due to the pack.segment.limit=-1 setting.)

Ready, steady, go!

Now it's time to uncover how to run the building process on your own. These are steps:

In Eclipse

Building GeoGebra vanilla jar files (for testing)

• Make sure the JDK's bin folder is on the system path, e.g. C:\Program Files\Java\jdk1.6.0_17\bin (contains eg jar.exe, jarsigner.exe)
• Right click on build.xml -> Run As -> Ant Task...
  • targets -> ggb-jar-files or ggb-jar-files3D
• Apply, Run
• The jar files will take place in the build/ directory.

Building GeoGebra jar files for webstart or applet start

• Copy jre1.5.0_22/lib/rt.jar as workspace/geogebra/java150-rt.jar (not the desktop directory, but exactly outside it)
• (optional - to create signed JARs) Copy igi-keystore.p12 to workspace/geogebra/igi-keystore.p12
• Make sure the JDK's bin folder is on the system path eg C:\Program Files\Java\jdk1.6.0_17\bin (contains eg jar.exe, jarsigner.exe)
• Right click on pack.xml -> Run As -> Ant Task...
  • JRE -> Separate JRE -> jre1.5.0_22 (needed to avoid bug in Java 6 pack200)
  • JRE -> VM Arguments -> -Xmx512m (increases the memory allocation)
  • Targets -> geogebra or geogebra3D
• Apply, Run

Building GeoGebra installers (for Windows and Mac)

Creating an installer is not intended for public use, only for building official versions of GeoGebra by the release manager. To create an official build you may also have to install additional software like osslsigncode or a suitable version of NSIS. Currently you need to download all required 3rd party software by running the installer/build.xml file. You can read NSISonUnix for more details on the underlying subsystems. Finally, to build the installers, select "installer" as the target from the installer.xml file. Under Windows 7, you must run Eclipse as "Administrator".

From command line

To create the production JAR files (applet start, web start) and the installers as well, you need some preparations first. You have to download the 3rd party libraries and create a proper .classpath file. The following commands will do this for you:

cd desktop
# Download 3rd party libraries for packaging the JARs:
ant -f kickstart.xml geogebra5-packager-commandline
cd installer
# Download additional tools to create the installers:
ant
cd ..

Now go to desktop/scripts/autobuild, edit the autobuild.conf file and run the buildggb42 script.

To create the additional installers and deploy them please read more on the Deploy page.