Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. Building Derby ================================================================ Contents 1 About this document 1.1 Who should read this document 1.2 Notes 2 Downloads 2.1 Download source code 2.2 Download required software 2.2.1 Download and install Apache Ant 1.6.3 or higher 2.2.2 Download and install Java Development Kit release 1.4.x 2.2.3 Download and install Java Development Kit release 1.3.x 2.2.4 Download extensions for Java Development Kit release 1.3.x 2.2.5 Download and install JUnit 3.8.* 2.2.6 Download Java Development Kit release 1.6.x (Optional) 2.2.7 Download OSGi Service Platform release 3 (osgi.jar) (Optional) 2.2.8 Download Jikes 1.14 (Optional) 2.2.9 Download J2ME/CDC/FOundation 1.0 and JSR169 jars (Optional) 3 Build instructions 3.1 Set required environmental variables 3.2 Create property file 3.3 Run Derby build 3.4 Verify Derby build 4 Derby build miscellaneous information 4.1 Derby build targets 4.2 Derby source code upgrade 4.3 Derby build flow 5 MacOS X Requirements --------------------------------------------------------------- 1 About this document This document contains the instructions to build a binary distribution version of the derby database from a source distribution. 1.1 Who should read this document This document is intended for any one interested in downloading and building a binary distribution of derby source distribution. 1.2 Notes The following conventions are followed in the document: (1) The directories are referred in unix convention. For Windows, / should be replaced with \. (2) All examples or commands are given in unix conventions. For Windows, modify the examples or commands as per windows conventions. (3) This document contains urls to download required software for derby builds. Urls may change anytime. 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 Prior to building derby source code, download derby source code and required software as following: 2.1 Download source code Create a new directory and download derby source code in this directory. This directory will be referred to as the ${derby.source} directory in the rest of this document. After downloading source code to directory ${derby.source}, there should be the following files and directories: ${derby.source}/build.xml ${debry.source}/java ${derby.source}/tools 2.2 Download required software This section lists all the required software for Derby build environment. Notes: ----- (1) Derby build environment requires you to install two levels of Java Development Kit (JDK) - 1.3.x and 1.4.x as Derby is designed to work in JDK1.3.x (JDBC 2.0) and JDK 1.4.x (JDBC 3.0) environments. The Derby build is set up such that that most of the code is compiled against JDK 1.3.x libraries so that no dependencies on JDK 1.4.x classes exist, except for the code that only runs in JDK1.4.x. In addition Derby's JDBC 2.0 implementation must compile against JDBC 2.0 class definitions and the JDBC 3.0 implementation against JDBC 3.0 class definitions. (2) The Derby build environment is tested with JDK 131 (Sun), JDK 141(Sun), and Ant 161. The Derby build environment should work with other versions and other sources of JDK 13 (1.3.x) and JDK 14 (1.4.x), and other versions of Ant 1.6 (1.6.x). 2.2.1 Download and install Apache Ant 1.6.3 or higher (1) Download a binary distribution of Ant 1.6.x from: http://ant.apache.org/bindownload.cgi (2) Install Ant 1.6.x in any directory. This directory will be referred to as ${ant.dir} directory in the rest of this document. 2.2.2 Download and install Java Development Kit (JDK) release 1.4.x Skip steps 1-2 of this section if you already have JDK 1.4.x installed on your system. (1) Download JDK 1.4.x. 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. (3) The directory where you have installed JDK 1.4.x will be referred to as ${jdk14.dir} in the rest of this document. 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 or if you are on MacOS X. (1) Download JDK 1.3.x. The reference implementation is available at: http://java.sun.com/j2se (2) Install JDK 1.3.x according to the instructions included with the release in any directory. (3) The directory where you have installed JDK 1.3.x will be referred to as ${jdk13.dir} in the rest of this document. 2.2.4 Download extensions for Java Development Kit release 1.3.x (1) JDBC 2.0 Download JDBC 2.0 (jdbc2_0-stdext.jar) from: http://java.sun.com/products/jdbc/download.html by selecting "JDBC 2.0 Optional Package Binary". Save jdbc2_0-stdext.jar file in directory ${derby.source}/tools/java (2) Java Cryptography Extension (JCE) version 1.2.2 Download JCE 1.2.2 (jce-1_2_2.zip) from: http://java.sun.com/products/jce/index-122.html Note: You will need to register to download JCE 1.2.2. The downloaded file (jce-1_2_2.zip) for JCE contains documentation files and multiple jar files. After downloading the zip file, unzip the file and copy only jce1.2.2/lib/jce1_2_2.jar file to directory ${derby.source}/tools/java 2.2.5 Download and install JUnit 3.8.* (1) JUnit is needed for some of Derby's tests. Download a JUnit 3.8.* zip file from www.junit.org. Note that Derby has been successfully built with JUnit 3.8.1 and we expect that other 3.8.* versions will work with our build process. The 4.* series of JUnit releases may not work until we fix the Derby build to accomodate the 1.5 extensions to java. (2) Unzip the JUnit zip file and place junit.jar from the zip file into ${derby.source}/tools/java. 2.2.6 Optional - Download and install Java Development Kit (JDK) release 1.6.x Skip steps 1-2 of this section if you already have JDK 1.6.x installed on your system. (1) Download JDK 1.6 (aka "Mustang") This is currently under development, and is available as a release candidate at http://download.java.net/jdk6/binaries/ (2) Install JDK 1.6 according to the instructions in any directory. Verify that bin/javac(.exe) exists under the JDK install directory. (3) The directory where you have installed JDK 1.6 will be referred to as ${jdk16.dir} in the rest of this document. 2.2.7 Download OSGi Service Platform release 3 (osgi.jar) (Optional) This is an optional section. The reason is that osgi.jar is required to only build the class org.apache.derby.osgi.EmbeddedActivator. This class and jar file manifest entries created in derby.jar allow that jar file to be an OSGi bundle. If osgi.jar is not present EmbeddedActivator will not be build and derby.jar will not contain the manifest entries to be an OSGi bundle. OSGi Service Platform release 3 (osgi.jar) can be downloaded from: http://osgi.org Note: You will need to register to download OSGi Service Platform release 3. The downloaded file should be copied to directory ${derby.source}/tools/java Note: After following the steps in sections 2.2.4-2.2.8 of this document, you should have the following: ${derby.source}/tools/java/empty.jar ${derby.source}/tools/java/geronimo-spec-jta-1.0.1B-rc4.jar ${derby.source}/tools/java/geronimo-spec-servlet-2.4-rc4.jar ${derby.source}/tools/java/jakarta-oro-2.0.8.jar ${derby.source}/tools/java/javacc.jar ${derby.source}/tools/java/jce1_2_2.jar ${derby.source}/tools/java/jdbc2_0-stdext.jar ${derby.source}/tools/java/osgi.jar 2.2.8 Download and Install Jikes 1.14 (Optional) This is an optional section. Jikes is an open source java compiler that improves compile speed over standard java compiler. If you would like to have improved compile speed, you can proceed to install Jikes. Jikes 1.14 is the required version for derby builds. Jikes 1.14 can be downloaded from: http://jikes.sourceforge.net/ Install Jikes 1.14 in any directory. This directory will be referred to as the ${jikes.dir} directory in the rest of this document. 2.2.9 Download J2ME/CDC/Foundation and JSR 169 jars This is an optional section. Derby's embeded engine supports J2ME/CDC/Foundation 1.0 using the JDBC sub-set defined in JSR 169. In order to build Derby to support this platform, jars are needed for the Foundation 1.0 profile and the JSR169 JDBC subset. There is no standard place for these jars yet, possible downloads are: java.sun.com/j2me IBM's WCTME 5.7 Once you have obtained these jars and set the jsr169compile.classpath (see section 3.2) the regular Derby builds will include the JSR169 code for the embedded engine. The resulting jar file (derby.jar) can be used on J2ME, or J2SE, write once run anywhere. --------------------------------------------------------------- 3 Build instructions 3.1 Set Required Environmental Variables (1) Create environment variable ANT_HOME to point to the directory where you have installed Ant. For example: setenv ANT_HOME ${ant.dir} -- On unix(csh) export ANT_HOME=${ant.dir} -- On unix(ksh) set ANT_HOME=${ant.dir} -- On Windows (2) Modify the PATH environment variable to include the directory ${ant.dir}/bin in its list. This makes the "ant" command line script available, which will be used to actually perform the build. Also, if you opted to install jikes in section 2.2.8 of this document, add ${jikes.dir} to the PATH as well. For example: setenv PATH ${ant.dir}/bin:${jikes.dir}:$PATH -- On unix(csh) export PATH=${ant.dir}/bin:${jikes.dir}:$PATH -- On unix(ksh) set PATH=${ant.dir}\bin;${jikes.dir};%PATH% -- On Windows (3) Create environment variable JAVA_HOME to point to the directory where you have installed JDK 1.4.x. For example: setenv JAVA_HOME ${jdk14.dir} -- On unix(csh). export JAVA_HOME=${jdk14.dir} -- On unix(ksh) set JAVA_HOME=${jdk14.dir} -- On Windows 3.2 Create property file You will need to create a property file to specify your environment and some of your options. Do the following to specify your environment and options: (1) Determine the directory on your system that corresponds to the "user.home" system property of the JVM referred to by JAVA_HOME. This directory will be referred to as the ${user.home} directory in the rest of this document. In order to determine the correct value of ${user.home}, you can do either of the following: a) Run ant diagnostics and look for "user.home" in the list of System properties: ant -diagnostics b) Write and run a small java program that prints the value of the "user.home" system property, e.g. by including the following line in the program: System.out.println(System.getProperty("user.home")); On Unix systems, ${user.home} is often equivalent to the value of the environment variable $HOME or $home. On newer Windows systems, ${user.home} is often equivalent to the value of the environment variable %USERPROFILE%. NOTE: It is not a requirement that an ant.properties file resides in your user.home directory. The file can be placed anywhere accessible on the local filesystem, but ant must then be invoked with the -propertyfile option: ant -propertyfile {path_to_propertyfile} Alternatively or additionally, you can create a file called local.properties at the top of the checked out tree. Property settings in this file take precedence over those in the ant.properties file in the user.home directory. (2) Create a file called "ant.properties" in your ${user.home} directory and define the following variables in "ant.properties". NOTE TO MAC OS X USERS: See section 5. NOTE TO CYGWIN USERS: Put this in your *Windows* home directory, not your Cygwin home directory. NOTE TO WINDOWS USERS: *use forward slashes* ("/") in your path specifications. Backward-slashes ("\") confuse Ant. Check your path specifications for correct use of slashes in ant.properties if you get errors during the build saying java.lang can not be found. For example, you should have: j13lib=c:/jdk1.3.1_15/jre/lib NOT j13lib=c:\jdk1.3.1_15\jre\lib - j14lib This is a required variable which defines the location of JDK 1.4.x. Define the variable as follows: j14lib=${jdk14.dir}/jre/lib where ${jdk14.dir} is the directory name where you have installed JDK 1.4.x. Check out section 2.2.2 of this document. - j13lib This is a required variable which defines the location of JDK 1.3.x. Define the variable as follows: j13lib=${jdk13.dir}/jre/lib where ${jdk13.dir} is the directory name where you have installed JDK 1.3.x. Check out section 2.2.3 of this document. - Optional - jdk16 This specifies the location of your JDK 1.6 install directory. This is only needed if you want to build the JDK 1.6-specific code (e.g. JDBC 4 classes) - java14compile.classpath - IBM JVMs only IBM Java SDKs may be used in place of Sun's, but IBM packages its Java runtime libraries in multiple jar files instead of a single jar file, rt.jar. This means that if you are using IBM SDKs to provide your Java runtime environment, you need to also override the property java14compile.classpath in your ant.properties file to account for the difference in packaging. Define the variable as follows: java14compile.classpath=${j14lib}/core.jar;${j14lib}/server.jar;${j14lib}/xml.jar - build.compiler This variable defines if standard java compiler or jikes is used for build. The default value of this variable is set to use standard java compiler for build. If you opted to install jikes in section 2.2.8 of this document, you can give your option to use jikes for build by overwriting default value of this variable by setting it as following: build.compiler=jikes - proceed This variable directs Ant to proceed past any build errors and complete rest of the build (when set to true) or stop build any time an error is found (when set to false). The default value for this variable is false. You can overwrite default value by setting it to true by defining the variable as following: proceed=true - sane By default this variable is set to true and builds extra asserts and debugging information in the class files. When set to false no extra asserts or debugging information is included in the class files, making Derby run faster as it generates smaller class files. You can overwrite default value by setting it to false by defining the variable as following: sane=false Typically applications embedding Derby would use jar files built with sane=false. - Optional - jsr169compile.classpath If you downloaded the J2ME jar files (section 2.2.7) then setting this property will enable the optional JSR169 targets for the top-level default, engine or all targets. The compile classpath needs to include the Foundation 1.0 and JSR169 environments, see any documentation for your source of J2ME libraries. Here is an example for IBM's WCTME 5.7 jsr169compile.classpath=C:/wctme5.7/ive/lib/jclFoundation10/classes.zip;C:/wctme5.7/ive/lib/jdbc.jar - Optional - derbyTesting.jar.path This property is required to run upgrade tests. Set this property to point to the location of jar files from a previous release from which we need to test upgrade. This property needs to be set only if the source files will not be available when running tests. In this case, the jars can be copied to any location with the following relative path ${jar_location}/{majorversion.minorversion}. The property should be set as follows: derbyTesting.jar.path=${jar_location} If the test is run on the machine where the source files from svn have been built, then it is not required to set this property. The jars checked into svn will be used. If the tests are being run in a location where the jars from the previous release are available in a different location than where the source files for the upgrade tests have been built, the following property needs to be set on the command line for RunSuite or RunTest where the tests are being run: -Djvmflags=-DderbyTesting.jar.path={path_to_derby_jars} where {path_to_derby_jars} points to a directory where the jars for the previous Derby release being tested for upgrade reside in a subdirectory named according to the major.minor version. For example: If the Derby 10.1 jars for upgrade testing reside in /opt/testing/derby/10.1 then the command line needed for the upgrade tests to complete would include the following: java -Djvmflags=-DderbyTesting.jar.path=/opt/testing/derby \ org.apache.derbyTesting.functionTests.harness.RunSuite upgrade Please note that if you change the value of derbyTesting.jar.path you will need to remove the file org/apache/derbyTesting/functionTests/tests/upgradeTests/Upgrade_10_1_10_2.properties from your build output directory and run 'ant all' for the updated value of the property to be written into that generated file. 3.3 Run Derby build (1) Go to directory ${derby.source}. (2) Run the following command to start build: >ant The above command will build all classes into ${derby.source}/classes. If you add this directory in your classpath, you will have full functionality of engine, tools, and network server. In addition, if you would like to build the Derby test framework and related files, run the following command: >ant testing NOTE ABOUT building JDBC4/JDK1.6 : The JDBC4 class files have dependencies on JDK 1.6. However, to build for JDBC4, do NOT set your JAVA_HOME to the JDK 1.6 location. Instead, set it to your standard JDK 1.4 or JDK 1.3 location. In your ant.properties, make sure you set jdk16 as described in section 2.2.4, and that is all you need to do. (3) Run the following command to build all jars: >ant buildjars The above command will build the following jar files: - derby.jar (database engine), - derbytools.jar (utilities: sysinfo, dblook, ij) - derbynet.jar (network server). - derbyLocale_*.jar (9 jar files with locale support). - derbyclient.jar (derby network client) If the tests were built, the following jar file will also be built: - derbyTesting.jar (the test framework and related files) You can run the ant command to build an individual jar file as following: - command "ant derbyjar" to build derby.jar - command "ant derbytoolsjar" to build derbytools.jar - command "ant derbynetjar" to build derbynet.jar - command "ant derbylocalejars" to build the derby locale jar files. - command "ant derbytestingjar" to build derbyTesting.jar - command "ant derbyclientjar" to build derbyclient.jar Notes: (1) The estimated total time for build completion is ~5-10 minutes. (2) Derby build environment is NOT dependency based build environment. Make sure to check out explaination of "clobber" target in section 4.1 of this document. 3.4 Verify Derby build To verify if the Derby build was successful, do the following: (1) Run "ant" command again and nothing should happen. No files should get compiled, copied or generated. (2) Check if the following directories were created: - ${derby.source}/classes - ${derby.source}/jars if you have built the jars in step 3 of section 3.3 (3) Execute the following command: >java -cp ${derby.source}/classes org.apache.derby.tools.sysinfo You can also execute one of the following commands if you have built the jars in step 3 of section 3.3: For builds with sane=true >java -cp ${derby.source}/jars/sane/derby.jar:${derby.source}/jars/sane/derbytools.jar org.apache.derby.tools.sysinfo For builds with sane=false >java -cp ${derby.source}/jars/insane/derby.jar:${derby.source}/jars/insane/derbytools.jar org.apache.derby.tools.sysinfo The above commands should report the system info and output should look like the following: ------------------ Java Information ------------------ Java Version: 1.4.1_07 Java Vendor: Sun Microsystems Inc. Java home: C:\Program Files\Java\j2re1.4.1_07 Java classpath: c:\derby\classes OS name: Windows 2000 OS architecture: x86 OS version: 5.0 Java user name: derbyuser Java user home: C:\Documents and Settings\Administrator Java user dir: C:\derby --------- Derby Information -------- [C:\derby\classes] 10.0.2.0 - (1) ------------------------------------------------------ ----------------- Locale Information ----------------- ------------------------------------------------------ (4) Execute the following command: >java -cp ${derby.source}/classes org.apache.derby.tools.ij You can also execute one of the following commands if you have built the jars in step 3 of section 3.3: For builds with sane=true >java -cp ${derby.source}/jars/sane/derby.jar:${derby.source}/jars/sane/derbytools.jar org.apache.derby.tools.ij For builds with sane=false >java -cp ${derby.source}/jars/insane/derby.jar:${derby.source}/jars/insane/derbytools.jar org.apache.derby.tools.ij (5) Execute the following statement: connect 'jdbc:derby:test;create=true'; The above statement should create and connect to a database with no errors. (6) Derby also includes a suite of tests for more comprehensive verification. Information on how to run these tests can be found in the source tree, in the file ${derby.source}/java/testing/README.htm --------------------------------------------------------------- 4 Derby build miscellaneous information This section provides miscellaneous information about Derby builds. 4.1 Derby build targets Some of the main targets that can be called as "ant targetname" are as the following: all: builds the source code, demos, and tests. buildsource: to build source code. This is default target. demo: builds the simple demos in java/demo testing: builds the tests in java/testing. For additional information on testing, please see java/testing/org/apache/derbyTesting/README.htm javadoc: to create javadoc for all source code. publishedapi: to create javadoc for application api classes. buildjars: to create jar files clobber: remove all built objects except jars. You should run this target if you have source code upgrade or you changed the source code and you are getting some errors. clean: remove output directory (${derby.source}/classes) cleanjars: remove jars directory (${derby.source}/jars) cleandocs: remove javadoc directory (${derby.source}/javadoc) plugin: creates a zip file, derby_eclipse_plug-in.zip, in the jars/insane directory. The plugin target depends on the default ant target. This creates the Core plug-in only. 4.2 Derby source code upgrade After upgrading derby source code, do the following before building the code as per instructions given in section 3.3: (1) Go to directory ${derby.source}. (2) Run the following command to clean up: >ant clobber 4.3 Derby Build flow This section provides the information on Derby build flow. This section can be skipped unless you are really interested in learning about Derby build flow. Initially, Ant generates state.properties. This file contains a single property, sanity, with a boolean value that determines the sanity state of the build. 'Sanity' was a concept introduced early in Cloudscape as a way of having assert functionality in the code before Java actually supported such functionality syntactically. It was a way to keep development 'sane,' thus the name. Assertions are contained in an if-block based on the static final boolean values SanityState.DEBUG or SanityState.ASSERT, which are true in a sane (debug) build, and false in an insane (non-debug/optimized) build. Therefore, in an insane build, a smart compiler will not write the code in the if-block into the classfile, since it would never be run. The source file containing the static final boolean values of the sanity state, org.apache.derby.iapi.services.sanity.SanityState is then generated from a template. The sanity state defaults to true. This also directs the compiler to turn on all debugging options on the compiler. The sanity state can be set to insane by running 'ant insane' or passing in the value -Dsane=false. Note that this file will be removed after 'ant clobber,' so if you are rebuilding from scratch and want the build to be a non-debug build, run 'ant insane' before building. Once the sanity state has been generated, Ant prints out for reference the current properties that affect the build, including base directory, output directory, compiler, sanity state, and the value of the java property 'proceed.' Next, the parser files are generated with JavaCC. Once the parser files have been generated, the compilation of the source files begins. The source is compiled in a specific order, that order being: reference, internal API, public API, implementation. 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 Mac OS X Requirements With Mac OS 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. Beginning with Mac OS X 10.4, JDK 1.5 may also be included. However, only the JDK 1.4 and JDK 1.3 Java runtime libraries are needed to compile or run Derby. 5.1 Mac OS X ant.properties For MacOS X, 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 javatools.dir=${basedir}/tools/java 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 compile.classpath=${java13compile.classpath} javadoc.tool.jdk14=${java.home}/bin/javadoc