Here is a step-by-step walk-through from my recent experience on Windows NT. YMMV on other systems.
How to develop for RPTools
26 June 2010
Install Java
Why? This is the programming language and source code to the common libraries.
How? Search for "JAVA SDK" and install it.
Which version? Version 5 or later. The most recent (non-beta) is usually the best.
example:
http://java.sun.com/javase/downloads/widget/jdk6.jsp
Install Eclipse
Why? This is the IDE (integrated development environment) used by the core developers.
How? Go to eclipse.org and install the version for your operating system.
Which version? Eclipse IDE for Java EE Developers (about 200 MB)
example:
http://eclipse.org/downloads/
On a Win32 system, the installation consists of:
- 1. create a folder in your preferred location
2. unzip the contents you downloaded into the chosen folder
3. run eclipse.exe to test that it works.
Install Subclipse
Why? This lets Eclipse work with Subversion (SVN) file repositories.
How? This is an extension to Eclipse. The method for installing them may vary from one version to the next. For the Eclipse 1.3.0 Win32 version go to Help->Eclipse Marketplace. Type "subversion" into the "Find" field, and select "Subclipse" to install. (There may be other options, but this is the one we use.) You'll get a checkbox list of features. Install all of them.
Install ANTLR IDE
Why? This is a build tool that maptool uses.
How? Don't use the Marketplace- you can find a version of ANTLR there, but it's not the same version used for maptools! Instead, you have to use the slightly more circuitous procedure: Help->Install New Software. In the "Work with" dialog, type "
http://antlreclipse.sourceforge.net/updates/". Wait for it to find this. Then, select ANTLR UI. Next a couple times, accept the license, confirm the unsigned certificate, and restart Eclipse. Tada!
More docs here:
http://antlreclipse.sourceforge.net/
Do the tutorials
Why? This will get you up to speed with the basics of Eclipse, and ensure the Java SDK is installed correctly.
Checkout the Maptool files
Why? This is why you're here! You'll get a local copy to play around with.
How?
- Select File->Import.
Select "Other->Checkout projects from SVN". Next.
Select "Create new Repository location". This is really just storing an address for Eclipse to find files.
Paste "https://rptools.svn.sourceforge.net/svnroot/rptools" into the URL and proceed.
You will see lots of projects. WARNING! Don't get the root directory of any project. This will take a LONG time, since it includes many old versions. Also, the make files won't work, since the paths are not setup for this.
So, if you
don't get "maptool", what do you get? Navigate down to "maptool/tags/MapTool-1.3b70" (or some other version you like). This will ensure you get a known working build. Alternatively, you could Select "maptool/trunk". That is the most recent version of each file in the project, but there is a better chance that there are unknown bugs. Either way, select "Next". You might get a pop-up "Getting remote project info". When it's ready, you may have some options. Choose "Check out as a project in the workspace." The project name is probably pre-populated for you. Make sure that it contains the (root) name of the project you are getting, for example "maptool" or "common.build". Use the default workspace location (unless you know what you're doing.)
Now the SVN directory (e.g.)"
https://rptools.svn.sourceforge.net/svn ... ool/trunk/" is copied to your local path (e.g.) "C:\Documents and Settings\joebob\eclipse-workspace\tokentool". Notice you've lost a relative path segment "trunk". This is important for the build files to work. You will need to repeat this import operation several times, once for each project you need. The second and subsequent times, you don't need to enter the URL, you can select "Use existing repository location". Remember, don't get the root directory! Always drill down and get /trunk or one of the /tags builds.
You will need all of the following projects:
- rplib /trunk or /tags version
common.build /trunk or /tags version
parser /trunk or /tags version
You will probably want one of the following projects:
maptool /trunk or /tags version
tokentool /trunk or /tags version
Right-Click on the "parser" project. Select "Toggle ANTLR Project Nature". You should have a pair of moose antlers on the parser project now. (If you don't get that options, but you do have the option "Configure->Convert to ANTLR Project", you have installed the ANTLR version from the marketplace. Uninstall that, and do it the right way above! Actually, you can make that version work just fine by deleting the line that causes the error, but its probably better to sync your dev environment with what the main devs use.)
Test Run
In the eclipse navigator, RClick the file "maptool/MapToolClient(Std).launch". Select "Run As"-> MapToolCient(Std) and viola!
Now you're on your own. Good luck!
Edit1: When you want to update your project(s) against the SourceForge repository, right-click on the project and choose Team > Update. Then sit back and wait for a few seconds while Eclipse contacts the SVN repository and grabs any updates.
Edit2: If you are going to be submitting patches, please read the other thread on MapTool programming guidelines before submitting any changes.