Hi all,
I've merged in the information found in the INSTALL file into the
hacking guide, as discussed on list.
2007-04-15 Dalibor Topic <[EMAIL PROTECTED]>
* doc/cp-hacking.texinfo: Updated with information from
INSTALL file. Removed duplicate and outdated information.
Updated compiler information. Fixed versioning information
where entries diverged. Turned command, option, file and
URL strings into proper texinfo elements.
Index: doc/cp-hacking.texinfo
===================================================================
RCS file: /sources/classpath/classpath/doc/cp-hacking.texinfo,v
retrieving revision 1.2
diff -u -r1.2 cp-hacking.texinfo
--- doc/cp-hacking.texinfo 19 Feb 2007 14:42:46 -0000 1.2
+++ doc/cp-hacking.texinfo 15 Apr 2007 17:12:48 -0000
@@ -65,6 +65,9 @@
* Volunteering:: So you want to help out
* Project Goals:: Goals of the GNU Classpath project
* Needed Tools and Libraries:: A list of programs and libraries you will need
+* Installation:: Installation instructions
+* Building and running with the X AWT peers:: Building and running with the X AWT peers
+* Misc. Notes:: Miscellaneous notes
* Programming Standards:: Standards to use when writing code
* Hacking Code:: Working on code, Working with others
* Programming Goals:: What to consider when writing code
@@ -324,7 +327,7 @@
debugging current functionality is of higher priority then adding new
functionality.
[EMAIL PROTECTED] Needed Tools and Libraries, Programming Standards, Project Goals, Top
[EMAIL PROTECTED] Needed Tools and Libraries, Installation, Project Goals, Top
@comment node-name, next, previous, up
@chapter Needed Tools and Libraries
@@ -338,15 +341,19 @@
@itemize @bullet
@item
-GCC 3.3+
+GNU make 3.80+
[EMAIL PROTECTED]
+GCC 2.95+
[EMAIL PROTECTED]
+Eclipse Compiler for Java 3.1+
@item
CVS 1.11+
@item
-automake 1.7+
+automake 1.9+
@item
autoconf 2.59+
@item
-libtool 1.4.2+
+libtool 1.5+
@item
GNU m4 1.4
@item
@@ -356,35 +363,50 @@
All of these tools are available from
@uref{ftp://gnudist.gnu.org/pub/gnu/,gnudist.gnu.org} via anonymous
ftp, except CVS which is available from
[EMAIL PROTECTED]://www.cvshome.org/,www.cvshome.org}. They are fully
-documented with texinfo manuals. Texinfo can be browsed with the
-Emacs editor, or with the text editor of your choice, or transformed
-into nicely printable Postscript.
[EMAIL PROTECTED]://www.cvshome.org/,www.cvshome.org} and the Eclipse
+Compiler for Java, which is available from
[EMAIL PROTECTED]://www.eclipse.org/jdt/core,www.eclipse.org/jdt/core}.
+
+Except for the Eclipse Compiler for Java, they are fully documented
+with texinfo manuals. Texinfo can be browsed with the Emacs editor,
+or with the text editor of your choice, or transformed into nicely
+printable Postscript.
Here is a brief description of the purpose of those tools.
@table @b
[EMAIL PROTECTED] make
+GNU make ("gmake") is required for building Classpath.
+
@item GCC
The GNU Compiler Collection. This contains a C compiler (gcc) for
compiling the native C code and a compiler for the java programming
-language (gcj). You will need at least gcj version 3.3 or higher. If
-that version is not available for your platform you can try the
[EMAIL PROTECTED]://www.jikes.org/, jikes compiler}. We try to keep all code
-compilable with both gcj and jikes at all times.
+language (gcj). You will need at least gcc version 2.95 or higher
+in order to compile the native code. There is currently no
+released version of gcj that can compile the Java 1.5 programming
+language used by GNU Classpath.
+
[EMAIL PROTECTED] ecj
+The Eclipse Compiler for Java. This is a compiler for the Java 1.5
+programming language. It translates source code to bytecode. The
+Eclipse Foundation makes ``ecj.jar'' available as the JDT Core Batch
+Compiler download.
@item CVS
A version control system that maintains a centralized Internet
repository of all code in the Classpath system.
@item automake
-This tool automatically creates Makefile.in files from Makefile.am
-files. The Makefile.in is turned into a Makefile by autoconf. Why
-use this? Because it automatically generates every makefile target
-you would ever want (clean, install, dist, etc) in full compliance
-with the GNU coding standards. It also simplifies Makefile creation
-in a number of ways that cannot be described here. Read the docs for
-more info.
+This tool automatically creates @file{Makefile.in} files from
[EMAIL PROTECTED] files. The @file{Makefile.in} is turned into a
[EMAIL PROTECTED] by @command{autoconf}.
+
+Why use this? Because it automatically generates every makefile
+target you would ever want (@option{clean}, @option{install},
[EMAIL PROTECTED], etc) in full compliance with the GNU coding standards.
+It also simplifies Makefile creation in a number of ways that cannot
+be described here. Read the docs for more info.
@item autoconf
Automatically configures a package for the platform on which it is
@@ -414,12 +436,29 @@
@end table
+For any build environment involving native libraries, recent
+versions of @command{autoconf}, @command{automake}, and @command{libtool}
+are required if changes are made that require rebuilding @file{configure},
[EMAIL PROTECTED], @file{aclocal.m4}, or @file{config.h.in}.
+
+When working from CVS you can run those tools by executing
[EMAIL PROTECTED] in the source directory.
+
+For building the Java bytecode (.class files), you can select
+which compiler should be employed using @option{--with-javac} or
[EMAIL PROTECTED] as argument to @command{configure};
+the present default is @command{ecj}.
+
+Instead of @command{ecj}, you can also use @command{javac}, which is
+available at
[EMAIL PROTECTED]://openjdk.dev.java.net/compiler, openjdk.dev.java.net/compiler}.
For compiling the native AWT libraries you need to have the following
-libraries installed:
+libraries installed (unless @option{--disable-gtk-peer} is used as an argument
+to @command{configure}):
@table @b
[EMAIL PROTECTED] GTK+ 2.2.x
[EMAIL PROTECTED] GTK+ 2.8.x
@uref{http://www.gtk.org/,GTK+} is a multi-platform toolkit for
creating graphical user interfaces. It is used as the basis of the
GNU desktop project GNOME.
@@ -427,8 +466,125 @@
@item gdk-pixbuf
@uref{http://www.gnome.org/start/,gdk-pixbuf} is a GNOME library for
representing images.
+
[EMAIL PROTECTED] XTest
[EMAIL PROTECTED]://www.x.org,www.x.org} hosts the XTest Extension (libXtst).
+It is necessary for GdkRobot support in java.awt.
+
[EMAIL PROTECTED] table
+
+There is a bug in earlier versions of at-spi, atk, and gail, which are
+used for GNOME accessibility. Prior to version 1.18.0 of these packages,
+gtk graphical applications should be run without accessibility (clear the
+GTK_MODULES environment variable).
+
+For building the Qt AWT peer JNI native libraries you have to
+specify @option{--enable-qt-peer} and need the following library:
+
[EMAIL PROTECTED] @b
[EMAIL PROTECTED] Qt
[EMAIL PROTECTED]://www.trolltech.com/products/qt,Qt} version 4.0.1 or higher.
+The Qt library is a cros-platform graphics toolkit.
+
[EMAIL PROTECTED] table
+
+Please note that at the moment most operating systems do not
+ship Qt version 4.0.1 by default. We recommend using GNU Classpath' Qt
+support only for its developers and bug reporters. See
[EMAIL PROTECTED]://developer.classpath.org/mediation/ClasspathShowcase, the wiki}
+for details on how to get it to work.
+
+For building the X AWT peers you have to specify where to find the
+Escher library on your system using the @option{--with-escher=ABS.PATH} option.
+You will need the following library:
+
[EMAIL PROTECTED] @b
[EMAIL PROTECTED] Escher
[EMAIL PROTECTED]://escher.sourceforge.net,Escher} version 0.2.3 or higher.
+The Escher library is an implementation of X protocol and associated
+libraries written in the Java programming language.
+
[EMAIL PROTECTED] table
+
+For building the ALSA midi provider code you will need
+the following library:
+
+
[EMAIL PROTECTED] @b
[EMAIL PROTECTED] ALSA
[EMAIL PROTECTED]://www.alsa-project.org,ALSA} libraries.
+
+The ALSA project provides sound device drivers and associated
+libraries for the Linux kernel.
+
[EMAIL PROTECTED] table
+
+Building the ALSA midi provider code can be disabled by passing
[EMAIL PROTECTED] to @command{configure}.
+
+For building the DSSI midi synthesizer provider code you will
+need the following libraries:
+
[EMAIL PROTECTED] @b
[EMAIL PROTECTED] DSSI
[EMAIL PROTECTED]://dssi.sourceforge.net,DSSI} library for audio
+processing plugins.
+
[EMAIL PROTECTED] liblo
[EMAIL PROTECTED]://plugin.org.uk/liblo/,liblo}, the Lightweight OSC
+implementation.
+
[EMAIL PROTECTED] LADSPA
[EMAIL PROTECTED]://www.ladspa.org,LADSPA}, the Linux Audio Developer's
+Simple Plugin API.
+
[EMAIL PROTECTED] JACK
[EMAIL PROTECTED]://jackit.sourceforge.net,JACK}, a low latency audio
+server.
+
[EMAIL PROTECTED] libsndfile
[EMAIL PROTECTED]://www.mega-nerd.com/libsndfile/,libsndfile}, an audio
+file I/O library.
+
[EMAIL PROTECTED] fluidsynth
[EMAIL PROTECTED]://www.fluidsynth.org/,fluidsynth}, a real-time SoundFont
+2 based soft-synth.
+
[EMAIL PROTECTED] table
+
+The GConf-based backend for java.util.prefs needs the following
+library headers:
+
[EMAIL PROTECTED] @b
[EMAIL PROTECTED] GConf
[EMAIL PROTECTED]://www.gnome.org/projects/gconf/,GConf} version 2.11.2
+(or higher). GConf is used for storing dektop and application
+configuration settings in GNOME.
+
@end table
+For building @command{gcjwebplugin} you'll need the Mozilla plugin
+support headers and libraries, which are available at
[EMAIL PROTECTED]://www.mozilla.org,www.mozilla.org}.
+
+For enabling the com.sun.tools.javac support in tools.zip you
+will a need jar file containing the Eclipse Java Compiler.
+Otherwise com.sun.tools.javac will not be included in @file{tools.zip}.
+
+For building the xmlj JAXP implementation (disabled by default,
+use @command{configure --enable-xmlj}) you need the following libraries:
+
[EMAIL PROTECTED] @b
[EMAIL PROTECTED] libxml2
[EMAIL PROTECTED]://www.xmlsoft.org/,libxml2} version 2.6.8 or higher.
+
+The libxml2 library is the XML C library for the Gnome desktop.
+
[EMAIL PROTECTED] libxslt
[EMAIL PROTECTED]://www.xmlsoft.org/XSLT/,libxslt} version 1.1.11 or higher.
+
+The libxslt library if the XSLT C library for the Gnome desktop.
[EMAIL PROTECTED] table
GNU Classpath comes with a couple of libraries included in the source
that are not part of GNU Classpath proper, but that have been included
@@ -457,8 +613,167 @@
@end table
[EMAIL PROTECTED] Installation, Building and running with the X AWT peers, Needed Tools and Libraries, Top
[EMAIL PROTECTED] node-name, next, previous, up
[EMAIL PROTECTED] Installation instructions
+
+This package was designed to use the GNU standard for configuration
+and makefiles. To build and install do the following:
+
[EMAIL PROTECTED]
[EMAIL PROTECTED] Configuration
+
+Run the @command{configure} script to configure the package. There are
+various options you might want to pass to @command{configure} to control how the
+package is built. Consider the following options, @command{configure --help}
+gives a complete list.
+
[EMAIL PROTECTED] @option
[EMAIL PROTECTED] --enable-java
+
+compile Java source ([EMAIL PROTECTED]).
+
[EMAIL PROTECTED] --enable-jni
+
+compile JNI source ([EMAIL PROTECTED]).
+
[EMAIL PROTECTED] --enable-gtk-peer
+
+compile GTK native peers ([EMAIL PROTECTED]).
+
[EMAIL PROTECTED] --enable-qt-peer
+
+compile Qt4 native peers ([EMAIL PROTECTED]).
+
[EMAIL PROTECTED] --enable-default-toolkit
+
+fully qualified class name of default AWT toolkit ([EMAIL PROTECTED]).
+
[EMAIL PROTECTED] --enable-xmlj
+
+compile native libxml/xslt library ([EMAIL PROTECTED]).
+
[EMAIL PROTECTED] --enable-load-library
+
+enable to use JNI native methods ([EMAIL PROTECTED]).
+
[EMAIL PROTECTED] --enable-local-sockets
+
+enable build of local Unix sockets.
+
[EMAIL PROTECTED] --with-glibj
+define what to install @option{(zip|flat|both|none)} ([EMAIL PROTECTED]).
+
[EMAIL PROTECTED] --with-escher=/path/to/escher
+
+enable build of the X/Escher peers, with
+the escher library at @file{/path/to/escher}, either
+in the form of a JAR file, or a directory
+containing the .class files of Escher.
+
[EMAIL PROTECTED] --enable-Werror
+
+whether to compile C code with @option{-Werror} which turns
+any compiler warning into a compilation failure
+([EMAIL PROTECTED]).
+
[EMAIL PROTECTED] --with-gjdoc
+
+generate documentation using @command{gjdoc} ([EMAIL PROTECTED]).
+
[EMAIL PROTECTED] --with-jay
+
+Regenerate the parsers with @command{jay}, must be given the
+path to the @command{jay} executable
+
[EMAIL PROTECTED] --with-glibj-zip=ABS.PATH
+
+use prebuilt glibj.zip class library
+
[EMAIL PROTECTED] --with-ecj-jar=ABS.PATH
+
+specify jar file containing the Eclipse Java Compiler
+
[EMAIL PROTECTED] table
+
+For more flags run @command{configure --help}.
+
[EMAIL PROTECTED] Building
+
+Type @command{gmake} to build the package. There is no longer a
+dependency problem and we aim to keep it that way.
+
[EMAIL PROTECTED] Installation
+
+Type @command{gmake install} to install everything. This may require
+being the superuser. The default install path is /usr/local/classpath
+you may change it by giving @command{configure} the
[EMAIL PROTECTED]<path>} option.
+
[EMAIL PROTECTED] enumerate
+
+Report bugs to @email{classpath@@gnu.org} or much better to the
+GNU Classpath bug tracker at
[EMAIL PROTECTED]://savannah.gnu.org/support/?func=addsupport&group=classpath,Savannah}.
+
+Happy Hacking!
+
+Once installed, GNU Classpath is ready to be used by any VM that supports
+using the official version of GNU Classpath. Simply ensure that
[EMAIL PROTECTED]/usr/local/classpath/share/classpath} is in your @env{CLASSPATH} environment
+variable. You'll also have to set your @env{LD_LIBRARY_PATH}
+variable (or similar system configuration) to include the Classpath
+native libraries in @file{/usr/local/classpath/lib/classpath}.
+
+*NOTE* All example paths assume the default prefix is used with @command{configure}.
+If you don't know what this means then the examples are correct.
+
[EMAIL PROTECTED]
+LD_LIBRARY_PATH=/usr/local/classpath/lib/classpath
+CLASSPATH=/usr/local/classpath/share/classpath/glibj.zip:.
+export LD_LIBRARY_PATH CLASSPATH
[EMAIL PROTECTED] example
+
+More information about the VMs that use GNU Classpath can be found in the
[EMAIL PROTECTED] file.
+
[EMAIL PROTECTED] Building and running with the X AWT peers, Misc. Notes, Installation, Top
[EMAIL PROTECTED] node-name, next, previous, up
[EMAIL PROTECTED] Building and running with the X AWT peers
+
+In order build the X peers you need the Escher library version 0.2.3
+from @uref{http://escher.sourceforge.net,escher.sourceforge.net}.
+Unpack (and optionally build) the
+Escher library following the instructions in the downloaded
+package. Enable the build of the X peers by passing
[EMAIL PROTECTED]/path/to/escher} to @command{configure} where @file{/path/to/escher}
+either points to a directory structure or JAR file containing the
+Escher classes. For Unix systems it is preferable to also build local
+socket support by passing @option{--enable-local-sockets}, which accelerates
+the network communication to the X server significantly.
+
+In this release you have to enable the X peers at runtime by
+setting the system property awt.toolkit=gnu.java.awt.peer.x.XToolkit
+by passing @option{-Dawt.toolkit=gnu.java.awt.peer.x.XToolkit} to the @command{java}
+command when running an application.
+
[EMAIL PROTECTED] Misc. Notes, Programming Standards, Building and running with the X AWT peers, Top
[EMAIL PROTECTED] node-name, next, previous, up
[EMAIL PROTECTED] Misc. Notes
+
+Compilation is accomplished using a compiler's @@file syntax. For our
+part, we avoid placing make style dependencies as rules upon the
+compilation of a particular class file and leave this up to the Java
+compiler instead.
+
+The @option{--enable-maintainer-mode} option to @command{configure} currently does very
+little and shouldn't be used by ordinary developers or users anyway.
+
+On Windows machines, the native libraries do not currently build, but
+the Java bytecode library will. Gcj trunk is beginning to work under
+Cygwin.
[EMAIL PROTECTED] Programming Standards, Hacking Code, Needed Tools and Libraries, Top
[EMAIL PROTECTED] Programming Standards, Hacking Code, Misc. Notes, Top
@comment node-name, next, previous, up
@chapter Programming Standards
