Before you start

(I. Before we start is based on the JSynthLib Programmer's guide)

Running JSynthLib

On Linux (debian), execute the JSynthLib-0.20.0.jar file with Java 6 runtime if you have it installed.
(Here's an example of a linux desktop file to get it running with one click from your desktop)

Gathering information

Basic information you need before you can get started:
1. the System Exclusive rules for your synth that you find in it's manual.
2. a clear understanding of the structure of your synth's memory, the address map.
3. a dump of every type of dump your synth can send or receive. e.g. SPD-11dump_all, SPD11dump_patch
4. let the world know about your intentions, and check if nobody else is already writing a driver for the synth (development-list).

Setting up your working environment

1. Install Eclipse (or Netbeans)

(Eclipse online manual)
Since 2009, JSynthLib can be downloaded from SVN, to download it from within Eclipse, you need Subclipse.
If you already downloaded the sourcefiles, you can skip step 1.1 and 1.2.1.

1.1. Install Subclipse (if you need to download from SVN)

Installation instructions at http://subclipse.tigris.org/install.html.
This are instructions for Eclipse 3.0. (If you have a newer version the process is slightly different)
  1. From the Help menu choose Software Updates.
  2. Selected the Available Software tab and click Add Site...
  3. Type the update URL from Step 4 of the Subclipse installation instructions
    http://subclipse.tigris.org/update_1.0.x
and click OK.
  1. Expand the subclipse url and check Subclipse. You may also want to check some of the optional components, I installed them all. (Some of them require extra plugins to be installed first)
  2. Click the Install button.
  3. Restart Eclipse after installing the plugin.
This are instructions for Eclipse 3.2:
  1. Help-> Software Updates-> Find and Install...
  2. Select "Search for new features to install" and click Next
  3. Click Add new remote site and enter the name and URL you find at step 4 of the Subclipse installation instructions
  4. to be continued, I get errors here :)

1.2 Create a Project

1.2.1 Create a Project (SVN style)

  1. From the File menu choose New then Project.
  2. Under SVN choose Checkout projects from SVN, then click Next.
  3. Select Create a new repository location and click Next
  4. Enter the url https://jsynthlib.svn.sourceforge.net/svnroot/jsynthlib/trunk and click Next;
  5. You may get a warning because Eclipse doesn't understand SourceForge's wildcard http certificate. Click Accept Permanently.
  6. Select the JSynthLib folder and click Finish.

1.2.2 Create a Project (from existing project)

  1. Create a folder somewhere on your drive to use as workspace.
  2. In eclipse: File > Switch workspace > browse to the folder created in step 1.
  3. File > Import.. > General > existing projects into workspace
  4. Browse to where you have the existing project and click "Ok"

1.3. Set up the Library Setting and Exclude MidiProvider


(Note: These steps don't seem to be required using Eclipse (3.2 or) 3.3)
  1. Right click (Ctrl-Click on a Mac) on the new project and choose Properties.
  2. Choose Java Build Path, then the Libraries tab.
  3. Click Add JARs....
  4. Click the arrow next to JSynthLib and select groovy.jar, then click OK.
  5. Click on the Source tab.
  6. Click the arrow next to JSynthLib, then Excluded: (None), then Edit....
  7. At the bottom of the window, next to the box that says Exclusion patterns, click Add Multiple....
  8. Choose midiprovider, then click OK three times to close all the Properties windows.

1.4. Displayed Tab Width (code conventions)

Eclipse 3.0: Preferences->Java->Editor->Displayed tab width set to '8'.
Eclipse 3.2: Window-> Preferences-> General-> Editors-> Text Editors-> Displayed tab width set to '8'.

1.5. Setting up Javadocs (Optional, but recommended)

  1. For using the Javadocs for the JDK (e.g. the "J2SE 5.0 Documentation") go to Preferences->Java->Installed JREs->Edit->Javadoc URL set to the directory where you installed the Javadocs. A short description is shown when moving the mouse cursor on a class or a member. You can see the full documentation by hitting Shift-F2 after selecting a class or member.
  2. Don't forget to generate the Javadocs for JSynthlib with Project->Generate Javadoc....

Congratulations. Now you're ready to start hacking.
Note:
Download the source files from svn only by entering this code in your linux terminal:
svn co https://jsynthlib.svn.sourceforge.net/svnroot/jsynthlib/trunk/JSynthLib
for a full example of how this goes, see the svn page

About your code

We should follow the rules listed here on the JSL Programmer's Guide.

2. Quick start guide