Difference between revisions of "MemoryAnalyzer/Contributor Reference"

From Eclipsepedia

Jump to: navigation, search
m (New page: == Getting Started == Similar to Mylyn/Contributor Reference this page is meant to help you contribute to the Memory Analyzer project. == Workspace == === Setup === Install Eclipse...)
 
m (Setup)
(42 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 
== Getting Started ==
 
== Getting Started ==
  
Similar to [[Mylyn/Contributor Reference]] this page is meant to help you contribute to the Memory Analyzer project.
+
This page is meant to help you contribute to the Memory Analyzer project.
  
 
== Workspace ==
 
== Workspace ==
Line 8: Line 8:
  
 
Install Eclipse and configure it to develop Java 5 applications.
 
Install Eclipse and configure it to develop Java 5 applications.
* We usually use the [http://download.eclipse.org/eclipse/downloads/ latest milestone build] from the 3.4 train. However, as of today, a 3.3er release works just as well.
+
* You can use 3.x or 4.x as you prefer.
* Install [http://www.eclipse.org/birt/phoenix/ BIRT] via the Update Manager: ''Help -> Software Updates...'' and select the Update Site appropriate for your release (e.g. ''Europa Discovery Site'')
+
** While working with the 3.4 release candidates, I found the following approach the simplest: download the appropriate milestone/release candidate build plus all requirements from BIRT's [http://download.eclipse.org/birt/downloads/build_list.php Recent Build Page] and unzip 'em into the dropins folder: '''Chart Engine, DTP, EMF+XSD, GEF Runtime'''
+
* Install the [http://www.eclipse.org/subversive/downloads.php Subversion Team Provider]
+
  
=== Checkout ===
+
Setup your development environment:
 +
* Via the Update Manager ''Help -> Install New Software...'' install:
 +
** Subversive SVN Team Provider
 +
** Subversive SVN Connectors (See [http://www.eclipse.org/subversive/downloads.php Subversion Team Provider] Download Page for the Update Site URL)
 +
** Eclipse BIRT Framework
 +
** IBM Diagnostic Tool Framework for Java (See [http://www.ibm.com/developerworks/java/jdk/tools/dtfj.html IBM Diagnostic Tool Framework for Java Version 1.5] to find the archived Update Site.) This is needed to compile and run with the DTFJ adapter which is part of Memory Analyzer and allows Memory Analyzer to read dumps from IBM virtual machines for Java.
 +
* Configure the Code Formatter Template:
 +
** ''Preferences -> Java -> Code Style -> Formatter -> Import...'' and import this [http://www.eclipse.org/mat/dev/mat_code_formatter.xml template].
  
As the project is still in incubation, you'll find only the trunk code line. Check out the projects by saving <code>[http://www.eclipse.org/mat/dev/mat.psf mat.psf]</code> file locally, and then using ''File -> Import -> Team Project Set''. Use user name "anonymous" and an empty password.
+
=== Checkout ===
  
More infos: [[SVN_Howto]], [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mat/?root=Technology_SVN Web Access]
+
The MAT repository in SVN is: https://dev.eclipse.org/svnroot/tools/org.eclipse.mat/
 +
 
 +
The branch with the most recent development is 'trunk'.
 +
 
 +
If you do not intend to build the MAT update site and standalone distributions, then it is enough to chech out only the MAT plugins. Check out the projects by saving <code>[http://www.eclipse.org/mat/dev/mat.psf mat.psf]</code> file locally, and then using ''File -&gt; Import -&gt; Team Project Set''. Use user name "anonymous" and an empty password.
 +
 
 +
If you want to run locally the Maven/Tycho build for MAT, which produces an update site and standalone RCP products, follow the checkout instructions on the build Wiki page: [[MemoryAnalyzer/Building_MAT_With_Tycho#Checkout_MAT_Sources_from_SVN]]
 +
 
 +
More information: [[SVN Howto]], [http://dev.eclipse.org/viewcvs/index.cgi/?root=TOOLS_MAT Web Access], [[MemoryAnalyzer/Building_MAT_With_Tycho]]
 +
 
 +
If you do not have BIRT installed then there will be compilation errors in the org.eclipse.mat.chart and org.eclipse.mat.chart.ui projects.
 +
 
 +
If you do not have the IBM DTFJ feature installed then there will be compilation errors in the org.eclipse.mat.dtfj project.
 +
 
 +
=== Configure API Tooling Baseline ===
 +
 
 +
In order to guarantee that no API breaking changes are introduced we recomment using the PDE API Tooling and defining the latest released version of MAT as an API Baseline. Here is a short description how this could be done:
 +
 
 +
* Download the latest released version in order to use it as an API Baseline
 +
** Go to the [http://www.eclipse.org/mat/downloads.php MAT download page]
 +
** Download the "Archived Update Site" zip file for the latest release
 +
** Unzip the file somewhere locally
 +
* Configure the API Baseline in the IDE
 +
** In the IDE open '' Window -> Preferences -> Plug-in Development -> API Baselines ''
 +
** Press ''Add Baseline''
 +
** Browse and select as ''Location'' the directory in which the zip was extracted
 +
** Enter a name for the baseline, click ''Finish'' and confirm the rest of the dialogs
 +
 
 +
Once the API Tooling is properly setup, one will see errors reported if API changes are introduced.
  
 
=== Launch Configuration ===
 
=== Launch Configuration ===
Line 27: Line 59:
 
** Deselect ''org.eclipse.mat.tests''
 
** Deselect ''org.eclipse.mat.tests''
 
** Deselect ''Target Platform'' and click ''Add Required Plug-ins''
 
** Deselect ''Target Platform'' and click ''Add Required Plug-ins''
** Select ''org.eclipse.pde.runtime'' (3.3) or ''org.eclipse.ui.views.log'' (3.4) to include the Error Log
+
** Select ''org.eclipse.pde.runtime'' (3.3) or ''org.eclipse.ui.views.log'' (3.4 or later) to include the Error Log
 +
** Select ''com.ibm.dtfj.api'' ''com.ibm.dtfj.j9'' ''com.ibm.dtfj.phd'' ''com.ibm.dtfj.sov'' if you have installed the IBM DTFJ feature and wish to process dumps from IBM virtual machines
 +
** Select ''com.ibm.java.doc.tools.dtfj'' for help for IBM DTFJ
 
or as '''feature plugged into the IDE''':
 
or as '''feature plugged into the IDE''':
 
* Create a new ''Eclipse Application'' configuration
 
* Create a new ''Eclipse Application'' configuration
Line 33: Line 67:
 
* Launch with: ''plug-ins selected below only''
 
* Launch with: ''plug-ins selected below only''
 
** Deselect ''org.eclipse.mat.tests'' and ''org.eclipse.mat.ui.rcp''
 
** Deselect ''org.eclipse.mat.tests'' and ''org.eclipse.mat.ui.rcp''
 +
** Select ''com.ibm.dtfj.api'' ''com.ibm.dtfj.j9'' ''com.ibm.dtfj.phd'' ''com.ibm.dtfj.sov'' if you have installed the IBM DTFJ feature and wish to process dumps from IBM virtual machines
 +
** Select ''com.ibm.java.doc.tools.dtfj'' for help for IBM DTFJ
 +
 +
=== Create a Stand-Alone RCP ===
 +
 +
See [[MemoryAnalyzer/Building MAT With Tycho]] if you want to produce a standalone MAT.
  
 
=== JUnit Tests ===
 
=== JUnit Tests ===
  
 
The unit tests a placed in the ''org.eclipse.mat.tests'' project. Execute the tests by right-clicking on the project and choose ''Run As... -> JUnit Plug-in Test''.
 
The unit tests a placed in the ''org.eclipse.mat.tests'' project. Execute the tests by right-clicking on the project and choose ''Run As... -> JUnit Plug-in Test''.
 +
 +
The following VM arguments are required in the run configuration for the JUnit Plug-in Test:
 +
''-Xmx850m -ea''
 +
 +
=== Build Help with DITA ===
 +
 +
* Download [http://downloads.sourceforge.net/dita-ot/DITA-OT1.4.2.1_full_easy_install_bin.zip?modtime=1210005901&big_mirror=0 DITA-OT1.4.2.1] and unzip it into C:\DITA-OT1.4.2.1
 +
* In plugin '''org.eclipse.mat.ui.help''' select '''DitaBuild.xml''' and configure the runtime configuration:
 +
** right click ''Run As > Ant Build...''
 +
** add all the libraries from C:\DITA-OT1.4.2.1\lib into the classpath
 +
* To modify Help documentation modify xml files
 +
** XML Buddy - might not be available anymore
 +
*** [http://www.xmlbuddy.com Download XMLBuddy] and copy a product directory (e.g., com.objfac.xmleditor_2.0_72) to the plugins directory of your Eclipse installation.
 +
*** Configure XMLBuddy editor as described [http://www.ditainfocenter.com/eclipsehelp/index.jsp?topic=/ditaotug_top/settingup/configuring_xmlbuddy.html here]
 +
** or use the XML editor from Eclipse Web Tools
 +
*** Window > Preferences > XML > XML files > Validation > Enable markup validation
 +
*** Window > Preferences > Validator > XML Validator > Settings > Include Group > Add Rule > File extensions : dita
 +
*** Window > Preferences > XML > XML Catalog > User supplied entries > Link reference.dtd, task.dtd, concept.dtd to the corresponding files in the Dita directory /dtd/technicalContent/dtd
 +
* Run ant on DitaBuild.xml to build html files.
 +
 +
=== Build OQL Parser using JavaCC ===
 +
 +
* Download [http://java.net/projects/javacc/downloads/download/javacc-5.0.tar.gz JavaCC 5.0 tar.gz] or [http://java.net/projects/javacc/downloads/download/javacc-5.0.zip JavaCC 5.0 zip] and unpack it.
 +
* Copy javacc.jar to the root of the '''org.eclipse.mat.parser''' project
 +
* In plugin '''org.eclipse.mat.parser''' select '''build_javacc.xml'''
 +
** right click ''Run As > Ant Build...''
 +
* Select package '''org.eclipse.mat.parser.internal.oql.parser'''
 +
** Source > Organize Imports
 +
** Source > Format
 +
** Ignore the choice conflict message and non-ASCII character message
 +
** Synchronize with the source repository to add the copyright header etc. back in
 +
 +
== Building MAT with Maven/Tycho ==
 +
 +
The following page describes how Memory Analyzer (p2 repository and standalone RCP applications) can be build using Maven/Tycho: [[MemoryAnalyzer/Building MAT With Tycho]]
  
 
== Ideas for Contributions ==
 
== Ideas for Contributions ==
  
This is an initial list of ideas. If you are missing a feature and have some time to contribute, please do not hesitate to contact us.
+
This is just a short list of ideas. If you are missing a feature and have some time to contribute, please do not hesitate to contact us.
 +
 
 +
* Extensions to the tool adding application knowledge: MAT provides some extension points which can help you to plug-in pieces of information that give meaning to your specific object structures. It would be nice to have in MAT application knowlegde about prominent open source projects, e.g. different Eclipse components, servers like Tomcat and Glassfish, etc... Some examples:
 +
** using an org.eclipse.mat.api.nameResolver extension one can specify what description should be shown next to an object, similar to a toString() method. See for example [https://bugs.eclipse.org/bugs/show_bug.cgi?id=273915 bug 273915 ]
 +
** using an org.eclipse.mat.api.requestResolver extension one can add to the leak report information about what a threads was executing, e.g. tell which HTTP request it was processing, list the URL, parameters, etc... For example [https://bugs.eclipse.org/bugs/show_bug.cgi?id=318989 bug 318989] proposes an extension which points to the ruby script a thread is executing
 +
** using an org.eclipse.mat.api.query extension one can add a useful query which will be available all the other queries/commands seen in the tool. See for example [https://bugs.eclipse.org/bugs/show_bug.cgi?id=256154 bug 256154]
 +
* Documentation
 +
* Unit Tests
 +
 
 +
== Writing plugins for the Memory Analyzer  ==
 +
 
 +
If you want to write a plugin for the Memory Analyzer, you can find information on the following pages:
 +
 
 +
*[[MemoryAnalyzer/Reading Data from Heap Dumps]]
 +
*[[MemoryAnalyzer/Extending Memory Analyzer]]
 +
*[[MemoryAnalyzer/Adding a new heap dump format to the Memory Analyzer]]
 +
 
 +
You should develop and test your plug-ins using the Eclipse environment, making sure that your plug-in is listed in the run configuration. Memory Analyzer uses the p2 installer [[Equinox p2 Getting Started]]. To get your plug-in installed in standalone version of MAT then you need to build an Eclipse feature or update site including your plug-in, then install the feature or update site into MAT.
 +
 
 +
Help &gt; Install New Software &gt; Add &gt; Archive &gt; your exported feature
 +
 
 +
You may need to deselect 'Group items by category' if your feature does not have categories.
 +
 
 +
If you wish to import an plug-in without building a feature then you need to create a dropins folder under the mat directory in MAT, put your plug-in jar there, then restart MAT with
 +
MemoryAnalyzer -console
 +
and type
 +
start org.eclipse.equinox.p2.reconciler.dropins
 +
in the console so that the p2 installer will look in the plugins directory for your plug-ins.
 +
 
 +
== Simultaneous release policies ==
 +
[http://wiki.eclipse.org/MemoryAnalyzer/Retention_policy Retention policy]
 +
[http://wiki.eclipse.org/MemoryAnalyzer/API_policy API Policy]
 +
[http://wiki.eclipse.org/MemoryAnalyzer/MAT_Capabilities Capabilities]
 +
 
 +
== Maintaining MAT Website ==
  
* Application Knowledge: Name/Request Resolvers for major open source projects: Glassfish, JBoss, Jetty, Tomcat ...
+
See [[MemoryAnalyzer/Contributor Reference/Website]]
* Open Java Source file via context menu of a class
+
* Check WeakHashMaps: find those where the value references the key and hence prevents garbage collection
+
* Documentation and Unit Tests (pretty lame, but much appreciated!)
+

Revision as of 10:42, 23 November 2012

Contents

Getting Started

This page is meant to help you contribute to the Memory Analyzer project.

Workspace

Setup

Install Eclipse and configure it to develop Java 5 applications.

  • You can use 3.x or 4.x as you prefer.

Setup your development environment:

  • Via the Update Manager Help -> Install New Software... install:
    • Subversive SVN Team Provider
    • Subversive SVN Connectors (See Subversion Team Provider Download Page for the Update Site URL)
    • Eclipse BIRT Framework
    • IBM Diagnostic Tool Framework for Java (See IBM Diagnostic Tool Framework for Java Version 1.5 to find the archived Update Site.) This is needed to compile and run with the DTFJ adapter which is part of Memory Analyzer and allows Memory Analyzer to read dumps from IBM virtual machines for Java.
  • Configure the Code Formatter Template:
    • Preferences -> Java -> Code Style -> Formatter -> Import... and import this template.

Checkout

The MAT repository in SVN is: https://dev.eclipse.org/svnroot/tools/org.eclipse.mat/

The branch with the most recent development is 'trunk'.

If you do not intend to build the MAT update site and standalone distributions, then it is enough to chech out only the MAT plugins. Check out the projects by saving mat.psf file locally, and then using File -> Import -> Team Project Set. Use user name "anonymous" and an empty password.

If you want to run locally the Maven/Tycho build for MAT, which produces an update site and standalone RCP products, follow the checkout instructions on the build Wiki page: MemoryAnalyzer/Building_MAT_With_Tycho#Checkout_MAT_Sources_from_SVN

More information: SVN Howto, Web Access, MemoryAnalyzer/Building_MAT_With_Tycho

If you do not have BIRT installed then there will be compilation errors in the org.eclipse.mat.chart and org.eclipse.mat.chart.ui projects.

If you do not have the IBM DTFJ feature installed then there will be compilation errors in the org.eclipse.mat.dtfj project.

Configure API Tooling Baseline

In order to guarantee that no API breaking changes are introduced we recomment using the PDE API Tooling and defining the latest released version of MAT as an API Baseline. Here is a short description how this could be done:

  • Download the latest released version in order to use it as an API Baseline
    • Go to the MAT download page
    • Download the "Archived Update Site" zip file for the latest release
    • Unzip the file somewhere locally
  • Configure the API Baseline in the IDE
    • In the IDE open Window -> Preferences -> Plug-in Development -> API Baselines
    • Press Add Baseline
    • Browse and select as Location the directory in which the zip was extracted
    • Enter a name for the baseline, click Finish and confirm the rest of the dialogs

Once the API Tooling is properly setup, one will see errors reported if API changes are introduced.

Launch Configuration

Launch the Memory Analyzer as stand-alone RCP:

  • Create a new Eclipse Application configuration
  • Run a product: org.eclipse.mat.ui.rcp.MemoryAnalyzer
  • Launch with: plug-ins selected below only
    • Deselect org.eclipse.mat.tests
    • Deselect Target Platform and click Add Required Plug-ins
    • Select org.eclipse.pde.runtime (3.3) or org.eclipse.ui.views.log (3.4 or later) to include the Error Log
    • Select com.ibm.dtfj.api com.ibm.dtfj.j9 com.ibm.dtfj.phd com.ibm.dtfj.sov if you have installed the IBM DTFJ feature and wish to process dumps from IBM virtual machines
    • Select com.ibm.java.doc.tools.dtfj for help for IBM DTFJ

or as feature plugged into the IDE:

  • Create a new Eclipse Application configuration
  • Run a product: org.eclipse.sdk.ide
  • Launch with: plug-ins selected below only
    • Deselect org.eclipse.mat.tests and org.eclipse.mat.ui.rcp
    • Select com.ibm.dtfj.api com.ibm.dtfj.j9 com.ibm.dtfj.phd com.ibm.dtfj.sov if you have installed the IBM DTFJ feature and wish to process dumps from IBM virtual machines
    • Select com.ibm.java.doc.tools.dtfj for help for IBM DTFJ

Create a Stand-Alone RCP

See MemoryAnalyzer/Building MAT With Tycho if you want to produce a standalone MAT.

JUnit Tests

The unit tests a placed in the org.eclipse.mat.tests project. Execute the tests by right-clicking on the project and choose Run As... -> JUnit Plug-in Test.

The following VM arguments are required in the run configuration for the JUnit Plug-in Test: -Xmx850m -ea

Build Help with DITA

  • Download DITA-OT1.4.2.1 and unzip it into C:\DITA-OT1.4.2.1
  • In plugin org.eclipse.mat.ui.help select DitaBuild.xml and configure the runtime configuration:
    • right click Run As > Ant Build...
    • add all the libraries from C:\DITA-OT1.4.2.1\lib into the classpath
  • To modify Help documentation modify xml files
    • XML Buddy - might not be available anymore
      • Download XMLBuddy and copy a product directory (e.g., com.objfac.xmleditor_2.0_72) to the plugins directory of your Eclipse installation.
      • Configure XMLBuddy editor as described here
    • or use the XML editor from Eclipse Web Tools
      • Window > Preferences > XML > XML files > Validation > Enable markup validation
      • Window > Preferences > Validator > XML Validator > Settings > Include Group > Add Rule > File extensions : dita
      • Window > Preferences > XML > XML Catalog > User supplied entries > Link reference.dtd, task.dtd, concept.dtd to the corresponding files in the Dita directory /dtd/technicalContent/dtd
  • Run ant on DitaBuild.xml to build html files.

Build OQL Parser using JavaCC

  • Download JavaCC 5.0 tar.gz or JavaCC 5.0 zip and unpack it.
  • Copy javacc.jar to the root of the org.eclipse.mat.parser project
  • In plugin org.eclipse.mat.parser select build_javacc.xml
    • right click Run As > Ant Build...
  • Select package org.eclipse.mat.parser.internal.oql.parser
    • Source > Organize Imports
    • Source > Format
    • Ignore the choice conflict message and non-ASCII character message
    • Synchronize with the source repository to add the copyright header etc. back in

Building MAT with Maven/Tycho

The following page describes how Memory Analyzer (p2 repository and standalone RCP applications) can be build using Maven/Tycho: MemoryAnalyzer/Building MAT With Tycho

Ideas for Contributions

This is just a short list of ideas. If you are missing a feature and have some time to contribute, please do not hesitate to contact us.

  • Extensions to the tool adding application knowledge: MAT provides some extension points which can help you to plug-in pieces of information that give meaning to your specific object structures. It would be nice to have in MAT application knowlegde about prominent open source projects, e.g. different Eclipse components, servers like Tomcat and Glassfish, etc... Some examples:
    • using an org.eclipse.mat.api.nameResolver extension one can specify what description should be shown next to an object, similar to a toString() method. See for example bug 273915
    • using an org.eclipse.mat.api.requestResolver extension one can add to the leak report information about what a threads was executing, e.g. tell which HTTP request it was processing, list the URL, parameters, etc... For example bug 318989 proposes an extension which points to the ruby script a thread is executing
    • using an org.eclipse.mat.api.query extension one can add a useful query which will be available all the other queries/commands seen in the tool. See for example bug 256154
  • Documentation
  • Unit Tests

Writing plugins for the Memory Analyzer

If you want to write a plugin for the Memory Analyzer, you can find information on the following pages:

You should develop and test your plug-ins using the Eclipse environment, making sure that your plug-in is listed in the run configuration. Memory Analyzer uses the p2 installer Equinox p2 Getting Started. To get your plug-in installed in standalone version of MAT then you need to build an Eclipse feature or update site including your plug-in, then install the feature or update site into MAT.

Help > Install New Software > Add > Archive > your exported feature

You may need to deselect 'Group items by category' if your feature does not have categories.

If you wish to import an plug-in without building a feature then you need to create a dropins folder under the mat directory in MAT, put your plug-in jar there, then restart MAT with

MemoryAnalyzer -console 

and type

start org.eclipse.equinox.p2.reconciler.dropins 

in the console so that the p2 installer will look in the plugins directory for your plug-ins.

Simultaneous release policies

Retention policy API Policy Capabilities

Maintaining MAT Website

See MemoryAnalyzer/Contributor Reference/Website