2003/09/07 04:31:44
[org.ibex.core.git] / README
diff --git a/README b/README
index 3ead8bd..6f34a57 100644 (file)
--- a/README
+++ b/README
@@ -1,6 +1,6 @@
 ==============================================================================
 ==============================================================================
-XWT README
-      
+XWT README 
+              
 ______________________________________________________________________________
 Documentation
 
 ______________________________________________________________________________
 Documentation
 
@@ -8,19 +8,19 @@ 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
       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
@@ -30,15 +30,28 @@ presented below:
 ______________________________________________________________________________
 Directory Structure
 
 ______________________________________________________________________________
 Directory Structure
 
-/
-   AUTHORS                - people involved in developing XWT
+/       
+   AUTHORS                - people involved in developing XWT   
    README                 - this file
    COPYING                - copyright information for all files in this distro
    README                 - this file
    COPYING                - copyright information for all files in this distro
-   TM                     - trademark information for XWT
+   CHANGES                - the changelot
+   TM                     - trademark information for XWT       
    Makefile               - build file for gcc 3.3
    Makefile               - build file for gcc 3.3
-   bin/                   - all binary stuff generated by xwt builds
+   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/                   - 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
    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
@@ -49,292 +62,52 @@ Directory Structure
        org/
            bouncycastle/  - the BouncyCastle Crypto Library
            mozilla/       - a copy of Rhino, the Mozilla JavaScript interpreter
        org/
            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/builtin/   - .xwt's and .png's that are essential to bootstrapping the engine
            xwt/plat/      - platform-specific code
-
-______________________________________________________________________________
-Build Targets and Requirements
-
-Build requirements:
-- jdk 1.4+
-- jikes (warning: Jikes 1.16 has a fatal bug; use 1.15)
-- gcj 3.3+
-- binutils 2.13+
-- fastjar
-
-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.
-
-Public build targets:
-
-    compile       - compiles all .java files into bin/*.class
-    Win32         - Win95 or later (bin-Win32/xwt.exe)
-    Linux         - Linux 2.2 or later (bin-Linux/xwt.linux)
-    Java2         - Any Java 1.2+ compliant JVM
-    clean         - cleanup
-
-
-______________________________________________________________________________
-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__ */
-
+           xwt/util/      - misc utilities
+           xwt/js/        - the XWT JavaScript Interpreter
 
 
 ______________________________________________________________________________
 
 
 ______________________________________________________________________________
-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