[Home] [News] [Contextual Features] [Lightweight Version] [Full Version]
Lightweight Version Installation and User's Guide
The lightweight version of eMoose allows users to benefit from the contextual features of eMoose without any investment. It applies to the user's existing //TODO comments, and to directives that we have annotated in several APIs and which can be downloaded from our server. Users can also annotate their own programs by embedding tags in source code comments, but users will require the source code to benefit from the contextual support for this information. At present, this is the only supported version. See the full version if you would like to create your own data or to use our episodic features.
eMoose is a research tool and is therefore focused on functionality, not on maximal efficiency. Since Eclipse is slow in its own right, using eMoose is not recommended if your Eclipse performance is already sluggish. We would recommend using a machine with at least two CPU cores and 2GB of RAM. It is also (generally) a good idea to increase the maximal heap space available to Eclipse by modifying its eclipse.ini file.
Also note that at present the directives for APIs are loaded over the network every time that Eclipse is started (to ensure proper updates, as coverage increases over time). eMoose should not be used offine, unless you wish to benefit from the support for //TODO comments.
eMoose has been compiled against Java 6 (Java 5 om Mac OS X) and the official 3.4.1 release of Eclipse. No guarantees are made about earlier versions or later versions (though we will routinely update eMoose for new versions). Check this site regularly for updates on compatibility with upcoming 3.5 milestones. Because of these requirements, the default distribution is intended for PCs running Windows or Linux. There is a separate update site for the Mac OS X version, which is compiled against JDK5 since Eclipse does not support Java 6.
In general (and especially if you run eMoose), you may want to let Eclipse use a greater maximal heap space, or you would experience slowdowns (you can use Preferences->General->Show Heap Status to check this). On windows, edit eclipse.ini, and on a Mac open the Eclipse.app as a package with the finder, and go to Eclipse.app/Contents/MacOS/eclipse.ini. Change the Xmx parameter to at least 512.
The standard mechanism for installing eMoose is using the official update site. At present there is some problem with updates, so eMoose would need to be completely uninstalled before upgrading to later versions; see instructions later for details.
Start Eclipse and make sure no previous eMoose versions are installed.
Go to Help -> Software Updates in the main menu
Change the tab to available software
Click Add Site
For a PC, use the following site:
http://emoose.cs.cmu.edu//dist/updatesite/
For a Mac (which only supports Eclipse on Java 5 and is therefore compiled separately), use the following site:
http://emoose.cs.cmu.edu/dist/updatesite_mac/
An entry for the update site will appear, listing eMoose features, similar to the following dialog:
Due to what appears to be a bug in Eclipse 3.4, you will not see the exact categories.
For the lightweight version, you must select the following features and no others, then click install:
"eMoose Third Party Libraries" - Archives of utilities used by eMoose, such as apache-commons and the JMS API.
"eMoose Common Functionality Feature" - The core of eMoose which is shared by all versions of the tool
"eMoose Lightweight client for Eclipse" - The actual client program specific to the lightweight version
If you want to download all the API annotations from the server every time Eclipse starts (and thus always have the most updated version), add the "eMoose default Server-based prepackaged..." feature
If you want to download and use an offline copy (which you would have to occasionally update), select the two local file features for JDK6 and Eclipse (and any others, if available).
Don't be alarmed if Eclipse doesn't tell you what it's installing, just hit next and the actual things should appear.
Let Eclipse restart.
If eMoose is present, you will see a gray eMoose logo on the lower trim.
If you ever want to uninstall eMoose, Go to Help -> Software Updates in the main menu, go to the Installed Software tab, select the above four features for uninstallation, uninstall and restart Eclipse.
Remember that eMoose is a research tool that updates often with bug fixes and features. Make sure to update regularly and to occasionally visit this site to check for new features!
The first time that you run eMoose, you will need to perform an initial configuration.
The first popup simply introduces eMoose
The next popup asks you for consent to have usage information monitored and reported back to the eMoose server for research purposes. The data involves what calls are decorated at each point, and whether you hover over any of these calls. If you are using confidential programs, do not allow monitoring. If you are working on an open-source project or a general program, please select yes if you are willing to have things captured. You will then be asked to provide a userid (does not have to be real, but should be unique) and a project name (against, just has to be unique).
For now please select no reporting!
These popups will only appear the first time. Though less relevant for the lightweight version, if you ever need to redo the configuration without installing eMoose, you can go to the preferences and pick eMoose prosthetic memory -> Prepackaged Lightweight -> Require quick-configuration on next startup.
Every time you load Eclipse, you will be prompted to load directives from our preexisting corpuses of annotated APIs. These APIs are only partially covered though we are constantly extending them. New APIs become available with eMoose updates (The eMoose Default Prepackaged Observations Repositories feature and those downloaded locally). Note that you will probably see a different list, depending on what you picked. If the same API is available from the server or a local file, pick between them.
Once you have made your selections and confirmed, the eMoose clients contacts the eMoose server via the Java Messaging System; in case of server problems, this may fail and you would get a notification for each library that could not be loaded. You can also choose to have your selections remembered for the next restart of Eclipse. You can later load and unload APIs from the menu.
Take a look now at the eMoose symbol, which is part of the lower window trim. The symbol starts out gray, indicating that there are no subjective observations (SOs) that are currently tracked by eMoose. SOs represent discrete knowledge elements that eMoose tracks, and which are typically associated with specific methods or classes. They initially include your //TODO comments and embedded eMoose directives, and then anything downloaded for the core APIs. The number will initially go up for the todo comments if loaded, and later on will go up as API details are loaded and you add todos and tags. As it goes up, the icon will turn blue and then green. Hovering over the icon (finding the exact location may be tricky on some platforms) will list the number of tracked SOs in the hover.
To reduce clutter, eMoose does not install a new menu into your IDE. Instead, all configuration functionality is accessed by right clicking on the eMoose trim icon, revealing the following menu:
The first item allows you to bring up the dialog box for selecting APIs. You can request new APIs, or request to unload others. Note that it takes a few minutes for the full impact to be seen.
The next four options allow you to toggle things related to the contextual presentation. The first will have eMoose use solid boxes around //TODO comments and your own embedded tags if they are the basis for SOs. The second is more important, and will decorate call targets with dashed boxes if they have associated SOs (yours or the APIs). The third, which is typically on, allows you to see the decorations for any method in the current file. If you disable this option, you will only see decorations if and when your insertion point is inside the method body. Finally, you can have eMoose decorate calls if a possible dynamic target includes directives. Since eMoose relies on Eclipse's type hierarchy mechanism, this can have a serious performance impact. In addition, eMoose will not determine what dynamic types could be used in the specific context, and rely solely on the hierarchy. Nevertheless, this information can sometimes be important.
The next three toggles allow you to automatically create SOs for material in your code, albeit with some performance impact. The first option allows you to track all //TODO and //FIXME comments in your code; the second will also allow you to truck the stubs automatically generated by Eclipse. The third will track your own embedded tags. The impact from turning these on and off takes a while to be evident.
To see how eMoose works, look at one of your functions that contains a todo comment, as can be seen below. There is a box around the //TODO which merely highlights it:
The real benefit of eMoose appears when we look at calls to a method that has a todo. We see a dashed box, and an inversed to-do marker.
Now we can hover over this call and see the details in the lower pane. Remember that you can click on it or press F2 to resize it and view everything.
You can right click over each of the observations in the lower pane and ask to open the corresponding artifact in the code editor. However, you must avoid the other options in the context menu while using the lightweight version.
eMoose allows you to create your own SOs in the code by embedding special tags inside comments within the method or in the method header. Tags not directly associated with methods have no impact at this time. The tags will be recognized soon after you enter them or when you first load Eclipse. They will be recognized as SOs (you will see a green box around them) and pushed. No server is needed and anyone using eMoose would be able to benefit them, as long as they have the source code. If you are distributing an API in binary form and would like to push your tags, please contact Uri.
Please make sure that tag tracking is enabled (see the context menu on the trim icon) or that tagsea is enabled.
The format of a tag comment is:
@tag type.subtype: text until the end of the line
Any metadata that you would like to use must appear in the format -META=VALUE after the tag type but before the semicolon. And present it is not being processed. For example:
@tag type.subtype: text until the end of the line
Following is a list of all tags that you can create, in the form (type.subtype). Please be aware that you must have both.
usage - Various directives pertaining to how the client should use the invoked method