fix erroneous search-replace
[org.ibex.core.git] / README
diff --git a/README b/README
index dd24929..095be99 100644 (file)
--- a/README
+++ b/README
 ==============================================================================
-XWT README
-           
+Ibex README 
+
+Test
+              
 ______________________________________________________________________________
 Documentation
 
-If you're new to XWT, you should read the documentation in the order
+If you're new to Ibex, you should read the documentation in the order
 presented below:
 
 - README [this file]
-
+        
       Start here. Includes a map of all other documentation and a
       description of the directory strucure
 
-- The XWT home page [http://www.xwt.org/]
-
-- The XWT tutorial [http://www.xwt.org/tutorial.html]
+- The Ibex home page [http://www.ibex.org/]       
+          
+- The Ibex tutorials [http://www.ibex.org/tutorials.html]
 
-      Gentle introduction to what XWT is, and how to write
-      .xwt's. Good for anybody who wants to write XWT applications.
+      Gentle introduction to what Ibex is, and how to write
+      .ibex's. Good for anybody who wants to write Ibex applications.
 
-- The XWT reference [http://www.xwt.org/reference.html]
-
-      Precise, technical spec of exactly how XWT works. Assumes
-      familiarity with XWT (ie, you've read the tutorial). This is the
-      authoritative source for how an XWT engine should
+- The Ibex reference [http://www.ibex.org/reference.html]
+        
+      Precise, technical spec of exactly how Ibex works. Assumes
+      familiarity with Ibex (ie, you've read the tutorial). This is the
+      authoritative source for how an Ibex engine should
       behave.
 
 
 ______________________________________________________________________________
 Directory Structure
 
-/
-   AUTHORS               - people involved in developing XWT
-   README                - this file
-   COPYING               - copyright information for all files in this distro
-   TM                    - trademark information for XWT
-   ant                   - a unix shell script to launch ant
-   bin/                  - all binary stuff generated by ant builds
-
-   build.xml             - ANT build file
-   Makefile              - build file for gcc 3.3
-
-   lib/                  - any third-party binary stuff needed during the build process
-       javago            - a copy of the javago post-compilation bytecode inliner
-       ant.jar           - the Jakarta project's ANT build tool, including Sun's XML parser
-       netscape.jar      - minimal set of classes required for compiling against Netcape's Applet interfaces
-       msjvm.jar         - minimal set of classes required for compiling against Microsoft's Applet interfaces
-       javasrc.jar       - javasrc, a tool for generating hyperlinked, syntax-colored html from java code
-
-   src/                  - all java source files and xwt sources go here
+/       
+   AUTHORS                  - people involved in developing Ibex   
+   README                   - this file
+   COPYING                  - copyright information for all files in this distro
+   CHANGES                  - the changelot
+   TM                       - trademark information for Ibex       
+   Makefile                 - build file for gcc 3.3
+   next.build               - the build id of the next build to be generated
+
+   build/                   - anything generated by the build process winds up here
+         h/                 - header files generated by gcjh
+         java/              - auto-generated .java source files
+         class/             - java .class files
+         xwar/              - generated xwars (mainly builtin.xwar)
+         mips/              - mips binaries (interpreted on all platforms)
+         JVM/               - java Jar archives
+         Linux/             - Linux binaries
+         Win32/             - Win32 binaries
+         Darwin/            - Darwin binaries
+         Solaris/           - Solaris binaries
+
+   Makefile.upstream        - build/download/install instructions for upstream packages
+   upstream/                - download, build, and install area for upstream packages
+            install/        - this is the --prefix for all configure invocations
+            gcc-3.3/        - build/download area for gcc
+            jpeg-6b/        - build/download area for libjpeg
+            freetype-2.1.4/ - build/download area for freetype
+            newlib-1.11.0/  - build/download area for newlib
+            darwin-linker/  - build/download area for a hacked version of Apple's binutils
+
+   lib/                     - any third-party binary stuff needed during the build process
+       javago               - a copy of the javago post-compilation bytecode inliner
+       jump.jar             - the jump2 bytecode-to-palmos translator
+       libgcj-minimal.jar   - a tiny portion of libgcj.jar; allows java->bytecode compilation without gcj
+
+   src/                     - all java source files and ibex sources go here
+       edu/stanford/ejalbr  - source code for BrowserLauncher
+       gnu/regexp/          - source code for the GNU regexp library for Java
        org/
-           bouncycastle/ - the BouncyCastle Crypto Library
-           mozilla/      - a copy of Rhino, the Mozilla JavaScript interpreter
-           xwt/builtin/  - .xwt's and .png's that are essential to bootstrapping the engine
-           xwt/plat/     - platform-specific code
-
-______________________________________________________________________________
-Build Targets
-
-        *** XWT now requires JDK 1.4 or later to build ***
-
-To build, make sure your $JAVA_HOME points to jdk1.4 or later, and type
-
-    ./ant -Dplat=<platform> <targetname>
-
-The name of any class in org.xwt.plat is a valid <platform>; here is a
-list as of 20-Mar-2002:
-
-    Win32         - Windows 95 / NT4 or later
-    Java12        - Any Java 1.2+ compliant JVM
-
-Valid <target>s are:
-
-    build         - builds a binary for the selected platform
-
-The following targets do not require that you specify a platform:
-
-    compile       - compiles all .java's to .class'es
-    clean         - empties bin/ and compiled binaries in dist/
+           bouncycastle/    - the BouncyCastle Crypto Library
+           ibex/
+               translators/ - .ibex's and .png's that are essential to bootstrapping the engine
+               plat/        - platform-specific code
+               util/        - misc utilities
+               js/          - the Ibex JavaScript Interpreter
+               mips/        - the Ibex MIPS interpreter/recompiler
+               builtin/     - content for the core builtin resource
 
 
 ______________________________________________________________________________
-Building
-
-- WARNING: Jikes 1.16 has a bug which will cause it to generate
-  corrupt .class files; you must downgrade to 1.15 in order to compile
-  XWT.
-
-- If you only want to build the JVM version of XWT, delete these three
-  files:
-
-    xwt/src/org/xwt/plat/Win32.java
-    xwt/src/org/xwt/plat/POSIX.java
-    xwt/src/org/xwt/plat/GCJ.java
-
-  This will allow XWT to build correctly *without* gcc 3.1. Otherwise,
-  you must compile and install gcc 3.1.
-
-- The Win32 native version of XWT can ONLY be built with the very
-  latest pre-release of GCC 3.3.  Run "make gcc-lin" to build a gcc
-  3.3 that targets Linux; run "make gcc-win" to build a gcc 3.3 that
-  targets Win32.
-
-
-
-______________________________________________________________________________
-inet_addr patch
-
-Index: java/net/natInetAddress.cc
-===================================================================
-RCS file: /cvs/gcc/gcc/libjava/java/net/natInetAddress.cc,v
-retrieving revision 1.18.18.1
-diff -u -r1.18.18.1 natInetAddress.cc
---- java/net/natInetAddress.cc  4 Mar 2002 20:02:19 -0000       1.18.18.1
-+++ java/net/natInetAddress.cc  27 May 2002 22:54:40 -0000
-@@ -9,6 +9,7 @@
- details.  */
-
- #include <config.h>
-+#include <platform.h>
-
- #ifdef WIN32
-
-Index: include/win32.h
-===================================================================
-RCS file: /cvs/gcc/gcc/libjava/include/win32.h,v
-retrieving revision 1.3.8.5
-diff -u -r1.3.8.5 win32.h
---- include/win32.h     24 Apr 2002 01:04:45 -0000      1.3.8.5
-+++ include/win32.h     27 May 2002 22:54:40 -0000
-@@ -35,4 +35,8 @@
-    ARRAY and return the exact number of values stored.  */
- extern int backtrace (void **__array, int __size);
-
-+// configure cannot correctly detect inet_addr due to Win32's
-+// oddball header naming scheme
-+#define HAVE_INET_ADDR
-+
- #endif /* __JV_WIN32_H__ */
-
-
-
-______________________________________________________________________________
-Throwable.printStackTrace() patch
-
-Index: Class.h
-===================================================================
-RCS file: /cvs/gcc/gcc/libjava/java/lang/Class.h,v
-retrieving revision 1.43
-diff -u -r1.43 Class.h
---- Class.h    21 Dec 2001 19:47:50 -0000      1.43
-+++ Class.h    24 Apr 2002 03:06:14 -0000
-@@ -308,6 +308,7 @@
-   friend void _Jv_LayoutVTableMethods (jclass klass);
-   friend void _Jv_SetVTableEntries (jclass, _Jv_VTable *);
-   friend void _Jv_MakeVTable (jclass);
-+  friend JArray<java::lang::reflect::Method*>* _Jv_GetAllMethods();
-   // Return array class corresponding to element type KLASS, creating it if
-   // necessary.
-Index: ClassLoader.java
-===================================================================
-RCS file: /cvs/gcc/gcc/libjava/java/lang/ClassLoader.java,v
-retrieving revision 1.16
-diff -u -r1.16 ClassLoader.java
---- ClassLoader.java   7 Dec 2001 23:34:12 -0000       1.16
-+++ ClassLoader.java   24 Apr 2002 03:06:14 -0000
-@@ -577,4 +577,8 @@
-     // Default to returning null.  Derived classes implement this.
-     return null;
-   }
-+
-+  static native java.lang.reflect.Method[] getAllMethods();
-+  static native long[] getAllMethodAddrs();
-+
- }
-Index: Throwable.java
-===================================================================
-RCS file: /cvs/gcc/gcc/libjava/java/lang/Throwable.java,v
-retrieving revision 1.10
-diff -u -r1.10 Throwable.java
---- Throwable.java     24 Feb 2001 03:52:49 -0000      1.10
-+++ Throwable.java     24 Apr 2002 03:06:14 -0000
-@@ -123,21 +123,64 @@
-     printStackTrace (writer);
-   }
-+  private native static long longFromStackTraceBytes(byte[] stackTrace, int i);
-+
-   public void printStackTrace (PrintWriter wr)
-   {
--    try
--      {
--      CPlusPlusDemangler cPlusPlusFilter = new CPlusPlusDemangler (wr);
--      PrintWriter writer = new PrintWriter (cPlusPlusFilter);
--      printRawStackTrace (writer);    
--      writer.close ();
--      if (cPlusPlusFilter.written == 0) // The demangler has failed...
--        printRawStackTrace (wr);
-+      try
-+          {
-+              CPlusPlusDemangler cPlusPlusFilter = new CPlusPlusDemangler (wr);
-+              PrintWriter writer = new PrintWriter (cPlusPlusFilter);
-+              printRawStackTrace (writer);    
-+              writer.close ();
-+              if (cPlusPlusFilter.written > 0) return;
-+          }
-+      catch (Exception e1)
-+          {
-+          }
-+
-+      wr.println(toString());
-+      if (stackTrace == null) {
-+          wr.flush();
-+          return;
-       }
--    catch (Exception e1)
--      {
--      printRawStackTrace (wr);
-+      
-+      long[] allAddrs = ClassLoader.getAllMethodAddrs();
-+      java.lang.reflect.Method[] meths = ClassLoader.getAllMethods();
-+      
-+      // FIXME: assumes little endian
-+      for(int i=0; i<stackTrace.length; i++) {
-+          long addr = longFromStackTraceBytes(stackTrace, i);
-+          if (addr == 0) break;
-+          
-+          int whichMethod = -1;
-+          for(int j=0; j<allAddrs.length; j++) {
-+              if (allAddrs[j] <= addr &&
-+                  (whichMethod == -1 || allAddrs[whichMethod] < allAddrs[j])) {
-+                  whichMethod = j;
-+              }
-+          }
-+          
-+          if (whichMethod == -1) {
-+              wr.println("[" + Long.toString(addr, 16) + "]  " + "??");
-+              continue;
-+          }
-+          
-+          if (meths[whichMethod].getDeclaringClass().getName().equals("gnu.gcj.runtime.FirstThread") &&
-+              meths[whichMethod].getName().equals("call_main"))
-+              break;
-+          
-+          wr.println("    [" + Long.toString(addr, 16) + "] " +
-+                     meths[whichMethod].getDeclaringClass().getName() + "." +
-+                     meths[whichMethod].getName() + "() " +
-+                     "+" + (addr - allAddrs[whichMethod])
-+                     );
-+          
-+          if (java.lang.Thread.class.isAssignableFrom(meths[whichMethod].getDeclaringClass()) &&
-+              meths[whichMethod].getName().equals("run"))
-+              break;
-       }
-+      wr.flush();
-   }
-   public Throwable ()
-Index: natClassLoader.cc
-===================================================================
-RCS file: /cvs/gcc/gcc/libjava/java/lang/natClassLoader.cc,v
-retrieving revision 1.47.8.1
-diff -u -r1.47.8.1 natClassLoader.cc
---- natClassLoader.cc  2 Apr 2002 22:19:55 -0000       1.47.8.1
-+++ natClassLoader.cc  24 Apr 2002 03:06:14 -0000
-@@ -40,6 +40,10 @@
- #include <java/lang/StringBuffer.h>
- #include <java/io/Serializable.h>
- #include <java/lang/Cloneable.h>
-+#include <java/lang/reflect/Method.h>
-+
-+#include<java/lang/reflect/Constructor.h>
-+#include<gcj/method.h>
- // FIXME: remove these.
- #define CloneableClass java::lang::Cloneable::class$
-@@ -347,6 +351,50 @@
- static jclass loaded_classes[HASH_LEN];
- // This is the root of a linked list of classes
-+
-+JArray<java::lang::reflect::Method*>*
-+java::lang::ClassLoader::getAllMethods()
-+{
-+    return _Jv_GetAllMethods();
-+}
-+
-+JArray<jlong>*
-+java::lang::ClassLoader::getAllMethodAddrs()
-+{
-+    JArray<java::lang::reflect::Method*>* arr = _Jv_GetAllMethods();
-+    java::lang::reflect::Method** el = (java::lang::reflect::Method**)elements(arr);
-+    JArray<jlong>* ret = JvNewLongArray(arr->length);
-+    jlong* retel = (jlong*)elements(ret);
-+    for(int i=0; i<arr->length; i++)
-+        retel[i] = (jlong)((unsigned int)(_Jv_FromReflectedMethod (el[i])->ncode));
-+    return ret;
-+}
-+
-+JArray<java::lang::reflect::Method*>*
-+_Jv_GetAllMethods()
-+{
-+  int numMethods = 0;
-+
-+  for(int i=0; i<HASH_LEN; i++)
-+      for(jclass c = loaded_classes[i]; c; c = c->next)
-+          numMethods += c->getDeclaredMethods()->length;
-+
-+  JArray<java::lang::reflect::Method*>* ret =
-+    (JArray<java::lang::reflect::Method*>*)
-+    JvNewObjectArray(numMethods, &java::lang::reflect::Method::class$, NULL);
-+
-+  java::lang::reflect::Method** el = (java::lang::reflect::Method**)elements(ret);
-+
-+  for(int i=0; i<HASH_LEN; i++)
-+      for(jclass c = loaded_classes[i]; c; c = c->next) {
-+          JArray<java::lang::reflect::Method*>* methods = c->getDeclaredMethods();
-+          jint len = methods->length;
-+          java::lang::reflect::Method** meths = (java::lang::reflect::Method**)elements(methods);
-+          for(int j=0; j<len; j++) el[--numMethods] = meths[j];
-+      }
-+
-+  return ret;
-+}
\f
-Index: natThrowable.cc
-===================================================================
-RCS file: /cvs/gcc/gcc/libjava/java/lang/natThrowable.cc,v
-retrieving revision 1.11
-diff -u -r1.11 natThrowable.cc
---- natThrowable.cc    7 Feb 2002 19:26:06 -0000       1.11
-+++ natThrowable.cc    24 Apr 2002 03:06:14 -0000
-@@ -32,6 +32,7 @@
- #include <stdio.h>
- #include <unistd.h>
-+#include <platform.h>
- #ifdef HAVE_EXECINFO_H
- #include <execinfo.h>
-@@ -102,3 +103,18 @@
- #endif /* HAVE_BACKTRACE */
-   wr->flush ();
- }
-+
-+// Returns the i^th call address in the stackTrace member, or 0 if i
-+// is beyond the end of the trace. This has to be done in C++ because
-+// the addresses in stackTrace are the same width as the platform's
-+// pointers (which is unknown to Java code), and stackTrace is a
-+// byte[] using the platform's endianness (which is unknown to Java
-+// code).
-+jlong
-+java::lang::Throwable::longFromStackTraceBytes(jbyteArray stackArr, jint i)
-+{
-+    if (i * sizeof(void*) > stackArr->length) return 0;
-+    unsigned int* stack = (unsigned int*)elements(stackArr);
-+    return (jlong)stack[i];
-+}
-+
-
-
-
-
+Build Requirements
+
+There are pre-built, digitally signed binaries on http://dist.ibex.org/
+for every supported platform.  Please consider using those unless
+you're absolutely certain you need to go through the trouble of trying
+to get Ibex to build.
+
+Requirements:
+    - jdk 1.3+
+    - the standard set of POSIX utilities (wc, grep, find, make, etc)
+
+Build Targets:
+    - compile: compiles all .java files into build/class/
+    - JVM:     Any true Java JVM (ie not GCJ)
+    - Win32:   Win95 OSR2 or later
+    - Linux:   Linux 2.2 or later
+    - Darwin:  Any Darwin-based OS (Mac OS X, OpenDarwin)
+    - Solaris: Solaris 2.7+
+    - clean:   always run this after doing a 'cvs update'