README

   1 ==============================================================================
   2 XWT README
   3
   4 ______________________________________________________________________________
   5 Documentation
   6
   7 If you're new to XWT, you should read the documentation in the order
   8 presented below:
   9
  10 - README [this file]
  11
  12       Start here. Includes a map of all other documentation and a
  13       description of the directory strucure
  14
  15 - The XWT home page [http://www.xwt.org/]
  16
  17 - The XWT tutorial [http://www.xwt.org/tutorial.html]
  18
  19       Gentle introduction to what XWT is, and how to write
  20       .xwt's. Good for anybody who wants to write XWT applications.
  21
  22 - The XWT reference [http://www.xwt.org/reference.html]
  23
  24       Precise, technical spec of exactly how XWT works. Assumes
  25       familiarity with XWT (ie, you've read the tutorial). This is the
  26       authoritative source for how an XWT engine should
  27       behave.
  28
  29 - Javadoc [http://www.xwt.org/javadoc/]
  30
  31       The org.xwt.* packages are all documented with javadoc. You
  32       should start by reading the package summary for org.xwt.Main,
  33       and work your way around from there.
  34
  35 - Javasrc [http://www.xwt.org/javasrc]
  36
  37       Javasrc generates a syntax-colored and hyperlinked html copy of
  38       the XWT source code.
  39
  40
  41 ______________________________________________________________________________
  42 Directory Structure
  43
  44 /
  45    AUTHORS               - people involved in developing XWT
  46    README                - this file
  47    COPYING               - copyright information for all files in this distro
  48    TM                    - trademark information for XWT
  49    ant                   - a unix shell script to launch ant
  50    bin/                  - all binary stuff generated by ant builds
  51    build.xml             - ANT build file
  52
  53    lib/                  - any third-party binary stuff needed during the build process
  54        javago            - a copy of the javago post-compilation bytecode inliner
  55        ant.jar           - the Jakarta project's ANT build tool, including Sun's XML parser
  56        netscape.jar      - minimal set of classes required for compiling against Netcape's Applet interfaces
  57        msjvm.jar         - minimal set of classes required for compiling against Microsoft's Applet interfaces
  58        javasrc.jar       - javasrc, a tool for generating hyperlinked, syntax-colored html from java code
  59
  60    src/                  - all java source files and xwt sources go here
  61        org/
  62            bouncycastle/ - the BouncyCastle Crypto Library
  63            mozilla/      - a copy of Rhino, the Mozilla JavaScript interpreter
  64            xwt/builtin/  - .xwt's and .png's that are essential to bootstrapping the engine
  65            xwt/plat/     - platform-specific code
  66
  67 ______________________________________________________________________________
  68 Build Targets
  69
  70         *** XWT now requires JDK 1.4 or later to build ***
  71
  72 To build, make sure your $JAVA_HOME points to jdk1.4 or later, and type
  73
  74     ./ant -Dplat=<platform> <targetname>
  75
  76 The name of any class in org.xwt.plat is a valid <platform>; here is a
  77 list as of 20-Mar-2002:
  78
  79     Win32         - Windows 95 / NT4 or later
  80     Java12        - Any Java 1.2+ compliant JVM
  81
  82 Valid <target>s are:
  83
  84     build         - builds a binary for the selected platform
  85
  86 The following targets do not require that you specify a platform:
  87
  88     compile       - compiles all .java's to .class'es
  89     clean         - empties bin/ and compiled binaries in dist/
  90
  91
  92 ______________________________________________________________________________
  93 Building
  94
  95 - WARNING: Jikes 1.16 has a bug which will cause it to generate
  96   corrupt .class files; you must downgrade to 1.15 in order to compile
  97   XWT.
  98
  99 - If you only want to build the JVM version of XWT, delete these three
 100   files:
 101
 102     xwt/src/org/xwt/plat/Win32.java
 103     xwt/src/org/xwt/plat/POSIX.java
 104     xwt/src/org/xwt/plat/GCJ.java
 105
 106   This will allow XWT to build correctly *without* gcc 3.1. Otherwise,
 107   you must compile and install gcc 3.1.
 108
 109
 110 - The Win32 native version of XWT can ONLY be built with the very
 111   latest pre-release of GCC 3.3. You can follow the steps below to
 112   create a cross-compiler from linux to Win32.
 113
 114   If the steps below fail, try adding "-D 11-Oct-2002" to the cvs
 115   checkout line; 11-Oct-2002 was the last date on which the compiler
 116   was known to work. Please don't do this unless you have attempted
 117   without it, however, since it puts additional strain on the gcc cvs
 118   server.
 119
 120   There are also three patches at the end of this file which can be
 121   applied to the branch -- the first fixes an inet_addr() bug on
 122   Win32, the second fixes a garbage collector bug, and the third
 123   enables stack traces.
 124
 125   # create an install area
 126   export CLASSPATH=
 127   export PREFIX=/usr/local/gcc
 128   export CC=/usr/bin/gcc
 129
 130   sudo rm -rf $PREFIX
 131   export PATH=$PATH:$PREFIX/bin
 132   sudo mkdir $PREFIX
 133   sudo mkdir $PREFIX/i686-pc-mingw32/
 134
 135   wget http://telia.dl.sourceforge.net/sourceforge/mingw/MinGW-1.1.tar.gz
 136   sudo tar -C $PREFIX/i686-pc-mingw32/ -xvzf MinGW-1.1.tar.gz
 137
 138   wget ftp://ftp.gnu.org/gnu/binutils/binutils-2.11.2.tar.gz
 139   tar xzvf binutils-2.11.2.tar.gz
 140   cd binutils-2.11.2
 141   ./configure --target=i686-pc-mingw32 --prefix=$PREFIX
 142   make
 143   sudo make install
 144   cd ..
 145
 146   cvs -d :pserver:anoncvs@subversions.gnu.org:/cvsroot/gcc co -rgcc-3_1-branch gcc
 147   mkdir bin
 148   cd bin
 149   ../gcc/configure \
 150                    --prefix=$PREFIX \
 151                    --target=i686-pc-mingw32 \
 152                    --host=i686-pc-linux-gnu \
 153                    --enable-languages=c,c++,java \
 154                    --disable-nls \
 155                    --with-as=$PREFIX/i686-pc-mingw32/bin/as \
 156                    --with-ld=$PREFIX/i686-pc-mingw32/bin/ld \
 157                    --with-gnu-ld \
 158                    --with-gnu-as \
 159                    --enable-libgcj \
 160                    --enable-gc-type=boehm \
 161                    --disable-shared \
 162                    --enable-threads=win32 \
 163                    --enable-hash-synchronization \
 164                    --disable-interpreter \
 165                    --enable-sjlj-exceptions
 166
 167   make
 168   sudo make install
 169
 170 - The Linux native version can also be built with the latest
 171   prerelease of gcj 3.3. You should configure your compiler with:
 172
 173   ../gcc/configure \
 174                    --prefix=$PREFIX \
 175                    --enable-languages=c,c++,java \
 176                    --disable-nls \
 177                    --enable-libgcj \
 178                    --enable-threads=posix \
 179                    --enable-hash-synchronization \
 180                    --enable-static \
 181                    --disable-interpreter
 182
 183
 184 ______________________________________________________________________________
 185 Native-Code "ant"
 186
 187 ** THIS DOESN'T WORK YET **
 188
 189 Ant takes a long time to start up, mainly because it has to load a
 190 JVM. If you compile ant to native code using GCJ, it will load much
 191 more quickly. So far, this only works on Linux.
 192
 193     mkdir /tmp/ant
 194     cd /tmp/ant
 195     jar xvf ~/xwt/lib/ant.jar
 196     for A in `find * -name \*.properties -or -name \*.txt -or -name \*.mf`
 197         do gcj -c --resource $A $A -o $A.o
 198     done
 199     CLASSPATH= gcj --main=org.apache.tools.ant.Main \
 200                `find . -name \*.class -or -name \*.o` -o ant
 201     mv ant ~/xwt/ant
 202
 203
 204 ______________________________________________________________________________
 205 inet_addr patch
 206
 207 Index: java/net/natInetAddress.cc
 208 ===================================================================
 209 RCS file: /cvs/gcc/gcc/libjava/java/net/natInetAddress.cc,v
 210 retrieving revision 1.18.18.1
 211 diff -u -r1.18.18.1 natInetAddress.cc
 212 --- java/net/natInetAddress.cc  4 Mar 2002 20:02:19 -0000       1.18.18.1
 213 +++ java/net/natInetAddress.cc  27 May 2002 22:54:40 -0000
 214 @@ -9,6 +9,7 @@
 215  details.  */
 216
 217  #include <config.h>
 218 +#include <platform.h>
 219
 220  #ifdef WIN32
 221
 222 Index: include/win32.h
 223 ===================================================================
 224 RCS file: /cvs/gcc/gcc/libjava/include/win32.h,v
 225 retrieving revision 1.3.8.5
 226 diff -u -r1.3.8.5 win32.h
 227 --- include/win32.h     24 Apr 2002 01:04:45 -0000      1.3.8.5
 228 +++ include/win32.h     27 May 2002 22:54:40 -0000
 229 @@ -35,4 +35,8 @@
 230     ARRAY and return the exact number of values stored.  */
 231  extern int backtrace (void **__array, int __size);
 232
 233 +// configure cannot correctly detect inet_addr due to Win32's
 234 +// oddball header naming scheme
 235 +#define HAVE_INET_ADDR
 236 +
 237  #endif /* __JV_WIN32_H__ */
 238
 239
 240
 241 ______________________________________________________________________________
 242 GC patch
 243
 244 Index: win32_threads.c
 245 ===================================================================
 246 RCS file: /cvs/gcc/gcc/boehm-gc/win32_threads.c,v
 247 retrieving revision 1.9.2.2
 248 diff -u -r1.9.2.2 win32_threads.c
 249 --- win32_threads.c     29 Jun 2002 17:29:51 -0000      1.9.2.2
 250 +++ win32_threads.c     2 Jul 2002 18:10:02 -0000
 251 @@ -134,10 +134,7 @@
 252                                 (LPCONTEXT)&thread_table[i].context))
 253           ABORT("GetThreadContext failed");
 254  #      ifdef I386
 255 -         if (thread_table[i].context.Esp >= (DWORD)thread_table[i].stack
 256 -             || thread_table[i].context.Esp < (DWORD)bottom)
 257 -             ABORT("Thread stack pointer out of range");
 258 -         GC_push_one ((word) thread_table[i].context.Edi);
 259 +             GC_push_one ((word) thread_table[i].context.Edi);
 260           GC_push_one ((word) thread_table[i].context.Esi);
 261           GC_push_one ((word) thread_table[i].context.Ebp);
 262           GC_push_one ((word) thread_table[i].context.Ebx);
 263
 264
 265
 266 ______________________________________________________________________________
 267 Throwable.printStackTrace() patch
 268
 269 Index: Class.h
 270 ===================================================================
 271 RCS file: /cvs/gcc/gcc/libjava/java/lang/Class.h,v
 272 retrieving revision 1.43
 273 diff -u -r1.43 Class.h
 274 --- Class.h     21 Dec 2001 19:47:50 -0000      1.43
 275 +++ Class.h     24 Apr 2002 03:06:14 -0000
 276 @@ -308,6 +308,7 @@
 277    friend void _Jv_LayoutVTableMethods (jclass klass);
 278    friend void _Jv_SetVTableEntries (jclass, _Jv_VTable *);
 279    friend void _Jv_MakeVTable (jclass);
 280 +  friend JArray<java::lang::reflect::Method*>* _Jv_GetAllMethods();
 281
 282    // Return array class corresponding to element type KLASS, creating it if
 283    // necessary.
 284 Index: ClassLoader.java
 285 ===================================================================
 286 RCS file: /cvs/gcc/gcc/libjava/java/lang/ClassLoader.java,v
 287 retrieving revision 1.16
 288 diff -u -r1.16 ClassLoader.java
 289 --- ClassLoader.java    7 Dec 2001 23:34:12 -0000       1.16
 290 +++ ClassLoader.java    24 Apr 2002 03:06:14 -0000
 291 @@ -577,4 +577,8 @@
 292      // Default to returning null.  Derived classes implement this.
 293      return null;
 294    }
 295 +
 296 +  static native java.lang.reflect.Method[] getAllMethods();
 297 +  static native long[] getAllMethodAddrs();
 298 +
 299  }
 300 Index: Throwable.java
 301 ===================================================================
 302 RCS file: /cvs/gcc/gcc/libjava/java/lang/Throwable.java,v
 303 retrieving revision 1.10
 304 diff -u -r1.10 Throwable.java
 305 --- Throwable.java      24 Feb 2001 03:52:49 -0000      1.10
 306 +++ Throwable.java      24 Apr 2002 03:06:14 -0000
 307 @@ -123,21 +123,64 @@
 308      printStackTrace (writer);
 309    }
 310
 311 +  private native static long longFromStackTraceBytes(byte[] stackTrace, int i);
 312 +
 313    public void printStackTrace (PrintWriter wr)
 314    {
 315 -    try
 316 -      {
 317 -       CPlusPlusDemangler cPlusPlusFilter = new CPlusPlusDemangler (wr);
 318 -       PrintWriter writer = new PrintWriter (cPlusPlusFilter);
 319 -       printRawStackTrace (writer);
 320 -       writer.close ();
 321 -       if (cPlusPlusFilter.written == 0) // The demangler has failed...
 322 -         printRawStackTrace (wr);
 323 +      try
 324 +          {
 325 +              CPlusPlusDemangler cPlusPlusFilter = new CPlusPlusDemangler (wr);
 326 +              PrintWriter writer = new PrintWriter (cPlusPlusFilter);
 327 +              printRawStackTrace (writer);
 328 +              writer.close ();
 329 +              if (cPlusPlusFilter.written > 0) return;
 330 +          }
 331 +      catch (Exception e1)
 332 +          {
 333 +          }
 334 +
 335 +      wr.println(toString());
 336 +      if (stackTrace == null) {
 337 +          wr.flush();
 338 +          return;
 339        }
 340 -    catch (Exception e1)
 341 -      {
 342 -       printRawStackTrace (wr);
 343 +
 344 +      long[] allAddrs = ClassLoader.getAllMethodAddrs();
 345 +      java.lang.reflect.Method[] meths = ClassLoader.getAllMethods();
 346 +
 347 +      // FIXME: assumes little endian
 348 +      for(int i=0; i<stackTrace.length; i++) {
 349 +          long addr = longFromStackTraceBytes(stackTrace, i);
 350 +          if (addr == 0) break;
 351 +
 352 +          int whichMethod = -1;
 353 +          for(int j=0; j<allAddrs.length; j++) {
 354 +              if (allAddrs[j] <= addr &&
 355 +                  (whichMethod == -1 || allAddrs[whichMethod] < allAddrs[j])) {
 356 +                  whichMethod = j;
 357 +              }
 358 +          }
 359 +
 360 +          if (whichMethod == -1) {
 361 +              wr.println("[" + Long.toString(addr, 16) + "]  " + "??");
 362 +              continue;
 363 +          }
 364 +
 365 +          if (meths[whichMethod].getDeclaringClass().getName().equals("gnu.gcj.runtime.FirstThread") &&
 366 +              meths[whichMethod].getName().equals("call_main"))
 367 +              break;
 368 +
 369 +          wr.println("    [" + Long.toString(addr, 16) + "] " +
 370 +                     meths[whichMethod].getDeclaringClass().getName() + "." +
 371 +                     meths[whichMethod].getName() + "() " +
 372 +                     "+" + (addr - allAddrs[whichMethod])
 373 +                     );
 374 +
 375 +          if (java.lang.Thread.class.isAssignableFrom(meths[whichMethod].getDeclaringClass()) &&
 376 +              meths[whichMethod].getName().equals("run"))
 377 +              break;
 378        }
 379 +      wr.flush();
 380    }
 381
 382    public Throwable ()
 383 Index: natClassLoader.cc
 384 ===================================================================
 385 RCS file: /cvs/gcc/gcc/libjava/java/lang/natClassLoader.cc,v
 386 retrieving revision 1.47.8.1
 387 diff -u -r1.47.8.1 natClassLoader.cc
 388 --- natClassLoader.cc   2 Apr 2002 22:19:55 -0000       1.47.8.1
 389 +++ natClassLoader.cc   24 Apr 2002 03:06:14 -0000
 390 @@ -40,6 +40,10 @@
 391  #include <java/lang/StringBuffer.h>
 392  #include <java/io/Serializable.h>
 393  #include <java/lang/Cloneable.h>
 394 +#include <java/lang/reflect/Method.h>
 395 +
 396 +#include<java/lang/reflect/Constructor.h>
 397 +#include<gcj/method.h>
 398
 399  // FIXME: remove these.
 400  #define CloneableClass java::lang::Cloneable::class$
 401 @@ -347,6 +351,50 @@
 402  static jclass loaded_classes[HASH_LEN];
 403
 404  // This is the root of a linked list of classes
 405 +
 406 +JArray<java::lang::reflect::Method*>*
 407 +java::lang::ClassLoader::getAllMethods()
 408 +{
 409 +    return _Jv_GetAllMethods();
 410 +}
 411 +
 412 +JArray<jlong>*
 413 +java::lang::ClassLoader::getAllMethodAddrs()
 414 +{
 415 +    JArray<java::lang::reflect::Method*>* arr = _Jv_GetAllMethods();
 416 +    java::lang::reflect::Method** el = (java::lang::reflect::Method**)elements(arr);
 417 +    JArray<jlong>* ret = JvNewLongArray(arr->length);
 418 +    jlong* retel = (jlong*)elements(ret);
 419 +    for(int i=0; i<arr->length; i++)
 420 +        retel[i] = (jlong)((unsigned int)(_Jv_FromReflectedMethod (el[i])->ncode));
 421 +    return ret;
 422 +}
 423 +
 424 +JArray<java::lang::reflect::Method*>*
 425 +_Jv_GetAllMethods()
 426 +{
 427 +  int numMethods = 0;
 428 +
 429 +  for(int i=0; i<HASH_LEN; i++)
 430 +      for(jclass c = loaded_classes[i]; c; c = c->next)
 431 +          numMethods += c->getDeclaredMethods()->length;
 432 +
 433 +  JArray<java::lang::reflect::Method*>* ret =
 434 +    (JArray<java::lang::reflect::Method*>*)
 435 +    JvNewObjectArray(numMethods, &java::lang::reflect::Method::class$, NULL);
 436 +
 437 +  java::lang::reflect::Method** el = (java::lang::reflect::Method**)elements(ret);
 438 +
 439 +  for(int i=0; i<HASH_LEN; i++)
 440 +      for(jclass c = loaded_classes[i]; c; c = c->next) {
 441 +          JArray<java::lang::reflect::Method*>* methods = c->getDeclaredMethods();
 442 +          jint len = methods->length;
 443 +          java::lang::reflect::Method** meths = (java::lang::reflect::Method**)elements(methods);
 444 +          for(int j=0; j<len; j++) el[--numMethods] = meths[j];
 445 +      }
 446 +
 447 +  return ret;
 448 +}
 449
 450  \f
 451
 452 Index: natThrowable.cc
 453 ===================================================================
 454 RCS file: /cvs/gcc/gcc/libjava/java/lang/natThrowable.cc,v
 455 retrieving revision 1.11
 456 diff -u -r1.11 natThrowable.cc
 457 --- natThrowable.cc     7 Feb 2002 19:26:06 -0000       1.11
 458 +++ natThrowable.cc     24 Apr 2002 03:06:14 -0000
 459 @@ -32,6 +32,7 @@
 460  #include <stdio.h>
 461
 462  #include <unistd.h>
 463 +#include <platform.h>
 464
 465  #ifdef HAVE_EXECINFO_H
 466  #include <execinfo.h>
 467 @@ -102,3 +103,18 @@
 468  #endif /* HAVE_BACKTRACE */
 469    wr->flush ();
 470  }
 471 +
 472 +// Returns the i^th call address in the stackTrace member, or 0 if i
 473 +// is beyond the end of the trace. This has to be done in C++ because
 474 +// the addresses in stackTrace are the same width as the platform's
 475 +// pointers (which is unknown to Java code), and stackTrace is a
 476 +// byte[] using the platform's endianness (which is unknown to Java
 477 +// code).
 478 +jlong
 479 +java::lang::Throwable::longFromStackTraceBytes(jbyteArray stackArr, jint i)
 480 +{
 481 +    if (i * sizeof(void*) > stackArr->length) return 0;
 482 +    unsigned int* stack = (unsigned int*)elements(stackArr);
 483 +    return (jlong)stack[i];
 484 +}
 485 +
 486
 487
 488
 489
 490