- 1 Installation
- 1.1 Recommended configuration
- 1.2 Spell Checking
- 1.3 Install Troubleshooting
- 1.4 Installing on Linux
- 1.5 Installing on MacOS
- 1.6 Uninstall troubleshooting
- 1.7 Task List backup and restore
- 1.8 Rich Task List Client Install
- 2 Integration
- 3 Tasks and Repositories
- 4 Java Development
- 5 Team Support
- 6 Integration with other tools
- 7 Key Limitations
Recommendations for Mylar 0.6.x:
- Package Explorer
- Use flat layout in the Package Explorer (local pull down -> Layout -> Flat). Hierarchical layout is not supported.
- Link the Package Explorer with the editor (toolbar -> Link with Editor). With Mylar applied this won't cause the jumping around problems it typically does.
- Deselect the Referenced Libraries filter (local pull down -> Filters -> Referenced Libraries). With Mylar applied libraries won't blow up the tree.
- Leave the General -> Appearance -> Label Decorations -> Java Type Indicator off. Since the type under the Java file is visible when Mylar is visible when Mylar is applied this information is redundant.
- Turn comment folding on to reduce clutter when using auto folding (Preferences -> Java -> Editor -> Folding).
- Turn off or increase the number of editors to leave open (Preferences -> General -> Editors -> Number of opened editors before closing). Since Mylar will manage the open editors with task activation, this number can be set higher or automatic closing disabled entirely.
- If auto folding is used, the Outline view can be closed or made a fast view
- Outline: can keep closed for Java development, since the Package Explorer and folded signatures should provide enough context, and the in-place Outline (Ctrl+O) can be used when needed.
- Set Synchronize view to Change Sets mode (on 3.2: third toolbar button: select Change Sets; on 3.1: toggle toolbar button: Show Change Sets)
- Use graphical CVS decorators only (Preferences -> Team -> CVS -> Label Decorations -> Text Decorations -> clear all but Project; Icon Decorations -> enable all). This helps reduce visual clutter.
Spell checking is supported in the task editor for local tasks and for connectors that support rich editing (e.g. Bugzilla, Trac).
- To install spell checking for editors that support it you need to enable the preference in General -> Editors -> Text Editors -> Spelling.
- You also need to install a dictionary, some instructions and a link are here: http://www.javalobby.org/java/forums/t17453.html
For supported platforms and known limitations please see the Download Page. Install/update failures can include:
Update manager failure
The update manager failed because it could not access the update site, or because it got confused about the configuration state of your Eclipse. First try updating again to see if the feature is accessible. If you are trying to update the JIRA connector you can also try de-selecting that feature in case the Tigris.org update site is not accessible. Using use "Search new features.." when installing can help avoid this problem. If that does not work see the feature configuration troubleshooting below.
Incompatible VM (e.g. JDK 1.4)
In this case you'll errors like the following in your log file. To check JDK version that Eclipse was launched with to to Help -> About Eclipse SDK -> Configuration Details and verify that the java.vm.version is 1.5. Mac users should refer to the last comment on bug 1163477 for instructions on how to change the 1.4 default.
Root exception: java.lang.UnsupportedClassVersionError: org/eclipse/mylar/tasklist/MylarTasklistPlugin (Unsupported major.minor version 49.0)
If you are using JDK 1.6 on Eclipse 3.1 (not recommended) you must add the following line to your config.ini file:
Incompatible version of Eclipse
Separate versions and update sites exist for Eclipse 3.1 and 3.2), in which case you may see errors like the following in your <workspace>/.metadata/.log file or in a Mylar view:
java.lang.NoSuchMethodError: org.eclipse.ui.internal.dialogs.FilteredTree.getFilterControl() The activator org.eclipse.mylar.java.MylarJavaPlugin for bundle org.eclipse.mylar.java is invalid
Mylar feature configuration problem
If the above do not address the issue, the easiest thing to do is uninstall any old versions and update to the latest Mylar. Your tasks won't be lost, by default they are stored in the <workspace>/.mylar/tasklist.xml file which will be read next time Mylar starts correctly. First, uninstall the old version of Mylar using Help -> Software Updates -> Manage Configuration. You need to first Disable on all Mylar features by right-clicking them, allow Eclipse to restart after the last is disabled, and after restart. Then ensure that the 3rd toolbar button is pressed (figure below) so that you see the disabled features to uninstall, and Uninstall them using the popup menu. If you don't uninstall the the Update Manager will think that you have the latest and tell you that there are no updates. Note that manually removing the plug-ins and features can lead to Eclipse configuration errors. After uninstalling update Eclipse by adding the correct update site specified at on the download page, and after that automatically or manually updating will install the correct version.
Installing on Linux
Installing Java 5
Mylar requires Java 5 (see #Install Troubleshooting). If you have comments on how to configure Java 5 on Linux please put them here.
- Before testing the browser support in Mylar, you must first ensure that the Eclipse internal browser is correctly configured.
- Read the SWT FAQ - Browser inside Eclipse on Linux/GTK or Linux/Motif
- Notice: GTK is not supported, you must use GTK2.
- Test manually by: Window - Show View - Internal Web browser, and going to a webpage.
- On Linux, the internal eclipse web browser does not work properly. Errors such as "Could not create Browser page: No more handles (java.lang.UnsatisfiedLinkError: ...)" may appear. A quick work around is to disable the internal browser pages in Mylar editors. To do this: Window - Preferences - Mylar - Tasks - Disable internal browser.
- The internal browser does not correctly support HTTPS. See bug 80033.
Mylar Task Management features makes use of Eclipse's Internal Browser, which may require additional install steps listed below. You also have the option of disabling Mylar's use of the Internal Browser via Preferences -> Mylar -> Tasks.
The following steps have been verified on Fedora Core 5, and OpenSuSE 10.1.
- Run Mozilla (not firefox) to confirm that it works.
- Confirm the location of your Mozilla install (ex: /usr/lib/mozilla-1.7.12)
- Set necessary environment variables in <home_directory>/.bashrc, adding the following 3 lines
MOZILLA_FIVE_HOME=/usr/lib/mozilla-1.7.12 LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$MOZILLA_FIVE_HOME export MOZILLA_FIVE_HOME LD_LIBRARY_PATH
- Log out and log in again (or type "source .bashrc" at the prompt)
- Start Eclipse and test the internal web browser
If you are get exceptions indicating missing libraries, check that the paths are accurate and that you in fact have the libraries requested. For example, on our test box a library was still missing after these steps. The libstdc++.so.5 was being reported as missing. To solve this problem, find an rpm online that will install the missing legacy library. In our case we found necessary rpm (compat-libstdc++-33-3.2.3-47.fc4.i386.rpm) on rpmfind.net using their search facility. See also: SWT FAQ
Keyboard and Alt+Click mappings
If the Ctrl+Alt+Shift+Arrow Up shortcut for Mark as Landmark does not work do the following:
- Menu Bar -> Desktop -> Control Centre -> Keyboard Shortcuts -> Move one workspace up, Move one workspace down: disable both.
If Alt+Click quick unfiltering does not work try one of the following:
- Hold down the Windows key while holding Alt, if available (ironic, but unsurprisingly this key is not usually mapped on Linux).
- Disable the Alt+drag to move functionality:
- Open a terminal and run gconf-editor
- Go into: /apps/metacity/general
- Edit the mouse_button_modifier field. Setting it to nothing disables it. You can use <Super> to set it to the windows key.
- Exit gconf-editor.
- Run the KDE Control Center.
- Go to the Desktop/Window Behavior panel and select the "Window Actions" tab.
- Down in the Inner Window, Titlebar & Frame area, change the "Modifier Key option from Alt to Meta.
Installing on MacOS
If you see errors like the following it may be due to Xerces missing from the Mac JDK so you may need to add it to your default classpath. Please refer to and comment on bug 144287 if you see this problem.
Could not create Bugzilla editor input java.io.IOException: SAX2 driver class org.apache.xerces.parsers.SAXParser not found
To ensure that you are using the 1.5 VM refer to the last comment on bug 1163477 for instructions on how to change the 1.4 default.
On Eclipse 3.1, you may need to reset the Java editor to be default for ".java" again via: Preferences -> General -> Editors -> File Associations
On Eclipse 3.2, if after uninstalling content assist proposals no longer appear you need to ensure that the "Java Completions" and "Java Types" proposal categories are included in the default proposals via: Preferences -> Java -> Editor -> Content Assist -> Advanced -> Restore Defaults. Also see: Mylar FAQ#Content assist troubleshooting. This bug has been fixed in Eclipse 3.2.1.
Task List backup and restore
The task list is backed up by default in the <workspace>/.mylar/backup directory, with rolling backups set according to the schedule in Preferences -> Mylar -> Task List -> Backup. Use File -> Import -> Mylar Task Data to restore from one of the archive zips.
Note that uninstalling a connector will cause all of the queries and tasks of that kind to disappear from the Task List, but if you reinstall that connector they will reappear.
If the Task List is blank Mylar failed to install or update, or there was a problem reading the task list. By default Mylar keeps your task list in <workspace>/.mylar/tasklist.xml. If you move workspaces, and have not changed the Mylar data directory via the Task List preference page, the new location will be used when Eclipse restarts (hit Restore Defaults on that page to copy tasks back to the default location). If your tasks disappear due to to a bug you can check the .mylar folder for a tasklist-backup.xml file, which will contain the previously-saved list.
You can also back up your task list and context data manually or periodically use File -> Import/Export -> Mylar Task Data.
Task and context data can be restored from a backup snapshot via File -> Import -> Mylar Task Data. By default backup snapshots are taken daily and kept for 30 days.
Rich Task List Client Install
Mylar's Task Management features can be used purely as a rich client to supported bug/task/issue trackers. For example, to use Mylar as a rich client for Bugzilla:
- Install the Eclipse 3.2 Platform Runtime binary (e.g. for Windows, Linux x86/GTK 2, Mac OSX).
- Use the update site listed on Mylar download page for installing the Task List and Bugzilla Connector. Note that Mylar requires Java 5.
The goal is for Mylar to have no noticeable effect on Eclipse's speed or memory usage, you do not need to increase the amount of memory Eclipse runs with to use Mylar, and any performance issue should be reported as a bug. The current performance profile is:
- Mylar only runs if a task is active, and has no impact on Eclipse if no task is active.
- Task context models have negligible memory overhead.
- When a task is active, additional view refresh is required to update the views based on interest model changes. This should not be noticeable on Windows where refresh is very quick, but could be more noticeable on other platforms.
- The time to activate a task context is dominated by the time it takes Eclipse to open the editors in the context. You can set the preference for how many editors to open in the Mylar preference page (e.g. setting to 1 will dramatically reduce activation time, but also remove the benefit of having open editors correspond to the task context). You can also turn off editor management entirely in the Mylar Tasks view pull-down.
- Eclipse startup is slowed down by (4) if a task is active when Eclipse is shut down.
- The low priority background searches that the Active Search view runs can be noticeable on slower machines.
Which Focused UI features can I turn off?
All of them. When no task is active neither are any of Mylar's features. When working with task contexts Mylar's Focused UI features are all optional and in general configurable. The following table summarizes how the key features can be toggled. Additional configuration options are under the Mylar and General -> Appearance preference pages.
|UI Mechanism||Example/description||Toggle using|
|Interest filtering||Package Explorer||Apply Mylar button on view toolbar|
|Interest decoration||Bolding of landmark elements||Preferences -> General -> Appearance -> Label Decoration|
|Content assist||Ranking of interesting elements||Eclipse 3.2: Java -> Editor -> Content Assist -> Work in Progress -> turn off Mylar, turn on Java
Eclipse 3.1: set the Java editor to be default for .java, not the MylarJava editor
|Active change sets||Grouping of changes by tasks||Preferences -> Mylar -> Team|
|Editor management||Auto opening/closing of editors||Preferences -> Mylar -> Editor Management|
|Active views||Active Search and Hierarchy||Only on if view is active|
Does the Task List replace the Eclipse Tasks view?
The SDK's Tasks view is used for showing markers such as 'todo' tags which indicate a local problem with a resource, similar to a compiler warning. As such, these 'tasks' are at a much lower level of granularity than than Mylar's tasks, and one task could involve cleaning up multiple todos. In order to make working with only the markers in a particular task context, e.g. for clean-up before committing, the Apply Mylar filter is available for both the Problems and the Tasks views.
Task List view
- Ctrl+F: find
- Insert: new personal task
- Delete: delete selected
- F5: synchronize
- Ctrl+Shift+F11: open task dialog
- Ctrl+Shift+F12: activate task dialog
- Ctrl+Shift+F9: deactivate task
- Ctrl+Shift+Up: mark as landmark
- Ctrl+Shift+Down: mark less interesting
Tasks and Repositories
What if Mylar doesn't support my task/bug/issue/ticket repository?
First, do a search of the open repository connector requests and vote for the corresponding bug if your tracker is there, or create a new bug. In the meantime, you can work with those reports (but not with queries) via the web integration. To create a task from any web-based repository:
- Drag the URL from the Address bar of the browser, or from a hyperlink in a bug listing to the Mylar Tasks view. This will create a task for the bug, link it to the page, and populate the description with the title of the corresponding page. In Mozilla, simply drag the URL. In Internet Explorer you must have Ctrl pressed in order for Eclipse to recognize the drop.
- Alternatively you can copy the URL, press the New Task button on the Mylar Tasks view. This has the same effect as above but you can edit the description after retrieving it.
- Opening the task will now open the corresponding issue. You can also right-click the task and select Open in External Browser.
Bugzilla Connector troubleshooting
If you are just looking for a place to start be sure to check out the Mylar User Guide.
- The times that appear in the Bugzilla bug editor (ie. created, modified) are local to the server hosting the Bugzilla repository, not your local machine's time zone.
- We recommend using the latest release of Bugzilla.
- If attributes are missing options in the bug editor (ie. missing a recently added milestone, bug# 155431):
- Update attributes by choosing "Update Attributes" from the context menu in the Task Repositories view
- Synchronize the task in the tasklist
- Reopen the task - new options should be available.
- If queries are not working correctly ensure that you have the right Bugzilla server version selected for the corresponding repository: Task Repositories (view) -> right+click repository -> Properties. For supported versions see the download page. If the repository is still not functioning it may be due to authentication or connectivity problems. If that does not resolve the problem please post a message to the newsgroup or submit a bug.
- If reports are failing to submit or you're missing products or components to submit to try updating the attributes for the repository via New -> New Repository Task -> select Bugzilla repository -> Update Products from Repository. Currently our support for retrieving the products/components etc. available on the server relies on the information from <your-repository-url>/config.cgi?ctype=rdf. If you are unable to access this url with your web browser then this is likely the source of problems related to missing products/configuration.
- If reports fail to load or reports fail to synchronize (task description remains italic), check the error log for a "File not found" error pointing to bugzilla.dtd or a "Failed to retrieve products from server" error message - these result when the urlbase parameter is not set on the bugzilla server.
- If upon opening a bug, the Bugzilla tab only displays a warning "Could not download task data, possibly due to timeout or connectivity problem. Please check connection and try again.", ensure that your repository is returning xml data by pointing your browser to <your-repository-url>/show_bug.cgi?id=1&ctype=xml to show the contents of bug 1 in xml form. The Bugzilla client requires that bugs be accessible in xml form. If the repository doesn't support xml then it is likely that the repository is too old (Mylar currently supports Bugzilla 2.18 and up).
- If attachments are failing to submit and you see that after processing the attachment, the bugzilla bug shows a size of "bytes" (no numbers), your database may be dropping the packet sending the file. On MySQL, check the max_allowed_packet directive. You may see errors like: DBD::mysql::st execute failed: Got a packet bigger than 'max_allowed_packet' bytes [for Statement "INSERT INTO attach_data (id, thedata) VALUES (38, ?)"] at /path/to/bugzilla/attachment.cgi line 993. Also, check the maximum attachment size in Bugzilla Parameters - Attachments.
- If you are using Bugzilla 2.18 and are getting mid-air collisions this is likely due to incorrectly formatted timestamp field in the underlying bugs database table (bug 149513). This can be resolved by upgrading to Bugzilla 2.20 or later.
JIRA Connector troubleshooting
- If you get a 503 error code verify that the SOAP/RPC interface is enabled.
- If you get a 403 error code verify as above, and also check your authentication mechanism. If the server is using NTLM authentication, see bug 156937 for diagnosis steps.
Trac Connector troubleshooting
The Trac connector offers two access methos:
- Trac 0.9 and later: In this mode the standard Trac web interface is used for repository access. Tickets may be created and edited through a web browser.
- XML-RPC Plugin (Trac trunk): This requires the latest revision (1175) of the XmlRpcPlugin for Trac to be enabled for the accessed repository. The XmlRpcPlugin provides a remote interface to the Trac repository and is distributed separately from Trac (see #217). As things are now Trac and the XmlRpcPlugin need to be installed from source. See these install instructions for requirements and documentation.
Generic Web Repository Connector
The generic web-based repository connector allows to retrieve list of issue from a web page using regular expressions. Currently the connector is experimental and only available from the Sandbox category in dev builds. This bare-bones connector parses HTML to provide basic query integration for task repositories that do not have a rich connector.
As an example consider the configuration steps for IssueZilla on java.net:
- Create new Generic web-based repository with the following settings (GlassFish project is used as an example):
- Server: https://glassfish.dev.java.net/servlets/ProjectIssues
- Task Prefix URL: https://glassfish.dev.java.net/issues/show_bug.cgi?id=
- New task URL: https://glassfish.dev.java.net/issues/enter_bug.cgi?issue_type=DEFECT
- Create new Query for glassfish task repository using following properties:
- URL (it can be copied from the web page that shows query result in IssueZilla). For example, all new issues: https://glassfish.dev.java.net/issues/buglist.cgi?component=glassfish&issue_status=NEW&issue_status=STARTED&issue_status=REOPENED&order=Issue+Number
- Regexp (1st matching group should be issue id and 2nd - issue description): <a href="show_bug.cgi\?id\=(.+?)">.+?(.+?)
- Task prefix (in most of the cases it is the same as prefix in repository settings): https://glassfish.dev.java.net/issues/show_bug.cgi?id=
Above settings can be automatically filled in from templates avaialble from a drop down lists in repository and query settings. Templates for the following issue tracking system are included with web connector:
- Google Code Hosting (code.google.com)
- IssueZilla (java.net, dev2dev, tigris.org)
- GForge (objectweb.org)
- SourceForge (sf.net)
Network and proxy server troubleshooting
For accessing repositories via a proxy server, Mylar uses the settings under Preferences -> Install/Update. If you are seeing errors like "HTTP Response Code 407" it is likely that you need to configure these proxy server settings.
Content assist troubleshooting
In Eclipse 3.2, Mylar uses extended content assist processors in order to rank and separate the elements in the current task context. To see proposals ranked according to interest you must have only the (Mylar) proposals kinds enabled in the list below, otherwise you will see duplicates. If you do not see any proposals, check this list to ensure that either the Mylar or the plain proposals are enabled. Running New -> Mylar -> Recommended Preferences will do this for you automatically, or you can set toggle them manually in the preference page. Proposals will disappear if a workspace into which Mylar was installed is run without Mylar installed (e.g. as a result of uninstalling or multiple Eclipses using same workspace, see Platform bug 140416).
If after invoking content assist you see an error message dialog that states "The extension tool too long to return from the 'computeCompletionProposals()' operation", this is most likely due to something interrupting the proposal operation (e.g. garbage collection). Ignore it if it does not recur, increase Eclipse's memory if it does (e.g via -Xmx384M command line argument), or see bug 141457 for more details.
How do I stop declarations from showing in the Package Explorer?
If you don't like Mylar's constant showing of Java members in the Package Explorer, select the drop-down menu, then Filters... and enable the Mylar Java Declarations Filter. It will then stick in the menu in case you want to toggle between modes. Note that this will hide interest information about members that aren't in your current file (e.g. showing you which methods are landmarks) so this mode is not recommended, but can be useful for 1024x768 screen resolutions.
Why does nothing show up in the Active Search or Active Hierarchy?
As you work and elements become landmarks (bold decoration), and these elements populate the Active Search and Active Hierarchy views. To force an element to populate the views manually make it a landmark by right-clicking or hitting Ctrl+Alt+Shift+Up Arrow.
Active Change Set management
There are two modes for Eclipse's Change Sets support: the models mode (Eclipse 3.2 and later) and the standard mode. These modes are unrelated to Mylar and apply to both Mylar's automated Change Sets and the ones you can created manually in Eclipse. The models mode is toggled via Synchronize View -> Preferences -> CVS -> Allow Models to participate in synchronizations. The Eclipse UI for Change Sets is not obvious so consider the following guidelines if you are having problems with it.
If you are using the standard mode, Change Sets toolbar button will only appear if the Synchronize view is in Incoming or Outgoing mode, not in the combined Incoming/Outgoing mode. This button must be pressed in order for change sets to appear. For working with CVS two modes are indistinguishable beyond this limitation. Subclipse only supports the standard mode. If you switch modes you must re-create your synchronization via the Synchronize... button available form the first toolbar button on the Synchronize view.
If you are using the models mode, you will notice that the Mylar Active Change sets work show up with a decoration in the lower-right corner, and that you can view both incoming and outgoing change sets at the same time. However, note that there is a refresh problem with this mode (bug 142395), and until it is resolved we recommend that you use the standard mode for CVS. To work around the former, if a a Change Set you expect is missing or if you get a There are no more Incoming/Outgoing changes message in the view on startup toggle the third toolbar button between All Models and Change Sets. If that doesn't resolve it activate and deactivate the current task.
Working with Change Sets
Operations such as committing, updating, and patch creation can all be performed on Mylar's automatically managed Change Sets. Right+click the change set node to get the corresponding Team menu. Changed resources that are not a part of any task context will appear under the root of the Synchronize view. If needed missing resources can be added to the task context Change Set via the Synchronize View by right+clicking the resource and selecting Add to and then selecting the corresponding task.
Integration with other tools
Mylar relies on Bridges to integrate the context model with the structure and UI features of domain-specific tools. The core set of Bridges supports the Eclipse SDK (i.e. has bridges for Java, JUnit, PDE, Ant and Resources). The Resources Bridge enables a basic level of interoperability with other tools that use files (e.g. .php, .cpp), and enables Mylar filtering to work for generic views that shows those files (i.e. the Project Explorer, Navigator) and any corresponding markers (i.e. the Problems and Tasks views). This is only the most basic context model integration, and does not offer the benefits of a specialized structure bridge, such as making declarations part of the context and providing Active Search facilities. Without a bridge Mylar also can not be applied to tool-specific views.
If you would like to see support for a particular tool, first do a search of the open bridge requests and vote for the corresponding bug if your tool is there, or create a new bug. Also consider adding your experiences to the FAQ sections below.
Using Mylar with WTP
Context modeling works at the file level, noting the limitation of bug 144882: interest filter fails on WTP Dynamic Web Project
- Bug 106678: The Package Explorer hierarchical layout is not supported on Eclipse 3.2.0 and will show uninteresting elements when enabled. Resolved on Eclipse 3.2.1 and Eclipse 3.3.