2003/09/27 00:54:23
[org.ibex.core.git] / README
diff --git a/README b/README
index efc227b..5d5ea78 100644 (file)
--- a/README
+++ b/README
@@ -1,6 +1,5 @@
 ==============================================================================
 ==============================================================================
-XWT README
-\r
+XWT README 
               
 ______________________________________________________________________________
 Documentation
               
 ______________________________________________________________________________
 Documentation
@@ -15,7 +14,7 @@ presented below:
 
 - 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]
+- The XWT tutorials [http://www.xwt.org/tutorials.html]
 
       Gentle introduction to what XWT is, and how to write
       .xwt's. Good for anybody who wants to write XWT applications.
 
       Gentle introduction to what XWT is, and how to write
       .xwt's. Good for anybody who wants to write XWT applications.
@@ -27,315 +26,77 @@ presented below:
       authoritative source for how an XWT engine should
       behave.
 
       authoritative source for how an XWT engine should
       behave.
 
+
 ______________________________________________________________________________
 Directory Structure
 
 /       
 ______________________________________________________________________________
 Directory Structure
 
 /       
-   AUTHORS                - people involved in developing XWT   
-   README                 - this file
-   COPYING                - copyright information for all files in this distro
-   TM                     - trademark information for XWT       
-   Makefile               - build file for gcc 3.3
-   next.build             - the build id of the next build to be generated
-   bin/                   - all binary stuff generated by xwt builds    
-   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
-   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
+   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)
+         mips/              - mips binaries (interpreted on all platforms)
+         JVM/               - java Jar archives
+         Linux/             - Linux binaries
+         Win32/             - Win32 binaries
+         Darwin/            - Darwin binaries
+         Solaris/           - Solaris binaries
+
+   Makefile.upstream        - build/download/install instructions for upstream packages
+   upstream/                - download, build, and install area for upstream packages
+            install/        - this is the --prefix for all configure invocations
+            gcc-3.3/        - build/download area for gcc
+            jpeg-6b/        - build/download area for libjpeg
+            freetype-2.1.4/ - build/download area for freetype
+            newlib-1.11.0/  - build/download area for newlib
+            darwin-linker/  - build/download area for a hacked version of Apple's binutils
+
+   lib/                     - any third-party binary stuff needed during the build process
+       javago               - a copy of the javago post-compilation bytecode inliner
+       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
+       edu/stanford/ejalbr  - source code for BrowserLauncher
+       gnu/regexp/          - source code for the GNU regexp library for Java
        org/
        org/
-           bouncycastle/  - the BouncyCastle Crypto Library
-           mozilla/       - a copy of Rhino, the Mozilla JavaScript interpreter
-           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
+           bouncycastle/    - the BouncyCastle Crypto Library
+           xwt/
+               translators/ - .xwt's and .png's that are essential to bootstrapping the engine
+               plat/        - platform-specific code
+               util/        - misc utilities
+               js/          - the XWT JavaScript Interpreter
+               mips/        - the XWT MIPS interpreter/recompiler
+               builtin/     - content for the core builtin resource
 
 
 ______________________________________________________________________________
 
 
 ______________________________________________________________________________
-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
+
+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.
+
+Requirements:
+    - jdk 1.3+
+    - the standard set of POSIX utilities (wc, grep, find, make, etc)
+
+Build Targets:
+    - compile: compiles all .java files into build/class/
+    - JVM:     Any true Java JVM (ie not GCJ)
+    - Win32:   Win95 OSR2 or later
+    - Linux:   Linux 2.2 or later
+    - Darwin:  Any Darwin-based OS (Mac OS X, OpenDarwin)
+    - Solaris: Solaris 2.7+
+    - clean:   always run this after doing a 'cvs update'