diff options
Diffstat (limited to 'libjava/HACKING')
| -rw-r--r-- | libjava/HACKING | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/libjava/HACKING b/libjava/HACKING new file mode 100644 index 000000000..3e99bed0e --- /dev/null +++ b/libjava/HACKING @@ -0,0 +1,190 @@ +Things libgcj hackers should know +--------------------------------- + +If you want to hack on the libgcj files you need to be aware of the +following things. There are probably lots of other things that should be +explained in this HACKING file. Please add them if you discover them :) + +-- + +If you plan to modify a .java file, you will need to configure with +--enable-java-maintainer-mode. In order to make this work properly, +you will need to have 'ecj1' and 'gjavah' executables in your PATH at +build time. + +One way to do this is to download ecj.jar (see contrib/download_ecj) +and write a simple wrapper script like: + + #! /bin/sh + gij -cp /home/tromey/gnu/Generics/trunk/ecj.jar \ + org.eclipse.jdt.internal.compiler.batch.GCCMain \ + ${1+"$@"} + +For gjavah, you can make a tools.zip from the classes in +classpath/lib/tools/ and write a gjavah script like: + + #! /bin/sh + dir=/home/tromey/gnu/Generics/Gcjh + gij -cp $dir/tools.zip \ + gnu.classpath.tools.javah.Main \ + ${1+"$@"} + +Another way to get a version of gjavah is to first do a +non-maintainer-mode build and use the newly installed gjavah. + +-- + +To regenerate libjava/configure, first run aclocal passing the flags +found near the top of Makefile.am, then autoconf. H. J. Lu writes that +this can be done using these commands: + + cd libjava && + rm -f aclocal.m4 && + ACFLAGS=$(grep "^ACLOCAL_AMFLAGS" Makefile.in | sed -e "s/ACLOCAL_AMFLAGS[ \t ]*=//") && + aclocal-1.11 $ACFLAGS && + rm -f configure && + autoconf-2.64 && + rm -fr autom4te.cache + +See the GCC documentation which auto* versions to use. + +-- + +libgcj uses GNU Classpath as an upstream provider. Snapshots of +Classpath are imported into the libgcj source tree. Some classes are +overridden by local versions; these files still appear in the libgcj +tree. + +To import a new release: + +- Check out a classpath snapshot or take a release tar.gz file. + I use 'cvs export' for this. Make a tag to ensure future hackers + know exactly what revision was checked out; tags are of the form + 'libgcj-import-DATE' (when using a tagged checkout do: + - ./autogen.sh && ./configure && make dist + to get a proper .tar.gz for importing below). +- Get a svn checkout of + svn+ssh://gcc.gnu.org/svn/gcc/branches/CLASSPATH/libjava/classpath + this contains "pure" GNU Classpath inside the GCC tree. +- Clean it up and get the files from a new version: + - find classpath -type f | grep -v '/\.svn' | grep -v '/\.cvs' | xargs rm + - tar zxf classpath-x.tar.gz + - cp -r classpath-x/* classpath +- Add/Remove files: + - svn status classpath | grep ^\! | cut -c8- | xargs svn remove + - svn status classpath | grep ^\? | cut -c8- | xargs svn add +- If there are any empty directories now they can be removed. You can find + candidates (dirs with files removed) with: + - for i in `svn status classpath | grep ^D | cut -c8-`; \ + do ls -d `dirname $i`; done | uniq +- Update vendor branch + - svn commit classpath +- Note the new revision number (Xrev) +- Get a fresh svn trunk checkout and cd gcc/libjava +- Merge the changes between classpath versions into the trunk. + svn merge -rXrev-1:Xrev \ + svn+ssh://gcc.gnu.org/svn/gcc/branches/CLASSPATH/libjava/classpath \ + classpath +- Resolve any conflicts pointed out by svn status classpath | grep ^C + - Makefile.in files will be regenerated in the next step. + - Other files should have a "GCJ LOCAL" comment, and/or are mentioned + in the classpath/ChangeLog.gcj file. + (Don't forget to svn resolved files.) +- Use auto* to create configure, Makefile.in, etc + Make sure you have Automake 1.11.1 installed. Exactly that version! + You have to make sure to use the gcc libtool.m4 and gcc lt* scripts + cd .../classpath + cp ../../lt* . + cp ../../config.sub ../../config.guess . + aclocal -I m4 -I ../.. -I ../../config + autoconf + autoheader + automake + rm -rf autom4te.cache + cd .. + scripts/makemake.tcl > sources.am + automake +- Remove the generated class and header files: + find classpath -name '*.class' | xargs -r rm -f + find gnu java javax org sun -name '*.h' \ + | xargs -r grep -Fl 'DO NOT EDIT THIS FILE - it is machine generated' \ + | xargs -r rm -f +- Build, fix, till everything works. + Be sure to build all peers (--enable-java-awt=gtk,xlib,qt + --enable-gconf-peer --enable-gstreamer-peer). + Be sure to build gjdoc (--enable-gjdoc). + Be sure to update gnu/classpath/Configuration.java to reflect + the new version + Possibly update the gcj/javaprims.h file with scripts/classes.pl + (See below, it can only be done after the first source->bytecode + pass has finished.) + You will need to configure with --enable-java-maintainer-mode and you + will need to update the .class files and generated CNI header files in + your working tree +- Add/Remove newly generated files: + - svn status classpath | grep '^!.*\.class$' | cut -c8- | xargs svn remove + - svn status classpath | grep '^?' | cut -c8- | xargs svn add + - svn status gnu java javax org sun | grep '^!.*\.h$' | cut -c8- | xargs svn remove + - svn status gnu java javax org sun | grep '^?' | cut -c8- | xargs svn add + +Over time we plan to remove as many of the remaining divergences as +possible. + +File additions and deletions require running scripts/makemake.tcl +before running automake. + +-- + +In general you should not make any changes in the classpath/ +directory. Changes here should come via imports from upstream. +However, there are three (known) exceptions to this rule: + +* In an emergency, such as a bootstrap breakage, it is ok to commit a + patch provided that the problem is resolved (by fixing a compiler + bug or fixing the Classpath bug upstream) somehow and the resolution + is later checked in (erasing the local diff). + +* On a release branch to fix a bug, where a full-scale import of + Classpath is not advisable. + +* We maintain a fair number of divergences in the build system. + This is a pain but they don't seem suitable for upstream. + +-- + +You can develop in a GCC tree using a CVS checkout of Classpath, most +of the time. (The exceptions are when an incompatible change has been +made in Classpath and some core part of libgcj has not yet been +updated.) + +The way to set this up is very similar to importing a new version of +Classpath into the libgcj tree. In your working tree: + +* cd gcc/libjava; rm -rf classpath +* cvs co classpath +* cd classpath + Now run the auto tools as specified in the import process; then + cd .. +* Run 'scripts/makemake.tcl > sources.am' in the source tree +* Run automake for libgcj + +Now you should be ready to go. + +If you are working in a tree like this, you must remember to run +makemake.tcl and automake whenever you update your embedded classpath +tree. + +-- + +If you add a class to java.lang, java.io, or java.util +(including sub-packages, like java.lang.ref). + +* Edit gcj/javaprims.h + +* Go to the `namespace java' line, and delete that entire block (the + entire contents of the namespace) + +* Then insert the output of `perl scripts/classes.pl' into the file + at that point. This must be run from the source tree, in + libjava/classpath/lib; it uses the .class file name to determine + what to print. |