GAIA tool for the Roland GAIA SH-01
Copyright 2010 Laurens Holst
Table of Contents
- Project information
- Contribution information
- Getting the source code
- Build instructions
- Eclipse setup instructions
The Gaia Tool is a free tool to view and edit the settings of a Roland GAIA SH-01 synthesizer connected to your PC or Mac.
It is written in Java and should work on all Java SE 6 plaforms. Specific builds for Windows and Mac are also generated.
The tool is Apache 2.0 licensed, which means that you are free to use the source code in any way you wish as long as attribution is given to the original project and its author(s). For details, please consult the LICENSE file.
First of all, contributions are very welcome!
However to make it easier for me to accept your contributions and to minimise any wasted effort, here are some guidelines you should try to follow when contributing:
Coordinate your changes with me.
When you start, contact me and tell me about your ideas. That way we can brainstorm a on it a bit, and make sure that we agree on the direction. This way you won’t be wasting your time on duplicated effort or a dead end.
Share your work in progress.
Once you have code to share, send me a link to your Mercurial repository so I can see your changes. If you need a place to put it, bitbucket.com offers free hosting. I can then provide code review comments and catch problems early, saving you time.
Adhere to the coding style.
I think it is important, so please adhere to it. You should be able to glean much of the style from the existing code, and I think most of these are standard Java and good practices, but let me just name a few:
- Indent code with tabs.
- Put curly braces on the same line.
- Always put the body of an
whilestatement on a new line.
whileblocks braces are optional, but don’t mix.
- Variables and members are written with lower
camelCase. Class names use upper
- Don’t abbreviate with initialisms. E.g. write
FileReader reader, not
FileReader fr. (Notable exception:
jfor loop counters.)
- Don’t break lines at 80 characters, you can go up to 120 or so.
- Keep your functions small.
- Document your functions (but DRY).
- Only write inline comments when absolutely necessary.
Make small, incremental commits.
I really prefer not to receive one big blob of code, so please chop up your work into small commits. Keep unrelated changes separate: don’t make a functional change in the same commit as adjusting white space. If you need to refactor something, do it in a separate commit. Bullet points or the word “also” in your commit messages is a strong indicator it needs to be split.
Doing this is easier for me to review, and also makes it easier for me to already accept parts of your work into the code base while other parts get refined a little further.
Adhere to the MVC pattern
This project is using the Model-View-Controller pattern, which dictates that you separate the domain logic from the presentation. This gives you reusable models which contain all the logic and can basically work independently, and interchangeable views which focus solely on presentation.
To notify views of changes to the models I use an observer pattern; a model extends
notifyObservers()whenever it changes. Then, all classes that registered themselves as an
Observerwill receive a callback to their
The Gaia Tool’s
Observableonly has weak references to the observers, so generally you don’t have to worry about removing the observers for garbage collection. Also, views should use the
AWTObserverinterface, this ensures that their notifications are done on the AWT thread as required by Swing.
Write unit tests
Please write some unit tests for functionality that you add. Now I’ll be the first to admit that the current code base hasn’t got full test coverage, but it really does make a difference in terms of reliability. Note that you don’t have to write tests for the views.
This project is written using the Java SE 6 SDK.
This project is built using Maven 3, although Maven 2 will probably work as well (but I did not test this). It follows standard Maven project setup.
The source code of this project is managed with the Mercurial SCM.
Getting the source code
The source is managed using the Mercurial SCM, you can retrieve it with the following command:
hg clone https://bitbucket.org/grauw/gaia-tool gaia-tool
This will download the project source code into the gaia-tool directory.
If you’re new to Mercurial, here are some resources to get you started:
In a nutshell: Mercurial is a distributed version control system (DVCS), which means that the complete source code repository including all history is cloned onto your hard drive. You can perform all version control operations on that local clone, such as committing and viewing change history. When you are ready to share your changes you push them to a public repository, which can then be reviewed and merged back into the main project repository.
Advantages of this distributed model are that all operations are fast, you can continue working when you have no internet connection or the server is down, you can experiment without fear of messing up the main repository, and you don’t need to ask me for commit access.
The command line interface of Mercurial is very simple and intuitive, but I would also recommend the TortoiseHg GUI if you’re on Windows or Linux. On Mac OS X, I have good experiences with Atlassian’s SourceTree.
From the project directory, enter the following command:
This will build and test the project, and output the binaries into the
directory. The first time it may take a while, because Maven needs to download
The build creates both a general-purpose jar, as well as a .exe-version for Windows and a -app.zip version for Mac OS X. Some other jars are also generated but these are intermediate files and you can ignore them.
To make Mac OS X builds on Windows or Linux machines, you need to get a copy of
JavaApplicationStub file from a Mac and put it in the
src/main/app-resources directory. The next time you build, a Mac binary will
be generated as well. Due to licensing issues I can not include this file with
the source code.
Eclipse setup instructions
There is no requirement for any specific editor, however here are some instructions to get you started with this project in Eclipse. Eclipse can be downloaded from http://www.eclipse.org/.
(Note that these instructions are based on Eclipse Indigo SR1, you may have to adapt them a little for older or newer versions of Eclipse.)
You can let Maven generate the project configuration so that Eclipse is properly configured using the following command:
Next, in Eclipse, go to File, Import, select General, Existing Projects into Workspace, and press Next. Browse to your project folder, and press Finish.
Now you can build and launch the project from Eclipse by right-clicking on the project, selecting Debug As, Java Application. You can also run the unit tests by selecting Debug As, JUnit Test.
If you have the m2eclipse (Maven) plugin for Eclipse installed, you can also right-click on the project and select Configure, Convert to Maven Project to enable some extra Maven integration.