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