2010-05-27 Kai Tietz <kai.tietz@onevision.com>

[pf3gnuchains/gcc-fork.git] / libjava / HACKING

diff --git a/libjava/HACKING b/libjava/HACKING
index 7a9b69d..3e99bed 100644 (file)
--- a/libjava/HACKING
+++ b/libjava/HACKING
@@ -7,6 +7,49 @@ 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
 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


@@ -14,30 +57,75 @@ tree.
 
 To import a new release:
 
 
 To import a new release:
 

-- Check out a classpath snapshot
+- 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
   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'.
+  '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
 - 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 .
   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 ../..
+  aclocal -I m4 -I ../.. -I ../../config

   autoconf
   autoheader
   automake
   rm -rf autom4te.cache
   autoconf
   autoheader
   automake
   rm -rf autom4te.cache

-- Test everything first.  The simplest way to do this is by overlaying
-  the checked out classpath on your gcc tree and then doing a build.
-- Use 'cvs import' to import.  The vendor tag is 'CLASSPATH'.  For the
-  release tag, if this is a released classpath version, use something
-  like 'classpath-import-VERSION'; otherwise something like
-  'classpath-import-DATE'.
-  Be sure to use -ko and -I\!
-- Remove any files that were deleted in Classpath
-- Run 'scripts/makemake.tcl > sources.am' in the source tree
-- Run automake for libgcj
+  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.
 
 Over time we plan to remove as many of the remaining divergences as
 possible.


@@ -49,7 +137,7 @@ before running automake.
 
 In general you should not make any changes in the classpath/
 directory.  Changes here should come via imports from upstream.
 
 In general you should not make any changes in the classpath/
 directory.  Changes here should come via imports from upstream.

-However, there are two (known) exceptions to this rule:
+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
 
 * 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


@@ -59,6 +147,9 @@ However, there are two (known) exceptions to this rule:
 * On a release branch to fix a bug, where a full-scale import of
   Classpath is not advisable.
 
 * 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
 --
 
 You can develop in a GCC tree using a CVS checkout of Classpath, most


@@ -94,11 +185,6 @@ If you add a class to java.lang, java.io, or java.util
   entire contents of the namespace)
 
 * Then insert the output of `perl scripts/classes.pl' into the file
   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 build tree, in
-  <build>/classpath/lib; it uses the .class file name to determine
+  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.
   what to print.

-
-If you're generating a patch there is a program you can get to do an
-offline `cvs add' (it will fake an `add' if you don't have write
-permission yet).  Then you can use `cvs diff -N' to generate the
-patch.  See http://www.red-bean.com/cvsutils/