Index: BUILDING.txt
===================================================================
--- BUILDING.txt	(revision 170836)
+++ BUILDING.txt	(working copy)
@@ -29,6 +29,7 @@
 4.2   Derby source code upgrade
 4.3   Derby build flow
 
+5     MacOS X Requirements
 
 ---------------------------------------------------------------
 1     About this document
@@ -63,8 +64,9 @@
     If there is any problem with any url, notify it
     via derby mailing list.
 
+(4) There are specific requirements for MacOS X that you
+    should read prior to doing anything else. See section 5.
 
-
 ---------------------------------------------------------------
 2     Downloads
 
@@ -133,6 +135,9 @@
     The reference implementation is available at:
        http://java.sun.com/j2se
 
+    For MacOS X, get the latest download from:
+       http://developer.apple.com/java/download
+
 (2) Install JDK 1.4.x according to the instructions included 
     with the release in any directory. 
 
@@ -144,7 +149,7 @@
 2.2.3 Download and install Java Development Kit (JDK) release 1.3.x
 
 Skip steps 1-2 of this section if you already have JDK 1.3.x 
-installed on your system.  
+installed on your system or if you are on MacOS X.  
 
 (1) Download JDK 1.3.x. 
     The reference implementation is available at:
@@ -282,7 +287,7 @@
 
 (2) Create a file called "ant.properties" in user home 
     directory and define the following variables in 
-    "ant.properties":
+    "ant.properties". For MacOS X, see section 5.
    
     - j14lib
 
@@ -559,3 +564,48 @@
 At the end of the build, the properties files containing the 
 message files are copied into the output directory and the 
 version information properties files are generated.
+
+5. MacOS X Requirements
+
+With MacOS X, Java is now distributed as core technology, so no 
+downloads are needed except to upgrade to the latest release. The
+distribution includes both JDK 1.4 and JDK 1.3. 
+
+5.1 For MacOS X, the ant.properties is different from other environments,
+and should contain the following. Note that for readability, multiple
+jar files are shown as part of the classpath values, but they need
+to be entered on a single line in the properties file.
+
+j13lib=/System/Library/Frameworks/JavaVM.framework/Versions/1.3.1/Classes
+
+j14lib=/System/Library/Frameworks/JavaVM.framework/Versions/1.4.2/Classes
+
+java13compile.classpath=
+${j13lib}/classes.jar;
+${j13lib}/ui.jar;
+${j13lib}/i18n.jar;
+${j13lib}/sunrsasign.jar;
+${javatools.dir}/jdbc2_0-stdext.jar
+
+java14compile.classpath=
+${j14lib}/classes.jar;
+${j14lib}/ui.jar;
+${j14lib}/laf.jar;
+${j14lib}/sunrsasign.jar;
+${j14lib}/jsse.jar;
+${j14lib}/jce.jar;
+${j14lib}/charsets.jar
+
+javatools.dir=${basedir}/tools/java
+
+compile.classpath=${java14compile.classpath}
+
+5.2 MacOS X 10.3 and earlier have a bug in the file system handling
+that causes problems with Derby. See DERBY-1. The workaround is to 
+provide a derby.properties file with the entry:
+
+derby.storage.fileSyncTransactionLog=true
+
+The derby.properties file should be located in your derby.system.home 
+directory. For more information, see 
+http://incubator.apache.org/derby/manuals/tuning/perf14.html#HDRSII-SETPROP-16827