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