MyBatis Generator Feature Debug Reference

This page contains reference information about how to build and debug the MyBatis Generator (MBG) feature from source.

Build Overview

The feature is built using Eclipse Tycho - which is Maven support for Eclipse projects. Tycho is a thin wrapper over the normal Eclipse PDE build processes. Even though some of the projects have a pom.xml, the projects are not structured like normal Maven projects. Within Eclipse, you still need to use normal PDE support and editors to modify the feature. Do not try to import the projects into your IDE as Maven projects - it will not work. The projects need to be imported as regular Eclipse projects.

Feature Structure

There are eleven total projects that makeup the feature. Some projects are just for build support and testing.

The published MBG feature is composed of five different Eclipse projects - a feature project, and four plugin projects. The feature project groups the four plugins together for easy installation. Those projects are structured as follows:

Project Description
org.mybatis.generator This project is the Eclipse feature project for MBG.
org.mybatis.generator.core This plugin holds the Java source for the core MBG library. Source from the core MBG source tree is copied into this plugin during the build. There is an Ant build file in this plugin (copySource.xml) that performs the copy. If you find a bug in the core MBG, you must make the correction in the core source tree - NOT this plugin.
org.mybatis.generator.eclipse.core This plugin holds Java support classes for the other plugins. This plugin does not contribute to the Eclipse user interface. This plugin includes classes for Java file merging, and Eclipse implementations of the MBG callback interfaces.
org.mybatis.generator.eclipse.doc This plug-in holds the documentation for MBG. There is an Ant build file in this plugin (buildDoc.xml) that will build the documentation and package it for inclusion into the Eclipse help system. The Ant script merges the core MBG documentation into the eclpse documentation. If you need to correct something in the core MBG documentation, you must make the correction in the core MPB project - NOT the eclipse documentation project.
org.mybatis.generator.eclipse.ui This plug-in holds the Java code for the Eclipse user interface for MBG. If you are experiencing trouble with the plugin specific features (like the integrated Ant task), then the code for those features will be found in this plugin. An Ant script in this plugin (copyDtds.xml) will copy the DTDs from the core MBG source tree into a location suitable for packaging in this plugin.

This plugin also contains a custom Ant builder for the Ant task. This is required because of the way that eclipse accepts contributed Ant tasks - they need to be in a separate JAR from the main plugin.

Other Projects

There are six other Eclipse projects that are used in the build of the feature:

Project Description
org.mybatis.generator.eclipse.site This project is a P2 publishing site that is used to publish the feature.
org.mybatis.generator.eclipse.core.tests This project is a plugin fragment that holds unit tests for the org.mybatis.generator.eclipse.core plugin.
org.mybatis.generator.eclipse.ui.tests This project is a plugin fragment that holds unit tests for the org.mybatis.generator.eclipse.ui plugin.
org.mybatis.generator.eclipse.test.utilities This project is a plugin that contains specialized AST visitors and custom Hamcrest (http://hamcrest.org) matchers that are used in the test fragments for writing unit tests that cover the Java merge functionality.
org.mybatis.generator.eclipse.test.utilities.tests This project is a plugin fragment that holds tests for the org.mybatis.generator.eclipse.test.utilities plugin.
releng This project is a simple project that holds other items useful during the build.

Eclipse Workspace Setup

The following instructions show how to setup an Eclipse workspace for building the MBG feature and plug-ins from the latest source in the GitHub repository. We assume that you are somewhat familiar with git and the Eclipse plug-in development environment (PDE).

  1. The authoritative source code for MyBatis Generator is on GitHub at https://github.com/mybatis/generator. You can either fork the current source, or clone directly from the authoritative repository. If you plan on submitting fixes or enhancements, you should fork the code into your own account.
  2. Clone the repository from GitHub. Note: this will also checkout the source for the MBG core JAR which is required.
  3. Start Eclipse and make a new workspace
  4. Important: make sure that a version 8.0 or higher JDK is available and visible to Eclipse (Window>Preferences>Java>Installed JREs). A JDK is required - a JRE alone will fail because of JavaDoc generation in the build and Tycho requires JDK 8.0 or above.
  5. Import the projects into the workspace
    1. Start the Eclipse project import wizard (File>Import>General>Existing Projects into Workspace)
    2. Set the root directory to the "eclipse" sub-directory in your Git clone
    3. Select all eleven projects, do not copy the projects into your workspace. The filled out wizard looks similar to this:

      Eclipse Project Import Wizard

    4. Press "Finish", wait for the workspace to build.
  6. The project includes Eclipse target platform definition files. The purpose is to set the minimum version of Eclipse supported by the feature and to ensure that you do not inadvertently use Eclipse features from later versions. Target platform files are in the releng project. To activate the target platform, open the proper target file and click on the link that says "Set as active target platform". This action may take a few minutes to complete. The README in the releng project contains information about which target platform file to use.
  7. You will likely have workspace errors due to missing source code in the org.mybatis.generator.core project. There are two ways to solve this:
    1. If you are comfortable with Maven, then you can run the Maven build by executing "./mvnw clean integration-test" on the pom.xml in the parent directory of all Eclipse projects (../eclipse) A slight warning: this will download many dependent JARs from Maven central and eclipse.org the first time you run it.

      This method is preferred because it runs the full build for all the plugins. This will make is possible to debug all of the plugin features including documentation.

    2. If you would rather not run the Maven build, you can run just run the copySource.xml Ant file in the org.mybatis.generator.core project. This should resolve the build errors.

Debugging

At this point the projects should be successfully compiled in Eclipse. If you want to debug something in the plug-in, you will need to start another instance of Eclipse in debug mode. The following instructions explain how to do this.

  1. Set a breakpoint in the code you would like to debug.
  2. Double click on the "plugin.xml" file in the "org.mybatis.generator.eclipse.ui" project. This should open the plug-in manifest editor. If some other editor opens, then close the editor, right click on "plugin.xml" and select the "Open With>Plug-in Manifest Editor" option.
  3. Select the "Overview" editor tab
  4. Take the option to "Launch an Eclipse Application in Debug mode". This will start a new instance of Eclipse in debug mode with the MBG plug-ins installed.

Once you have the other instance of Eclipse started you should create a new Java project in the new workspace, create and fill out an MBG configuration file, and then run MBG. MBG should eventually hit your breakpoint, and then you step through the code. Note that the "Manual Test Scripts" page in these instructions has instructions for creating a test project if you need one.

The following classes will likely be of the most interest in debugging:

Class Description
org.mybatis.generator.eclipse.ui.launcher.GeneratorLaunchConfigurationDelegate This class is used by eclipse launch support to execute a launch. If you are experiencing a problem where the attributes you set in a launch configuration seen to be ignored or aren't working, you should set a breakpoint in the launch method of this class to follow the launch from the beginning.

Note that the launcher uses Ant under the covers, so this method simply sets up an Ant environment and launches Ant. If you are experiencing issues in the core functionality of MBG, see below for a better staring point.

org.mybatis.generator.eclipse.ui.ant.GeneratorAntTask The MBG launcher uses Ant under the covers, and will eventually cause this task to be executed. You can set a breakpoint in the execute method of this class to follow the MBG code generation process from the beginning.

Note that eclipse will not be able to find the source code initially, so the debug window will just show a blank class file. Add the antsrc directory in the org.mybatis.generator.eclipse.ui project to the source lookup path to solve that issue.

org.mybatis.generator.eclipse.core.merge.JavaFileMerger This class implements the Java file merge function. You can set a breakpoint in the getMergedSource method to follow the merging process.

Running the Unit Tests

The plugin fragment project org.mybatis.generator.eclipse.core.tests contains unit tests for many of the classes in the org.mybatis.generator.eclipse.core project. These tests cover the core functionality of Java code merging and workspace file resolution that is an extra capability added by the eclipse feature.

The tests will be run during a maven build of the feature, but you can also run them directly in eclipse. Running these unit tests is similar to running regular unit tests in eclipse with the following exceptions:

To run all tests, run the class org.mybatis.generator.eclipse.core.tests.RunAllTests which contains a test suite of all unit tests.

Building the Documentation

The documentation for MBG is integrated into the Eclipse help system. The documentation is partially generated (JavaDocs), partially copied in from the core MBG source tree, and partially maintained in the plugin itself. This full documentation set is not in source control because it is partially generated. If you would like to rebuild the documentation, simply execute the buildDoc.xml file in the org.mybatis.generator.eclipse.doc project (an Ant build file). This step is included in the Maven build, so if you are using the Maven build you will not need to do this.

Building the Feature for Local Distribution

If you want to build an updated version of the feature and distribute it locally, then follow these steps:

  1. Run the Maven build by running "./mvnw clean integration-test" in the parent directory of all projects (".../eclipse")
  2. Once the build completes the feature will be available in the target/repository directory of the org.mybatis.generator.eclipse.site project.

After the build executes, the easiest way to install this new version of the feature is to create a new local repository that points to this directory (Help>Install New Software...) and install the new version with P2.

If you are interested in publishing a new version to JFrog, please see the instructions on the Publishing page.