Table of Contents
Contents
Introduction
This guide is for New Developers to get started quickly with establishing their build environment for Derby and contribute to Derby.
FLOW OF EVENTS
A Quick look at the phases a developer would go through with Derby:
Getting Started
Setting the build environment(Command Line)
Prerequisites (Software) for setting up the environment: Derby Source, Java 5 or later JDK, Ant 1.7.0 or higher, JUnit 3.8.2
Derby has been tested on various platforms.
(i) Setting DERBY_HOME:
Assuming that you havechecked out the trunk in C:\derby\trunk on Windows, /home/<username>/derby/trunk on Linux or /Users/<username>/derby/trunk on OSX. Following are the instructions for setting DERBT_HOME on the respective platforms.
Operating System |
Command |
Linux |
export DERBY_HOME=/home/<username>/derby/trunk |
Windows |
set DERBY_HOME=C:\derby\trunk |
Mac OSX |
export DERBY_HOME=/Users/<username>/derby/trunk |
(ii) Make sure that java is included in your classpath. To test it run java –version from the command prompt(windows)/terminal(linux).
(iii) Set PATH variable
Operating System |
Command |
Linux / OSX |
export PATH="$DERBY_HOME/bin:$PATH" |
Windows |
set PATH=%DERBY_HOME%\bin;%PATH% You can also add %DERBY_HOME%\bin at the of the system path from Control Panel. |
(iv) Setting CLASSPATH: Following are the jars that needs to be included in your classpath
Jar name |
Purpose |
jakarta-oro-2.0.8.jar (trunk\tools\java) |
Required for running Derby harness tests |
derbyTesting.jar |
test files and classes |
derby.jar |
main derby package classes |
derbytools.jar |
derby tools classes for tools like ij and dblook |
derbyrun.jar |
executable jar file for tools like ij and dblook |
derbynet.jar |
derby network server classes |
derbyclient.jar |
derby client classes |
junit.jar |
assertion-based test machinery. It needs to be manually put into trunk/tools/java directory. See BUILDING.html for details. It is required for running JUnit tests in Derby |
For Derby checked out from the trunk, the classpath should be set as follows: Say, you want to add derbyclient.jar to the classpath:
Operating System |
Command |
Linux / OSX |
export CLASSPATH=$DERBY_HOME/sane/jars/derbyclient.jar |
Windows |
set CLASSPATH=%DERBY_HOME%\jars\sane\derbyclient.jar |
Note: It is advisable to set the classpath only for the session for Derby if you have other versions of junit, jakarta-oro etc. set in the global classpath. To set the classpath for only a session: set the classpath from the terminal/command window.
b) Building Derby from source:
Refer to BUILDING.html for detailed instructions.
c) Verify the build
To verify that the build is a good one, you must run the regression tests.
But for quickly verifying your build, please try running the test SimpleTest. To run it, type the following in the terminal
java junit.textui.TestRunner org.apache.derbyTesting.functionTests.tests.lang.SimpleTest
If the test fails, then you must check your build of Derby.
Running Regression Tests
There are two types of test in Derby: Harness Tests and JUnit Tests. We are converting the harness tests to JUnit Tests . Why ? Whenever you make changes to the code, these tests need to be run so as to make sure that the changes didn’t break any other part of Derby.
To run suites.All (the suite that runs all the JUnit tests in Derby), add junit.jar to your classpath and run:
java -XX:MaxPermSize=512m junit.textui.TestRunner org.apache.derbyTesting.functionTests.suites.All
(Note: It can take approximately 4-6 hours for these tests to complete)
To run derbyAll (the suite for running harness tests in Derby), add jakarta-oro-2.0.8.jar to your classpath and run:
java org.apache.derbyTesting.functionTests.harness.RunSuite derbyall
For detailed information about tests, refer Testing README
Using IDE to Build Derby
Either Eclipse or Netbeans can be used to build derby
1) Using Eclipse to build Derby
2) Using Netbeans to build Derby
New Developer Tips
1) Join Derby Developers Mailing List, ask questions, help others and become a part of the community. Derby has a very active, helping and nice community, so feel free to drop any of your queries to the mailing list.
2) While running tests, clean your current directory containing any artifacts from previous tests. Refer DERBY-5129
3) When you rebuild Derby, if you face issues related to the build procedure (buildjars), not being able to overwrite some of the existing jars, delete the existing jars from trunk/jars/sane directory and run the buildjars (ant –quiet buildjars) again.See DERBY-5128
Next Steps
Following resources are for developers who would like to contribute to Derby
* For suggested starting point for New Developers, please visit The ForNewDevelopers wiki page
* The Apache Derby: Get Involved! page includes tips for contributing code and documentation.
* The Derby Engine papers provide internal details about Derby.
* If you want to know more about internals of Derby, refer How it works
Frequently Asked Questions
1) Where can I get help if I get stuck ?
You can ask questions at derby-dev@db.apache.org (the Derby Developers mailing list) You can also ask questions at our IRC channel: #derby at Freenode (irc.freenode.org)
2) Where are Apache Derby bugs logged ?
Apache Derby uses Apache's Jira issue tracker to track bugs.
3) Who can create a new Apache Derby issue ?
Anyone can browse Apache Derby issues. To log new issues, see the tips page, which describes how to create a userid for yourself and how to log useful bugs. To update existing issues, email your Jira userid to derby-dev@db.apache.org and request that it be added to the derby-developers Jira list.
4) How a change is made in Derby ?
Please refer to Derby Commit Process
5) Are there any guidelines on submitting or developing patches ?
Have a look at Patch Advise