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