Torque – Developer's Guide

Building from SVN

The Torque build process uses Maven 3 for building.
You need to check out the trunk part of the db/torque SVN repository. Please read the Torque Subversion page for more information.

Command line build

Change into the directory into which you checked out the torque 4 trunk. Run

mvn install

. The runtime, generator, templates, maven 3 generator plugin and ant tasks will be built in turn and installed in your local maven repository.

Eclipse integration

Assuming you want to check out the project from eclipse:

Install the svn eclipse plugin of your choice (if you have not already done so) (the following description applies for subclipse)
Create the repository location https://svn.apache.org/repos/asf
Browse into the directory db/torque/torque4/trunk
Right-click and "checkout...", choose "checkout as a project in the workspace" and name the project "torque4".
Right-click "delete" on the torque4 project in the package explorer view but then do not check "delete project on disk". This step is needed because eclipse does not import projects inside an existing project.

From here on, the steps are the same whether you checked out from command line or from eclipse. If you check out from command line, the whole torque4 folder should be checked out in the future workspace.

In command line, change into the torque4 directory you just checked out and run
```
mvn -Ptest,derbyEmbedded eclipse:configure-workspace install eclipse:clean eclipse:eclipse
```
.
In command line, delete the .project file in this directory but not in the subdirectories (otherwise the following import will not work).
In eclipse again, click File -> Import... -> General -> Existing projects into workspace -> next and choose the torque4 folder as root directory. Then you should see the projects "torque-ant-tasks", "torque-generator", "torque-maven-plugin", "torque-runtime", "torque-templates".
Click file -> New -> Project... -> General -> Project, enter "torque-site" as project name, deselect the checkbox "use default project location" and choose the torque4/torque-site folder as project location.
In eclipse, Click file -> New -> Project... -> General -> Project, enter "torque4" as project name and click "Finish". By now, you should see the projects "torque-ant-tasks", "torque-generator", "torque-maven-plugin", "torque-runtime", "torque-site", "torque-templates", "torque-test" and "torque4" in your eclipse workspace, with the torque4 project containing all the other projects. That's it.

To later change or update a project change into the module directory and run

mvn eclipse:eclipse

. or in case of the "special" test module torque-test run

mvn -Phsqldb eclipse:configure-workspace eclipse:clean eclipse:eclipse

Testing

Torque is tested by running the test project. Please refer to the Test Project docs for information.

Building a release / release candidate

You need gpg installed for building a release. Possibly, you need to change some gpg defaults. This can be done in the profiles section of the maven configuration file settings.xml. E. g.

  <profiles>
    <profile>
      <id>gnupg</id>
      <properties>
        <gpg.publicKeyring>${location of public keyring}</gpg.publicKeyring>
        <gpg.secretKeyring>${location of secret keyring}</gpg.secretKeyring>
        <gpg.keyname>${id of gpg key used for signing}</gpg.keyname>
        <gpg.passphrase>${your key passphrase. Not a recommended setting to store passphrase as clear text.}</gpg.passphrase>
        <gpg.useagent>${true or false}</gpg.useagent>
      </properties>
    </profile>
  </profiles>

  <activeProfiles>
    <activeProfile>gnupg</activeProfile>
  </activeProfiles>

You also need to define the servers to deploy to in your settings.xml E.g.

  <servers>
    <server>
      <id>apache.website</id>
      <username>tfischer</username>
      <filePermissions>664</filePermissions>
      <directoryPermissions>775</directoryPermissions>
    </server>
    <server>
      <id>apache.releases.https</id>
      <username>tfischer</username>
      <password>${encrypted apache password}</password>
    </server>
  </servers>

Before building a release, check that the project builds with tests and check the test project against the various databases. Make sure that the site is ready for the new release (check the bottom of the site guide for what to do).

To start building a release, run

mvn -DautoVersionSubmodules -Ptest release:prepare

. This will change the version in the poms to the release version and then run a clean verify cycle on the new poms. This will fail because the test project needs the maven plugin which is not installed in the new version yet. To fix this, you might have to run

rm torque-test/derby.log

, then run

mvn install

to install the torque artifacts in the release version. Then run again

mvn -Ptest release:prepare
        -Dusername=YourApacheUsername -Dpassword=YourApachePassword

to finish building the release, creating a tag for the release and changing the pom's version entry to the new development version.

To build the release and install it in the nexus staging repository, run

mvn release:perform

To test the release, login into https://repository.apache.org and download the source distribution from the staging repository. Remove the already installed release artifacts from your local maven repository, and check the source release builds. Then change into the test project of the source release, adjust the database properties in the profiles and run the test project against the various databases.

Adjust the version numbers in the site.

Call a vote on the torque dev list and forward to the db private and db pmc list (pmc@db.apache.org), as formally the entire db pmc is responsible. When the vote is finished, post the result to the dev list and again forward to the db private/pmc list.

When the vote is accepted, promote the staging repository in nexus and copy the distribution files to the directory /www/www.apache.org/dist/db/torque on people.apache.org. Deploy the site. When the various rsyncs are through, announce the release on the torque user list.