Skip to content
Google Cloud Platform plugin for Eclipse
Branch: master
Clone or download
elharo default to major version 2 (#3473)
* default to major version 2
Latest commit 7df29b1 Jun 13, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Drop support for Eclipse Neon (#3234) Aug 24, 2018
.settings Fixes #6 - Add build instructions Mar 21, 2016
.travisci Add build target for Java 11 (#3249) Sep 18, 2018
build Add builds for Eclipse 2018-12 (#3301) Dec 19, 2018
eclipse update to appengine-plugins-core 0.7.4 (#3391) Feb 7, 2019
features Start releasing 1.8.1 (#3445) Jun 4, 2019
gcp-repo Start releasing 1.8.1 (#3445) Jun 4, 2019
kokoro Fix Kokoro (#3318) Dec 18, 2018
plugins default to major version 2 (#3473) Jun 13, 2019
release Remove files for old release process (#3146) Jun 8, 2018
third_party Removing leftover (#3240) Aug 31, 2018
.gitattributes Kokoro continuous test (#1872) Apr 27, 2017
.gitignore ignore remote systems explorer junk (#2818) Feb 20, 2018
.project Fixes #29 - One Google Cloud Platform for Eclipse Mars target Mar 31, 2016
.travis.yml Upgrade appengine-plugins-core to 0.7.5 and clean up more dev server2… Apr 8, 2019
CONTRIBUTING.md Try gcloud before reporting a bug (#2697) Jan 3, 2018
LICENSE Update LICENSE (#2379) Sep 13, 2017
README.md Add -Pide-target-platform to build target platform (#3390) Jan 22, 2019
TESTPLAN.md Note feature is for 4.5 and 4.6 (#434) Jul 22, 2016
codecov.yml reduce patch target to 50% (#2258) Aug 13, 2017
favicon.ico Initial open source boilerplate Jan 13, 2016
gcloud-eclipse-tools.launch Remove obsolete tracing option (#3302) Dec 14, 2018
pom.xml Bump appengine-plugins-core to version 0.7.6 (#3432) May 20, 2019

README.md

stable Build Status

This project provides an Eclipse plugin for building, debugging, and deploying Google Cloud Platform applications.

End user documentation and installation instructions can be found on cloud.google.com.

TL;DR: mvn package should generate a p2-accessible repository in gcp-repo/target/repository.

Development

This project is built using Maven Tycho, a set of extensions to Maven for building Eclipse bundles and features.

Requirements

  1. The Google Cloud SDK; install this somewhere on your file system.

    • An alternative is to install Cloud Tools for Eclipse into your Eclipse IDE and use its option to automatically install the Cloud SDK.
  2. JDK 8

  3. The Eclipse IDE. It's easiest to use the Eclipse IDE for Java EE Developers package. You must use Eclipse 4.7 (Oxygen) or later. We use target platforms to support building for earlier versions of Eclipse. You also need the following:

    1. The M2Eclipse plugin (also called m2e) is required to import the projects into Eclipse. M2Eclipse is included in several packages, such as the Eclipse IDE for Java EE Developers package.

    2. The m2e connector for maven-dependency-plugin should be installed from http://ianbrandt.github.io/m2e-maven-dependency-plugin/. This connector should be prompted for by M2Eclipse. If not, use Preferences > Maven > Discovery > Open Catalog and search for Dependency and install.

    3. The Google Java Format plugin for Eclipse. Download the latest version and place the jar into your Eclipse installation's dropins/ directory (on MacOS this may be in Eclipse.app/Contents/Eclipse/dropins/).

  4. Maven 3.5.0 or later. Although m2eclipse is bundled with its own Maven install, Maven is necessary to test command-line builds.

  5. git (optional: you can use EGit from within Eclipse instead)

  6. Clone the project to a local directory using git clone https://github.com/GoogleCloudPlatform/google-cloud-eclipse.git.

Running Tests

If all you want is to run tests, just do mvn verify.

However, the integration tests will interfere with your display, disrupt your using your computer, and likely fail if you touch the screen while the integration tests are running. A nice solution on Unix-like systems is to do xvfb-run mvn verify. (Install Xvfb if necessary.) xvfb-run will use a virtual display, and you and the tests will not be disrupted.

Configuring Maven/Tycho Builds

The plugin is built using Maven/Tycho and targeted to Java 8.

The tests need to find the Google Cloud SDK. You can either:

  1. Place the SDK/bin directory on your PATH
  2. Set GOOGLE_CLOUD_SDK_HOME to point to your SDK

Changing the Eclipse Platform compilation and testing target

By default, the build is targeted against Eclipse Photon / 4.8. You can explicitly set the eclipse.target property to oxygen (4.7), 2018-09 (4.9), or 2018-12 (4.10).

$ mvn -Declipse.target=oxygen package

Adding a new bundle/fragment

We normally put production code into a bundle and tests as a fragment hosted by that bundle, put under the plugins/ directory. For now we have been committing both the pom.xml and Eclipse's .project, .classpath, and .settings/ files. We have a master set of project settings in eclipse/settings; see the README.md for more details.

Our CI process is configured to run our tests with JaCoCo, which requires some additional configuration to add new bundles and fragments in build/jacoco/.

Import into Eclipse

We pull in some dependencies directly from Maven-style repositories, such as Maven Central and the Sonatype staging repository, which isn't directly supported within Eclipse. We have a few hoops to jump through to set up a working development environment.

Assemble the IDE Target Platform

The Eclipse IDE and Tycho both use a Target Platform to manage the dependencies for the source bundles and features under development. Although Tycho can pull dependencies directly from Maven-style repositories (like Maven Central), Eclipse cannot. So we use Tycho to cobble together a target platform suitable for the Eclipse IDE with the following command.

$ (cd eclipse; mvn -Pide-target-platform package)        # may want -Declipse.target=XXX

This command creates a local copy of the target platform, including any Maven dependencies, into eclipse/ide-target-platform/target/repository. You will use this repository to create a target platform within the IDE, as described below.

The Eclipse version used for the target platform is affected by the eclipse.target property, described below.

You must regenerate the target platform and reconfigure the IDE's target platform whenever dependencies are updated.

Steps to import into the Eclipse IDE

  1. Setup JDK 8 in Eclipse (this may already be set up by Eclipse's JRE/JDK auto-discovery)

    1. Select Window/Preferences (on Mac Eclipse/Preferences).

    2. Under Java/Installed JREs click Add.

    3. Select Standard VM and click Next.

    4. Select the folder that contains the JDK 8 installation by clicking Directory.

    5. Click Finish.

    6. Select Java/Installed JREs/Execution Environments page.

    7. Click on JavaSE-1.8 in the list on the left under Execution Environments:.

    8. The JDK just added should show up in the list on the right along with other installed JDKs/JREs. Set the checkbox next to the JDK 8 added in the previous steps to mark it as compatible with the JavaSE-1.8 execution environment.

    9. Click OK.

  2. Set up the Target Platform: you will need to repeat this process whenever items are changed in the target platform, such as a new release of the appengine-plugins-core.

    1. As described above, you must first build the target platform with Maven:

      $ (cd eclipse; mvn -Pide-target-platform package)

    2. Open the Preferences dialog, go to Plug-in Development > Target Platform.

    3. Click Add... > Nothing to create a new Target Platform.

    4. Name it GCP IDE Target Platform.

    5. Select Add > Software Site.

    6. Select the Add... button (found beside the Work with: field) and then select Local to find a local repository. Navigate to .../eclipse/ide-target-platform/target/repository, and click OK.

    7. Once the main content populates, check the Uncategorized item to pull in all items. Click Finish.

    8. Click Finish to complete the new target platform definition.

    9. Select your new target platform (instead of Running Platform) in the Target Platform preferences.

    10. Click Apply and Finish to load this new target platform.

    11. Eclipse will load the target.

  3. Import the projects.

    1. Select File/Import... menu in Eclipse.

    2. Select Existing Maven Projects from the list.

    3. Click Browse... and select the directory that contains the project.

    4. Under Projects: the pom.xml files representing modules should be displayed. Make sure that all of them are selected except the sub-directories under eclipse, and click Finish.

      • The subprojects under the eclipse directory define target platforms for the Tycho build. It's easier to edit the files from the eclipse-setup project.
    5. Maven may prompt you to install several additional plugin connector plugins from Tycho if they are not already installed. Click Finish to install them. If Eclipse prompts you to install any other plugins, do so.

    6. Restart Eclipse when prompted.

  4. Check the imported projects.

    • There should be no errors in the Markers or Problems views in Eclipse. However you may see several low-priority warnings.

      • You may see Maven-related errors like "plugin execution not covered by lifecycle configuration". If so, right-click on the problem and select Quick Fix > Discover new m2e connectors and follow the process to install the recommended plugin connectors.
  5. Create and initialize a launch configuration:

    1. Right-click the gcloud-eclipse-tools.launch file under the google-cloud-eclipse module in the Package Explorer.

    2. Select Run As > Run Configurations...

    3. Set variables required for launch:

      1. Go to the second tab for Arguments

      2. Click the Variables... button for VM argument:

      3. Click the Edit variables... button

      4. Click New...

      5. Set the name to oauth_id, and the value to the value you want to use (description optional)

      6. Click OK, the variable will appear in the list

      7. Repeat steps 6-8 but use oauth_secret as the name and use the corresponding value

      8. Click OK to close the edit variables dialog

      9. Click Cancel to close the variable selection dialog

      10. Click Apply to apply the changes to the run config

    4. From the Run menu, select Run History > gcloud-eclipse-tools. A new instance of Eclipse launches with the plugin installed.

Updating Target Platforms

Updating the .target files

We use Target Platform files (.target) to collect the dependencies used for the build. These targets specify exact versions of the bundles and features being built against. We currently maintain three target platforms, targeting the latest version of the current, previous, and next releases. This is currently:

These .target files are generated and should not be manually updated. Updating .target files directly becomes a chore once it has more than a couple of dependencies. We instead generate these .targets from Target Platform Definition .tpd files. The .tpd files use a simple DSL to specify the bundles and features, and the location of the repositories containing them. The .tpd files are processed using the TPD Editor which resolves the specified dependencies and creates a .target. The process is:

  1. Install the TPD Editor, if necessary
    • Use Help > Install New Software and specify http://download.eclipse.org/cbi/tpd/3.0.0-SNAPSHOT/ as the location.
    • Restart Eclipse when prompted
  2. Open the .tpd file in Eclipse.
  3. Make any necessary changes and save.
    • Note that the TPDs specify artifacts using their p2 identifiers. Bundles are specified using their OSGi Bundle Symbolic Name (e.g., org.eclipse.core.runtime). Features are specified using their Feature ID suffixed with .feature.group (e.g., org.eclipse.rcp.feature.group).
  4. Select the file in the Package Explorer, right-click, and choose Create Target Definition File to update the corresponding .target file.

Both the .tpd and .target files should be committed.

Updating Dependencies

The IDE Target Platform needs to be rebuilt at the command line and reimported into Eclipse when dependency versions are changed:

  1. (cd eclipse; mvn -Pide-target-platform package)
  2. Preferences > Plug-in Development > Target Platforms
  3. Select your target ("GCP IDE Target Platform") and click Edit
  4. Select the location and click Reload to cause any cached info to be discarded.
  5. Click Edit and then select Uncategorized.
  6. Finish / OK until done.

Updating the Eclipse IDE Target Platforms

The IDE Target Platform, defined in eclipse/ide-target-platform, may need to be updated when dependencies are added or removed. The contents are defined in the category.xml file, which specifies the list of features and bundles that should be included. This file can be edited using the Category editor in Eclipse. Ideally the version should be specified as "0.0.0" to indicate that the current version found should be used. Unlike the .tpd file, the identifiers are not p2 identifiers, and so features do not require the .feature.group suffix.

Other Miscellaneous Dev Tasks

Updating IDE settings

See eclipse/settings/ for details.

Configuring Maven/Tycho Toolchains for new JDK releases

Now that OpenJDK is moving to a 6-month release cycle...

We use Tycho's support for Maven Toolchains to ensure that new language features do not creep into the code. Tycho's support is automatically enabled in the build when compiling with a newer JDK than our minimium supported platform. When using such a JDK, currently anything later than JDK 8, we configure the Tycho compiler plugin to use the useJDK=BREE setting to ensure bundles are compiled with a JDK that matches the bundle's Bundle-RequiredExecutionEnvironment. However we leave tycho-surefire to run the tests using the current toolchain (the default for useJDK=SYSTEM) so as to catch any non-backwards compatible changes.

These settings require configuring Maven's toolchains to point to appropriate JRE installations. Tycho further requires that a toolchain defines an id for the specified Execution Environment identifier. For example, a ~/.m2/toolchains.xml to configure Maven on macOS for Java 7, 8, and 11 toolchains might be:

<?xml version="1.0" encoding="UTF8"?>
<toolchains>
  <toolchain>
    <type>jdk</type>
    <provides>
      <id>JavaSE-11</id>
      <version>11</version>
      <vendor>openjdk</vendor>
    </provides>
    <configuration>
      <jdkHome>/Library/Java/JavaVirtualMachines/jdk-11.jdk/Contents/Home</jdkHome>
    </configuration>
  </toolchain>
  <toolchain>
    <type>jdk</type>
    <provides>
      <id>JavaSE-1.8</id>
      <version>1.8</version>
      <vendor>oracle</vendor>
    </provides>
    <configuration>
      <jdkHome>/Library/Java/JavaVirtualMachines/jdk1.8.0_181.jdk/Contents/Home/jre</jdkHome>
    </configuration>
  </toolchain>
  <toolchain>
    <type>jdk</type>
    <provides>
      <id>JavaSE-1.7</id>
      <version>1.7</version>
      <vendor>oracle</vendor>
    </provides>
    <configuration>
      <jdkHome>/Library/Java/JavaVirtualMachines/jdk1.7.0_80.jdk/Contents/Home/jre</jdkHome>
    </configuration>
  </toolchain>
</toolchains>

Note that jdkHome for JavaSE-1.7 and JavaSE-1.8 specifies the jre/ directory: Tycho sets the default boot classpath to jdkHome/lib/*, jdkHome/lib/ext/*, and jdkHome/lib/endorsed/*. For many JDKs, including Oracle's JDK and the OpenJDK prior to Java 9, those directories are actually found in the jre/ directory. Compilation errors such as java.lang.String not found and java.lang.Exception not found indicate a misconfigured jdkHome. With the introduction of Java modules with Java 9, there is no longer a separate JRE distribution.

You can’t perform that action at this time.