Skip to content

Latest commit

 

History

History
257 lines (201 loc) · 17.3 KB

Contributor_Reference.md

File metadata and controls

257 lines (201 loc) · 17.3 KB
Raw

Memory Analyzer Contributor Reference

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

Workspace

Here you'll find instructions on how to setup your development environment for developing MAT using Eclipse as IDE

Get the source

The Memory Analyzer code is hosted on Github:

https://github.com/eclipse-mat/mat

Setup Eclipse as IDE

You need a recent Eclipse installation. Memory Analyzer is a set of eclipse plugins, therefore you'll need the appropriate tooling for plugin development. The ''Eclipse IDE for Eclipse Committers'' is an appropriate package.

There are eclipse .project files as part of MATs source code, so that the projects (plugins, features, etc...) can be easily imported into the Eclipse IDE.

Dependencies - you'll need the following to be able to compile MAT

The easiest way to setup all dependencies is to use a target platform definition file, which can be found in org.eclipse.mat.targetdef. Open the most recent one with the Target Definition Editor and select ''Set as Active Target Platform''. After this, all projects should compile.

Alternatively, if you don't want to use the predefined target platform definition, you'll should install via the update manager

  • Eclipse BIRT Framework
  • IBM Diagnostic Tool Framework for Java - See IBM Diagnostic Tool Framework for Java Version 1.12. An Update Site is available here. 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.

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 the Code Formatter Template

The MAT code is formatted with a specific code formatter. Use it if you would like to contribute you changes to MAT.

''Preferences -> Java -> Code Style -> Formatter -> Import...'' and import this template.

Configure API Tooling Baseline

In order to guarantee that no API breaking changes are introduced we recommend 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'', ''org.eclipse.mat.ui.rcp.tests'', ''org.eclipse.mat.ui.capabilities''
    • Deselect ''Target Platform'' and click ''Select Required'' (previously ''Add Required Plug-ins'')
    • With Eclipse 2024-03 this is all you need to do. With older Eclipse versions, you'll need to manually select a few more plugins
      • 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''
    • De-select ''org.eclipse.mat.tests'', ''org.eclipse.mat.ui.rcp.tests'', ''org.eclipse.mat.ui.capabilities'' 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 Building MAT with Maven 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 --add-exports java.base/jdk.internal.org.objectweb.asm=ALL-UNNAMED

For the ''org.eclipse.mat.rcp.tests'' project install SWTBot - API from [https://www.eclipse.org/swtbot/].

Build Help with DITA

  • Download DITA-OT 3.7 and unzip it into somewhere on your disk, e.g. C:\dita-ot-3.7. 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...''
    • Refresh > Refresh resources upon completion. > The project containing the selected resource
    • 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.dir
      • Value: the location of DITA, e.g. C:\dita-ot-3.7
      • OK
    • Alternatively to run DITA-OT from the command line
      • Set the dita directory variable, e.g. <code>set DITA_DIR=C:\dita-ot-3.7</code>
      • Add DITA to the path, e.g. <code>set PATH=%DITA_DIR%\bin;%PATH%</code>
      • change to the org.eclipse.mat.ui.help directory and run one of the following:
        • <code>ant -f DitaBuild.xml</code> [attempts to not change HTML files which have no content changes]
        • <code>ant -f DitaBuild.xml -Djustnew=true</code> [attempts to not change HTML files which have no content changes]
        • <code>ant -f DitaBuild.xml -Djustnew=false</code> [HTML files are as they come from DITA build, some HTML files may be changed which have no content changes]

  • 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 > Add XML Catalog Element > Delegate Catalog
        • Key type to match: URI
        • Matching start string: -//OASIS//DTD DITA
        • Delegate to this XML catalog file: %DITA_DIR%/plugins/org.oasis-open.dita.v1_3/catalog.xml
        • [substitute %DITA_DIR% with the actual path]
      • Note that the validation does not seem to work with Eclipse 2022-03 any more - some previous versions did work.
    • or or use the XML editor from Eclipse Web Tools and Vex
      • It may be easier to still use the XML Editor, as the Vex editor deliberately doesn't show tags, but Vex provides DTD files for DITA, making it possible for XML validation and content assist for DITA files

  • 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.

For Mac, consider using icnsutil from PyPI to help build the icns file.

#!/bin/sh
cp memory_analyzer_16.png icon_16x16.png
cp memory_analyzer_32.png icon_32x32.png
cp memory_analyzer_48.png icon_48x48.png
cp memory_analyzer_64.png icon_64x64.png
cp memory_analyzer_128.png icon_128x128.png
cp memory_analyzer_256.png icon_256x256.png
icnsutil convert icon_16x16.argb icon_16x16.png
icnsutil convert icon_32x32.argb icon_32x32.png
cp icon_32x32.png [email protected]
cp icon_48x48.png [email protected]
cp icon_64x64.png [email protected]
cp icon_128x128.png [email protected]
cp icon_256x256.png [email protected]
icnsutil c memory_analyzer.icns icon_16x16.argb [email protected] [email protected] icon_32x32.argb [email protected] icon_48x48.png icon_128x128.png [email protected] icon_256x256.png --toc
icnsutil i memory_analyzer.icns
rm icon_*

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: Building MAT With Maven

Testing using Docker

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

Testing using Windows Subsystem for Linux

It is possible to run Memory Analyzer under WSL, which might allow testing of a Linux distributions when running Windows.

Contributing code

See CONTRIBUTING.md

New version development process

  • Document new version at MAT project page

  • 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 ** org.eclipse.mat.ui.rcp.feature rootfiles/.eclipseproduct (hidden file, may need to use navigator view)

  • 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.

  • Update copyright date in source code if updated in a new year

  • 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
    • create a new /org.eclipse.mat.product/mat-<Eclipse-rel>.product file - normally use the same basename as for the target
    • create a new /org.eclipse.mat.product/mat-<Eclipse-rel>.p2.inf file - normally use the same basename as for the target

  • Check for regressions/changes in report outputs using the regression test suite

    • Check out the previous release from Git
    • Get it compiled - may need to change target platform
    • In org.eclipse.mat.test, run the org.eclipse.mat.tests.application with -regression ./dumps "-Xmx500m -DMAT_HPROF_DUMP_NR=#1 --add-exports=java.base/jdk.internal.org.objectweb.asm=ALL-UNNAMED. This will run the tests, and establish a baseline if one does not exist
    • Switch back to master
    • Rerun the test which will detect any changes. Examine report.xml to understand whether the changes are expected.

  • Towards the end, change the update site references

  • Update copyright date in feature.properties etc. if feature/plugin updated in a new year

    • 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. This should be done in org.eclipse.mat.help in noteworthy.dita, and take the generated noteworthy.html, modify it if needed and add to the website.

  • Follow [Simultaneous release policies](#Simultaneous release policies)

  • After release create Bugzilla entry for the new version Bugzilla Manager

  • Add a new Babel definition so the messages files could be translated.

Simultaneous release policies

MAT Policies - to satisfy Simultaneous Release Requirements

Download Statistics

Eclipse committers once logged in at accounts.eclipse.org can see download statistics at Download Stats. These are from downloads via the Find a Mirror script for stand-alone MAT and from p2 downloads from an update site. Search for '/mat/' for mirror downloads and 'org.eclipse.mat.api' for p2 downloads.