OSDN Git Service

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