Table of Contents

Feel free to add your tips for building Derby below.

Using Eclipse to Build Derby

  1. Install Subclipse if not already installed.
    Go to Help -> Software Updates -> Find and Install... and choose "Search for new features to install" and click Next. At the next screen, click New Remote Site and enter Subclipse for the name field and http://subclipse.tigris.org/update_1.4.x for the URL. This will add the Subclipse update site to your list of update sites. Click Finish and Eclipse will search for new features and updates to install. On the next screen, check the Subclipse box. If warned that you do not have Mylyn installed, expand the Subclipse box and uncheck the Mylyn Integration box. Click Next. You should be presented with the license terms for Subclipse. If you agree, click the correct radio button to accept the license and click Next, then Finish, then Install All to install/update Subclipse and related components.
  2. Check out the Derby codeline using Subclipse.
    Open the SVN Repository Exploring perspective by going to Window -> Open Perspective -> Other... and then double clicking on SVN Repository Exploring. Right-click in the SVN Repository frame and choose New... and specify https://svn.apache.org/repos/asf/db/derby/code as the Repository URL. Right-click on 'trunk' or expand the branches directory and right-click on a branch name and choose Checkout.... Check out the project using the New Project Wizard, so click Finish without changing anything. Select Java Project (usually the first option) and click Next. Give the new project a name, and click Next. Add /classes to the Default Output Folder so that the default is now '{projectname}/classes' and also click Remove project 'name' from Build Path. We will configure the Build Path ourselves after checkout. Click Finish. Subclipse will check out the Derby source files into a new project in your workspace.
  3. Uncheck the Default builder.
    Once the checkout is complete, right-click on the new project in the Package Explorer and choose Properties. In the Properties window, select Builders. Uncheck the Java Builder. Eclipse will pop up a dialog saying that unexpected things could occur. Click Ok.
  4. Uncheck Build Automatically.
    Go to the Project menu and make sure that Build Automatically is unchecked.
  5. Follow the instructions in BUILDING.html in the checkout regarding the placement of jars and your ~/ant.properties. See also http://db.apache.org/derby/dev/derby_source.html for more information.
    If you follow the instructions correctly, you should be able to build the checked out workspace from the command-line by running 'ant all'.
  6. Add the source folders to the Java Build Path
    Back in Eclipse, right-click on the new project in the Package Explorer and choose Properties. In the Properties window, select Java Build Path. Select Add Folder... and then click the checkbox for each of the folders in the java folder (build, client, drda, etc.) but NOT the java folder itself. Click OK.
  7. Add a new Ant Builder
    While still in the Properties window, go to the Builders tab. Select New.... And choose Ant Build. In the next screen, click Browse workspace... under Buildfile, and choose the top-level build.xml. Go to the Targets tab, and in the Manual Build section, click the Set Targets... button. Uncheck the default buildsource and select the all target.
  8. Build
    Once your new Ant Builder is set up, ctrl-B (or cmd-B on a Mac) will start a Derby build. If you get an error that com.sun.tools.javac could not be found and to check if your JAVA_HOME is set, you may need to go to back to the Classpath tab of your Ant Builder that you just set up and add tools.jar from your JDK 1.4.2 installation by clicking on User Entries and then Add External Jars....
  9. Running JUnit Tests
    Make sure that you have added junit.jar to the Build Path by right-clicking on the project in the workspace, and choosing Properties. In the Properties dialog, choose Java Build Path and select the Libraries tab. Click the Add Jars... button if you have a copy of junit.jar in your workspace, or Add External Jars... if you have a copy outside of your current workspace. Once a complete build has occurred, if you want to run JUnit tests, right-click on a test class and select Run As... and then JUnit test. If it complains that there are errors building, just ignore and select Run Anyway.

NOTE: Because some files are based on the JDBC 4.0 interfaces, there will be some files marked as having errors by Eclipse, since they do not conform to the version of Java set as your JRE System Library.

Using NetBeans to Build Derby

This section describes how to checkout and build Derby using NetBeans versions 5.5 and 6.0. Similar steps should work on other NetBeans versions as well, though there will most likely be some differences.

Steps 1, 2 and 3 below describe checking out the Derby source code with Subversion from within NetBeans. If you would rather like to build source code obtained by other means (for example distributed as an official release), or you have already checked out the source, proceed to Step 4.

  1. Install Subversion
    Set up Subversion on your machine if you have not already done so. This is described in the NetBeans 5.5 IDE help under "IDE basics"->"Working with Subversion", and in the NetBeans 6.0 IDE help under "IDE basics"->"Version Control and File History"->"Working with Subversion".
  2. (NetBeans 5.5 only) Install NetBeans' Subversion module
    Visit the Update Center ("Tools"->"Update Center") and download the Subversion module listed in the Version Control category. If you are using NetBeans 6, you already have this module. If you are using NetBeans 5.0 or earlier, you cannot use the IDE to checkout Derby.
  3. Check out the Derby source code
    Note: If you have already checked out the Derby repository outside of the IDE, NetBeans will automatically recognize the files as being under version control; proceed to step 4.
    1. With NB 5.5, use the "Subversion"->"Checkout..." menu item. In NB 6.0 you will find this as "Versioning"->"Subversion"->"Checkout...". Enter the URL for the repository (folder) you want to check out in the "Repository URL" field. Normally this would be the URL for the latest development trunk, https://svn.apache.org/repos/asf/db/derby/code/trunk/. If you want to build a specific branch instead, you may browse to the desired folder after clicking the "Next" button, or you may specify the branch URL directly (see the Derby web site for further info). Leave the user and password fields blank (unless you are a committer and want to commit patches using NetBeans' Subversion interface). Enter your proxy information if you are using a proxy to connect to the Internet. Click "Next".
    2. Verify that the correct folder shows up in the "Repository Folder(s)" field. For trunk, this would be db/derby/code/trunk. Specify the local folder in which you want to place your working copy of the repository, for example /home/user/dev/derby/svn. Leave other fields/checkboxes as-is. In NB 6.0, if you leave the checkbox for "Scan for Netbeans Projects after Checkout" checked, you will be asked later if you want to use one of the Derby NetBeans projects checked into the subversion repository (if available). Click "Finish".
    3. Observe the progress in the "Output" section of the NetBeans window. This may take a few minutes. Once the checkout has finished, you will either be prompted to create a new Project, or to open a Project that was checked out from the Subversion repository (available from the head of the trunk).
  4. Add Derby as a NetBeans Project
    (Parts of the following description may be specific for trunk, but the process should not be too different for branches, releases or snapshots).
    1. Create (or open) a new Derby Project
      1. If you checked out a recent version of the trunk using Subversion and want to get started developing Derby as quickly as possible, you can simply open a NetBeans Project that comes with the source code (not available in branches at the time of this writing).
        1. If you used NB 6.0 to check out Derby, and the check box for "Scan for Netbeans Projects after Checkout" was checked, NetBeans will tell you that it has checked out a number of projects (if available in that part of the Derby SVN repository), and will ask you if you want to open one of them.
        2. Otherwise, select "File"->"Open Project..."
        3. Browse to your checked out working copy of the Derby repository and select the NetBeans Project folder matching your NetBeans version, under trunk->tools->ide->netbeans. For example, if you are using NetBeans 6.0, this folder is called 6.0.
        4. Complete the Open Project dialogue/wizard. You will now have a new Project called "derby" in your Projects window.
        5. Wait until the IDE completed its work (e.g. compiling sources), then customize your project settings by right-clicking on the project name and selecting "Properties" (see below for details).
      2. If you are using Derby source that does not include NetBeans Project folders, or if you for some other reason would like to create a completely new Project, select "File"->"New Project..." on the menu.
        1. Select Category "General" and Project "Java Project with Existing Ant Script". Click "Next".
        2. For "Location", browse to the trunk folder of your working copy of the repository (or, if you are not using SVN, the top level directory of your source distribution, containing the top level build.xml file). NetBeans will automatically fill in the field for "Build Script" (e.g. .../trunk/build.xml) when you specify the correct location. Specify a Project Name (for example "DerbyTrunk") and a NetBeans Project folder (to avoid mixing repository/source files with NetBeans project files, you may want to use a folder in a different location than the Derby source, but this is not a requirement). Leave "Set as Main project" checked if you want to (this is easy to change later on). Click "Next".
        3. For the Build and Run actions, select the following ant targets:
          • Build Project: all
          • Clean Project: clobber
          • Generate Javadoc: javadoc
          • Run Project: <blank>
          • Test Project: junitreport
            You may specify additional targets later, as needed. Click "Next".
            I.#4 Click the "Add Folder..." button next to the "Source Package Folders" area. Select and add all the folders within the "java" folder (or just the "java" folder itself; the only difference is how it looks in your Project view).
        4. Select source level "JDK1.4" if you are working with the trunk or a Derby version number that is 10.3 or higher. Select "JDK 1.3" if you are working with a branch for (or release/snapshot of) Derby 10.2 or older. Click "Next".
        5. Uncheck the "Separate Classpath for Each Source Package Folder" checkbox.
        6. Read BUILDING.html in the top level source folder in order to identify which external jars you need in order to build Derby, and the contents and location of your ant.properties file, as well as other requirements (Java versions, etc.). Place the required jars in the location(s) indicated in BUILDING.html. For Derby versions 10.2 or newer this includes for example junit.jar.
        7. (Optional) The following is useful in order to enjoy the full set of NetBeans features, such as code completion and refactoring, but is not necessary in order to build Derby: Use the "Add JAR/Folder..." button to select and add the external jars you need (usually located in .../tools/java/) to your "Java Sources Classpath". See also http://db.apache.org/derby/dev/derby_source.html for details.
        1. Click "Finish".
  2. (Not needed after DERBY-5023) Specify the ant.library.dir property
    Select "Tools"->"Options" from the menu. Enter the "Miscellaneous" section and
    • (NetBeans 5.5) expand the "Ant" line. Click "Manage Properties...".
    • (NetBeans 6.0) make sure the "Ant" tab is selected. Click in the "Properties" text field.
      Then and add the line 
          ant.library.dir=<path>
      where <path> is the full path to the lib folder of your ant installation. NetBeans bundles a version of Ant which should be good enough for Derby, so you may specify the lib/ folder of the bundled ant (for example /opt/netbeans-5.5/ide7/ant/lib or /opt/netbeans-6.0/java1/ant/lib).
      Alternatively, you can specify this property in your ant.properties file instead. Do note that in Netbeans 6.1 (at least in Windows) this is the only working option due to a parsing issue.
      1.#5 (Optional) Add a target for building the jar files
      Right click your Derby project in NetBeans' Projects view and select "Properties...". Under "Build and Run", click the "Add" button. Click in the field below the "Ant target" heading and select the buildjarsclean target (this target will delete any old jars before building new ones). Click in the field below "Label" and type the IDE command name you want to use for this target, for example "Build clean jars". Set focus (click) somewhere else in the window to save your label name. Click "OK".
  3. (NetBeans 6 only) Add classpath reference to ant.jar
    • In NB 6.0, you need to add ant.jar to your "Java Sources Classpath" (in you Project properties) in order to get the build to pass and to get rid of some of the error symbols in the editor and the File and Projects windows. If you decided to use (open) a Project folder available from a Derby Subversion repository checkout, all you have to do is to copy (or add a symlink to) ant.jar to tools/java/ (or tools\java on Windows). You can find ant.jar in Ant's library directory, see step 5. See also this mail thread for details.
  4. Build the Derby classes
    If your Derby Project is set as main project: Press F11, or select the "Build"->"Build Main Project" menu item, or right-click your Derby project and select "Build Project".
    If your Derby project is not set as main project, right-click your Derby project and select "Build Project".
    If the build fails, right-click the Derby project and select "Clean Project" before you try again (after fixing the issues (errors) reported) - or run "Clean and Build Project" instead on the next try. If you get an error message complaining about not finding ant classes, revisit Step 5. Warnings can be ignored. The "BUILD SUCCESSFUL" message indicates that all went well.
  5. (optional) Build the Derby jars
    Right-click your Derby project and select the label you created in Step 6. Depending on the settings in your ant.properties file, the Derby jars will end up in the jars/sane/ or the jars/insane/ directory.
  6. Congratulations, you have now built Derby! Now it's time to update the "Output" and "Java Sources Classpath" properties of your Derby project if needed for code completion, debugging, etc. and start hacking some Derby code (or create tests, or review code, or...)!
  7. This page also describes how to use Netbeans with Derby, including nice screenshots: http://wiki.netbeans.org/NetbeansedDerby. Note that it is a bit dated, that latest release is no longer 10.3.

Known Issues

  • Problem: You are using the 1.6 version of the JDK and you still get the errors on the JDBC4 classes.
  • Solution: Under Eclipse, you just need to give the JDK a higher 'priority'. To do this, you need to go to the properties of your Derby project, then under Java Build Path go to Order and Export. There you will need to move the JRE System Library item right to the top and also check it.
  • No labels