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 "MemoryAnalyzer/Contributor Reference"

m (Simultaneous release policies)
(Building MAT with Maven/Tycho)
(38 intermediate revisions by 4 users not shown)
Line 14: Line 14:
 
Setup your development environment:
 
Setup your development environment:
 
* Via the Update Manager ''Help -> Install New Software...'' install:
 
* 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
 
** 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.
+
** 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.11] to find the 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:
 
* 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].
 
** ''Preferences -> Java -> Code Style -> Formatter -> Import...'' and import this [http://www.eclipse.org/mat/dev/mat_code_formatter.xml template].
  
=== Checkout  ===
+
=== Get the source===
  
The MAT repository in SVN is: https://dev.eclipse.org/svnroot/tools/org.eclipse.mat/
+
Since December 2014 the Memory Analyzer code is stored in a git repository. The URLs to access it are:
  
The branch with the most recent development is 'trunk'.
+
<nowiki>ssh://<username>@git.eclipse.org:29418/mat/org.eclipse.mat</nowiki>
  
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.
+
<nowiki>https://<username>@git.eclipse.org/r/mat/org.eclipse.mat</nowiki>
  
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]]
+
A web browsable repository is available at
 +
https://git.eclipse.org/c/mat/org.eclipse.mat.git/
  
More information: [[SVN Howto]], [http://dev.eclipse.org/viewcvs/index.cgi/?root=TOOLS_MAT Web Access], [[MemoryAnalyzer/Building_MAT_With_Tycho]]  
+
The Eclipse Memory Analyzer project also uses Gerrit, and the Gerrit code reviews are at: https://git.eclipse.org/r/#/q/mat/org.eclipse.mat
 +
 
 +
and the Gerrit version of the source repositories is available at:
 +
<nowiki>ssh://git.eclipse.org:29418/mat/org.eclipse.mat</nowiki>
 +
https://git.eclipse.org/c/gerrit/mat/org.eclipse.mat.git
 +
 
 +
You can clone the repository using your favorite Git client. More information: [[Git]], [[EGit/User Guide]].
 +
 
 +
There are eclipse .project files, so that the projects (plugins, features, etc...) can be easily imported into the Eclipse IDE.
 +
 
 +
If you do not intend to build the MAT update site and standalone distributions, then it is enough to import only the MAT plugins.
 +
 
 +
If you want to run locally the Maven/Tycho build for MAT, which produces an update site and standalone RCP products, follow the instructions on the build Wiki page: [[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 BIRT installed then there will be compilation errors in the org.eclipse.mat.chart and org.eclipse.mat.chart.ui projects.
Line 48: Line 59:
 
** In the IDE open '' Window -> Preferences -> Plug-in Development -> API Baselines ''
 
** In the IDE open '' Window -> Preferences -> Plug-in Development -> API Baselines ''
 
** Press ''Add Baseline''
 
** Press ''Add Baseline''
 +
** Select ''An Existing Eclipse installation Directory'' as the source for this baseline.
 
** Browse and select as ''Location'' the directory in which the zip was extracted
 
** 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
 
** Enter a name for the baseline, click ''Finish'' and confirm the rest of the dialogs
Line 59: Line 71:
 
* Run a product: ''org.eclipse.mat.ui.rcp.MemoryAnalyzer''
 
* Run a product: ''org.eclipse.mat.ui.rcp.MemoryAnalyzer''
 
* Launch with: ''plug-ins selected below only''
 
* Launch with: ''plug-ins selected below only''
** Deselect ''org.eclipse.mat.tests''
+
** Deselect ''org.eclipse.mat.tests'' and ''org.eclipse.mat.ui.rcp.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 or later) 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.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
 
** Select ''com.ibm.java.doc.tools.dtfj'' for help for IBM DTFJ
 +
** Eclipse >= Neon: Select ''org.eclipse.equinox.ds'' and ''org.eclipse.equinox.event''
 
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 71: Line 84:
 
** 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.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
 
** Select ''com.ibm.java.doc.tools.dtfj'' for help for IBM DTFJ
 +
** Eclipse >= Neon: Select ''org.eclipse.equinox.ds'' and ''org.eclipse.equinox.event''
 +
** Eclipse >= Oxygen: Select ''org.eclipse.equinox.event''
  
 
=== Create a Stand-Alone RCP ===
 
=== Create a Stand-Alone RCP ===
Line 82: Line 97:
 
The following VM arguments are required in the run configuration for the JUnit Plug-in Test:  
 
The following VM arguments are required in the run configuration for the JUnit Plug-in Test:  
 
''-Xmx850m -ea''
 
''-Xmx850m -ea''
 +
 +
For the ''org.eclipse.mat.rcp.tests'' project install SWTBot - API from [https://www.eclipse.org/swtbot/].
  
 
=== Build Help with DITA ===
 
=== 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
+
* Download [http://downloads.sourceforge.net/dita-ot/DITA-OT1.7.4_full_easy_install_bin.zip?modtime=1210005901&big_mirror=0 DITA-OT1.7.4] and unzip it into somewhere on your disk, e.g. C:\DITA-OT1.7.4. Please stick to this DITA version, it is the one with which the help pages are currently built. Using a different version results in many unnecessary file changes to the generated files (which are also committed in the git repository).
 +
 
 
* In plugin '''org.eclipse.mat.ui.help''' select '''DitaBuild.xml''' and configure the runtime configuration:
 
* In plugin '''org.eclipse.mat.ui.help''' select '''DitaBuild.xml''' and configure the runtime configuration:
 
** right click ''Run As > Ant Build...''
 
** right click ''Run As > Ant Build...''
** add all the libraries from C:\DITA-OT1.4.2.1\lib into the classpath
+
** configure the DITA directory and libraries:
** to use another version of DITA-OT such as 1.5.4 or 1.7.4 or DITA-OT installed in another location
+
 
*** add property dita.dir (this overrides the version in DitaBuild.xml)
 
*** add property dita.dir (this overrides the version in DitaBuild.xml)
 
**** Properties
 
**** Properties
Line 97: Line 114:
 
**** New
 
**** New
 
***** Name: dita_home
 
***** Name: dita_home
***** Value: C:\DITA-OT1.7.4
+
***** Value: the location of DITA, e.g. C:\DITA-OT1.7.4
 
***** OK
 
***** OK
 
**** Select Variable dita_home OK
 
**** Select Variable dita_home OK
Line 118: Line 135:
 
*** Window > Preferences > XML > XML files > Validation > Enable markup validation
 
*** Window > Preferences > XML > XML files > Validation > Enable markup validation
 
*** Window > Preferences > Validator > XML Validator > Settings > Include Group > Add Rule > File extensions : dita
 
*** 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
+
*** 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 as Key type 'Public ID' Key '-//OASIS//DTD DITA Reference//EN' '-//OASIS//DTD DITA Task//EN' or '-//OASIS//DTD DITA Concept//EN'
 
* Run ant on DitaBuild.xml to build html files.
 
* Run ant on DitaBuild.xml to build html files.
  
 
=== Build OQL Parser using JavaCC ===
 
=== 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.
+
* Download [https://javacc.org/downloads/javacc-5.0.tar.gz JavaCC 5.0 tar.gz] or [https://javacc.org/downloads/javacc-5.0.zip JavaCC 5.0 zip] and unpack it.
 
* Copy javacc.jar to the root of the '''org.eclipse.mat.parser''' project
 
* Copy javacc.jar to the root of the '''org.eclipse.mat.parser''' project
 
* In plugin '''org.eclipse.mat.parser''' select '''build_javacc.xml'''
 
* In plugin '''org.eclipse.mat.parser''' select '''build_javacc.xml'''
Line 132: Line 149:
 
** Ignore the choice conflict message and non-ASCII character message
 
** Ignore the choice conflict message and non-ASCII character message
 
** Synchronize with the source repository to add the copyright header etc. back in
 
** Synchronize with the source repository to add the copyright header etc. back in
 +
 +
=== Creating and editing icons ===
 +
 +
Consider using [https://marketplace.eclipse.org/content/eclipaint EcliPaint].
 +
 +
Also see how the icons look in high-contrast mode. See [https://bugs.eclipse.org/bugs/show_bug.cgi?id=342543 Bug 342543 Icon decorators not visible in high contrast mode]
 +
Also consider dark theme: Window > Preferences > General > Appearance > Theme
  
 
== Building MAT with Maven/Tycho ==
 
== 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]]
 
The following page describes how Memory Analyzer (p2 repository and standalone RCP applications) can be build using Maven/Tycho: [[MemoryAnalyzer/Building MAT With Tycho]]
 +
 +
== Testing using Docker ==
 +
 +
It is possible to [[MemoryAnalyzer/Docker|run Memory Analyzer in a Docker container]], which might allow testing on different Linux distributions
  
 
== Ideas for Contributions ==
 
== Ideas for Contributions ==
Line 147: Line 175:
 
* Documentation
 
* Documentation
 
* Unit Tests
 
* Unit Tests
 +
 +
== Contributing code ==
 +
 +
Eclipse Memory Analyzer uses [[Gerrit]] for contributions, including from committers. Contributions are pushed to Gerrit using these [[#Get_the_source|URLs]], not directly to Git. After an approval process (including the [[Development_Resources#Everyone:_IP_Cleanliness|Eclipse IP process]]) by MAT committers, the contributions are pushed by Gerrit to the main Eclipse Git repository. The code is then build by [https://ci.eclipse.org/mat/job/tycho-mat-nightly/ Jenkins].
 +
 +
Example Workflow
 +
 +
* Open a bug at https://bugs.eclipse.org/bugs/enter_bug.cgi?product=MAT
 +
* Open Eclipse's Git perspective
 +
* Right click on the repository and click Pull to get the latest changes
 +
* Right click on the repository and click Switch To > New Branch and enter an arbitrary branch name (perhaps with the bug number) and click Finish
 +
* Make your code changes
 +
* Format your code to the project standards using [http://www.eclipse.org/mat/dev/mat_code_formatter.xml MAT code style format]
 +
* Run org.eclipse.mat.tests as a Junit Plugin Test and org.eclipse.mat.rcp.tests as an SWTBot test and ensure all pass
 +
* Switch to the Team Synchronizing perspective and review your changes
 +
* Add the changes you want to commit to the index (e.g. right click on the project and click Add to Index)
 +
* Right click on the projects/files and click Commit...
 +
* Use the following commit message template:
 +
 +
[Bug ID from step #1 in square brackets] Commit message...
 +
 +
Example:
 +
 +
[497127] Handle copying heapdumps greater than 2GB on certain platforms.
 +
 +
* Click Commit (do not click Commit and Push)
 +
* In the Git perspective, expand org.eclipse.mat > Remotes, then right click on origin, then click Gerrit Configuration..., set destination branch to master and click Finish.
 +
* Right click on org.eclipse.mat and click Push to Gerritt... and click Finish
 +
* The results dialog should show the Gerrit link at the bottom such as https://git.eclipse.org/r/76397
 +
* In the Git perspective, right click the repository and click Switch To > master (now you're back on master without your changes)
 +
* Gerrit requires two code review votes and one verify vote. For trivial changes, you may give the +2/+1 yourself. Otherwise, ideally, two other committers would review and approve your change, but given the size of the team and their limited availability, you may also give your own +1. In the trivial case, add a comment such as "Simple patch; judging it doesn't require others' review so adding +2 code review". To request that a committer reviews your change, click Add next to Reviewers and find the name
 +
* Once the +2 Code Review/+1 Verified exists, a "Submit" button will show up which you can click to push the change to master.
 +
* The bug report will be updated automatically
 +
* Change the bug report to Resolved after testing the changes from a nightly build
 +
 +
 +
If you are asked to modify your Gerrit change, you will need to amend your commit and add a patch set: https://gerrit-review.googlesource.com/Documentation/intro-user.html#upload-patch-set
 +
 +
Note in particular that the amended commit should have "\nChange-Id: ..." at the bottom which matches the Gerrit change.
 +
 +
== Uses Mylyn for handling Bugzilla tasks ==
 +
 +
From the ''Task Repositories'' view add your Bugzilla user ID and password:
 +
 +
* Server: https://bugs.eclipse.org/bugs
 +
* Label: Eclipse.org
 +
* User ID: my_name@example.com
 +
* Password: ********
 +
 +
From the Task List then create a Query: New > Query > Eclipse.org > Create query using form > Next
 +
 +
* Product: MAT
 +
* Status: UNCONFIRMED NEW ASSIGNED REOPENED
 +
 +
This lets you handle Bugzilla from inside Eclipse.
  
 
== Writing plugins for the Memory Analyzer  ==
 
== Writing plugins for the Memory Analyzer  ==
Line 167: Line 250:
 
  start org.eclipse.equinox.p2.reconciler.dropins  
 
  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.
 
in the console so that the p2 installer will look in the plugins directory for your plug-ins.
 +
 +
== New version development process ==
 +
* Document new version at [https://projects.eclipse.org/projects/tools.mat MAT project page]
 +
* Create Bugzilla entries for target milestone [https://dev.eclipse.org/committers/bugs/bugz_manager.php Bugzilla Manager]
 +
* Update references to old release in the code e.g. 1.X -> 1.Y excluding update sites
 +
** See pom.xml e.g. <code>&lt;version&gt;1.9.1-SNAPSHOT&lt;/version&gt;</code>
 +
** See manifest.mf e.g. <code>&lt;Bundle-Version: 1.9.1.qualifier</code>
 +
** See feature.xml, excluding updateSiteName
 +
** See org.eclipse.mat.ui.rcp about.mappings
 +
** org.eclipse.mat.product mat.product
 +
 +
* Develop features and fix bugs
 +
* If a plugin depends on new function in another plugin, update the dependency version in manifest.mf
 +
* If creating a new plugin, add it to the JavaDoc build process in extrabuild.xml, use package-info.java to mark packages as not API or API as appropriate. Consider carefully adding new APIs.
 +
* If the Java version changes then the minor version must increase, also change:
 +
** .classpath
 +
** .settings/org.eclipse.jdt.core.prefs
 +
** manifest.mf <code>Bundle-RequiredExecutionEnvironment: J2SE-1.5</code>
 +
** Update org.eclipse.ui.help extrabuild.xml for the new JavaDoc compile level, and for the link to the Java class library documentation
 +
** Consider keeping org.eclipse.mat.ibmdumps at a lower level as it uses classes for the exec dump provider and the attach jar which may be executed on lower level JVMs.
 +
* If the RCP is to be built against a newer version of Eclipse, then:
 +
** create a new target platform in org.eclipse.mat.targetdef
 +
** update org.eclipse.mat.ui.help extrabuild.xml to add a link to the Eclipse help for the platform
 +
* Towards the end, change the update site references
 +
** See feature.xml, including updateSiteName
 +
* Also write a New and Noteworthy document replacing the previous release, and add a link to the old document on the MAT website.
 +
* Follow [[MemoryAnalyzer/Contributor Reference#Simultaneous release policies]]
 +
* After release create Bugzilla entry for the new version [https://dev.eclipse.org/committers/bugs/bugz_manager.php Bugzilla Manager]
  
 
== Simultaneous release policies ==
 
== Simultaneous release policies ==
[[MemoryAnalyzer/Ramp Down Plan|Ramp Down Plan]]
+
* For reference, to [[Simrel/Contributing_to_Simrel_Aggregation_Build|contribute to the Simultaneous Release Build]]
[[MemoryAnalyzer/Retention_policy|Retention Policy]]
+
* [https://ci.eclipse.org/mat/job/prepare_simrel_contribution/ Build] to copy update site build to SimRel location.
[[MemoryAnalyzer/API_policy|API Policy]]
+
* Preserve the [https://ci.eclipse.org/mat/job/tycho-mat-nightly/ tycho-build-nightly] as 'Keep forever' and label it with the release build e.g. 'Photon RC2'
[[MemoryAnalyzer/MAT_Capabilities|Capabilities]]
+
* The [http://git.eclipse.org/c/simrel/org.eclipse.simrel.build.git/tree/mat.aggrcon MAT configuration file] which is updated using Gerrit/Git to match the SimRel location.
 +
* Tag in Git with 'R_1.X.Y' the source used to generate the final build for a release. See [https://git.eclipse.org/c/gerrit/mat/org.eclipse.mat.git/refs/ MAT Git Refs]
 +
* To release, also run the [https://ci.eclipse.org/mat/job/mat-standalone-packages/ Stand-alone packing build] and copy the results to the download site
 +
* Also release on [https://marketplace.eclipse.org/content/memory-analyzer-0 Eclipse Marketplace]
 +
* Also consider archiving some old releases
 +
 
 +
 
 +
MAT Policies - to satisfy [[SimRel/Simultaneous_Release_Requirements/Appendix]]
 +
* [[MemoryAnalyzer/Ramp Down Plan|Ramp Down Plan]]
 +
* [[MemoryAnalyzer/Retention_policy|Retention Policy]]
 +
* [[MemoryAnalyzer/API_policy|API Policy]]
 +
* [[MemoryAnalyzer/MAT_Capabilities|Capabilities]]
  
 
== Maintaining MAT Website ==
 
== Maintaining MAT Website ==
  
 
See [[MemoryAnalyzer/Contributor Reference/Website]]
 
See [[MemoryAnalyzer/Contributor Reference/Website]]

Revision as of 11:15, 16 February 2020

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:
    • Eclipse BIRT Framework
    • IBM Diagnostic Tool Framework for Java (See IBM Diagnostic Tool Framework for Java Version 1.11 to find the 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.

Get the source

Since December 2014 the Memory Analyzer code is stored in a git repository. The URLs to access it are:

ssh://<username>@git.eclipse.org:29418/mat/org.eclipse.mat

https://<username>@git.eclipse.org/r/mat/org.eclipse.mat

A web browsable repository is available at https://git.eclipse.org/c/mat/org.eclipse.mat.git/

The Eclipse Memory Analyzer project also uses Gerrit, and the Gerrit code reviews are at: https://git.eclipse.org/r/#/q/mat/org.eclipse.mat

and the Gerrit version of the source repositories is available at:

ssh://git.eclipse.org:29418/mat/org.eclipse.mat
https://git.eclipse.org/c/gerrit/mat/org.eclipse.mat.git

You can clone the repository using your favorite Git client. More information: Git, EGit/User Guide.

There are eclipse .project files, so that the projects (plugins, features, etc...) can be easily imported into the Eclipse IDE.

If you do not intend to build the MAT update site and standalone distributions, then it is enough to import only the MAT plugins.

If you want to run locally the Maven/Tycho build for MAT, which produces an update site and standalone RCP products, follow the instructions on the build Wiki page: 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
    • Select An Existing Eclipse installation Directory as the source for this 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 and org.eclipse.mat.ui.rcp.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
    • Eclipse >= Neon: Select org.eclipse.equinox.ds and org.eclipse.equinox.event

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
    • Eclipse >= Neon: Select org.eclipse.equinox.ds and org.eclipse.equinox.event
    • Eclipse >= Oxygen: Select org.eclipse.equinox.event

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

For the org.eclipse.mat.rcp.tests project install SWTBot - API from [1].

Build Help with DITA

  • Download DITA-OT1.7.4 and unzip it into somewhere on your disk, e.g. C:\DITA-OT1.7.4. Please stick to this DITA version, it is the one with which the help pages are currently built. Using a different version results in many unnecessary file changes to the generated files (which are also committed in the git repository).
  • In plugin org.eclipse.mat.ui.help select DitaBuild.xml and configure the runtime configuration:
    • right click Run As > Ant Build...
    • configure the DITA directory and libraries:
      • add property dita.dir (this overrides the version in DitaBuild.xml)
        • Properties
        • Add Property
        • Variables
        • Edit Variables
        • New
          • Name: dita_home
          • Value: the location of DITA, e.g. C:\DITA-OT1.7.4
          • OK
        • Select Variable dita_home OK
        • Add Property
          • Name = dita.dir
          • Value ${dita_home}
      • add all the libraries from C:\DITA-OT1.7.4\lib into the classpath
      • add all the libraries from C:\DITA-OT1.7.4\lib\saxon into the classpath
      • add variable ${dita_home}\lib into the classpath (this allows configuration.properties to be found)
    • Alternatively to run DITA-OT from the command line
      • run 'startcmd.bat' from the dita directory
      • change to the org.eclipse.mat.ui.help directory
      • edit DitaBuild.xml dita.dir to point to the dita installation
      • ant -f DitaBuild.xml
  • 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 as Key type 'Public ID' Key '-//OASIS//DTD DITA Reference//EN' '-//OASIS//DTD DITA Task//EN' or '-//OASIS//DTD DITA Concept//EN'
  • 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

Creating and editing icons

Consider using EcliPaint.

Also see how the icons look in high-contrast mode. See Bug 342543 Icon decorators not visible in high contrast mode Also consider dark theme: Window > Preferences > General > Appearance > Theme

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

Testing using Docker

It is possible to run Memory Analyzer in a Docker container, which might allow testing on different Linux distributions

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

Contributing code

Eclipse Memory Analyzer uses Gerrit for contributions, including from committers. Contributions are pushed to Gerrit using these URLs, not directly to Git. After an approval process (including the Eclipse IP process) by MAT committers, the contributions are pushed by Gerrit to the main Eclipse Git repository. The code is then build by Jenkins.

Example Workflow

  • Open a bug at https://bugs.eclipse.org/bugs/enter_bug.cgi?product=MAT
  • Open Eclipse's Git perspective
  • Right click on the repository and click Pull to get the latest changes
  • Right click on the repository and click Switch To > New Branch and enter an arbitrary branch name (perhaps with the bug number) and click Finish
  • Make your code changes
  • Format your code to the project standards using MAT code style format
  • Run org.eclipse.mat.tests as a Junit Plugin Test and org.eclipse.mat.rcp.tests as an SWTBot test and ensure all pass
  • Switch to the Team Synchronizing perspective and review your changes
  • Add the changes you want to commit to the index (e.g. right click on the project and click Add to Index)
  • Right click on the projects/files and click Commit...
  • Use the following commit message template:

[Bug ID from step #1 in square brackets] Commit message...

Example:

[497127] Handle copying heapdumps greater than 2GB on certain platforms.

  • Click Commit (do not click Commit and Push)
  • In the Git perspective, expand org.eclipse.mat > Remotes, then right click on origin, then click Gerrit Configuration..., set destination branch to master and click Finish.
  • Right click on org.eclipse.mat and click Push to Gerritt... and click Finish
  • The results dialog should show the Gerrit link at the bottom such as https://git.eclipse.org/r/76397
  • In the Git perspective, right click the repository and click Switch To > master (now you're back on master without your changes)
  • Gerrit requires two code review votes and one verify vote. For trivial changes, you may give the +2/+1 yourself. Otherwise, ideally, two other committers would review and approve your change, but given the size of the team and their limited availability, you may also give your own +1. In the trivial case, add a comment such as "Simple patch; judging it doesn't require others' review so adding +2 code review". To request that a committer reviews your change, click Add next to Reviewers and find the name
  • Once the +2 Code Review/+1 Verified exists, a "Submit" button will show up which you can click to push the change to master.
  • The bug report will be updated automatically
  • Change the bug report to Resolved after testing the changes from a nightly build


If you are asked to modify your Gerrit change, you will need to amend your commit and add a patch set: https://gerrit-review.googlesource.com/Documentation/intro-user.html#upload-patch-set

Note in particular that the amended commit should have "\nChange-Id: ..." at the bottom which matches the Gerrit change.

Uses Mylyn for handling Bugzilla tasks

From the Task Repositories view add your Bugzilla user ID and password:

From the Task List then create a Query: New > Query > Eclipse.org > Create query using form > Next

  • Product: MAT
  • Status: UNCONFIRMED NEW ASSIGNED REOPENED

This lets you handle Bugzilla from inside Eclipse.

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.

New version development process

  • Document new version at MAT project page
  • Create Bugzilla entries for target milestone Bugzilla Manager
  • Update references to old release in the code e.g. 1.X -> 1.Y excluding update sites
    • See pom.xml e.g. <version>1.9.1-SNAPSHOT</version>
    • See manifest.mf e.g. <Bundle-Version: 1.9.1.qualifier
    • See feature.xml, excluding updateSiteName
    • See org.eclipse.mat.ui.rcp about.mappings
    • org.eclipse.mat.product mat.product
  • Develop features and fix bugs
  • If a plugin depends on new function in another plugin, update the dependency version in manifest.mf
  • If creating a new plugin, add it to the JavaDoc build process in extrabuild.xml, use package-info.java to mark packages as not API or API as appropriate. Consider carefully adding new APIs.
  • If the Java version changes then the minor version must increase, also change:
    • .classpath
    • .settings/org.eclipse.jdt.core.prefs
    • manifest.mf Bundle-RequiredExecutionEnvironment: J2SE-1.5
    • Update org.eclipse.ui.help extrabuild.xml for the new JavaDoc compile level, and for the link to the Java class library documentation
    • Consider keeping org.eclipse.mat.ibmdumps at a lower level as it uses classes for the exec dump provider and the attach jar which may be executed on lower level JVMs.
  • If the RCP is to be built against a newer version of Eclipse, then:
    • create a new target platform in org.eclipse.mat.targetdef
    • update org.eclipse.mat.ui.help extrabuild.xml to add a link to the Eclipse help for the platform
  • Towards the end, change the update site references
    • See feature.xml, including updateSiteName
  • Also write a New and Noteworthy document replacing the previous release, and add a link to the old document on the MAT website.
  • Follow MemoryAnalyzer/Contributor Reference#Simultaneous release policies
  • After release create Bugzilla entry for the new version Bugzilla Manager

Simultaneous release policies


MAT Policies - to satisfy SimRel/Simultaneous_Release_Requirements/Appendix

Maintaining MAT Website

See MemoryAnalyzer/Contributor Reference/Website

Back to the top