Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Linux Tools Project/LTTng Eclipse Plug-in Development Environment Setup"

(Run (or Debug) the plugins)
(Replaced content with "The Eclipse LTTng (and related) plugins have moved to the [http://eclipse.org/tracecompass Trace Compass] project. Updated instructions can now be found on Trace_Compass...")
 
(10 intermediate revisions by 4 users not shown)
Line 1: Line 1:
This page describes how to setup LTTng Eclipse Plug-in development environment.
+
The Eclipse LTTng (and related) plugins have moved to the [http://eclipse.org/tracecompass Trace Compass] project. Updated instructions can now be found on [[Trace_Compass/Development_Environment_Setup | this page]].
 
+
Note that this should only be required if you want to make modifications to the code or contribute patches. If you only want to run the plugin as a user, you would probably be better served by the stable or nightly builds, available on [http://www.eclipse.org/linuxtools/downloads.php this page].
+
 
+
= Get the Eclipse SDK =
+
 
+
Under [http://eclipse.org/downloads/ eclipse.org downloads], select the '''Eclipse Standard''' archive. You can start with any Eclipse pre-package, but make sure you have the ''Eclipse Plug-in Development Environment'' feature installed.
+
 
+
''Note:'' The JDT in Eclipse 4.3.1 has some issues which results in it throwing NullPointerExceptions all over the place. We recommend people to keep using [http://www.eclipse.org/downloads/packages/eclipse-standard-43/keplerr 4.3.0] until 4.3.2 comes out.
+
 
+
Uncompress and start Eclipse. Example for Linux:
+
 
+
$ tar xzvf eclipse-SDK-4.3-linux-gtk-x86_64.tar.gz
+
$ cd eclipse
+
$ ./eclipse
+
 
+
The first time you run it, it will ask for a workspace directory. You can use the default location.
+
 
+
You will then be greeted by the welcome screen, which you can dismiss by clicking the ''Workbench'' arrow in the upper-right corner.
+
 
+
= Install dependencies =
+
 
+
One additionnal dependency is needed in your Eclipse runtime to build the LTTng plugin, which is the Maven Eclipse plugin (m2e). If you know what you are doing, you can run Maven from the command line and skip this step. If you are not sure, keep reading:
+
 
+
* Select "Help -> Install New Software..."
+
* Select the current Eclipse release repository (e.g. Kepler)
+
* Select (check) "Collaboration -> m2e - Maven Integration for Eclipse"
+
* Click Next/Next/Finish to install the packages.
+
* Restart Eclipse.
+
 
+
= Get the source code for org.eclipse.linuxtools =
+
 
+
First, make sure you have a Git client installed (either the git command-line tool, or the [http://www.eclipse.org/egit/ EGit] plugin, also available in Eclipse's "Install New Software").
+
 
+
Then, simply clone the following repository somewhere on your hard drive:
+
* git://git.eclipse.org/gitroot/linuxtools/org.eclipse.linuxtools.git
+
 
+
= Import LTTng projects into the workspace =
+
 
+
* Select "File -> Import..."
+
* Select "General -> Existing Projects into Workspace"
+
* Next to "Select root directory" click "Browse..."
+
* Navigate to the directory where you git clone'd the project earlier.
+
* Select the ''lttng/'' subdirectory and click OK.
+
* It should now list the available plugins. Make sure they are all checked and click "Finish".
+
* The plugins should now be added to your workspace, and visible in the Package Explorer view on the left.
+
 
+
You will probably get a bunch of build errors at this point. DON'T PANIC! This is because LTTng/TMF needs additional dependencies that might not be present in your current Eclipse installation. We will install those in the following sections.
+
 
+
= Set the Target Platform =
+
Eclipse offers the ability to set target platforms, which will download a specific environement to run your plugins, without having to "pollute" your Eclipse install. LTTng ships target definition plugins, which is the recommended way of installing its dependencies.
+
 
+
To set the target platform for the LTTng plugins:
+
* Expand the "org.eclipse.linuxtools.lttng.target" plugin.
+
* Double-click the .target file that corresponds to your Eclipse version (lttng-e4.3.target, at the time of this writing).
+
* In the view that just opened, click ''Set as Target Platform'' on the top right.
+
 
+
Eclipse will now download the required dependencies, which may take some time the first time.
+
 
+
If you wish to switch target platforms in the future, you can come back to this plugin, or you can go to "Window -> Preferences -> Plug-in Development -> Target Platform". From that page, you can switch between any of the known targets, or your base Eclipse runtime.
+
 
+
= Generate the CTF parser files =
+
 
+
You will probably still have some build errors. This is because the CTF parser files are missing, and need to be generated from the grammar files. Unfortunately, there is no simple, platform-agnostic way to build those from Eclipse, since the version of Antlr shipped in Orbit only contains the runtime, and not the tool to generate Java files. This is where m2e comes into play:
+
* Expand the "org.eclipse.linuxtools.ctf.parser" project.
+
* Right-click the "pom.xml" file (should be a direct child of the project folder itself).
+
* Select "Run As -> Maven install" (not "Maven build", "install"!)
+
* You should see the Maven output in the console, which should hopefully finish with a BUILD SUCCESSFUL message.
+
 
+
Note that m2e behaves like a Maven client, which means it will ignore most of Eclipse's settings and use its own ''settings.xml'' file. For instance, if you need to configure a proxy, it will need to be set in that file. You can read more about the ''settings.xml'' file [http://maven.apache.org/ref/3.0.4/maven-settings/settings.html here].
+
 
+
Alternatively, if you have "antlr3" installed on your system, you can use the "generate-grammar.sh" script to achieve the same result.
+
 
+
Once the parser is built, if the other projects didn't refresh, you can force a refresh manually (Collapse All, shift+click to select all the plugins, then press F5). The errors should all disappear.
+
 
+
If you ever run a ''git clean'', or if you make modifications to the CTF grammar (.g) files, you will need to regenerate these files using the same method.
+
 
+
= Build the documentation (optional) =
+
 
+
If you imported the *.help plugins (which contain the user and developer guides), you might notice warnings in these plugins because of missing files. Similarly to the CTF parser, the documentation plugins need to be built using a separate component. If you do not care for the documentation, you can ignore those warnings, or even remove those plugins from your workspace.
+
 
+
On the other hand, if you want to build or work on the documentation (which you should do if you add user-visible features!), here is how to build it.
+
 
+
First you need to install the Mylyn-Wikitext Eclipse plugin:
+
* Go to "Help -> Install New Software..."
+
* Select "-- All Available Sites--"
+
* In the list of available plugins, select "Collaboration -> Mylyn Wikitext", and click Next/Finish to install it.
+
* Restart Eclipse
+
 
+
You can now build the documentation plugins:
+
* Click on one of the *.help projects
+
* In the top menu, click "Project -> Build Project"
+
* After it is built, the warning should disappear, and the HTML files should be present in its ''doc/'' subdirectory.
+
 
+
Note that this builder does not run automatically ; Ant is not very smart at figuring out which files were changed, so it would end up constantly rebuilding the doc plugins for nothing. For this reason, if you modify the source (.mediawiki) files, you will have to rebuild the HTML manually, using the same method.
+
 
+
= Define an API baseline (optional) =
+
 
+
Since Linux Tools is now out of incubation, all API changes have to be tracked and marked with the proper @since annotations. The Eclipse API tool works by comparing the contents of the current workspace with a clean, separate installation of Eclipse in another directory (the "baseline").
+
 
+
If you will only be using this setup to run the latest git code, you can decide to ignore these errors by performing these steps:
+
 
+
* Select "Window -> Preferences -> Plug-in Development -> API Baselines"
+
* Under "Options -> Missing API baseline:" select "Ignore"
+
* Click "OK"
+
 
+
 
+
However, if you intend of hacking at the code and contributing patches, then you are strongly encouraged to setup a baseline installation correctly:
+
 
+
==== Download the baseline install ====
+
* Go to http://eclipse.org/downloads and download a copy of the '''Eclipse IDE for C/C++ Developers''', if you don't already have one. The exact version does not really matter, as we will install the latest Linux Tools next.
+
* Extract it in a directory somewhere, separate from your normal Eclipse installation. We will call this new installation the ''baseline''.
+
 
+
==== Update the baseline ====
+
The baseline needs to be updated with the latest version of Linux Tools. Intermediate releases might not be part of the base Eclipse install, so they have to be downloaded from the update site. To verify if you have the latest version, and update it if needed:
+
 
+
* Run your baseline installation of Eclipse (''cd'' to its directory and run ''./eclipse'').
+
** To be safe, select a different workspace that the one for your real installation (you can use a ''workspace/'' subdirectoy under the baseline's ''eclipse/'' directory for example).
+
 
+
* Dismiss the splash screen and go to "Help -> Install New Software".
+
* In the new window, click on the ''Available Software Sites'' link at the top.
+
* In the following window, check the box next to the ''Linux Tools'' repository. If it's not present, you can add it, the URL is:
+
** http://download.eclipse.org/linuxtools/update
+
 
+
* Click OK until you go back to the first window, then on the drop-down menu, select ''--All Available Sites--''.
+
* In the list, open the ''Linux Tools'' subtree, and check all the ''LTTng *'' features.
+
** If you do not see any LTTng* entry, it means you already have the latest versions installed. This may happen if you downloaded a Service Release that includes the latest Linux Tools stable release. You can skip the rest and go back to your real Eclipse.
+
 
+
* Click Next, Next, Finish. The new versions of the plugins will be downloaded and installed.
+
* Eclipse will offer to restart at this point. It might be a good idea to restart and make sure that the correct versions are installed.
+
 
+
Once you are done, close the baseline Eclipse. You should never have to run this installation, other than to update it.
+
 
+
==== Set up your regular Eclipse to use the baseline ====
+
* In your regular Eclipse install, go to "Window -> Preferences -> Plug-in Development -> API Baselines".
+
* Click on "Add Baseline..."
+
* In the new window click "Browse...", and point it to the directory of the baseline Eclipse install you set up earlier.
+
* Give your baseline a name, then click "Finish".
+
 
+
Once that is done, your workspace will be rebuilt and the API changes will now be tracked. Any new method or class will have to be annotated with "@since n", where n is the major.minor version number found in the plugin's MANIFEST.MF file.
+
 
+
= Run (or Debug) the plugins =
+
 
+
To run (or debug) the code, start a nested Eclipse with the plugins loaded:
+
 
+
* Select "Run -> Run Configurations" (or Debug -> Debug Configurations)
+
* Select "Eclipse Application"
+
* Click the "New launch configuration" icon
+
* Rename the configuration (e.g. "Eclipse Application")
+
* Select "Program to Run -> Run a product -> org.eclipse.sdk.ide" or "Run an application -> org.eclipse.ui.ide.workbench"
+
* Click Run (or Debug)
+
 
+
The next time you can just select "Eclipse Application" from the Run (or Debug) button menu.
+

Latest revision as of 13:38, 27 October 2014

The Eclipse LTTng (and related) plugins have moved to the Trace Compass project. Updated instructions can now be found on this page.

Back to the top