libjava/HACKING - gcc - Git at Google

 Things libgcj hackers should know
 ---------------------------------

 If you want to hack on the libgcj files you need to be aware of the
 following things. There are probably lots of other things that should be
 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
 tree.

 To import a new release:

 - 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
   '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
   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 .
   aclocal -I m4 -I ../.. -I ../../config
   autoconf
   autoheader
   automake
   rm -rf autom4te.cache
   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.

 File additions and deletions require running scripts/makemake.tcl
 before running automake.

 --

 In general you should not make any changes in the classpath/
 directory.  Changes here should come via imports from upstream.
 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
   bug or fixing the Classpath bug upstream) somehow and the resolution
   is later checked in (erasing the local diff).

 * 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
 of the time.  (The exceptions are when an incompatible change has been
 made in Classpath and some core part of libgcj has not yet been
 updated.)

 The way to set this up is very similar to importing a new version of
 Classpath into the libgcj tree.  In your working tree:

 * cd gcc/libjava; rm -rf classpath
 * cvs co classpath
 * cd classpath
   Now run the auto tools as specified in the import process; then
   cd ..
 * Run 'scripts/makemake.tcl > sources.am' in the source tree
 * Run automake for libgcj

 Now you should be ready to go.

 If you are working in a tree like this, you must remember to run
 makemake.tcl and automake whenever you update your embedded classpath
 tree.

 --

 If you add a class to java.lang, java.io, or java.util
 (including sub-packages, like java.lang.ref).

 * Edit gcj/javaprims.h

 * Go to the `namespace java' line, and delete that entire block (the
   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 source tree, in
   libjava/classpath/lib; it uses the .class file name to determine
   what to print.
	Things libgcj hackers should know
	---------------------------------

	If you want to hack on the libgcj files you need to be aware of the
	following things. There are probably lots of other things that should be
	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
	tree.

	To import a new release:

	- 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
	'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
	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 .
	aclocal -I m4 -I ../.. -I ../../config
	autoconf
	autoheader
	automake
	rm -rf autom4te.cache
	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.

	File additions and deletions require running scripts/makemake.tcl
	before running automake.

	--

	In general you should not make any changes in the classpath/
	directory. Changes here should come via imports from upstream.
	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
	bug or fixing the Classpath bug upstream) somehow and the resolution
	is later checked in (erasing the local diff).

	* 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
	of the time. (The exceptions are when an incompatible change has been
	made in Classpath and some core part of libgcj has not yet been
	updated.)

	The way to set this up is very similar to importing a new version of
	Classpath into the libgcj tree. In your working tree:

	* cd gcc/libjava; rm -rf classpath
	* cvs co classpath
	* cd classpath
	Now run the auto tools as specified in the import process; then
	cd ..
	* Run 'scripts/makemake.tcl > sources.am' in the source tree
	* Run automake for libgcj

	Now you should be ready to go.

	If you are working in a tree like this, you must remember to run
	makemake.tcl and automake whenever you update your embedded classpath
	tree.

	--

	If you add a class to java.lang, java.io, or java.util
	(including sub-packages, like java.lang.ref).

	* Edit gcj/javaprims.h

	* Go to the `namespace java' line, and delete that entire block (the
	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 source tree, in
	libjava/classpath/lib; it uses the .class file name to determine
	what to print.