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 If you plan to modify a .java file, you will need to configure with
  11 --enable-java-maintainer-mode.  In order to make this work properly,
  12 you will need to have 'ecj1' and 'gjavah' executables in your PATH at
  13 build time.
  14
  15 One way to do this is to download ecj.jar (see contrib/download_ecj)
  16 and write a simple wrapper script like:
  17
  18     #! /bin/sh
  19     gij -cp /home/tromey/gnu/Generics/trunk/ecj.jar \
  20        org.eclipse.jdt.internal.compiler.batch.GCCMain \
  21        ${1+"$@"}
  22
  23 For gjavah, you can make a tools.zip from the classes in
  24 classpath/lib/tools/ and write a gjavah script like:
  25
  26     #! /bin/sh
  27     dir=/home/tromey/gnu/Generics/Gcjh
  28     gij -cp $dir/tools.zip \
  29        gnu.classpath.tools.javah.Main \
  30        ${1+"$@"}
  31
  32 Another way to get a version of gjavah is to first do a
  33 non-maintainer-mode build and use the newly installed gjavah.
  34
  35 --
  36
  37 To regenerate libjava/configure, use:
  38
  39     aclocal -I . -I .. -I ../config -I libltdl
  40     autoconf
  41
  42 See the GCC documentation which auto* versions to use.
  43
  44 --
  45
  46 libgcj uses GNU Classpath as an upstream provider.  Snapshots of
  47 Classpath are imported into the libgcj source tree.  Some classes are
  48 overridden by local versions; these files still appear in the libgcj
  49 tree.
  50
  51 To import a new release:
  52
  53 - Check out a classpath snapshot or take a release tar.gz file.
  54   I use 'cvs export' for this.  Make a tag to ensure future hackers
  55   know exactly what revision was checked out; tags are of the form
  56   'libgcj-import-DATE' (when using a tagged checkout do:
  57   - ./autogen.sh && ./configure && make dist
  58   to get a proper .tar.gz for importing below).
  59 - Get a svn checkout of
  60   svn+ssh://gcc.gnu.org/svn/gcc/branches/CLASSPATH/libjava/classpath
  61   this contains "pure" GNU Classpath inside the GCC tree.
  62 - Clean it up and get the files from a new version:
  63   - find classpath -type f | grep -v /\.svn | grep -v /\.cvs | xargs rm
  64   - tar zxf classpath-x.tar.gz
  65   - cp -r classpath-x/* classpath
  66 - Add/Remove files:
  67   - svn status classpath | grep ^\! | cut -c8- | xargs svn remove
  68   - svn status classpath | grep ^\? | cut -c8- | xargs svn add
  69 - If there are any empty directories now they can be removed. You can find
  70   candidates (dirs with files removed) with:
  71   - for i in `svn status classpath | grep ^D | cut -c8-`; \
  72       do ls -d `dirname $i`; done | uniq
  73 - Update vendor branch
  74   - svn commit classpath
  75 - Note the new revision number (Xrev)
  76 - Get a fresh svn trunk checkout and cd gcc/libjava
  77 - Merge the changes between classpath versions into the trunk.
  78   svn merge -rXrev-1:Xrev \
  79   svn+ssh://gcc.gnu.org/svn/gcc/branches/CLASSPATH/libjava/classpath \
  80   classpath
  81 - Resolve any conflicts pointed out by svn status classpath | grep ^C
  82   - Makefile.in files will be regenerated in the next step.
  83   - Other files should have a "GCJ LOCAL" comment, and/or are mentioned
  84     in the classpath/ChangeLog.gcj file.
  85    (Don't forget to svn resolved files.)
  86 - Use auto* to create configure, Makefile.in, etc
  87   Make sure you have Automake 1.9.6 installed. Exactly that version!
  88   You have to make sure to use the gcc libtool.m4 and gcc lt* scripts
  89   cd .../classpath
  90   cp ../../lt* .
  91   cp ../../config.sub ../../config.guess .
  92   aclocal -I m4 -I ../.. -I ../../config
  93   autoconf
  94   autoheader
  95   automake
  96   rm -rf autom4te.cache
  97   cd ..
  98   scripts/makemake.tcl > sources.am
  99   automake
 100 - Build, fix, till everything works.
 101   Be sure to build all peers (--enable-java-awt=gtk,xlib,qt
 102   --enable-gconf-peer)
 103   Be sure to update gnu/classpath/Configuration.java to reflect
 104     the new version
 105   Possibly update the gcj/javaprims.h file with scripts/classes.pl
 106   (See below, it can only be done after the first source->bytecode
 107    pass has finished.)
 108   You will need to configure with --enable-maintainer-mode and you
 109   will need to update the .class files and generated CNI header files in
 110   your working tree
 111
 112 Over time we plan to remove as many of the remaining divergences as
 113 possible.
 114
 115 File additions and deletions require running scripts/makemake.tcl
 116 before running automake.
 117
 118 --
 119
 120 In general you should not make any changes in the classpath/
 121 directory.  Changes here should come via imports from upstream.
 122 However, there are three (known) exceptions to this rule:
 123
 124 * In an emergency, such as a bootstrap breakage, it is ok to commit a
 125   patch provided that the problem is resolved (by fixing a compiler
 126   bug or fixing the Classpath bug upstream) somehow and the resolution
 127   is later checked in (erasing the local diff).
 128
 129 * On a release branch to fix a bug, where a full-scale import of
 130   Classpath is not advisable.
 131
 132 * We maintain a fair number of divergences in the build system.
 133   This is a pain but they don't seem suitable for upstream.
 134
 135 --
 136
 137 You can develop in a GCC tree using a CVS checkout of Classpath, most
 138 of the time.  (The exceptions are when an incompatible change has been
 139 made in Classpath and some core part of libgcj has not yet been
 140 updated.)
 141
 142 The way to set this up is very similar to importing a new version of
 143 Classpath into the libgcj tree.  In your working tree:
 144
 145 * cd gcc/libjava; rm -rf classpath
 146 * cvs co classpath
 147 * cd classpath
 148   Now run the auto tools as specified in the import process; then
 149   cd ..
 150 * Run 'scripts/makemake.tcl > sources.am' in the source tree
 151 * Run automake for libgcj
 152
 153 Now you should be ready to go.
 154
 155 If you are working in a tree like this, you must remember to run
 156 makemake.tcl and automake whenever you update your embedded classpath
 157 tree.
 158
 159 --
 160
 161 If you add a class to java.lang, java.io, or java.util
 162 (including sub-packages, like java.lang.ref).
 163
 164 * Edit gcj/javaprims.h
 165
 166 * Go to the `namespace java' line, and delete that entire block (the
 167   entire contents of the namespace)
 168
 169 * Then insert the output of `perl scripts/classes.pl' into the file
 170   at that point.  This must be run from the build tree, in
 171   <build>/classpath/lib; it uses the .class file name to determine
 172   what to print.