libjava/HACKING

   1 Things libgcj hackers should know
   2 ---------------------------------
   3
   4 If you want to hack on the libgcj files you need to be aware of the
   5 following things. There are probably lots of other things that should be
   6 explained in this HACKING file. Please add them if you discover them :)
   7
   8 --
   9
  10 libgcj uses GNU Classpath as an upstream provider.  Snapshots of
  11 Classpath are imported into the libgcj source tree.  Some classes are
  12 overridden by local versions; these files still appear in the libgcj
  13 tree.
  14
  15 To import a new release:
  16
  17 - Check out a classpath snapshot or take a release tar.gz file.
  18   I use 'cvs export' for this.  Make a tag to ensure future hackers
  19   know exactly what revision was checked out; tags are of the form
  20   'libgcj-import-DATE'.
  21 - Get a svn checkout of
  22   svn+ssh://gcc.gnu.org/svn/gcc/branches/CLASSPATH/libjava/classpath
  23   this contains "pure" GNU Classpath inside the GCC tree.
  24 - Clean it up and get the files from a new version:
  25   - find classpath -type f | grep -v /\.svn | grep -v /\.cvs
  26   - tar zxf classpath-x.tar.gz
  27   - cp -r classpath-x/* classpath
  28 - Add/Remove files:
  29   - svn status classpath | grep ^\! | cut -c8- | xargs svn remove
  30   - svn status classpath | grep ^\? | cut -c8- | xargs svn add
  31 - If there are any empty directories now they can be removed.
  32 - Update vendor branch
  33   - svn commit classpath
  34 - Note the new revision number (Xrev)
  35 - Get a fresh svn trunk checkout and cd gcc/libjava
  36 - Merge the changes between classpath versions into the trunk.
  37   svn merge -rXrev-1:Xrev \
  38   svn+ssh://gcc.gnu.org/svn/gcc/branches/CLASSPATH/libjava/classpath \
  39   classpath
  40 - Resolve any conflicts pointed out by svn status classpath | grep ^C
  41   - Makefile.in files will be regenerated in the next step.
  42   - Other files should have a "GCJ LOCAL" comment, and/or are mentioned
  43     in the classpath/ChangeLog.gcj file.
  44    (Don't forget to svn resolved files.)
  45 - Use auto* to create configure, Makefile.in, etc
  46   Make sure you have Automake 1.9.3 installed. Exactly that version!
  47   You have to make sure to use the gcc libtool.m4 and gcc lt* scripts
  48   cd .../classpath
  49   cp ../../lt* .
  50   cp ../../config.sub ../../config.guess .
  51   aclocal -I m4 -I ../..
  52   autoconf
  53   autoheader
  54   automake
  55   rm -rf autom4te.cache
  56   cd ..
  57   scripts/makemake.tcl > sources.am
  58   automake
  59 - Build, fix, till everything works.
  60   Possibly update the gcj/javaprims.h file with scripts/classes.pl
  61   (See below, it can only be done after the first source->bytecode
  62    pass has finished.)
  63
  64 Over time we plan to remove as many of the remaining divergences as
  65 possible.
  66
  67 File additions and deletions require running scripts/makemake.tcl
  68 before running automake.
  69
  70 --
  71
  72 In general you should not make any changes in the classpath/
  73 directory.  Changes here should come via imports from upstream.
  74 However, there are two (known) exceptions to this rule:
  75
  76 * In an emergency, such as a bootstrap breakage, it is ok to commit a
  77   patch provided that the problem is resolved (by fixing a compiler
  78   bug or fixing the Classpath bug upstream) somehow and the resolution
  79   is later checked in (erasing the local diff).
  80
  81 * On a release branch to fix a bug, where a full-scale import of
  82   Classpath is not advisable.
  83
  84 --
  85
  86 You can develop in a GCC tree using a CVS checkout of Classpath, most
  87 of the time.  (The exceptions are when an incompatible change has been
  88 made in Classpath and some core part of libgcj has not yet been
  89 updated.)
  90
  91 The way to set this up is very similar to importing a new version of
  92 Classpath into the libgcj tree.  In your working tree:
  93
  94 * cd gcc/libjava; rm -rf classpath
  95 * cvs co classpath
  96 * cd classpath
  97   Now run the auto tools as specified in the import process; then
  98   cd ..
  99 * Run 'scripts/makemake.tcl > sources.am' in the source tree
 100 * Run automake for libgcj
 101
 102 Now you should be ready to go.
 103
 104 If you are working in a tree like this, you must remember to run
 105 makemake.tcl and automake whenever you update your embedded classpath
 106 tree.
 107
 108 --
 109
 110 If you add a class to java.lang, java.io, or java.util
 111 (including sub-packages, like java.lang.ref).
 112
 113 * Edit gcj/javaprims.h
 114
 115 * Go to the `namespace java' line, and delete that entire block (the
 116   entire contents of the namespace)
 117
 118 * Then insert the output of `perl scripts/classes.pl' into the file
 119   at that point.  This must be run from the build tree, in
 120   <build>/classpath/lib; it uses the .class file name to determine
 121   what to print.
 122
 123 If you're generating a patch there is a program you can get to do an
 124 offline `cvs add' (it will fake an `add' if you don't have write
 125 permission yet).  Then you can use `cvs diff -N' to generate the
 126 patch.  See http://www.red-bean.com/cvsutils/