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