|
|
| (449 intermediate revisions by 44 users not shown) |
| Line 1: |
Line 1: |
| − | = Getting Started =
| + | [https://github.com/eclipse-mylyn/org.eclipse.mylyn/wiki/User-Guide The user guide has a new home] |
| − | | + | |
| − | == Installation ==
| + | |
| − | To install Mylar, you need to
| + | |
| − | * Download and install Eclipse. We recommend using a stable version of Eclipse, but it must be at least as old as 3.1. Go to the [http://www.eclipse.org/downloads/ the Eclipse download site] for more information on downloading Eclipse.
| + | |
| − | * [[#Download Mylar]].
| + | |
| − | * [[#Download Required Applications]], if needed. Mylar needs the Java 5 Virtual Machine and a browser that works with Eclipse.
| + | |
| − | | + | |
| − | After you have installed Mylar, there are a few more configuration steps that you might wish to do. See the [Mylar Configuration Guide].
| + | |
| − | | + | |
| − | | + | |
| − | === Download Mylar ===
| + | |
| − | For supported platforms and known limitations please see the [http://eclipse.org/mylar/dl.php Download Page].
| + | |
| − | | + | |
| − | The recommended way to install Mylar is from inside Eclipse.
| + | |
| − | # Select Help->Software Updates->Find and Install.
| + | |
| − | # Select Search for new features to install and select Next.
| + | |
| − | # Select New Remote Site.
| + | |
| − | # Enter Mylar for the name and insert the download site given on the [http://www.eclipse.org/mylar/dl.php Mylar downloads page]. The URL should end up as something similar to http://download.eclipse.org/technology/mylar/update-site/eX.Y. Select OK.
| + | |
| − | # Make sure there is a check in the Mylar box, and select Finish.
| + | |
| − | # Put a check in the box next to Mylar. If you don't mind downloading some stuff you don't need, go ahead and select Next. Otherwise, expand the Mylar line (by clicking on the disclosure triangle) and select what you want. We recommend downloading the Task List, the Focused UI, and connectors appropriate to the bug repository that you use -- Bugzilla, Trac, or Jira. (Note that to download Jira, you need both the core and the connector.) You can download Mylar without a bug repository, but it won't be as interesting an experience.
| + | |
| − | # Read the license agreements, accept or decline as appropriate, and either select Next (if you accept) or Cancel (if you do not accept). If you decline, goodbye, hope to see you again someday!
| + | |
| − | # You will see a list of features and where to install them. If the default installation directory is fine, select Finish.
| + | |
| − |
| + | |
| − | You might get some errors during the download process.
| + | |
| − | | + | |
| − | An error that says:
| + | |
| − | '''Network connection problems encountered during search'''
| + | |
| − | means that Eclipse couldn't find the location you entered. This might be because you copied something incorrectly (watch for extra characters -- even extra spaces can mess things up), or because the site went down. You might be able to see if the site is down by copying the URL into your Web browser.
| + | |
| − | | + | |
| − | An error that reads:
| + | |
| − | ''' Update manager failure '''
| + | |
| − | means that Eclipse could not access the update site, or that it got confused about the configuration state of your Eclipse. First try updating again to see if the update site 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.
| + | |
| − | | + | |
| − | You will probably get a warning that the feature was unsigned. If you trust that hackers have not molested the Mylar plug-in, select Install All.
| + | |
| − | | + | |
| − | You will get a dialog box asking if you would like to restart Eclipse. We recommend that you say Yes. <!--- If you are running Eclipse from the command line, it might be worthwhile to start it once with (@@@? true?)
| + | |
| − | eclipse -clean --->
| + | |
| − | | + | |
| − | === Download Required Applications ===
| + | |
| − | | + | |
| − | Mylar needs the Java 5 virtual machine. (You do not need to use the 1.5 compiler, just the 1.5 VM.) You also need a web browser that works with the Standard Widget Toolkit; Windows and MacOS users are fine, but Linux users might have to download another browser.
| + | |
| − | | + | |
| − | === Download and configure Java 5 or 6 ===
| + | |
| − | To check the version of the Java virtual machine 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 [https://bugs.eclipse.org/bugs/show_bug.cgi?id=116347#c4 bug 1163477] for instructions on how to change the 1.4 default.
| + | |
| − | | + | |
| − | * If you do not have Java 5, you can download it from [http://72.5.124.55/javase/downloads/index.jsp Sun's web site].
| + | |
| − | * If you have more than one VM, you need to specify that Eclipse should use the JDK1.5 VM.
| + | |
| − | | + | |
| − | In Unix, set the environment variable JAVA_HOME to the root of the JDK1.5 installation and/or set the PATH variable to put the JDK1.5 executable directory before any other VM executable directories. For example, under bash in Unix:
| + | |
| − | export JAVA_HOME="''(location of JDK1.5 root)''"
| + | |
| − | export PATH=$JAVA_HOME/bin:$PATH
| + | |
| − | | + | |
| − | <b>We do [https://bugs.eclipse.org/bugs/show_bug.cgi?id=140955 not recommend] using JDK 1.6 on Eclipse 3.1.</b> (It works fine with Eclipse 3.2 or 3.3.) To use JDK 1.6 on Eclipse 3.1, you must add the following line to your config.ini file:
| + | |
| − | <code>
| + | |
| − | org.osgi.framework.executionenvironment=OSGi/Minimum-1.0,OSGi/Minimum-1.1,JRE-1.1,J2SE-1.2,
| + | |
| − | J2SE-1.3,J2SE-1.4,J2SE-1.5,JavaSE-1.6
| + | |
| − | </code>
| + | |
| − | | + | |
| − | === Installation Troubleshooting ===
| + | |
| − | If you have trouble while installing, see the [[Mylar_FAQ#Installation]].
| + | |
| − | | + | |
| − | === Installing Browser on Linux ===
| + | |
| − | Mylar uses the Standard Widget Toolkit Browser, which means that there must be a browser on the system that works with the SWT Browser. For Windows and MacOS, the standard works fine, but on some Linux distributions, you will need to download one. Note that as of 3 Oct 2006, default Firefox distributions for Linux will not work.
| + | |
| − | | + | |
| − | See [http://www.eclipse.org/swt/faq.php#browserlinux the SWT Browser guide] for which browsers will work.
| + | |
| − | | + | |
| − | *Before testing the browser support in Mylar, you must first ensure that the Eclipse internal browser is correctly configured. To test to see if your browser is properly configured, select ''Window->Show View->Other->General->Internal Web Browser'', then try to bring up a Web page.
| + | |
| − | *A quick work around is to disable the internal browser pages in Mylar editors. To do this: ''Window - Preferences - Mylar - Tasks - Disable internal browser''.
| + | |
| − | *'''Notice''': GTK is not supported (??? by Eclipse or by Mylar???), you must use the GTK2 version.
| + | |
| − | *'''Notice''': The internal browser does not correctly support HTTPS. See [https://bugs.eclipse.org/bugs/show_bug.cgi?id=80033 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
| + | |
| − | <code>
| + | |
| − | 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
| + | |
| − | </code>
| + | |
| − | # 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: [http://www.eclipse.org/swt/faq.php Standard Widget Toolkit FAQ]
| + | |
| − | | + | |
| − | === 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 [https://bugs.eclipse.org/bugs/show_bug.cgi?id=144287 bug 144287] if you see this problem.
| + | |
| − | <code>
| + | |
| − | Could not create Bugzilla editor input
| + | |
| − | java.io.IOException: SAX2 driver class org.apache.xerces.parsers.SAXParser not found
| + | |
| − | </code>
| + | |
| − | To ensure that you are using the 1.5 VM refer to the last comment on [https://bugs.eclipse.org/bugs/show_bug.cgi?id=116347#c4 bug 1163477] for instructions on how to change the 1.4 default.
| + | |
| − | | + | |
| − | ---
| + | |
| − | | + | |
| − | Once you can run Mylar at all, you might want to configure it to make it even more powerful. See the [Mylar Configuration Guide].
| + | |
| − | | + | |
| − | == Starting Mylar for the first time ==
| + | |
| − | Once everything is working, you will see a dialog box titled ''Mylar Recommended Preferences''. It's probably best to accept the defaults unless you have already worked with Mylar enough to form opinions. Note that as of 3 Oct 2006, the video is quite out of date.
| + | |
| − | | + | |
| − | To see Mylar in action, select ''Window->Show View->Other'', then select ''Mylar'' and you will see the available Views.
| + | |
| − | | + | |
| − | == Configuration ==
| + | |
| − | After you have installed Mylar -- gotten it to the point where it will run at all -- there are a number of things that you can configure to make your experience even richer.
| + | |
| − | | + | |
| − | === General configuration ===
| + | |
| − | 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.
| + | |
| − | * Editors
| + | |
| − | ** 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
| + | |
| − | * Views
| + | |
| − | ** 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.
| + | |
| − | * Team
| + | |
| − | ** 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 ===
| + | |
| − | | + | |
| − | 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
| + | |
| − | | + | |
| − | [[Image:mylar-spell-checking-preference.gif]]
| + | |
| − | | + | |
| − | === 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:
| + | |
| − | GNOME Desktop
| + | |
| − | # 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.
| + | |
| − | KDE Desktop
| + | |
| − | # 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.
| + | |
| − | | + | |
| − | === 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 -> Tasks'' in the ''Task Data -> Backup'' section, or to change where Mylar saves the backups. 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, either 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''.
| + | |
| − | | + | |
| − | [[Image:mylar-tasklist-backup.gif]]
| + | |
| − | | + | |
| − | | + | |
| − | 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.
| + | |
| − | | + | |
| − | [[Image:mylar-tasklist-restore.gif]]
| + | |
| − | | + | |
| − | === 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 [http://download.eclipse.org/eclipse/downloads/drops/R-3.2-200606291905/index.php Eclipse 3.2 Platform Runtime] binary (e.g. for [http://download.eclipse.org/eclipse/downloads/drops/R-3.2-200606291905/download.php?dropFile=eclipse-platform-3.2-win32.zip Windows], [http://download.eclipse.org/eclipse/downloads/drops/R-3.2-200606291905/download.php?dropFile=eclipse-platform-3.2-linux-gtk.tar.gz Linux x86/GTK 2], [http://download.eclipse.org/eclipse/downloads/drops/R-3.2-200606291905/download.php?dropFile=eclipse-platform-3.2-macosx-carbon.tar.gz Mac OSX]).
| + | |
| − | * Use the update site listed on [http://www.eclipse.org/mylar/dl.php Mylar download page] for installing the Task List and Bugzilla Connector. Note that Mylar requires Java 5.
| + | |
| − | | + | |
| − | == Using Mylar ==
| + | |
| − | | + | |
| − | One of the most useful things that Mylar can do for you is hide things that you aren't interested in. This allows you to focus on the things you are interested in.
| + | |
| − | | + | |
| − | Another high-level thing that Mylar can do for you is help you keep track of tasks. Mylar doesn't just restrict your view to things that are relevant to you, it restricts your view to elements that are relevant to your current task. You tell Mylar when you are changing tasks, and it will hide all of the things associated with your current task (window layout and the contents of those windows) and bring up what was on the screen when you left the other task.
| + | |
| − | | + | |
| − | Mylar also helps you coordinate tasks among many people, by giving tight integration with bug-tracking (or task-tracking) services. Mylar doesn't just keep track of tasks that you define, but that other people define as well. For example, you can work on a specific bug in your Bugzilla repository; the information pertaining to that bug entry is easily available from inside Mylar/Eclipse. It is very easy to attach a full Mylar context -- what elements are interesting, what windows are open -- to a bug.
| + | |
| − | | + | |
| − | == Connectors to Repositories ==
| + | |
| − | Mylar allows you to collaborate on tasks via a shared task repository, also known as bug tracking systems. In order to collaborate, you need to have a ''connector'' to your particular repository.
| + | |
| − | | + | |
| − | === Bugzilla ===
| + | |
| − | | + | |
| − | Once Mylar is installed there are a few steps involved to get up and running.
| + | |
| − | * To access tasks (reports/issues) on a repository such as Bugzilla you must first set up a Task Repository
| + | |
| − | ** Navigate to Window > Show View > Other > Mylar > Task Repositories to open the Task Repositories view.
| + | |
| − | ** Launch the add repository wizard by pressing the add repository button located in the view's toolbar [[Image:Mylar-add-repository.png]].
| + | |
| − | ** The first page of this wizard asks for the type of repository you wish to connect to (if you have installed multiple connectors). Select Bugzilla for example and press the Next button.
| + | |
| − | ** On the second page you can enter the repository's address and your login credentials. After filling in these details, press the validate button to ensure the repository exists and your login credentials are valid. Once the settings validate you can finish the wizard. The repository you added will be shown in the Task Repositories view.
| + | |
| − | [[Image:Mylar-repository-configuration.jpg|Repository Configuration]]
| + | |
| − | * Once the repository has been created, you may add queries to the Task List.
| + | |
| − | ** In the Task List view right click anywhere in the list pane and select 'New Query' from the context menu.
| + | |
| − | ** Choose the repository you added in the previous steps.
| + | |
| − | ** Enter query title and search criteria and then press Finish.
| + | |
| − | ** A query with the title you gave will appear in the Task List and will synchronize with the remote repository. If the query has hits they will appear within the query folder you've created.
| + | |
| − | ** Double click to open a hit. Double click on the query to edit the query parameters.
| + | |
| − | ** Click on the lightly shaded button (left of task icon) in the Task List to activat the task. Click again to deactivate.
| + | |
| − | | + | |
| − | === Trac Connector ===
| + | |
| − | The Trac connector offers two access methods:
| + | |
| − | | + | |
| − | * '''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 [http://trac-hacks.org/wiki/XmlRpcPlugin 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 [http://trac.edgewall.org/ticket/217 #217]). As things are now Trac and the XmlRpcPlugin need to be installed from source. See these [http://trac-hacks.org/wiki/XmlRpcPlugin#Installation install instructions] for requirements and documentation.
| + | |
| − | | + | |
| − | === JIRA Connector ===
| + | |
| − | | + | |
| − | Note that the JIRA SOAP/RPC services have to be running on the server. For additional details see the Requirements on the [http://jira-dashboard.tigris.org JIRA Dashboard] page. For supported versions see the [http://www.eclipse.org/mylar/dl.php download page].
| + | |
| − | | + | |
| − | === Unsupported task repositories / Generic Web Repository Connector ===
| + | |
| − | @@@ Mik -- how are the unsupported and generic related? @@@
| + | |
| − | | + | |
| − | If your repository does not have a connector, all is not necessarily lost. If it has a Web interface, then you can create a task from any web-based repository via the Mylar Web integration:
| + | |
| − | | + | |
| − | * 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.
| + | |
| − | | + | |
| − | [[Image:mylar-tasklist-weblink-editor.gif]]
| + | |
| − | | + | |
| − | With the generic web-based repository connector, you can retrieve a list of issues 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. GlassFish project is used as an example and require the following settings:
| + | |
| − | ** 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 a new Query. For all new issues in the above GlassFish task repository the following properties can be used:
| + | |
| − | ** URL (which 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\=(.+?)">.+?<span class="summary">(.+?)</span>
| + | |
| − | ** 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=
| + | |
| − | | + | |
| − | The above settings can be automatically filled in from templates avaialble from a drop down lists in the repository and query settings. (@@@where?@@@) Templates for the following issue tracking system are included with the web connector:
| + | |
| − | | + | |
| − | * Google Code Hosting (code.google.com)
| + | |
| − | * IssueZilla (java.net, dev2dev, tigris.org)
| + | |
| − | * GForge (objectweb.org)
| + | |
| − | * SourceForge (sf.net)
| + | |
| − | * Mantis
| + | |
| − | * Jira
| + | |
| − | * Trac
| + | |
| − | * phpBB
| + | |
| − | * vBulletin
| + | |
