eclipse setup, tricks, etc

roippi

roippi

Developer
Doing this thread as a more tutorial-oriented thing than this thread, which may also be useful to nascent mafia devs. The other one was more along the lines of me querying other devs as to their tools; this is a thread on how to use a specific set of tools. Specifically, eclipse.

Motivation

If you've never worked on a collaborative project before, mafia's codebase seems impenetrable. How on earth do the devs ever find that one line of code that they're looking for?! There's thousands of files!?! AHH

Okay, calm down, I'd first say. Then I'd say: sometimes we know exactly where to look because we've been doing this for years. But often, we're unfamiliar with the particular subsystem that we're trying to troubleshoot. That's when we rely on tools. Use a global search to get yourself in the neighborhood, then IDE tools to navigate up and down the code tree. But I'm getting ahead of myself.

Sir Not Appearing in This Tutorial

Vim, Emacs, Linux CLI utilities. External SVN tools. There are myriad options out there for people who want to use them. Not in this tutorial! We're going to be installing Eclipse with the Subclipse SVN addon. The reasons for the addon are 1) because it's awesome and 2) so everything you need to get started is self-contained in this tutorial. There's no "check out mafia's root directory using an external SVN program" step. On to the good stuff.

Eclipse with Subclipse

First thing's first
Before you start, you need to get a JDK (Java Development Kit) on your system. Download one from here. As of this writing, I'd recommend using the older (but stable) JDK6 rather than the still-buggy JDK7. That recommendation is likely to change eventually, we'll see.

Installing Subclipse
  • Download and install Eclipse first. Duh.
  • Fire up Eclipse. Ignore all the stuff in the main interface for now. Help > Install New Software. Copy/paste this url into the box: http://subclipse.tigris.org/update_1.8.x
  • Check all the boxes. Accept all the license agreements. Restart when prompted. Subclipse installed!
Check out Mafia

Now that you've got a SVN client hooked up to your IDE, this couldn't be simpler.
  • File > Import...
  • SVN > Checkout project from SVN...
  • Create a new repository. Give it this url: https://svn.code.sf.net/p/kolmafia/code/
  • Choose the root directory, hit finish. It will probably pop up a warning about checking out the root directory. Yes, that's okay.
  • You'll probably need to tell it where to create the folder, what to call the project, etc. You can probably handle that stuff. That's it!
So, that wasn't hard. You have a dev environment. Now, for how to (properly) use it.
 
Last edited:
What am I looking at?!

The first thing that you need to know about IDEs, if you're new to them, is that I'm pretty sure that they never say "no" to any feature requests. If a dev somewhere wanted it, they added it.

Okay, that's a bit of an exaggeration, but seriously: there are more features here than you'll ever need. Close most of those side-tabs. I code with the main editor window open and the bottom window on whatever "utility" tab I care about at the time. When I need to browse to another file, I open up the package explorer, which collapses after I click away from it.

overview1-1.jpg

In the bottom "utility" area, there are some useful tabs: problems, search, console, history. I'll cover the more useful ones in the Tips section.

Already you may notice something added by the subclipse plugin in the above image - the amber-colored information after each .java file is info provided by SVN about the various files. Time/date of last commit, and who did it. Try right clicking on a file and doing Team > History... Pretty cool, huh?

Running the project

You spent all that time getting all this set up, let's do something with it. In package explorer, right-click on the project folder and choose Run As... > Java Application. Tell it that the main class is KoLMafia.java. It should fire up the familiar mafia interface quickly. In the future, you can just hit the green "play" button in the top bar and it should instantly fire up mafia with all the changes you've made to it (provided there are no errors).

Under the hood, what it's doing here is quite advanced: it is running an "incremental" builder. If you've ever built mafia using ant before, you know that it takes something like 10-15 seconds to build your program. Instead of doing a clean build every time, javac is just on-the-fly rebuilding the .class files that you make edits to - making the whole thing essentially instantaneous. Pretty ridiculous if you ask me. This makes debugging things SO MUCH faster and fun - type a line of code, see if it works, fiddle with it, repeat. Those 10-15 seconds add up when you're doing it 50 times in a row.

Navigating the code

Time for the good stuff. Note the case-sensitivity of these commands; h is different from H!

ctrl-h: workspace search

A good brute-force standby. There are several tabs here. "File search" is probably what you'd think of when you think of grep or the like - just look through all the files and find the string I want. Java search is more refined, if you know what you're looking for - a method, a class, etc. The other tabs I never use, I'd turn them off by clicking the Customize... button.

ctrl-f: file search

You probably know what ctrl-f does. Make sure to tick "incremental." If you want a lighter-weight version with no dialog box, use ctrl-j.

ctrl-G: find references

Such an awesome command. Say I see a method doStuffToString( String blah), and I want to know where in mafia that method is used. Select it, ctrl-G. You'll get an answer in the search tab down below.

search1.JPG

The constructor HiddenCityRequest( int ) is called there, and there. Double click to go there.

F3: find declaration

Equally awesome. I'm browsing through the code and it makes a new DoStuffRequest( blah1, blah2 ). What does that do? Select it and hit f3 - it will take you to that constructor. You can use this on practically any object - fields, variables, etc. Think of it like clicking on a hyperlink. In fact, if that makes more sense to you, you can use ctrl+click, which does the same thing. Once you get how this and ctrl-G interact, you shouldn't have any problems navigating the code.

Coding

Oh, you wanted to use the IDE to code? Okay, I guess...

ctrl-space: content assist

The autocomplete menu actually will pop up by default, after you add a decimal (.) that indicates you're calling a method. If you lose it for whatever reason - clicking away, etc - ctrl-space gets it back; it will show you matching methods in the current type, or fill it in if there's only one matching method. Think tab in Linux. Absurdly useful. You can try ctrl-shift-space for a slightly different flavor.

logger1.jpg

alt+R: rename

Ever renamed a variable and had to go through your code and fix it 37 times elsewhere? A find/replace will sometimes do it, but what if it's a field that is referenced by multiple types? Alt-R. This is probably the most basic of the "refactor" utilities that eclipse provides; see the right-click menu for lots more. I use rename and move a lot, with a good amount of Extract Method.

ctrl-F: invoke formatter

I am not the tidiest coder. I forget spaces, indent things wrong, etc all the time. What to do?!

Use the formatter to clean up your code. Mafia provides an .xml file to teach eclipse how to do this, actually. To set this up, first go to properties... > Java Code Style > Formatter. Hit import... and browse to util/formatter.xml. Do the same for Clean up and cleanup.xml. Now, when you select something and hit ctrl-F, it will fix all the whitespace, indenting, brackets, etc. It will even organize imports and fix some bad code style things (static references using this, etc. don't worry about it for now.) Cool.

ctrl-shift-/ and ctrl-shift-\: block comment/uncomment

Quick way to throw some /* */ tags around some code. Plain ctrl-/ works too, but is ugly.
 
Last edited:
Contrived examples

Theoretical ridiculous example 1: I want to debug something that's going wrong with the "!" CLI command.

-> Okay, first I have to find it. Let's say I know nothing about mafia's type hierarchy whatsoever. I can't global search "!", that's ridiculous. But, it's a CLI command, so let's search for a nearby one - ashref will do nicely. I hit ctrl-h, click the file search tab, and (for the purposes of the exercise) tick case sensitive.

ctrlh.JPG

Okay, one result. Double-clicking that gets me into KoLmafiaCLI.java.

Looking down a bit ( or doing a ctrl-f on "!" ) quickly finds this line:

Code: 
		new BangPotionsCommand().register( "!" ).register( "bang" ).register( "vials" );

Cool, that's what I need. I select BangPotionsCommand and hit F3. Now I'm where I need to be! Time to debug.

Quickly browsing the code, I might suspect that some indices are being miscalculated. I'd insert this line on line 73:
Code: 
			RequestLogger.printLine( "left chop: " + chopl +"; right chop: " + chopr);

(then run the formatter with ctrl-F to clean up my ugly formatting, haha)

Note that if RequestLogger were not already imported (it is, by chance), Eclipse would tell me about that. Hovering over the red underline would provide possible solutions, the top one being import RequestLogger.

Inserting RequestLogger print statements is perhaps the only tool you need to debug 96% of problems. You can use System.out.print too, but I favor having things displayed in the mafia gCLI rather than console output.



Theoretical contrived example 2: Some jerk broke something with a commit, and I want to fix it and post a .patch

I just updated to r12345 and my favorite widget has stopped widgeting. I know that my widget was working in r12300.

Using the SVN tools, pin down exactly which revision caused the problem. Right click on the kolmafia package > team > update to version. Use a highly-advanced search algorithm! Pick the halfway point of r12322, see if it's broken. Then iterate upwards if it's not broken yet, downwards if it is.

Now that you know the particular revision that caused it, do team > history and look at the files affected by the change. Zero in on the problem.

Fix the problem.

Whew, okay, you fixed the problem. That sure was easy. Time to post your fix on kolmafia.us. For this, you're going to generate a .patch file. Again right click on kolmafia package > team > Create Patch... You'll need to exclude all of the extraneous files other than the ones you've altered/added/deleted specifically for this fix. We probably don't need to commit your personal preferences file.
 
Last edited:
Chish said:
Thank you for posting this! Also thanks for linking to the previous one, I must have missed it.
Click to expand...

Sure thing. A couple things in that older thread are a bit dated, I edited in some comments appropriately.

I'll provide a few more examples when I get around to it.
 
Needs a wiki! Also, I should read this one of these days... I may well be the individual most involved with KoLmafia who's never even attempted to contribute to the code. ;)
 
I picked up a few things that carry over to NetBeans from this, so thanks (mostly because I barely know where things are unless there's no practical way to get by without them).
 
On netbeans: I actually adore netbeans. Its native SVN support is awesome. (Eclipse only natively supports CVS, hence the needed subclipse addon) Eclipse just has too many features I've come to depend on.

Ah, that reminds me of an example I should add.
 
Advanced-ish Stuff

Subclipse-powered quick diff

I'd recommend doing the following. Right click that area to the right of the vertical scrollbar (the "overview ruler") and choose preferences. Go to the quick diff tab and enable quick diff (I like showing it in the overview ruler too). Change the dropdown to be against Pristine SVN Copy (restart may be required). Now you can quickly see exactly what you've changed in your local version versus the SVN version.

Back on the annotations tab, you can tweak how eclipse displays errors, warnings, and the like. I prefer to turn off warnings showing up in the overview ruler, and a couple other tweaks.

Advanced-ish Commands

These are commands that are not strictly necessary, just fun to use once you are more comfortable with the basic ones.

alt+uparrow/downarrow

My new favorite thing, basically. Move a line or lines of code up and down.

ctrl+shift+uparrow/downarrow

Go to previous/next method in a file. You can fly through a big file this way.

ctrl+t

Show type hierarchy. This is like F4, but pops up in a nice context menu. You can toggle super/sub hierarchy by hitting ctrl+t again. Useful when dealing with lots of inheritance, or checking out exactly what something overrides.

ctrl+T

Open type. You know you want to open up UseItemRequest, you're tired of opening package explorer and browsing to it. There ya go.

ctrl+(lowercase L)

Go to line. Somebody posted a bug report, and you want to go to that line in the stack trace? Bingo.

ctrl+o

Method search. A nicer way of going to that particular get.. method that you can't quite remember the name of. Bonus: hitting ctrl+o again shows inherited stuff. Useful if your top-level type is shallow with just a couple of methods, but extends something with a boatload of methods.

ctrl+1

Quick fix. Potentially the most powerful command of any I've listed, but be careful with it. Essentially equivalent to the options provided when there is a warning/error and you hover over it. It is rather smart with providing useful recommendations, but not all are going to be sane. Make sure you know what it did if you invoke it.
 
Decent "short" tutorial you've written, Roippi :)

Ctrl+Left/Right is a good one too, useful after you have pressed F3 to jump to a declaration, you can press Ctrl+Left to jump back. Maybe I should try Eclipse again...
 
Catch-22 said:
Decent "short" tutorial you've written, Roippi :)
Click to expand...

>.>

Well, really the first post is the tutorial, and everything after that is tips/tricks... that's what I'll tell myself.

Ctrl+Left/Right is a good one too, useful after you have pressed F3 to jump to a declaration, you can press Ctrl+Left to jump back. Maybe I should try Eclipse again...
Click to expand...

Cool, I'll try that. I use ctrl+Q to jump back to my last edit sometimes, that's a pretty useful one.
 
This is a really useful guide, roippi. I wish I had had something like this available when I started.

Would you mind if I included parts of this in other projects I'm involved in? If that's okay, how would you like to be acknowledged?
 
roippi said:
ctrl+T

Open type. You know you want to open up UseItemRequest, you're tired of opening package explorer and browsing to it. There ya go.
Click to expand...

Also ctrl+R to open "resource" (any file in the workspace) by name.
Both ctrl+T and ctrl+R support wildcards (*, ?) and ctrl+T also some sort of fuzzy matching (for example, you can skip over most lowercase letters .. in mafia's workspace, RuLi will find RuntimeLibrary). Useful when you only know *part* of the type's name.
 
Grotfang said:
This is a really useful guide, roippi. I wish I had had something like this available when I started.

Would you mind if I included parts of this in other projects I'm involved in? If that's okay, how would you like to be acknowledged?
Click to expand...

Steal at will, I don't mind. You can mention my name if you like. You'll have to pull out the mafia-specific stuff :)
 
Yes, the kolmafia project migrated to the "new" (read: buggy) sourceforge system back in February, which included migrating to a new svn url. I'll update the OP when I get a chance.
 
Hey guys, KoLmafia needs an update to its code formatting rules. Namely, the option in the code formatting settings to enable block comment formatting should be disabled - this prevents Eclipse from horribly mangling block comments, which are used a lot in the KoLmafia source code.
 
I wasn't aware that I'd finished writing the document describing our code formatting rules; that was intended to go into the "devdoc" directory, but it is not there.

Perhaps Eclipse and NetBeans and such allow you to define formatting conventions which they will use for newly entered code. Again, I am not aware of where in our code tree we might have checked in such configuration.

In any case, surely the IDEs don't reformat existing code to follow such configuration unless you explicitly tell it to do so, right? If you have it configured to automatically reformat a whole file when you make a change in the file and save it, or something like that, you need to disable that. If you want to submit a patch which changes an existing method or adds a new one, it is not acceptable for the rest of the file to get reformatted. Doing so is likely to have the patch be discarded unexamined, since it is way too much work to wade through irrelevant formatting changes in order to find what was really changed.
 
FWIW I use NetBeans for mafia and Intellij professionally. Both have an explicit option to reformat code according to some set of formatting rules and those rules are defined in configuration files. However both also have some editor rules such as replacing tabs with spaces, or not, that are not voluntary. If you edit the code in the IDE and then check it in then those rules are unconditionally applied. Granted those are less obtrusive than reformatting block comments but they are nevertheless not practically optional. One has to set them correctly for KoLmafia. The whole formatting thing was also complicated in Ye Olden Days because SVN would not deal with the various CR LF options automatically and the Windows based devs were constantly screwing things up for the Mac devs.

All that said, I am not aware of a set of KoLmafia approved formatting rules for code that are implemented in such a way that an IDE user would have to import a file and thus be compliant. It would be wonderful if someone felt like taking that on. I'd even consider switching to Eclipse.
 
You must log in or register to reply here.
Back
Top