Eclipse Project Setup Guide

This is a project setup guide for the Eclipse IDE. It will take you through the steps needed to: (1) fork the project, (2) setup a fully working project in Eclipse, (3) push your changes (we'll add a test case) to your GitHub repository, and (4) create a pull request.

Git

Download and install Git for your operating system before proceeding to the next section. Remember to add the Git binaries directory to your OS PATH environment variable. See Git installation guide.

Maven

Download and install Maven before proceeding to the next section. Remember to add the Maven binaries directory to your OS PATH environment variable. See Maven installation guide.

Eclipse Plugins

Please install the following plugins through the Eclipse Marketplace before proceeding to the next section. You can check if they're already installed by selecting the Help->Installation Details menu item in the IDE menu bar. These plugins likely depend on the required entries to be included in the PATH variable as mentioned above.

• EGit (Git Integration for Eclipse)
• m2e (Maven support for Eclipse)
• m2e-connector for maven-dependency-plugin

You may find these plugins helpful as well, but aren't required:

• m2e javacc connector - Update site
• Maven SCM Handler for EGit (Support for Maven SCM commands)
• GitHub Mylyn Connector (Viewing Issues, Pull Requests, etc.)
• JavaCC Eclipse (Support for JavaCC files)
• SF JavaCC Eclipse Plugin-in Feature (Support for JavaCC files)
• JBehave Eclipse (Support for JBehave tests)
• JBehave Editor (Support for JBehave tests)

Coding Styling Guidelines

Please visit the code styling guide to set the formatting scheme for Eclipse. Be sure add a license header to each new file added to the project.

Fork Project

To fork the project, execute the following steps at the GitHub website:

1. Register an account with GitHub if not already done. Make sure you're signed into your account.
2. Visit the main repository page at https://github.com/javaparser/javaparser.
3. At the top right-hand corner of the page, just below your profile avatar (or profile settings dropdown), click the Fork button.
4. You now have a new repository whose content is an exact copy of the javaparser project.

Clone Project

To clone the project into Eclipse, execute the following steps in Eclipse:

1. Select the Window->Show View menu item in the IDE menu bar. Type git in the filter text field and select the Git Repositories view.
2. In the repository view, select the down arrow, which is the very last button in view's toolbar. Select Clone Repository.
3. In the Select Repository Source prompt, select Clone URI and press Next.
4. Go to your forked repository's main page on GitHub. Press the down arrow on the green button that says Clone or download. Copy the web URL to your clipboard. The URL is of the form https://github.com/<your-profile-name>/javaparser. In Eclipse, paste this URL in the URI text field, and the Host and Repository Path fields will be populated automatically.
5. Fill in the Authentication panel with your profile credentials. Also check Store in Secure Store to prevent Eclipse from re-prompting you later for those same credentials to make repository updates.
6. Press Next.
7. In the Branch Selection prompt, leave both branches selected and press Next.
8. In the Local Destination prompt, select the directory where you'd like to download the project to. Ideally, this should be your Eclipse workspace directory. The path should be: <path to workspace>/javaparser. Leave all other options untouched.
9. Congratulations! You've cloned the project and it exists as a repository in Eclipse.

Compile Sources

To build the project (and prevent IDE errors in the next sections), execute the following steps:

1. Open your OS command prompt and navigate to the root directory of the project.
2. Type mvn javacc:javacc.
3. Type mvn clean install. The installation may take some time. Verify in the Maven results summary that the javaparser-core module built successfully. Do not be concerned if the other module builds fail or are skipped for now.

Import (Core & Test) Project

To import the project into Eclipse, execute the following steps in Eclipse:

1. Select the File->Import menu item in the IDE menu bar. Type maven in the filter text field and select the Existing Maven Projects option.
2. In the Select Project prompt, click the Browse button and navigate to the root folder of the javaparser-core project. Press OK. Ensure the POM file that appears in the Projects text area is selected. Press Finish. Note that if you haven't installed the m2e connector for javacc-maven-plugin, Eclipse will alert you of an unresolved error. If so, you can still continue without problems for our purposes.
3. In the Package Explorer view, the project should appear annotated with Maven, Java, and Git Nature icons.
4. Repeat steps 1-3 for the javaparser-testing project.
5. Congratulations! You've imported the projects and are almost ready to start testing.

Add JavaCC Sources to Core Project Build Path

It's advisable to open the Problems view to see project errors resolve as you execute the following steps in Eclipse:

1. Right-click the javaparser-core project. In the context menu, select Build Path->Configure Build Path.
2. In the main panel, ensure the Source tab is selected. Press Add Folder. Expand target->generated-sources and select javacc. DO NOT deselect any other selected directories. Press OK.
3. Press Apply and OK. Clean and Build your workspace. All errors should be resolved.

Clean and Build After Changes to Core Project

Since javaparser-core is specified as a Maven dependency in the test project's POM file, it should already be listed under the Maven Dependencies directory of the javaparser-testing project. However, you'll need to re-build javaparser-testing after making changes to the core project. I recommend applying the Clean option in Eclipse's Project menu.

Make a Contribution

We're going to add a JUnit test and push it to our GitHub repository in the following steps in Eclipse:

1. In the Package explorer view, under the javaparser-testing project, expand the src/test/java directory. A number of test packages should appear.
2. Right-click the first package, com.github.javaparser, and in the context menu, select New->JUnit Test Case. If this option doesn't exist, select New->Other and find the JUnit Test Case option.
3. Name the class SetupTest and press Finish.
4. Remove the call to fail(String) in the test() method implementation.
5. Make sure to add the licensing header.
6. Select Run->Run As->JUnit Test in the IDE's menu bar. The test should pass.
7. You'll notice in the package explorer that the file icon for SetupTest.java is annotated with a question mark. This indicates you need to track the file in Git.
8. Right-click SetupTest.java, and in the context menu, select Team->Add to Index. The file icon will now be annotated with a green plus (+) symbol.
9. Now we'll commit the project changes. Right-click the project, javaparser-testing, and in the context menu, select Team->Commit. The Git Staging view will appear. Enter a commit message, e.g., 'Added setup test case', and press Commit. Now your changes to the project have been saved to Git.
10. Now we'll push your changes to your GitHub repository. In the Git Repositories view, right-click the javaparser repository, and in the context menu, select Push Branch 'master'.
11. In the Push to Branch prompt, you should see the URL for your GitHub repository selected for the Remote branch. Press Next.
12. Press Finish to complete the push. A window should appear confirming a successful push.
13. Congratulations! One step to go!

Creating a Pull Request

We'll create a pull request in the following steps. Please note that you should not create a pull request until you've actually made what you feel is a worthwhile contribution you'd like the maintainers to consider! Thank you.

1. Go to your repository's main page, and you'll see that you've made the latest commit.
2. Press the New pull request button right above the latest commit message (next to the branch selector drop menu).
3. A page entitled Comparing changes appears showing you what changes the maintainers will be shown upon reviewing your request.
4. Press the green Create pull request button to finalize your request.
5. Congratulations! You did it! 👍