2002/08/07 03:22:58
[org.ibex.core.git] / README
diff --git a/README b/README
index deb448b..e3ca552 100644 (file)
--- a/README
+++ b/README
@@ -12,37 +12,30 @@ presented below:
       Start here. Includes a map of all other documentation and a
       description of the directory strucure
 
-- The XWT home page [www/ or http://www.xwt.org/]
+- The XWT home page [http://www.xwt.org/]
 
-      A complete copy of all static and dynamic content for
-      www.xwt.org is in the xwt/www/ directory.
-
-- The XWT tutorial [www/html/tutorial.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 [www/html/reference.html]
+- 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.
 
-- Javadoc [www/html/javadoc/package-summary.html]
+- Javadoc [http://www.xwt.org/javadoc/]
 
-      The org.xwt.* packages are all documented with javadoc. If
-      you've just checked out or downloaded a fresh copy of the XWT
-      distribution, you can generate the javadoc by typing
-      "./ant www" at the root directory of the distribution. You
+      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 [www/html/javasrc/index.html]
+- Javasrc [http://www.xwt.org/javasrc]
 
       Javasrc generates a syntax-colored and hyperlinked html copy of
-      the XWT source code. To generate this documentation, type "./ant www"
-      from the root directory of the distribution.
+      the XWT source code.
 
 
 ______________________________________________________________________________
@@ -55,14 +48,6 @@ Directory Structure
    ant                   - a unix shell script to launch ant
    bin/                  - all binary stuff generated by ant builds
    build.xml             - ANT build file
-   doc/                  - documentation
-
-   www/                  - a copy of all static and dynamic content on xwt.org
-       etc/              - configuration files
-       html/             - static content -- files ending with an underscore get
-                           prefix.html/suffix.html/tagline.html added to them
-       launch/           - code for launch.xwt.org
-       src/              - source code for servlets running on xwt.org
 
    lib/                  - any third-party binary stuff needed during the build process
        javago            - a copy of the javago post-compilation bytecode inliner
@@ -100,7 +85,9 @@ Directory Structure
 ______________________________________________________________________________
 Build Targets
 
-To build, make sure your $JAVA_HOME points to jdk1.2 or later, and type
+        *** 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>
 
@@ -108,26 +95,31 @@ 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
+    Java12        - Any Java 1.2+ compliant JVM
 
 Valid <target>s are:
 
     build         - builds a binary for the selected platform
-    dist          - creates deployment materials for the selected platform in dist/
-    run           - runs the 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/
-    www           - rebuild www/html/
-    push          - push changes to the web server via ssh (RSA auth)
 
 
+______________________________________________________________________________
+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.
 
-______________________________________________________________________________
-Building a compiler
 
 - 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
@@ -139,6 +131,9 @@ Building a compiler
   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=
@@ -150,8 +145,8 @@ Building a compiler
   sudo mkdir $PREFIX
   sudo mkdir $PREFIX/i686-pc-mingw32/
   
-  wget http://prdownloads.sourceforge.net/mingw/MinGW-1.1.tar.gz
-  sudo tar -C $PREFIX/i686-pc-mingw32/ -xvzf ~/mingw-gcj/MinGW-1.1.tar.gz
+  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
@@ -185,3 +180,299 @@ Building a compiler
   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
+
+
+______________________________________________________________________________
+Native-Code "ant"
+
+** THIS DOESN'T WORK YET **
+
+Ant takes a long time to start up, mainly because it has to load a
+JVM. If you compile ant to native code using GCJ, it will load much
+more quickly. So far, this only works on Linux.
+
+    mkdir /tmp/ant
+    cd /tmp/ant
+    jar xvf ~/xwt/lib/ant.jar
+    for A in `find * -name \*.properties -or -name \*.txt -or -name \*.mf`
+        do gcj -c --resource $A $A -o $A.o
+    done
+    CLASSPATH= gcj --main=org.apache.tools.ant.Main \
+               `find . -name \*.class -or -name \*.o` -o ant
+    mv ant ~/xwt/ant
+
+
+______________________________________________________________________________
+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];
++}
++
+
+
+
+
+