From 65f50230def95e149ee3f5f390d150d3dcd02335 Mon Sep 17 00:00:00 2001 From: Krum Tsvetkov Date: Fri, 17 May 2024 22:50:55 +0200 Subject: [PATCH] Fixes for #50, Move Contributor Reference Wiki Content - add a slightly updated version of the contributor reference from the old Wiki to the code repo, under /dev-doc - add some of the referenced resources as markdown files under /dev-doc Signed-off-by: Krum Tsvetkov --- dev-doc/Building_MAT_with_Maven.md | 105 ++++++++++++ dev-doc/Contributor_Reference.md | 258 +++++++++++++++++++++++++++++ dev-doc/MAT_in_Docker.md | 26 +++ dev-doc/MAT_under_WSL.md | 127 ++++++++++++++ 4 files changed, 516 insertions(+) create mode 100644 dev-doc/Building_MAT_with_Maven.md create mode 100644 dev-doc/Contributor_Reference.md create mode 100644 dev-doc/MAT_in_Docker.md create mode 100644 dev-doc/MAT_under_WSL.md diff --git a/dev-doc/Building_MAT_with_Maven.md b/dev-doc/Building_MAT_with_Maven.md new file mode 100644 index 000000000..308e0cdc6 --- /dev/null +++ b/dev-doc/Building_MAT_with_Maven.md @@ -0,0 +1,105 @@ +# Building MAT with Maven + +This page describes how Memory Analyzer can be built using Maven/Tycho. The build will +* build all MAT bundles +* execute all tests +* (optional) run [SpotBugs](https://spotbugs.github.io/) static checks +* build eclipse features containing the MAT plugins and produce an update site (p2 repository) with them +* produce standalone (Eclipse RCP based) products for different OS platforms +* produce a software bill of materials listing +* sign and upload the produced artifacts (when executed on the Eclipse Jenkins server) + +## Prerequisites + +### Clone the Source Code from Git +MAT sources are in a Git repository, therefore you need a git client. Have a look at [Contributor_Reference.md#Get the source](Contributor_Reference.md#Get the source) + +### Use Java 17 for the Build +Memory Analyzer 1.15 requires Java 17 for the build and tests as it is based on Eclipse 4.30 2021-12, and uses Tycho 4.0.3, even though currently the highest level required to compile the Memory Analyzer plugins is 1.8. It requires Java 17 to run, and this is checked on start up. +Make sure the JAVA_HOME environment variable is set to point to a JDK 17 installation. + +Previous versions of Memory Analyzer required the MAT build has to be run with Java 1.8. For those, make sure the JAVA_HOME environment variable is set to point to a JDK 1.8 installation. + +### Install and Configure Maven +The Memory Analyzer build requires a Maven 3.9.* installation (3.8 won't work with Tycho 4.0.3). It is already present on the Jenkins server at Eclipse. For local build one can download it from [here](http://maven.apache.org/download.html). + +If you need to set a proxy for Maven, a snippet like this can be added to the Maven settings file: + +``` + + + true + http + 8080 + myproxy_host + non_proxy_hosts + + +``` + +More information on Maven settings: http://maven.apache.org/ref/3.9.5/maven-settings/settings.html + +## Building MAT from Sources + +### Execute the build +* Open a console and go into the ''/parent'' folder (it contains the parent pom.xml) +* To build MAT with the default profile (build-snapshot) simply execute +```mvn clean install``` +* This will cause a fresh build of all bundles, execute tests, build eclipse features, an update site (p2 repository) and standalone products +* If you want to also FindBugs checks are performed as part of the build, then execute +```mvn clean install spotbugs:spotbugs``` + +### Where to find the results? +You can find the results of the build in the corresponding .../target/ directories for each plugin, feature, etc... Of particular interest are: +* ''/org.eclipse.mat.updatesite/target/site/'' - it contains a p2 repository with MAT features +* ''/org.eclipse.mat.product/target/products/'' - it contains all standalone RCP applications + +## Building MAT Standalone RCPs from an Existing MAT Update Site + +### Configure and execute the build +* Open a console and go into the ''/parent'' folder (it contains the parent pom.xml) +* To produce only the standalone products, using an already existing MAT repository (i.e. without building the bundles again) specify that the ''build-release-rcp'' profile is used when you start maven: +```mvn clean install -P build-release-rcp``` +* It will take the already existing MAT plugins/features from the repository specified by the ''mat-release-repo-url'' property in ''/parent/pom.xml''. One can overwrite this location when calling maven. For example, to build products with the older 1.5.0 release, use: +```mvn clean install -P build-release-rcp -Dmat-release-repo-url=http://download.eclipse.org/mat/1.5/update-site``` + +### Where to find the results? +You can find the standalone products under ''/org.eclipse.mat.product/target/products/'' + +## Further Information +* The platforms for which RCPs are built are specified in the ''/parent/pom.xml'' file + +## Known Problems +### Wrong file permissions +When building MAT on a Windows box, the RCPs for any other OS will not have the proper permissions (e.g. the executables won't have the x flag). Building under Linux or other non-Windows OS helps. + +## Jenkins Job at Eclipse +The Jenkins continuous integration instance of the Memory Analyzer Project at the Eclipse is https://ci.eclipse.org/mat/. + +### Snapshot / Nightly builds +The [''tycho-mat-nightly''](https://ci.eclipse.org/mat/job/tycho-mat-nightly/) job is triggered when changes are pushed to the `master` branch and produces a snapshot build (see Building MAT from Sources) above. + +One can find the bill of matterials under [Last build artifacts: bill of materials](https://ci.eclipse.org/mat/job/tycho-mat-nightly/lastSuccessfulBuild/artifact/) + +The job is additionally configured to sign the plugins and features in the update site, and to upload all artifacts to the download server. +One can download such nightly/snapshot builds here: http://www.eclipse.org/mat/snapshotBuilds.php + +Info: +* Signing is activated by the build-server profile (i.e. with parameter `-P build-server` added to the maven command) +* The macOS builds are also notarized by the [mac-sign job](https://ci.eclipse.org/mat/job/mac-sign/) (committers only), which is automatically triggered after a successful snapshot build. + +### Release Builds +The job [''mat-standalone-packages''](https://ci.eclipse.org/mat/job/mat-standalone-packages/) can only be triggered manually to build the MAT standalone packages/products using an already existing MAT update site. This can be used in the following scenario - MAT has contributed its bundles and features to the simultaneous Eclipse release as part of a milestone or a release candidate. After the simultaneous release is complete, we would like to have exactly these bundles also packed in the standalone packages, potentially including also the final version of the dependencies (part of the same simultaneous release). + +The job is configured to use the ''build-release-rcp'' profile when calling maven. + +The job may need to be changed for each new release. + +After building the packages the macOS build needs to be notarized using the [''mac-sign job''](https://ci.eclipse.org/mat/job/mac-sign/) (committers only), with the parameter of the actual relative location of the dmg file on the download server. + +The downloads can then be tested. + +The job [''mat-promote-release''](https://ci.eclipse.org/mat/job/mat-promote-release/) (committers only) copies the files to their final location so they can be downloaded by all the users. + +The job [''update_latest_update-site''](https://ci.eclipse.org/mat/job/update_latest_update-site/) (committers only) copies a particular release update site to the /mat/latest/update-site + diff --git a/dev-doc/Contributor_Reference.md b/dev-doc/Contributor_Reference.md new file mode 100644 index 000000000..6ca0bd96e --- /dev/null +++ b/dev-doc/Contributor_Reference.md @@ -0,0 +1,258 @@ +# 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](https://www.ibm.com/docs/en/sdk-java-technology/8?topic=interfaces-dtfj). An Update Site is available [here](https://public.dhe.ibm.com/ibmdl/export/pub/software/websphere/runtimes/tools/dtfj/). 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](http://www.eclipse.org/mat/dev/mat_code_formatter.xml). + +### 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](http://eclipse.dev/mat/downloads.php) + * 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](Building_MAT_with_Maven.md) 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](https://github.com/dita-ot/dita-ot/releases/download/3.7/dita-ot-3.7.zip) 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](http://www.xmlbuddy.com) 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](http://www.ditainfocenter.com/eclipsehelp/index.jsp?topic=/ditaotug_top/settingup/configuring_xmlbuddy.html) + * 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](https://projects.eclipse.org/projects/mylyn.docs.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](https://javacc.org/downloads/javacc-5.0.tar.gz) or [JavaCC 5.0 zip](https://javacc.org/downloads/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](https://marketplace.eclipse.org/content/eclipaint). + +For Mac, consider using [icnsutil from PyPI](https://pypi.org/project/icnsutil/) 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 icon_16x16@2x.png +cp icon_48x48.png icon_24x24@2x.png +cp icon_64x64.png icon_32x32@2x.png +cp icon_128x128.png icon_64x64@2x.png +cp icon_256x256.png icon_128x128@2x.png +icnsutil c memory_analyzer.icns icon_16x16.argb icon_16x16@2x.png icon_24x24@2x.png icon_32x32.argb icon_32x32@2x.png icon_48x48.png icon_128x128.png icon_128x128@2x.png 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](https://bugs.eclipse.org/bugs/show_bug.cgi?id=342543) +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](Building_MAT_with_Maven.md) + +## Testing using Docker +It is possible to [run Memory Analyzer in a Docker container](MAT_in_Docker.md), which might allow testing on different Linux distributions + +## Testing using Windows Subsystem for Linux +It is possible to [run Memory Analyzer under WSL](MAT_under_WSL.md), which might allow testing of a Linux distributions when running Windows. + +## Contributing code + +See [CONTRIBUTING.md](../CONTRIBUTING.md) + +## New version development process + +* Document new version at [MAT project page](https://projects.eclipse.org/projects/tools.mat) +* Create Bugzilla entries for target milestone [Bugzilla Manager](https://dev.eclipse.org/committers/bugs/bugz_manager.php) +* Update references to old release in the code e.g. 1.X -> 1.Y excluding update sites +** See pom.xml e.g. `1.9.1-SNAPSHOT` +** 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](https://dev.eclipse.org/committers/bugs/bugz_manager.php) +* [Add a new Babel definition](https://wiki.eclipse.org/Babel/FAQ#How_do_I_add_my_project_to_Babel.3F) so the messages files could be translated. + + +## Simultaneous release policies + +* Create a release record in [Eclipse Memory Analyzer project page](https://projects.eclipse.org/projects/tools.mat) +* For reference, read [contribute to the Simultaneous Release Build](https://github.com/orgs/eclipse-simrel/discussions/3) +* [Build](https://ci.eclipse.org/mat/job/prepare_simrel_contribution/) to copy update site build to SimRel location. +* Follow the SimRel process to update mat.aggrcon in the SimRel build. +* Preserve the [tycho-build-nightly](https://ci.eclipse.org/mat/job/tycho-mat-nightly/) as 'Keep forever' and label it with the release build e.g. 'Photon RC2' +* The [MAT configuration file](http://git.eclipse.org/c/simrel/org.eclipse.simrel.build.git/tree/mat.aggrcon) which is [updated using Git in GitHub.com/eclipse-simrel](https://github.com/orgs/eclipse-simrel/discussions/3) 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 [MAT Git Refs](https://git.eclipse.org/c/mat/org.eclipse.mat.git/refs/) +* Complete the Eclipse release process, including getting a review if needed at [Eclipse Memory Analyzer project page](https://projects.eclipse.org/projects/tools.mat) +* To release, also run the [Stand-alone packaging build](https://ci.eclipse.org/mat/job/mat-standalone-packages/), notarize the Mac x86_64 and aarch64 .dmg files and copy the results to the download site using [promote release](https://ci.eclipse.org/mat/job/mat-promote-release/). +* Add the version name '1.XX' to [Bugzilla manager](https://dev.eclipse.org/committers/bugs/bugz_manager.php) so users can report bugs against the new version +* Also release on [Eclipse Marketplace](https://marketplace.eclipse.org/content/memory-analyzer-0) +* Also consider archiving some old releases + + +MAT Policies - to satisfy [Simultaneous Release Requirements](https://github.com/eclipse-simrel/.github/blob/main/wiki/SimRel/Simultaneous_Release_Requirements.md) +* [Ramp Down Plan](https://wiki.eclipse.org/MemoryAnalyzer/Ramp_Down_Plan) +* [Retention Policy](https://wiki.eclipse.org/MemoryAnalyzer/Retention_policy) +* [API Policy](https://wiki.eclipse.org/MemoryAnalyzer/API_policy) +* [Capabilities](https://wiki.eclipse.org/MemoryAnalyzer/MAT_Capabilities) + +## Download Statistics + +Eclipse committers once logged in at accounts.eclipse.org can see download statistics at +[Download Stats](https://dev.eclipse.org/committers/committertools/stats.php|Eclipse). +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. diff --git a/dev-doc/MAT_in_Docker.md b/dev-doc/MAT_in_Docker.md new file mode 100644 index 000000000..a253a476d --- /dev/null +++ b/dev-doc/MAT_in_Docker.md @@ -0,0 +1,26 @@ +# MAT in Docker + +It is possible to run Eclipse Memory Analyzer in a Docker container. A useful Docker image is the [following](https://hub.docker.com/r/kgibm/fedorawasdebug) + +It is also possible to have minimal images to allow Eclipse Memory Analyzer to be tested in various Linux distributions. These Dockerfiles allow testing of snapshot builds. + +``` +FROM ubuntu +#If docker build gets the wrong time , might need apt-get -o Acquire::Max-FutureTime=86400 update +RUN apt-get update && apt-get install -y default-jdk wget unzip libwebkit2gtk-4.0 firefox +# Download snapshot build, just for testing +RUN wget "http://www.eclipse.org/downloads/download.php?file=/mat/snapshots/rcp/org.eclipse.mat.ui.rcp.MemoryAnalyzer-linux.gtk.x86_64.zip&mirror_id=1" -O /tmp/org.eclipse.mat.ui.rcp.MemoryAnalyzer-linux.gtk.x86_64.zip +RUN unzip /tmp/org.eclipse.mat.ui.rcp.MemoryAnalyzer-linux.gtk.x86_64.zip -d /opt +ENV DISPLAY host.docker.internal:0.0 +CMD ["/opt/mat/MemoryAnalyzer"] +``` + +``` +FROM fedora +RUN yum install -y wget unzip java-1.8.0-openjdk.x86_64 webkitgtk4 firefox +# Download snapshot build, just for testing +RUN wget "http://www.eclipse.org/downloads/download.php?file=/mat/snapshots/rcp/org.eclipse.mat.ui.rcp.MemoryAnalyzer-linux.gtk.x86_64.zip&mirror_id=1" -O /tmp/org.eclipse.mat.ui.rcp.MemoryAnalyzer-linux.gtk.x86_64.zip +RUN unzip /tmp/org.eclipse.mat.ui.rcp.MemoryAnalyzer-linux.gtk.x86_64.zip -d /opt +ENV DISPLAY host.docker.internal:0.0 +CMD ["/opt/mat/MemoryAnalyzer"] +``` \ No newline at end of file diff --git a/dev-doc/MAT_under_WSL.md b/dev-doc/MAT_under_WSL.md new file mode 100644 index 000000000..3a9e498d1 --- /dev/null +++ b/dev-doc/MAT_under_WSL.md @@ -0,0 +1,127 @@ +# MAT under WSL + +it is possible to test Linux builds on a Windows 10 (or 11) machine using Windows Subsystem for Linux. + +## Windows Subsystem for Linux + +Install WSL2 with for example Ubuntu or Ubuntu 20 + +For Windows 10: Install Cygwin and X-Server + +For Windows 11: X-Server is installed on WSL2 by default + +For Windows 10: Install the appropriate graphics driver: [Microsoft WSL GUI apps](https://docs.microsoft.com/en-us/windows/wsl/tutorials/gui-apps) + +For Windows 11: Graphics driver is installed on WSL2 by default + +Install unzip + +```sudo apt install unzip``` + +Install GTK: + +```sudo apt-get install libswt-gtk-4-jni libswt-gtk-4-java``` + +Install WebKit: + +[Eclipse instructions](https://www.eclipse.org/swt/faq.php#browserlinux) + +```sudo apt-get install libwebkit2gtk-4.0-37``` + +Install Java 17 or later + +```sudo apt install openjdk-17-jre-headless``` + +For Windows 10, start the X-server: +Find the IP address of the WSL2 system: + +```ip addr | grep eth0``` + +From Cygwin64 command prompt. xhost should have the IP address of the WSL2 system as seen from Windows / Cygwin + +``` +startxwin -- -listen tcp +xhost +127.0.0.1 #Add the appropriate IP address, need to check for WSL2 +# xhost +172.22.46.35 # or use this for WSL2, replace the address with the address from ip addr above +# xhost +$(wsl hostname -I) # or use this from a Cygwin xterm window to automatically find the WSL2 address +``` + +Download Memory Analyzer zip + +```unzip MemoryAnalyzer-1.12.0.20210602-linux.gtk.x86_64.zip``` + +For WSL1 + +``` +cd mat +export DISPLAY=:0 +./MemoryAnalyzer +``` + +or for WSL2, Windows 10 + +``` +cd mat +export DISPLAY=$(ip route | grep default | cut -d ' ' -f 3)':0' # Finds the IP address of the Windows machine +./MemoryAnalyzer +``` + +or for WSL2, Windows 11 + +```./MemoryAnalyzer``` + +## Problems + +Problem: Failed to load swt-pi3 + +``` +./MemoryAnalyzer +SWT OS.java Error: Failed to load swt-pi3, loading swt-pi4 as fallback. +MemoryAnalyzer: +An error has occurred. See the log file +/home/user1/mat/configuration/1689022953567.log. +``` + +Solution: + +Install GTK4 + +Problem: Failed to create a browser + +``` +Failed to create a browser because of: No more handles because there is no underlying browser available. +Please ensure that WebKit with its GTK 3.x/4.x bindings is installed. +Consult error log for more details. +Press F1 or the help icon for help. +``` + +Solution: + +Install WebKit + +## Charts + +To get charts working, add `-Djava.awt.headless=true` to `MemoryAnalyzer.ini` in the vmargs section. + +### WebKit problems - e.g. Ubuntu 22.04 + +If you get errors such as the following, and blank pages for reports or help: + +``` +(WebKitWebProcess:22883): Gdk-ERROR **: 12:42:02.853: The program 'WebKitWebProcess' received an X Window System error. +This probably reflects a bug in the program. +The error was 'GLXBadFBConfig'. + (Details: serial 148 error_code 161 request_code 148 (GLX) minor_code 21) + (Note to programmers: normally, X errors are reported asynchronously; + that is, you will receive the error a while after causing it. + To debug your program, run it with the GDK_SYNCHRONIZE environment + variable to change this behavior. You can then get a meaningful + backtrace from your debugger if you break on the gdk_x_error() function.) +``` + +try starting Memory Analyzer like this +``` +WEBKIT_DISABLE_COMPOSITING_MODE=1 ./MemoryAnalyzer +``` + +See [https://bugs.launchpad.net/ubuntu/+source/evolution/+bug/1966418] for details. \ No newline at end of file