DeveloperGuide – squirrel-sql

Context Navigation

We are now using maven for our builds. This brings with it some benefits, not the least of which are portable builds, and a better experience for plugin writers. This page is meant to help you get your development environment setup. This guide assumes that you will be installing the JEE version of Eclipse 3.5. Other versions will work, but this is the version that these instructions were tested with.

Installing JDK

SQuirreL requires a minimum version of 1.6 for the JDK. You can find a version that is suitable for your platform (Linux/Windows/Other) here. Choose the "Java SE Development Kit (JDK)" and be sure to choose the correct platform (32-bit/64-bit). Once you have downloaded the file, extract it, and set your environment variable "JAVA_HOME" to be the top-level directory of the JDK software. The extraction process will typically create a directory called "jdk1.6.0..." in the current directory. This is the directory that you will want to point JAVA_HOME to. You will also want to update your PATH environment variable to include $JAVA_HOME/bin in front of all other paths.

Nexus is a popular web-enabled maven repository distributed by Sonatype. Our Nexus repository is only available using HTTPS for security reasons. However, the certificate for this server has only been signed by CACert.org. CACert.org's root certificate isn't distributed with the Sun JDK, so you must install it in order for Maven to trust this server. To do this, follow these steps:

Download the root.crt file here

Issue the following commands (and see responses) from the command-line to add this CA's cert to the JDK :

chmod u+w $JAVA_HOME/jre/lib/security/cacerts

wget http://www.cacert.org/certs/root.crt

keytool -import -keystore $JAVA_HOME/jre/lib/security/cacerts -file root.crt
  Enter keystore password: changeit

Trust this certificate? [no]:  yes
  Certificate was added to keystore

Installing Subversion Client

Their are two clients that you will want to have installed - one for Eclipse (Subclipse) and one for the command-line. Both of these clients are available from tigris.org. However, if you use Ubuntu (even the latest version), you may find that the default APT repositories do not have the latest command-line client. This is a problem when you use the latest version of the client in Eclipse (Subclipse) on your working copy, and then attempt to do anything with that same working copy from the command-line. The command-line will give an error stating that the working copy version isn't compatible with the command-line client version. There are a number of ways to install a more recent version of the command-line client, but I chose to write about the following method:

Launch Synaptic Package Manager, click on "Settings" -> "Repositories"
Click on the "Third-party Software" tab, and click the "Add" button at the bottom of the dialog window.

Add the following line in the textfield lablelled APT Line:

deb http://ppa.launchpad.net/anders-kaseorg/subversion-1.6/ubuntu intrepid main

Click the "Add" button once again and add the following line in the textfield lablelled APT Line:
```
deb-src http://ppa.launchpad.net/anders-kaseorg/subversion-1.6/ubuntu intrepid main
```
You need to tell Synaptic to "trust" this repository, and you can do this by importing Anders Kaseorg's public key, which I found here
Copy and paste the PGP key block on that page to a file - be sure not to add any extra spaces or lines.
From Synaptic Package Manager, once again choose the "Settings" -> "Repositories"
Click on the "Authentication" tab.
Click on the "Import Key File" button at the bottom and navigate to Anders Kaseorg's PGP key file that you just created.
Close the repositories dialog window and Click "Reload" button at the top of the Synaptic Package Manager window.
Now searching for Subversion should yield a later version of the command-line client (As of this writing, that is 1.6.5 and I am using Ubuntu 9.04).

Installing/Configuring Maven

To install the maven command line application:

Download and extract http://www.apache.org/dyn/closer.cgi/maven/binaries/apache-maven-3.0.4-bin.zip.
Put the MAVEN_HOME/bin folder in your path (for example, if you extracted maven into /opt/apache-maven-3.0.4, then your path should contain /opt/apache-maven-3.0.4/bin)
Test that maven has been correctly installed by issuing the following command (You should see version info including : Apache Maven 3.0.4)
```
mvn -version
```

Some documentation on Maven is available for download at the following links:

All of the SQuirreL maven project poms in subversion depend on artifacts that are available in the maven central repository. However, there may come a time when you would like to introduce a new library dependency to SQuirreL for a project that doesn't use maven (yet?). Or perhaps they do use maven, but their poms/artifacts cannot be found in the Maven central repository. Send a note to the squirrel developers list and someone from the team that has experience in this area will be glad to help.

We also host certain thirdparty proprietary artifacts (such as JDBC drivers) in our own Nexus maven repository. This allows us to add test-only dependencies to projects which are never deployed to Maven Central for the purpose of integration testing. The artifacts in this repository cannot be uploaded to Maven Central due to their restricted distribution license, so this is an internal use only Nexus repository.

To build SQuirreL SQL Client with Maven, you will need a custom settings.xml file. It must be placed in the <user.home>/.m2/ directory.

Setting up SQuirreL in various IDEs

These links will show you how to checkout the source-code using various IDEs:

Checking out the Source from the command line

If you don't care to setup an IDE, you can use the command-line version of subversion to checkout the code as follows:

svn co https://squirrel-sql.svn.sourceforge.net/svnroot/squirrel-sql/trunk/sql12 sql12

This will create a directory named "sql12" in the current directory containing the latest version of all active source code.

Running a plugin from the command line

Once you have checked-out the source-code from subversion you can launch SQuirreL with a single plugin loaded into it as follows:

cd in the plugin directory. For example :
```
cd sql12/plugins/db2
```
Execute the following maven command :
```
mvn clean test -P launch
```
This will launch SQuirreL with the plugin loaded. The JVM will be running in debug mode and listening for debuggers on port 8450.

Adding new library dependencies to the generic installer

In order to avoid software bloat, the installers are configured to include only those direct and transitive dependencies that are essential to running SQuirreL. Therefore, when adding runtime dependencies to any project in SQuirreL, it is important to update the installers to pickup these additional dependencies. This is done by adding an entry for each dependency in the installer module pom (sql12/installer/pom.xml) in the section of the pom with an execution id of "application-libraries". There are entries with the form of :

<includedArtifact>{groupId}:{artifactId}</includedArtifact>

For example, if you are adding a new dependency on the "foo" artifact from the "com.bar" group, you would add an entry that looks like this:

<includedArtifact>com.bar:foo</includedArtifact>

Any time there are new library dependency changes made to SQuirreL, it is a good idea to verify that the installer is picking up those dependencies properly.

cd into the generic installer directory :

cd sql12/installer/squirrelsql-other-installer

Execute the following maven command
```
mvn clean install -DtestInstallers
```

This test will launch SQuirreL using the "optional" install of all plugins, connect to an automatically created embedded derby database, shutdown after 20 seconds, and check the log for errors or exceptions. The build will fail if there are errors in the log. Otherwise if the build succeeds that is a good indication that the installer is picking up the dependencies as long as the new dependency is accessed during the test.

Download in other formats:

Plain Text