Developer's Quickstart guide
Getting access to the source code
There are two ways to get access to the muCommander source code:
- By downloading a nightly snapshot of the project at http://mucommander/download/nightly/
- By checking out the project from the anonymous Subversion (SVN) repository
The latter option is recommended as it makes it easier to merge the changes you made to the project with the latest made by fellow developers. Basically, you should check out the project from the repository if you're planning to do any serious work with muCommander. The following section explains how to do so.
Checking out the project
First, you'll need to make sure you have Subversion installed on your machine. Entering 'svn' in a terminal should tell you that. If you don't have it, you can get Subversion at http://subversion.tigris.org/ .
Open a terminal, change the current directory to where you'd like to download the project and enter two following line:
svn checkout https://svn.mucommander.com/mucommander/trunk mucommander
Next you'll see a gazillion files scrolling through your terminal. When this excitement is over, you should have a 'mucommander' directory in your current directory, this is it!
Note: the above command checks out the 'trunk', which is the main development branch. If you want to download the whole repository with tagged versions and other branches, issue the following command instead:
svn checkout https://svn.mucommander.com/mucommander mucommander
Updating the project
The SVN repository is frequently updated, as developers commit their latest changes. To bring your project directory up-to-date, change the current directory of your terminal to the 'mucommander' project directory and type :
If you modified project files and the same files were also modified in the SVN repository, your changes and the repository's will be merged. Conflicts may arise if the same lines of code were modified on both ends. In this unfortunate event, you'll need to edit the file and resolve the conflict manually.
Note that the anonymous SVN repository is read-only: you will not be able to commit your changes to it. Please refer to the 'Contributing your changes' section for information on how to contribute your changes back to the project.
muCommander requires that you have the following software installed:
- JDK 6 or later. You can download it at http://java.sun.com .
- Apache Ant 1.6.5 or later. You can download it at http://ant.apache.org .
Special instructions for Mac OS X:
- Mac OS X 10.5 (Leopard) comes with Java 6 built-in... if you're lucky enough to have a 64-bit Intel processor. If you have a 32-bit Intel processor, you can get Soylatte. If you have a PPC processor, I'm afraid you're out of luck.
- Mac OS X 10.4 (Tiger): you'll also need Soylatte, as Tiger only comes with Java 5.
From the 'mucommander' project directory, copy the 'local_template.xml' file to 'local.xml'. Edit 'local.xml' and fill in the required values (path to the Java runtime file and Ant JAR files).
Then, from the project directory, type:
This will compile and launch your freshly-built muCommander. For additional information about the build process, please refer to the 'compile.txt' file found in the project directory.
Contributing your changes
If you made changes to the code (new feature, bug fix...) that you think muCommander could benefit from, the preferred way to submit those changes is to:
- create a patch using svn diff.
- create a ticket with a description of your enhancement OR find an existing ticket that corresponds to the change you made
- attach the patch to the ticket
We'll then review your patch and follow up with you as we integrate it. Please note that we cannot guarantee your contribution will make it into muCommander as-is, or even at all. So if you plan on developing and contributing a feature, we advise that you first discuss it in this forum before you start working on it. This will ensure that the feature you have in mind has a chance of making in into muCommander. It will also give us a chance to point you into the right direction regarding the implementation, warn you about pitfalls... or even split the work with you. To put it simply, it will save you time.
You are free to distribute muCommander as long as you respect the terms of the GNU GPL License. In particular, any derived work must be released in source form, and must include the original license terms that come with muCommander.
Getting more information
- Links to additional development resources are available on the Developer Resources page.
- You can also browse the Wiki for other development-related pages.
- The roadmap and issue tracker are also good places to gather more information about what's currently being worked on.
Thanks for reading, we're looking forward to your contributions!