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