This document describes information you will need in order to contibute to the development of Aegis VM, Prelude, or libjpr. This file is best viewed in emacs outline mode. The latest version of this document can be found at the URL below: http://aegisvm.sourceforge.net/HACKING Please also consult the TODO file for a list of tasks open for contribution. * Build Environment Besides the usual tools like gcc/make/etc, you may need some of the following depending on what you want to do. You probably don't need all of them. Just install what you need. Detail instruction on how to install them on Mandrake 9.2 is also given at the end of this section. ** Autoconf 2.52, automake 1.6.2 and libtool 1.4.2 You need them if you plan to modify Makefile.am or configure.ac, or if you work with a CVS checkout. Automake 1.6.2 or later is preferred over earlier versions, which contains a bug that requires a nasty hack in the bootstrap script. The three tools can be obtained from the following: http://www.gnu.org/software/autoconf/ http://www.gnu.org/software/automake/ http://www.gnu.org/software/libtool/ After you modify Makefile.am and/or configure.ac, you can just run the bootstrap script to regenerate Makefile.in and the configure script. ** GNU gengetopt (for aegisvm only) You need it to regenerate aegisvm_cmdline.h and aegisvm_cmdline.c from aegisvm.ggo when the latter is modified. I am using version 2.11, but any recent version should work. The gengetopt package can be obtained from the following: http://www.gnu.org/software/gengetopt/ ** Sun Java 2 SDK (for aegisvm only) You need it to rebuild the built-in classes and the test scripts for Aegis VM in case you have modified their Java source files. I am using version 1.3.1, but anything newer than 1.3 should work. Download the SDK from the following: http://java.sun.com/j2se/ ** cvs2cl.pl You need this Perl script to regenerate ChangeLog if you plan to do a "make dist" or "make distcheck". In such case, you need to be in a CVS working directory. I am using version 2.47, but I think most recent versions should work. The Perl script can be obtained from the following: http://www.red-bean.com/cvs2cl/ ** doxygen You need this tool if you plan to generate hypertext documentation for the code by doing a "make dox". I am using version 1.3.3, but I think most recent versions should work. The tool can be obtained from the following address: http://www.doxygen.org/ You will need flex/bison to build doxygen from source. ** Notes for Mandrake Linux 9.2 Users If you are using a major brand Linux distribution (e.g. Redhat, Mandrake, SuSE), some of the above tools are already included in the distribution CDs. To avoid headache, You should try to install such tools using the native software or package manager rather than building them from source. Here, I include instructions on how this can be done with Mandrake 9.2. Mandrake offers both autoconf 2.13 and 2.5x (autoconf 2.57 for 9.2). The 2.13 release is the standard "autoconf" package, and the 2.5x release is called "autoconf2.5". You may install both versions of autoconf. Mandrake has wrapper scripts that will detect from your configure.in/ac file which release of autoconf should be invoked. To install autoconf2.5, become root, and type the following: urpmi autoconf2.5 Mandrake offers two versions of automake. The 1.4 release is the standard "automake" package. Mandrake 9.2 supplies automake 1.7.6 as "automake1.7". The two package can be exist parallel to each other. For the purpose of building Aegis VM. You can install automake1.7 as a superuser using the following command: urpmi automake1.7 Libtool 1.4.3 is the standard "libtool" package in the Mandrake 9.2 distribution: urpmi libtool Cvs2cl.pl is offered as a contrib package "cvs2cl" in Mandrake 9.2. You need to set up your contrib media using urpmi.addmedia before you can install the package. For example, to install cvs2cl from the Mandrake 9.2 contrib repository at Wisconsin, do the following as root: urpmi.addmedia contrib ftp://mirror.cs.wisc.edu/pub/mirrors/linux/Mandrakelinux/official/9.2/contrib/i586/ with hdlist.cz urpmi cvs2cl The "cvs2cl.pl" script is renamed as "cvs2cl" in Mandrake 9.2. Our configure scripts will detect if you have cvs2cl.pl or cvs2cl, and use the right one accordingly. The standard "doxygen" package in Mandrake 9.2 corresponds to Doxygen 1.3.3. urpmi doxygen Gengetopt is offered as a contrib package in Mandrake 9.2. With the contrib media properly set up, you can install gengetopt 2.11 with the following: urpmi gengetopt Many of the prerequisites of libjpr and GNU Classpath can also be found in the Mandrake offering. Check their existence with the following: urpmf --name package-name For example, libffi can be installed as follows: urpmi libffi2 Please note that the above instruction does not exhaust all the tools in the build environment. For example, the J2SDK is not described in this section. We are in the process of making it possible to use the IBM Jikes compiler to do all the building. The nice thing about this compiler is that it is now bundled with Mandrake Linux, so Mandrake users do not need to download the bloated J2SDK. * Accessing the CVS Repository If you are working on some small patches, then the tarball distribution of the package you are interested in should contain everything you need. Consult the README file of each package for instructions on how to build that package. If you are working on a bigger project, or you want to catch up with the most up-to-date snapshot of the code base, then you might want to check out the relevant modules from the project CVS repository at SourceForge. The module names for Aegis VM, libjpr and libprelude are AegisVM, JPR, and Prelude respectively. There are two types of CVS access. First, there is anonymous access. You can check out working copies of the repository, but you cannot commit changes. Then there is developer access, with which you are allowed to commit changes. If you think you need developer access, talk to the maintainer of the project about this, and consult the following SourceForge documentation page for usage instructions: http://sourceforge.net/docman/display_doc.php?docid=768&group_id=1 As for anonymous access, use the following to check out the latest snapshot of the AegisVM module: cvs -d:pserver:anonymous@cvs.aegisvm.sourceforge.net:/cvsroot/aegisvm checkout AegisVM If you would like to check out a tagged version of a module, say release-aegisvm-0_1_0b, do the following: cvs -d:pserver:anonymous@cvs.aegisvm.sourceforge.net:/cvsroot/aegisvm checkout -rrelease-aegisvm-0_1_0b AegisVM The first thing you should do after checking out a working copy is to execute the bootstrap script to regenerate Makefile.in and the configure script. The rest is just the same as building from the distribution tarball. Consult the README files in the repository for more details. I usually tag a snapshot of every package release. The general form of the tag name is "release-PACKAGE-RELEASE", where PACKAGE is the name of the package, and RELEASE is the version number with all dots replaced by underscores. For example, release 0.1.0 of libjpr has a cvs tag of "release-libjpr-0_1_0". I also create tags between releases. They usually represent stable snapshots containing major architectural restructuring or significant new features. If I feel the need, I'll announce the creation of such tags on the developer list, which means that anyone who have cvs checkouts should try to synchronize with the announced tags ASAP. The between-release tags are usually release tags with an extra letter behind the version number. For example, "release-aegisvm-0_1_0a" and "release-aegisvm-0_1_0b" are two snapshots between the release of aegisvm 0.1.0 and 0.1.1. The release tags will stay in the cvs repository forever, but the between-release tags will be deleted after the new release is out for some time. * Make Targets As the Makefiles are generated by autoconf/automake, they provides the standard targets specified in the GNU Coding Standard (http://www.gnu.org/prep/standards_toc.html). We describe some of the more useful ones here. ** all A "make all" builds the binary. ** clean A "make clean" will remove all files generated by "make all". Do this when you need a clean build. ** distclean A "distclean" will remove all files generated by "./configure", "make all", "make dox" and "make TAGS". You will need to regenerate the Makefiles by running "./configure" again. ** maintainer-clean A "make maintainer-clean" will remove all generated files, including those that comes with the distribution (e.g. Makefiles, configure, aegisvm.ggo, classfiles, etc). Normally you do not need to do a maintainer-clean. Do a maintainer-clean only if you are making changes to configure.ac and/or Makefile.am, and have access to autoconf, automake, libtool and gengetopt. After a maintainer-clean, you should regenerate "Makefile.in" and "configure" by running "./bootstrap", and then regenerate "Makefile" by running "./configure". ** check A "make check" will run all the regression test scripts. Do this after making changes to assure you haven't broken anything. ** install A "make install" will install the compiled binary into the location specified during configuration. ** uninstall A "make uninstall" will uninstall the installed binary from the location specified during configuration. ** dist A "make dist" will create a tarball of the distribution. The ChangeLog file is generated by cvs2cl.pl from a working CVS directory. Therefore, if you plan to modify or remove the ChangeLog file that comes with the tarball distribution (e.g. by a "make maintainer-clean"), you will need to install the Perl script and work from a CVS checkout. ** distcheck A "make distcheck" will create a tarball of the distribution, test if installation and uninstallation is okay, and run the test scripts. Since make dist is invoked, you need cvs2cl.pl if you have changed the ChangeLog file that comes with the tarball distribution, or if you are working from a fresh CVS checkout. ** tags or TAGS A "make tags" or "make TAGS" will run GNU etag to generate TAGS files (i.e. cross-reference databases) for all subdirectories. You can then use the GNU emacs editor to navigate the code base. Etags is part of the emacs distribution. ** dox A "make dox" will invoke doxygen to generate html cross reference documentations in the docs/ subdirectory. Of course, you will need doxygen installed in order to use this feature. * Understanding the Code Base Doxygen documentation is generated by "make dox". The front page of the documentation can be found in some subdirectory of the docs/ directory. Now that the doxygen documentation pages are reasonably populated, they are the preferred form of documentation. Thanks Chris for talking me into doing serious documentation. Use the tags table generated by "make tags" to navigate the code base in emacs. * Debugging The configure script has a number of debugging flags, when enabled, will turn on various logging facilities. Consult the output of "./configure --help" for details. * Background Documentations ** Java Virtual Machine Specification Familiarity of this spec is a preliminary to any work related to JVM. Online version can be accessed at: http://java.sun.com/docs/books/vmspec/2nd-edition/html/VMSpecTOC.doc.html ** Java Native Interface Specification If you need to work on the interface between a C application and the Aegis VM (i.e. jni.h/c), understanding of this spec is a definite prerequisite. Unfortunately, the published book form of the spec, which covers JNI up to J2SE 1.2, is not available online. The online spec of JNI 1.1, JNI enhancements introduced in v 1.2 and 1.4, and tutorial materials can be found at the following link: http://java.sun.com/j2se/1.4/docs/guide/jni/index.html ** Platform API Specification Our goal is for the Aegis VM to have J2ME CDC compiance. Consequently, we do not need to implement all classes in J2SE. J2ME Foundation Profile Specification 1.0 Final Release http://jcp.org/aboutJava/communityprocess/final/jsr046/index.html J2SE 1.3 API Specification http://java.sun.com/j2se/1.3/docs/api/index.html ** Java Programming Language Specification Certain language rules (e.g. method overriding) are missing from the JVM spec. In those cases, you need to consult the Java language spec instead: http://java.sun.com/docs/books/jls/second_edition/html/ In case you are developing class libraries or test scripts, and you need quick refresher of Java syntax, consult the definitive "The Java Programming Language (3rd Ed)" by Arnold at el. The book should be available from most university/college/public libraries. * Contribution Policy You are welcome to contribute code to the project. To make things simple, the project maintainer, Philip Fong, will remain the sole copyright holder of all the code in the code base. Your contribution will be acknowledged in the AUTHORS/THANKS files. Consult the Software Release Practice HOWTO for the rationale of this arrangement (http://www.tldp.org/HOWTO/Software-Release-Practice-HOWTO). Please submit your patch to the mailing list aegisvm-devel@lists.sourceforge.net. In case this is the first time you contribute to an open source project, I would recommend you to glance through the following section of the "Software Release Practice HOWTO": http://linuxdoc.org/HOWTO/Software-Release-Practice-HOWTO/patching.html This offers some guidelines of how to submit patches. If you are submitting bug fixing patches, it would save me a lot of work if your patch includes testscripts that reproduce the bug, which could be used to demonstrate that the fix really works. These testscripts should be integrated into the existing "make check" framework. Of course, patches that do not come with such testscripts are still welcome. :-) * Communication The maintainer, Philip Fong, can be reached at the following address: pwlfong@users.sourceforge.net Drop him a note if you want to help, or if you have ideas you want to suggest. You are also invited to subscribe to the developer mailing list: aegisvm-devel@lists.sourceforge.net Subscription form and archive of the list can be found at the following location: http://lists.sourceforge.net/lists/listinfo/aegisvm-devel