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    README                - this file
  46    COPYING               - copyright information for all files in this distro
  47    TM                    - trademark information for XWT
  48    ant                   - a unix shell script to launch ant
  49    bin/                  - all binary stuff generated by ant builds
  50    build.xml             - ANT build file
  51
  52    lib/                  - any third-party binary stuff needed during the build process
  53        javago            - a copy of the javago post-compilation bytecode inliner
  54        ant.jar           - the Jakarta project's ANT build tool, including Sun's XML parser
  55        netscape.jar      - minimal set of classes required for compiling against Netcape's Applet interfaces
  56        msjvm.jar         - minimal set of classes required for compiling against Microsoft's Applet interfaces
  57        signtool          - the Netscape Object Signing tool, for signing applets
  58        signcode.exe      - the Microsoft ActiveX Signing tool, for signing ActiveX controls
  59        guidgen.exe       - the Microsoft GUID generator, for generating OLE clsid's
  60        cabarc.exe        - the Microsoft CAB file generator, for creating .cab archives
  61        javasrc.jar       - javasrc, a tool for generating hyperlinked, syntax-colored html from java code
  62
  63    src/                  - all java source files and xwt sources go here
  64        jazz/             - jazzlib, which XWT currently uses since libgcj's java.util.zip.* is broken
  65
  66        org/
  67            bouncycastle/ - the BouncyCastle Crypto Library
  68            gimp/tigert/  - some icons used in XWT Mail, by Tigert Labs
  69            mozilla/      - a copy of Rhino, the Mozilla JavaScript interpreter
  70
  71            xwt/          - the source code for the XWT engine
  72                demo/     - the XWT widget sampler
  73                chess/    - XWT Chess
  74                fonts/    - some XWF fonts
  75                mail/     - XWT Mail
  76                plat/     - platform abstraction classes for XWT
  77                tasks/    - source code for some ANT tasks used in the XWT build process
  78                themes/   - some XWT themes
  79                util/     - some helper classes
  80
  81        xwt/standard/     - the XWT standard library
  82
  83
  84
  85 ______________________________________________________________________________
  86 Build Targets
  87
  88 To build, make sure your $JAVA_HOME points to jdk1.2 or later, and type
  89
  90     ./ant -Dplat=<platform> <targetname>
  91
  92 If you're using jdk1.2 or jdk1.3 to compile, you should remove
  93 src/org/xwt/plat/Java14.java, since it can only be compiled with
  94 jdk1.4+.
  95
  96 The name of any class in org.xwt.plat is a valid <platform>; here is a
  97 list as of 20-Mar-2002:
  98
  99     Win32         - Windows 95 / NT4 or later
 100     Java2         - Any Java 1.2+ compliant JVM
 101
 102 Valid <target>s are:
 103
 104     build         - builds a binary for the selected platform
 105
 106 The following targets do not require that you specify a platform:
 107
 108     compile       - compiles all .java's to .class'es
 109     clean         - empties bin/ and compiled binaries in dist/
 110
 111
 112 ______________________________________________________________________________
 113 Building
 114
 115 - If you only want to build the JVM version of XWT, delete these two
 116   files:
 117
 118     xwt/src/org/xwt/plat/Win32.java
 119     xwt/src/org/xwt/plat/GCJ.java
 120
 121   This will allow XWT to build correctly *without* gcc 3.1. Otherwise,
 122   you must compile and install gcc 3.1.
 123
 124
 125 - The Win32 native version of XWT can ONLY be built with the very
 126   latest pre-release of GCC 3.1. You can follow the steps below to
 127   create a cross-compiler from linux to Win32.
 128
 129   If the steps below fail, try adding "-D 20-Mar-2002" to the cvs
 130   checkout line; 20-Mar-2002 was the last date on which the compiler
 131   was known to work. Please don't do this unless you have attempted
 132   without it, however, since it puts additional strain on the gcc cvs
 133   server.
 134
 135   There are also three patches at the end of this file which can be
 136   applied to the branch -- the first fixes a bug related to
 137   GetFullPathName, the second disables Win32 file locking (so you can
 138   view XWT's log files while it is running), and the third makes
 139   Throwable.printStackTrace() work.
 140
 141   # create an install area
 142   export CLASSPATH=
 143   export PREFIX=/usr/local/gcc
 144   export CC=/usr/bin/gcc
 145
 146   sudo rm -rf $PREFIX
 147   export PATH=$PATH:$PREFIX/bin
 148   sudo mkdir $PREFIX
 149   sudo mkdir $PREFIX/i686-pc-mingw32/
 150
 151   wget http://prdownloads.sourceforge.net/mingw/MinGW-1.1.tar.gz
 152   sudo tar -C $PREFIX/i686-pc-mingw32/ -xvzf ~/mingw-gcj/MinGW-1.1.tar.gz
 153
 154   wget ftp://ftp.gnu.org/gnu/binutils/binutils-2.11.2.tar.gz
 155   tar xzvf binutils-2.11.2.tar.gz
 156   cd binutils-2.11.2
 157   ./configure --target=i686-pc-mingw32 --prefix=$PREFIX
 158   make
 159   sudo make install
 160   cd ..
 161
 162   cvs -d :pserver:anoncvs@subversions.gnu.org:/cvsroot/gcc co -rgcc-3_1-branch gcc
 163   mkdir bin
 164   cd bin
 165   ../gcc/configure \
 166                    --prefix=$PREFIX \
 167                    --target=i686-pc-mingw32 \
 168                    --host=i686-pc-linux-gnu \
 169                    --enable-languages=c,c++,java \
 170                    --disable-nls \
 171                    --with-as=$PREFIX/i686-pc-mingw32/bin/as \
 172                    --with-ld=$PREFIX/i686-pc-mingw32/bin/ld \
 173                    --with-gnu-ld \
 174                    --with-gnu-as \
 175                    --enable-libgcj \
 176                    --enable-gc-type=boehm \
 177                    --disable-shared \
 178                    --enable-threads=win32 \
 179                    --disable-hash-synchronization \
 180                    --disable-interpreter \
 181                    --enable-sjlj-exceptions
 182
 183   make
 184   sudo make install
 185
 186 - The Linux native version is still experimental. You should configure
 187   your compiler with:
 188
 189   ../gcc/configure \
 190                    --prefix=$PREFIX \
 191                    --enable-languages=c,c++,java \
 192                    --disable-nls \
 193                    --enable-libgcj \
 194                    --enable-threads=posix \
 195                    --enable-hash-synchronization \
 196                    --enable-static \
 197                    --disable-interpreter
 198
 199
 200 ______________________________________________________________________________
 201 GetFullPathName patch
 202
 203 Index: natFileWin32.cc
 204 ===================================================================
 205 RCS file: /cvs/gcc/gcc/libjava/java/io/natFileWin32.cc,v
 206 retrieving revision 1.9.2.1
 207 diff -u -r1.9.2.1 natFileWin32.cc
 208 --- natFileWin32.cc 16 Apr 2002 15:35:20 -0000  1.9.2.1
 209 +++ natFileWin32.cc 14 May 2002 01:57:39 -0000
 210 @@ -106,7 +106,7 @@
 211    LPTSTR unused;
 212    char buf2[MAX_PATH];
 213    if(!GetFullPathName(buf, MAX_PATH, buf2, &unused))
 214 -    throw new IOException (JvNewStringLatin1 ("GetFullPathName failed"));
 215 +    return NULL;
 216
 217    // FIXME: what encoding to assume for file names?  This affects many
 218    // calls.
 219
 220
 221 ______________________________________________________________________________
 222 File Locking Patch
 223
 224 Index: java/io/natFileDescriptorWin32.cc
 225 ===================================================================
 226 RCS file: /cvs/gcc/gcc/libjava/java/io/natFileDescriptorWin32.cc,v
 227 retrieving revision 1.5.2.2
 228 diff -u -r1.5.2.2 natFileDescriptorWin32.cc
 229 --- java/io/natFileDescriptorWin32.cc   10 Mar 2002 03:34:59 -0000  1.5.2.2
 230 +++ java/io/natFileDescriptorWin32.cc   27 Apr 2002 08:40:40 -0000
 231 @@ -112,7 +112,7 @@
 232          create = CREATE_ALWAYS;
 233      }
 234
 235 -  handle = CreateFile(buf, access, share, NULL, create, 0, NULL);
 236 +  handle = CreateFile(buf, access, FILE_SHARE_READ | FILE_SHARE_WRITE, NULL, create, 0, NULL);
 237
 238    if (handle == INVALID_HANDLE_VALUE)
 239      {
 240
 241
 242
 243 ______________________________________________________________________________
 244 Throwable.printStackTrace() patch
 245
 246 Index: Class.h
 247 ===================================================================
 248 RCS file: /cvs/gcc/gcc/libjava/java/lang/Class.h,v
 249 retrieving revision 1.43
 250 diff -u -r1.43 Class.h
 251 --- Class.h     21 Dec 2001 19:47:50 -0000      1.43
 252 +++ Class.h     24 Apr 2002 03:06:14 -0000
 253 @@ -308,6 +308,7 @@
 254    friend void _Jv_LayoutVTableMethods (jclass klass);
 255    friend void _Jv_SetVTableEntries (jclass, _Jv_VTable *);
 256    friend void _Jv_MakeVTable (jclass);
 257 +  friend JArray<java::lang::reflect::Method*>* _Jv_GetAllMethods();
 258
 259    // Return array class corresponding to element type KLASS, creating it if
 260    // necessary.
 261 Index: ClassLoader.java
 262 ===================================================================
 263 RCS file: /cvs/gcc/gcc/libjava/java/lang/ClassLoader.java,v
 264 retrieving revision 1.16
 265 diff -u -r1.16 ClassLoader.java
 266 --- ClassLoader.java    7 Dec 2001 23:34:12 -0000       1.16
 267 +++ ClassLoader.java    24 Apr 2002 03:06:14 -0000
 268 @@ -577,4 +577,8 @@
 269      // Default to returning null.  Derived classes implement this.
 270      return null;
 271    }
 272 +
 273 +  static native java.lang.reflect.Method[] getAllMethods();
 274 +  static native long[] getAllMethodAddrs();
 275 +
 276  }
 277 Index: Throwable.java
 278 ===================================================================
 279 RCS file: /cvs/gcc/gcc/libjava/java/lang/Throwable.java,v
 280 retrieving revision 1.10
 281 diff -u -r1.10 Throwable.java
 282 --- Throwable.java      24 Feb 2001 03:52:49 -0000      1.10
 283 +++ Throwable.java      24 Apr 2002 03:06:14 -0000
 284 @@ -123,21 +123,64 @@
 285      printStackTrace (writer);
 286    }
 287
 288 +  private native static long longFromStackTraceBytes(byte[] stackTrace, int i);
 289 +
 290    public void printStackTrace (PrintWriter wr)
 291    {
 292 -    try
 293 -      {
 294 -       CPlusPlusDemangler cPlusPlusFilter = new CPlusPlusDemangler (wr);
 295 -       PrintWriter writer = new PrintWriter (cPlusPlusFilter);
 296 -       printRawStackTrace (writer);
 297 -       writer.close ();
 298 -       if (cPlusPlusFilter.written == 0) // The demangler has failed...
 299 -         printRawStackTrace (wr);
 300 +      try
 301 +          {
 302 +              CPlusPlusDemangler cPlusPlusFilter = new CPlusPlusDemangler (wr);
 303 +              PrintWriter writer = new PrintWriter (cPlusPlusFilter);
 304 +              printRawStackTrace (writer);
 305 +              writer.close ();
 306 +              if (cPlusPlusFilter.written > 0) return;
 307 +          }
 308 +      catch (Exception e1)
 309 +          {
 310 +          }
 311 +
 312 +      wr.println(toString());
 313 +      if (stackTrace == null) {
 314 +          wr.flush();
 315 +          return;
 316        }
 317 -    catch (Exception e1)
 318 -      {
 319 -       printRawStackTrace (wr);
 320 +
 321 +      long[] allAddrs = ClassLoader.getAllMethodAddrs();
 322 +      java.lang.reflect.Method[] meths = ClassLoader.getAllMethods();
 323 +
 324 +      // FIXME: assumes little endian
 325 +      for(int i=0; i<stackTrace.length; i++) {
 326 +          long addr = longFromStackTraceBytes(stackTrace, i);
 327 +          if (addr == 0) break;
 328 +
 329 +          int whichMethod = -1;
 330 +          for(int j=0; j<allAddrs.length; j++) {
 331 +              if (allAddrs[j] <= addr &&
 332 +                  (whichMethod == -1 || allAddrs[whichMethod] < allAddrs[j])) {
 333 +                  whichMethod = j;
 334 +              }
 335 +          }
 336 +
 337 +          if (whichMethod == -1) {
 338 +              wr.println("[" + Long.toString(addr, 16) + "]  " + "??");
 339 +              continue;
 340 +          }
 341 +
 342 +          if (meths[whichMethod].getDeclaringClass().getName().equals("gnu.gcj.runtime.FirstThread") &&
 343 +              meths[whichMethod].getName().equals("call_main"))
 344 +              break;
 345 +
 346 +          wr.println("    [" + Long.toString(addr, 16) + "] " +
 347 +                     meths[whichMethod].getDeclaringClass().getName() + "." +
 348 +                     meths[whichMethod].getName() + "() " +
 349 +                     "+" + (addr - allAddrs[whichMethod])
 350 +                     );
 351 +
 352 +          if (java.lang.Thread.class.isAssignableFrom(meths[whichMethod].getDeclaringClass()) &&
 353 +              meths[whichMethod].getName().equals("run"))
 354 +              break;
 355        }
 356 +      wr.flush();
 357    }
 358
 359    public Throwable ()
 360 Index: natClassLoader.cc
 361 ===================================================================
 362 RCS file: /cvs/gcc/gcc/libjava/java/lang/natClassLoader.cc,v
 363 retrieving revision 1.47.8.1
 364 diff -u -r1.47.8.1 natClassLoader.cc
 365 --- natClassLoader.cc   2 Apr 2002 22:19:55 -0000       1.47.8.1
 366 +++ natClassLoader.cc   24 Apr 2002 03:06:14 -0000
 367 @@ -40,6 +40,10 @@
 368  #include <java/lang/StringBuffer.h>
 369  #include <java/io/Serializable.h>
 370  #include <java/lang/Cloneable.h>
 371 +#include <java/lang/reflect/Method.h>
 372 +
 373 +#include<java/lang/reflect/Constructor.h>
 374 +#include<gcj/method.h>
 375
 376  // FIXME: remove these.
 377  #define CloneableClass java::lang::Cloneable::class$
 378 @@ -347,6 +351,50 @@
 379  static jclass loaded_classes[HASH_LEN];
 380
 381  // This is the root of a linked list of classes
 382 +
 383 +JArray<java::lang::reflect::Method*>*
 384 +java::lang::ClassLoader::getAllMethods()
 385 +{
 386 +    return _Jv_GetAllMethods();
 387 +}
 388 +
 389 +JArray<jlong>*
 390 +java::lang::ClassLoader::getAllMethodAddrs()
 391 +{
 392 +    JArray<java::lang::reflect::Method*>* arr = _Jv_GetAllMethods();
 393 +    java::lang::reflect::Method** el = (java::lang::reflect::Method**)elements(arr);
 394 +    JArray<jlong>* ret = JvNewLongArray(arr->length);
 395 +    jlong* retel = (jlong*)elements(ret);
 396 +    for(int i=0; i<arr->length; i++)
 397 +        retel[i] = (jlong)((unsigned int)(_Jv_FromReflectedMethod (el[i])->ncode));
 398 +    return ret;
 399 +}
 400 +
 401 +JArray<java::lang::reflect::Method*>*
 402 +_Jv_GetAllMethods()
 403 +{
 404 +  int numMethods = 0;
 405 +
 406 +  for(int i=0; i<HASH_LEN; i++)
 407 +      for(jclass c = loaded_classes[i]; c; c = c->next)
 408 +          numMethods += c->getDeclaredMethods()->length;
 409 +
 410 +  JArray<java::lang::reflect::Method*>* ret =
 411 +    (JArray<java::lang::reflect::Method*>*)
 412 +    JvNewObjectArray(numMethods, &java::lang::reflect::Method::class$, NULL);
 413 +
 414 +  java::lang::reflect::Method** el = (java::lang::reflect::Method**)elements(ret);
 415 +
 416 +  for(int i=0; i<HASH_LEN; i++)
 417 +      for(jclass c = loaded_classes[i]; c; c = c->next) {
 418 +          JArray<java::lang::reflect::Method*>* methods = c->getDeclaredMethods();
 419 +          jint len = methods->length;
 420 +          java::lang::reflect::Method** meths = (java::lang::reflect::Method**)elements(methods);
 421 +          for(int j=0; j<len; j++) el[--numMethods] = meths[j];
 422 +      }
 423 +
 424 +  return ret;
 425 +}
 426
 427  \f
 428
 429 Index: natThrowable.cc
 430 ===================================================================
 431 RCS file: /cvs/gcc/gcc/libjava/java/lang/natThrowable.cc,v
 432 retrieving revision 1.11
 433 diff -u -r1.11 natThrowable.cc
 434 --- natThrowable.cc     7 Feb 2002 19:26:06 -0000       1.11
 435 +++ natThrowable.cc     24 Apr 2002 03:06:14 -0000
 436 @@ -32,6 +32,7 @@
 437  #include <stdio.h>
 438
 439  #include <unistd.h>
 440 +#include <platform.h>
 441
 442  #ifdef HAVE_EXECINFO_H
 443  #include <execinfo.h>
 444 @@ -102,3 +103,18 @@
 445  #endif /* HAVE_BACKTRACE */
 446    wr->flush ();
 447  }
 448 +
 449 +// Returns the i^th call address in the stackTrace member, or 0 if i
 450 +// is beyond the end of the trace. This has to be done in C++ because
 451 +// the addresses in stackTrace are the same width as the platform's
 452 +// pointers (which is unknown to Java code), and stackTrace is a
 453 +// byte[] using the platform's endianness (which is unknown to Java
 454 +// code).
 455 +jlong
 456 +java::lang::Throwable::longFromStackTraceBytes(jbyteArray stackArr, jint i)
 457 +{
 458 +    if (i * sizeof(void*) > stackArr->length) return 0;
 459 +    unsigned int* stack = (unsigned int*)elements(stackArr);
 460 +    return (jlong)stack[i];
 461 +}
 462 +
 463
 464
 465
 466
 467