Developing With Eclipse
From Multiverse
| Multiverse Server Plug-ins |
|
Understanding the Servers Processes, Plug-ins, and Agents Creating a Server Plug-in • Defining Command Handlers • Setting Perceiver Radius • |
| Examples and Tutorials |
|
Basic Server Plugin • Faction Plug-in • Creating a Slash Command |
| Server Development |
|
Setting Up an IDE • Using Eclipse |
| Reference |
Contents |
Overview
Eclipse is a popular open source Java IDE. While many Java IDEs are powerful enough for Multiverse development, Eclipse has some key features that make it particularly useful. Eclipse:
- Detects errors & warnings as you type and highlights them, reducing the amount of time you spend correcting and recompiling.
- Auto-builds each file as you save it, allowing you compile as you go.
- Has configurable, Microsoft Visual Studio-style intellisense and auto-completion.
- Has powerful and easy-to-use package building tools.
- Is cross-platform, allowing programmers on many different operating systems to collaborate in a similar environment.
Despite all the points in Eclipse's favor, it can have a steep learning curve. This document assists the first-time user to set up Eclipse to build the Multiverse MARS package and the corresponding mars.jar file, and provides advice for building custom Multiverse packages from Eclipse.
NOTE: This document is intended for those who have already installed the server and client. See Platform Tutorial Getting Started if you have not done this yet.
Setting Up Eclipse
Downloading
The first step is to download the Eclipse SDK. Go to Eclipse SDK downloads and download the latest Eclipse SDK version for your operating system. The download is quite large--feel free to take a break.
Once it has finished, extract the contents of the downloaded zip file to somewhere convenient, such as your desktop.
Installing Eclipse
In the folder that you extracted, there is an eclipse.exe file- run it to start eclipse for the first time. It will prompt you about where on your hard drive you would like your "workspace" to be located. A workspace is a persistent collection of projects that is loaded when Eclipse starts up. You can have multiple workspaces for different endeavors, or you can throw everything onto one workspace: it's up to you.
It doesn't really matter where you put this workspace, so long as it's got its own folder to play with. Going with the default it offers you usually works. If it gives you the opportunity to load the workspace automatically every time you start Eclipse: go ahead and take it. All your Multiverse work will automatically be loaded every time you start Eclipse.
Creating a project
Once your Eclipse UI loads up, you'll be ready to create a new project. Follow these steps:
- Choose File | New | Project. The New Project window opens.
- Choose "Java Project from Existing Ant Buildfile" and click Next.
- Specify your project name ("Multiverse" will do, or maybe the name of your game).
- Click "Browse" and choose the Ant build file,
mv-home/build_mars.xml. - After Eclipse loads the build file, it will put a "javac task" into the large box in the creation dialog box. Select it and click "Finish".
Congratulations, you now have an Eclipse project!
Making it compile
Of course, this fabulous project of yours won't build until you set it up to load the multiverse.jar file that MARS depends on. So let's take care of that:
- On the left side of the screen, right click your project and select "Properties".
- Click "Java Build Path" in the Properties side bar.
- Select the Libraries tab. This tab controls the JAR files that your project loads in when it tries to build.
- Select "Add External Jars..." and select
mv-home/dist/lib/multiverse.jar. - Now click "Java Compiler" in the side bar. Most of the controls on the dialog that comes up will be disabled (greyed out), but near the top, there is an option that says "Compiler compliance level". Make sure that's set to the version of the JDK that you are using (5.0 or 6.0). If it's not, check the box for "Enable project-specific settings" and manually set it to 6.0, if you are using Java 6.0, or 5.0, if you are using Java 5.0.
- Click OK.
Make the JAR
Rebuild
After you finish setting up the above, Eclipse should automatically initiate a full rebuild. If it doesn't, or if you want to do a full rebuild yourself, select Project->Clean. in the menu at the top. The entire project will recompile, and you'll be able to see in the package explorer on the left how things turned out. Files with errors will have a red mini-icon on them, files with warnings will have a yellow mini-icon. The errors and warning mini-icons will propogate upward, too, so (for instance) if any file in multiverse.mars.events has an error, the multiverse.mars.events will also have a red mini-icon, and so will the src folder, and so will the project itself. This makes it very easy to tell if you have any errors in your project, so pay attention to it.
The tedious part
Can someone verify that this section was obsoleted with 1.0? -Slink
There are, unfortunately, a lot of Java files that have the classes they represent commented out. They don't come up as compiler errors when you compile normally, but when you export as a JAR, the JAR builder expected a class and one didn't come out. You'll have to do something about these classes: You can delete them (I prefer this option, but maybe you don't) or set the project up to ignore them, but you'll have to do something. Just get rid of all the MARS files that have no class declaration or a commented-out class declaration.
Export
If your project has no errors in it at all (warnings are okay--MARS comes with a few dozen of them) then you're ready to export the JAR file.
- Choose File | Export. A dialog box will appear.
- Select Java->JAR File. You'll be greeted with a larger, multi-part dialog.
- Take your time here and look at the options. The important thing here is the file tree at the top of the first page that controls which files get exported to the JAR.
- Uncheck the top-level folder to deselect everything, and then reselect the individual packages in multiverse->src.
- You only want to export the contents of the mars packages and nothing else.
- You also want to set the JAR file export location to overwrite the existing mars.jar file.
- Make sure the server is shut down before exporting.
- When you're done selecting your packages and options, click Finish. You'll be prompted about overwriting
mars.jar, which of course, we want to do. It's probably a good idea to backup the originalmars.jar.
If you managed to get rid of all the classless Java files, the JAR file will finish with warnings. Otherwise, it will fail, and you'll have to go into details and dig through the output to find which file it is that's giving you the trouble. Once you finish, you're ready to go. Start up the server and let it run for a few minutes: if you don't get any tracebacks, you're golden.
Congratulations, you're building with Eclipse!
Using Ant to Build A Jar
In eclipse you can also use ANT to build the jar for you. Since your eclipse project contains all the files when you setup the project this is made even easier. To setup up an ANT build, follow these steps:
- Choose the Run Menu, then click on External Tools, and finally External Tools Dialog.
- You will now have an External Tools Dialog window with the choices Ant Build and Program in the left had part of the window.
- Click on Ant Build and click on the icon with a plus symbol just above and to the left of where you just clicked.
- Then to the left change the Name to something that makes more sense, like "Mars Ant".
- In the Build File part, click on Browse Workspace.
- Click on your project, and then select the build_mars.xml file.
- Click Ok.
- Now in the Base Directory part, click on Browse Workspace.
- Click on your project name, and click Ok.
- Click Apply, and then Click Run.
- You should get a console window showing up shortly after doing so showing the status of the build.
- If you have no errors in the build process, all went well.
You can now request an ANT build anytime by clicking on the toolbar button that looks like a green circle with an arrow in it and toolbox on top of it. It will run the last command you ran from there. If you setup more than one, you can click on the down arrow next to that button and choose your ant build process from there.
Troubleshooting Ant Builds
For the most part you will not have any problems when trying to run the the build process for Ant, however if your eclipse only finds the JRE and not the JDK in your registery it will fail on the first time you build due to the fact that it can't find the javac.exe. This is easily solved by following these steps:
- Click on Window, then Preferences..
- Click on the + sign next to Java in the left hand window (It could be an arrow if you are using vista).
- Click on the Installed Jres text under Java.
- In the right hand window you will have a data area with a JRE listed there.
- Click on the JRE that is there, and then click the Edit button to the right.
- Click on the Browse button next to the JRE Home Directory.
- Browse to your JDK directory (Top level just below Java, should be JDK1.X.X\)
- Click Ok, then click Ok again.
You can now re-run the ant build process you setup and it should compile without errors now.
Next steps
New packages and JARs
Adding custom packages to your Eclipse project is ridiculously easy. You don't even really do that much in Eclipse. In your OS's file browser, go to MV_HOME/src directory and add folders named according to the package structure. For instance- if you wanted to add two packages called multiverse.utdsgda.objects and multiverse.utdsgda.plugins, you could add a utdsgda folder to MV_HOME/src/multiverse and add an objects and plugins folder to the utdsgda folder. Then, manally added some blank java files to objects & plugins.
After that, move back to Eclipse, right click your src folder in the Eclipse package explorer on the left, and select "Refresh". Eclipse will load your new packages in, java files and all.
When it comes time to export to Jar, you may not like the idea of putting everything into your mars.jar file- it's not terribly clean to put all kinds of custom code in with the multiverse staff's own code (if you can help it). Instead, you may want to export your own code to its own jar file. When exporting the mars.jar file, only select mars packages to export. Then, do another round of exports, only selecting your own packages and export them to a different file: mypack.jar or some more descriptive name. It's that easy to split up the code with Eclipse. Just make sure that you add any new jar files to the appropriate place in your start-multiverse batch file, or your scripts won't be able to use your code!
Parting words about iterative rebuild
Eclipse compiles as you go, highlighting warnings and errors as you type, which cuts down the time you spend correcting, recompiling, correcting, recompiling, discovering new and interesting layers of compiler errors. Use this functionality to your advantage and correct errors as you go.
Another important point about the eclipse compiler is that when you save a file, it does an iterative clean and build of that one single file. Eclipse is not intended for full rebuilds, although you always have the option using the Project->Clean.. command. Please take advantage of one of Eclipse's finest features, and clean your project only rarely. The iterative compiler is a lot smarter than you might believe, and is capable of figuring out errors as they come up. Don't be afraid to rely on it.
