2003/09/07 04:31:44
[org.ibex.core.git] / README
diff --git a/README b/README
index f2d9d64..6f34a57 100644 (file)
--- a/README
+++ b/README
@@ -1,6 +1,6 @@
 ==============================================================================
 ==============================================================================
-XWT README
-
+XWT README 
+              
 ______________________________________________________________________________
 Documentation
 
 ______________________________________________________________________________
 Documentation
 
@@ -8,451 +8,106 @@ If you're new to XWT, you should read the documentation in the order
 presented below:
 
 - README [this file]
 presented below:
 
 - README [this file]
-
+        
       Start here. Includes a map of all other documentation and a
       description of the directory strucure
 
       Start here. Includes a map of all other documentation and a
       description of the directory strucure
 
-- The XWT home page [http://www.xwt.org/]
-
+- The XWT home page [http://www.xwt.org/]       
+          
 - The XWT tutorial [http://www.xwt.org/tutorial.html]
 
       Gentle introduction to what XWT is, and how to write
       .xwt's. Good for anybody who wants to write XWT applications.
 
 - The XWT reference [http://www.xwt.org/reference.html]
 - The XWT tutorial [http://www.xwt.org/tutorial.html]
 
       Gentle introduction to what XWT is, and how to write
       .xwt's. Good for anybody who wants to write XWT applications.
 
 - The XWT reference [http://www.xwt.org/reference.html]
-
+        
       Precise, technical spec of exactly how XWT works. Assumes
       familiarity with XWT (ie, you've read the tutorial). This is the
       authoritative source for how an XWT engine should
       behave.
 
       Precise, technical spec of exactly how XWT works. Assumes
       familiarity with XWT (ie, you've read the tutorial). This is the
       authoritative source for how an XWT engine should
       behave.
 
-- Javadoc [http://www.xwt.org/javadoc/]
-
-      The org.xwt.* packages are all documented with javadoc. You
-      should start by reading the package summary for org.xwt.Main,
-      and work your way around from there.
-
-- Javasrc [http://www.xwt.org/javasrc]
-
-      Javasrc generates a syntax-colored and hyperlinked html copy of
-      the XWT source code.
-
 
 ______________________________________________________________________________
 Directory Structure
 
 
 ______________________________________________________________________________
 Directory Structure
 
-/
-   README                - this file
-   COPYING               - copyright information for all files in this distro
-   TM                    - trademark information for XWT
-   ant                   - a unix shell script to launch ant
-   bin/                  - all binary stuff generated by ant builds
-   build.xml             - ANT build file
-
-   lib/                  - any third-party binary stuff needed during the build process
-       javago            - a copy of the javago post-compilation bytecode inliner
-       ant.jar           - the Jakarta project's ANT build tool, including Sun's XML parser
-       netscape.jar      - minimal set of classes required for compiling against Netcape's Applet interfaces
-       msjvm.jar         - minimal set of classes required for compiling against Microsoft's Applet interfaces
-       signtool          - the Netscape Object Signing tool, for signing applets
-       signcode.exe      - the Microsoft ActiveX Signing tool, for signing ActiveX controls
-       guidgen.exe       - the Microsoft GUID generator, for generating OLE clsid's
-       cabarc.exe        - the Microsoft CAB file generator, for creating .cab archives
-       javasrc.jar       - javasrc, a tool for generating hyperlinked, syntax-colored html from java code
-
-   src/                  - all java source files and xwt sources go here
-       jazz/             - jazzlib, which XWT currently uses since libgcj's java.util.zip.* is broken
-
+/       
+   AUTHORS                - people involved in developing XWT   
+   README                 - this file
+   COPYING                - copyright information for all files in this distro
+   CHANGES                - the changelot
+   TM                     - trademark information for XWT       
+   Makefile               - build file for gcc 3.3
+   next.build             - the build id of the next build to be generated
+
+   build/                 - anything generated by the build process winds up here
+         h/               - header files generated by gcjh
+         java/            - auto-generated .java source files
+         class/           - java .class files
+         xwar/            - generated xwars (mainly builtin.xwar)
+         Linux/           - Linux binaries
+         Win32/           - Win32 binaries
+         Carbon/          - MacOS X / Carbon binaries
+         Solaris/         - Solaris binaries
+
+   gcc/                   - build area for a custom copy of gcc3.3 and binutils2.13
+       Makefile           - will download, configure, compile, and private-install gcc3.3/binutils2.13
+       gcc.patch          - a patch to make boehm-gc work on Darwin (Mac OS X)
+   lib/                   - any third-party binary stuff needed during the build process
+       javago             - a copy of the javago post-compilation bytecode inliner
+       netscape.jar       - minimal set of classes required for compiling against Netcape's Applet interfaces
+       msjvm.jar          - minimal set of classes required for compiling against Microsoft's Applet interfaces
+       jump.jar           - the jump2 bytecode-to-palmos translator
+       libgcj-minimal.jar - a tiny portion of libgcj.jar; allows java->bytecode compilation without gcj
+   src/                   - all java source files and xwt sources go here
        org/
        org/
-           bouncycastle/ - the BouncyCastle Crypto Library
-           gimp/tigert/  - some icons used in XWT Mail, by Tigert Labs
-           mozilla/      - a copy of Rhino, the Mozilla JavaScript interpreter
-
-           xwt/          - the source code for the XWT engine
-               demo/     - the XWT widget sampler
-               chess/    - XWT Chess
-               fonts/    - some XWF fonts
-               mail/     - XWT Mail
-               plat/     - platform abstraction classes for XWT
-               tasks/    - source code for some ANT tasks used in the XWT build process
-               themes/   - some XWT themes
-               util/     - some helper classes
-
-       xwt/standard/     - the XWT standard library
-
+           bouncycastle/  - the BouncyCastle Crypto Library
+           mozilla/       - a copy of Rhino, the Mozilla JavaScript interpreter
+           ijg/           - as part of the build process, the Independent JPEG Group's JPEG implementation gets put here
+           xwt/builtin/   - .xwt's and .png's that are essential to bootstrapping the engine
+           xwt/plat/      - platform-specific code
+           xwt/util/      - misc utilities
+           xwt/js/        - the XWT JavaScript Interpreter
 
 
 ______________________________________________________________________________
 
 
 ______________________________________________________________________________
-Build Targets
-
-        *** XWT now requires JDK 1.4 or later to build ***
-
-To build, make sure your $JAVA_HOME points to jdk1.4 or later, and type
-
-    ./ant -Dplat=<platform> <targetname>
-
-The name of any class in org.xwt.plat is a valid <platform>; here is a
-list as of 20-Mar-2002:
-
-    Win32         - Windows 95 / NT4 or later
-    Java2         - Any Java 1.2+ compliant JVM
-
-Valid <target>s are:
-
-    build         - builds a binary for the selected platform
-
-The following targets do not require that you specify a platform:
-
-    compile       - compiles all .java's to .class'es
-    clean         - empties bin/ and compiled binaries in dist/
-
-
-______________________________________________________________________________
-Building
-
-- If you only want to build the JVM version of XWT, delete these three
-  files:
-
-    xwt/src/org/xwt/plat/Win32.java
-    xwt/src/org/xwt/plat/POSIX.java
-    xwt/src/org/xwt/plat/GCJ.java
-
-  This will allow XWT to build correctly *without* gcc 3.1. Otherwise,
-  you must compile and install gcc 3.1.
-
-
-- The Win32 native version of XWT can ONLY be built with the very
-  latest pre-release of GCC 3.1. You can follow the steps below to
-  create a cross-compiler from linux to Win32.
-
-  If the steps below fail, try adding "-D 20-Mar-2002" to the cvs
-  checkout line; 20-Mar-2002 was the last date on which the compiler
-  was known to work. Please don't do this unless you have attempted
-  without it, however, since it puts additional strain on the gcc cvs
-  server.
-
-  There are also two patches at the end of this file which can be
-  applied to the branch -- the first fixes an inet_addr() bug on
-  Win32, the second enables stack traces.
-
-  # create an install area
-  export CLASSPATH=
-  export PREFIX=/usr/local/gcc
-  export CC=/usr/bin/gcc
-  
-  sudo rm -rf $PREFIX
-  export PATH=$PATH:$PREFIX/bin
-  sudo mkdir $PREFIX
-  sudo mkdir $PREFIX/i686-pc-mingw32/
-  
-  wget http://telia.dl.sourceforge.net/sourceforge/mingw/MinGW-1.1.tar.gz
-  sudo tar -C $PREFIX/i686-pc-mingw32/ -xvzf MinGW-1.1.tar.gz
-  
-  wget ftp://ftp.gnu.org/gnu/binutils/binutils-2.11.2.tar.gz
-  tar xzvf binutils-2.11.2.tar.gz
-  cd binutils-2.11.2
-  ./configure --target=i686-pc-mingw32 --prefix=$PREFIX
-  make
-  sudo make install
-  cd ..
-  
-  cvs -d :pserver:anoncvs@subversions.gnu.org:/cvsroot/gcc co -rgcc-3_1-branch gcc
-  mkdir bin
-  cd bin
-  ../gcc/configure \
-                   --prefix=$PREFIX \
-                   --target=i686-pc-mingw32 \
-                   --host=i686-pc-linux-gnu \
-                   --enable-languages=c,c++,java \
-                   --disable-nls \
-                   --with-as=$PREFIX/i686-pc-mingw32/bin/as \
-                   --with-ld=$PREFIX/i686-pc-mingw32/bin/ld \
-                   --with-gnu-ld \
-                   --with-gnu-as \
-                   --enable-libgcj \
-                   --enable-gc-type=boehm \
-                   --disable-shared \
-                   --enable-threads=win32 \
-                   --disable-hash-synchronization \
-                   --disable-interpreter \
-                   --enable-sjlj-exceptions
-  
-  make
-  sudo make install
-
-- The Linux native version is still experimental. You should configure
-  your compiler with:
-
-  ../gcc/configure \
-                   --prefix=$PREFIX \
-                   --enable-languages=c,c++,java \
-                   --disable-nls \
-                   --enable-libgcj \
-                   --enable-threads=posix \
-                   --enable-hash-synchronization \
-                   --enable-static \
-                   --disable-interpreter
-
-
-______________________________________________________________________________
-inet_addr patch
-
-Index: java/net/natInetAddress.cc
-===================================================================
-RCS file: /cvs/gcc/gcc/libjava/java/net/natInetAddress.cc,v
-retrieving revision 1.18.18.1
-diff -u -r1.18.18.1 natInetAddress.cc
---- java/net/natInetAddress.cc  4 Mar 2002 20:02:19 -0000       1.18.18.1
-+++ java/net/natInetAddress.cc  27 May 2002 22:54:40 -0000
-@@ -9,6 +9,7 @@
- details.  */
-
- #include <config.h>
-+#include <platform.h>
-
- #ifdef WIN32
-
-Index: include/win32.h
-===================================================================
-RCS file: /cvs/gcc/gcc/libjava/include/win32.h,v
-retrieving revision 1.3.8.5
-diff -u -r1.3.8.5 win32.h
---- include/win32.h     24 Apr 2002 01:04:45 -0000      1.3.8.5
-+++ include/win32.h     27 May 2002 22:54:40 -0000
-@@ -35,4 +35,8 @@
-    ARRAY and return the exact number of values stored.  */
- extern int backtrace (void **__array, int __size);
-
-+// configure cannot correctly detect inet_addr due to Win32's
-+// oddball header naming scheme
-+#define HAVE_INET_ADDR
-+
- #endif /* __JV_WIN32_H__ */
-
-
-
-______________________________________________________________________________
-Throwable.printStackTrace() patch
-
-Index: Class.h
-===================================================================
-RCS file: /cvs/gcc/gcc/libjava/java/lang/Class.h,v
-retrieving revision 1.43
-diff -u -r1.43 Class.h
---- Class.h    21 Dec 2001 19:47:50 -0000      1.43
-+++ Class.h    24 Apr 2002 03:06:14 -0000
-@@ -308,6 +308,7 @@
-   friend void _Jv_LayoutVTableMethods (jclass klass);
-   friend void _Jv_SetVTableEntries (jclass, _Jv_VTable *);
-   friend void _Jv_MakeVTable (jclass);
-+  friend JArray<java::lang::reflect::Method*>* _Jv_GetAllMethods();
-   // Return array class corresponding to element type KLASS, creating it if
-   // necessary.
-Index: ClassLoader.java
-===================================================================
-RCS file: /cvs/gcc/gcc/libjava/java/lang/ClassLoader.java,v
-retrieving revision 1.16
-diff -u -r1.16 ClassLoader.java
---- ClassLoader.java   7 Dec 2001 23:34:12 -0000       1.16
-+++ ClassLoader.java   24 Apr 2002 03:06:14 -0000
-@@ -577,4 +577,8 @@
-     // Default to returning null.  Derived classes implement this.
-     return null;
-   }
-+
-+  static native java.lang.reflect.Method[] getAllMethods();
-+  static native long[] getAllMethodAddrs();
-+
- }
-Index: Throwable.java
-===================================================================
-RCS file: /cvs/gcc/gcc/libjava/java/lang/Throwable.java,v
-retrieving revision 1.10
-diff -u -r1.10 Throwable.java
---- Throwable.java     24 Feb 2001 03:52:49 -0000      1.10
-+++ Throwable.java     24 Apr 2002 03:06:14 -0000
-@@ -123,21 +123,64 @@
-     printStackTrace (writer);
-   }
-+  private native static long longFromStackTraceBytes(byte[] stackTrace, int i);
-+
-   public void printStackTrace (PrintWriter wr)
-   {
--    try
--      {
--      CPlusPlusDemangler cPlusPlusFilter = new CPlusPlusDemangler (wr);
--      PrintWriter writer = new PrintWriter (cPlusPlusFilter);
--      printRawStackTrace (writer);    
--      writer.close ();
--      if (cPlusPlusFilter.written == 0) // The demangler has failed...
--        printRawStackTrace (wr);
-+      try
-+          {
-+              CPlusPlusDemangler cPlusPlusFilter = new CPlusPlusDemangler (wr);
-+              PrintWriter writer = new PrintWriter (cPlusPlusFilter);
-+              printRawStackTrace (writer);    
-+              writer.close ();
-+              if (cPlusPlusFilter.written > 0) return;
-+          }
-+      catch (Exception e1)
-+          {
-+          }
-+
-+      wr.println(toString());
-+      if (stackTrace == null) {
-+          wr.flush();
-+          return;
-       }
--    catch (Exception e1)
--      {
--      printRawStackTrace (wr);
-+      
-+      long[] allAddrs = ClassLoader.getAllMethodAddrs();
-+      java.lang.reflect.Method[] meths = ClassLoader.getAllMethods();
-+      
-+      // FIXME: assumes little endian
-+      for(int i=0; i<stackTrace.length; i++) {
-+          long addr = longFromStackTraceBytes(stackTrace, i);
-+          if (addr == 0) break;
-+          
-+          int whichMethod = -1;
-+          for(int j=0; j<allAddrs.length; j++) {
-+              if (allAddrs[j] <= addr &&
-+                  (whichMethod == -1 || allAddrs[whichMethod] < allAddrs[j])) {
-+                  whichMethod = j;
-+              }
-+          }
-+          
-+          if (whichMethod == -1) {
-+              wr.println("[" + Long.toString(addr, 16) + "]  " + "??");
-+              continue;
-+          }
-+          
-+          if (meths[whichMethod].getDeclaringClass().getName().equals("gnu.gcj.runtime.FirstThread") &&
-+              meths[whichMethod].getName().equals("call_main"))
-+              break;
-+          
-+          wr.println("    [" + Long.toString(addr, 16) + "] " +
-+                     meths[whichMethod].getDeclaringClass().getName() + "." +
-+                     meths[whichMethod].getName() + "() " +
-+                     "+" + (addr - allAddrs[whichMethod])
-+                     );
-+          
-+          if (java.lang.Thread.class.isAssignableFrom(meths[whichMethod].getDeclaringClass()) &&
-+              meths[whichMethod].getName().equals("run"))
-+              break;
-       }
-+      wr.flush();
-   }
-   public Throwable ()
-Index: natClassLoader.cc
-===================================================================
-RCS file: /cvs/gcc/gcc/libjava/java/lang/natClassLoader.cc,v
-retrieving revision 1.47.8.1
-diff -u -r1.47.8.1 natClassLoader.cc
---- natClassLoader.cc  2 Apr 2002 22:19:55 -0000       1.47.8.1
-+++ natClassLoader.cc  24 Apr 2002 03:06:14 -0000
-@@ -40,6 +40,10 @@
- #include <java/lang/StringBuffer.h>
- #include <java/io/Serializable.h>
- #include <java/lang/Cloneable.h>
-+#include <java/lang/reflect/Method.h>
-+
-+#include<java/lang/reflect/Constructor.h>
-+#include<gcj/method.h>
- // FIXME: remove these.
- #define CloneableClass java::lang::Cloneable::class$
-@@ -347,6 +351,50 @@
- static jclass loaded_classes[HASH_LEN];
- // This is the root of a linked list of classes
-+
-+JArray<java::lang::reflect::Method*>*
-+java::lang::ClassLoader::getAllMethods()
-+{
-+    return _Jv_GetAllMethods();
-+}
-+
-+JArray<jlong>*
-+java::lang::ClassLoader::getAllMethodAddrs()
-+{
-+    JArray<java::lang::reflect::Method*>* arr = _Jv_GetAllMethods();
-+    java::lang::reflect::Method** el = (java::lang::reflect::Method**)elements(arr);
-+    JArray<jlong>* ret = JvNewLongArray(arr->length);
-+    jlong* retel = (jlong*)elements(ret);
-+    for(int i=0; i<arr->length; i++)
-+        retel[i] = (jlong)((unsigned int)(_Jv_FromReflectedMethod (el[i])->ncode));
-+    return ret;
-+}
-+
-+JArray<java::lang::reflect::Method*>*
-+_Jv_GetAllMethods()
-+{
-+  int numMethods = 0;
-+
-+  for(int i=0; i<HASH_LEN; i++)
-+      for(jclass c = loaded_classes[i]; c; c = c->next)
-+          numMethods += c->getDeclaredMethods()->length;
-+
-+  JArray<java::lang::reflect::Method*>* ret =
-+    (JArray<java::lang::reflect::Method*>*)
-+    JvNewObjectArray(numMethods, &java::lang::reflect::Method::class$, NULL);
-+
-+  java::lang::reflect::Method** el = (java::lang::reflect::Method**)elements(ret);
-+
-+  for(int i=0; i<HASH_LEN; i++)
-+      for(jclass c = loaded_classes[i]; c; c = c->next) {
-+          JArray<java::lang::reflect::Method*>* methods = c->getDeclaredMethods();
-+          jint len = methods->length;
-+          java::lang::reflect::Method** meths = (java::lang::reflect::Method**)elements(methods);
-+          for(int j=0; j<len; j++) el[--numMethods] = meths[j];
-+      }
-+
-+  return ret;
-+}
\f
-Index: natThrowable.cc
-===================================================================
-RCS file: /cvs/gcc/gcc/libjava/java/lang/natThrowable.cc,v
-retrieving revision 1.11
-diff -u -r1.11 natThrowable.cc
---- natThrowable.cc    7 Feb 2002 19:26:06 -0000       1.11
-+++ natThrowable.cc    24 Apr 2002 03:06:14 -0000
-@@ -32,6 +32,7 @@
- #include <stdio.h>
- #include <unistd.h>
-+#include <platform.h>
- #ifdef HAVE_EXECINFO_H
- #include <execinfo.h>
-@@ -102,3 +103,18 @@
- #endif /* HAVE_BACKTRACE */
-   wr->flush ();
- }
-+
-+// Returns the i^th call address in the stackTrace member, or 0 if i
-+// is beyond the end of the trace. This has to be done in C++ because
-+// the addresses in stackTrace are the same width as the platform's
-+// pointers (which is unknown to Java code), and stackTrace is a
-+// byte[] using the platform's endianness (which is unknown to Java
-+// code).
-+jlong
-+java::lang::Throwable::longFromStackTraceBytes(jbyteArray stackArr, jint i)
-+{
-+    if (i * sizeof(void*) > stackArr->length) return 0;
-+    unsigned int* stack = (unsigned int*)elements(stackArr);
-+    return (jlong)stack[i];
-+}
-+
-
-
-
-
+Build Requirements
+
+**** STOP! ****
+
+Compiling the engine is Really Hard.  Unless you're planning on
+helping develop the engine, you probably don't need (or want) to
+compile it yourself!
+
+There are pre-built, digitally signed binaries on http://dist.xwt.org/
+for every supported platform.  Please consider using those unless
+you're absolutely certain you need to go through the trouble of trying
+to get XWT to build.  You have been warned.  Please do not post to the
+mailing lists asking for help building XWT unless you're genuinely
+interested in helping to develop the engine.
+
+Requirements:
+    - jdk 1.4+
+    - the standard set of POSIX utilities (wc, grep, find, make, etc)
+
+Automatically-Downloaded components:
+    - gcj 3.3+
+    - binutils 2.13+
+    * If you already have a suitably configured gcj 3.3 and binutils
+      2.13+ you can set "gcc_path" to point at its installation
+      location; otherwise the Makefile will download, configure,
+      compile, and install gcc and binutils in xwt/gcc/
+
+Optional components:
+    - fastjar (builds archives faster)
+    - jikes 1.18 (makes builds go much faster)
+    * If jikes is in your $PATH, the Makefile will find and use it.
+      Otherwise you can type 'make jikes' to download and build jikes.
+
+Build Targets:
+    - compile: compiles all .java files into bin/*.class
+    - Win32:   Win95 OSR2 or later
+    - Linux:   Linux 2.2 or later
+    - Java2:   Any Java 1.2+ compliant JVM
+    - Darwin:  Any Darwin-based OS (Mac OS X, OpenDarwin) with an X11 server
+    - clean:   cleanup