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
-
The Google Cloud SDK; install this somewhere on your file system.
-
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:
-
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.
-
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. -
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 inEclipse.app/Contents/Eclipse/dropins/
). -
Maven 3.5.0 or later. Although m2eclipse is bundled with its own Maven install, Maven is necessary to test command-line builds.
-
JDK 8
-
git (optional: you can use EGit from within Eclipse instead)
-
Clone the project to a local directory using
git clone https://github.com/GoogleCloudPlatform/google-cloud-eclipse.git
.
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:
- Place the SDK
/bin
directory on yourPATH
- 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 Oxygen / 4.7.
You can explicitly set the eclipse.target
property to
neon
(4.6).
$ mvn -Declipse.target=neon 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 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
-
Setup JDK 8 in Eclipse (this may already be set up by Eclipse's JRE/JDK auto-discovery)
-
Select
Window/Preferences
(on MacEclipse/Preferences
). -
Under
Java/Installed JREs
clickAdd
. -
Select Standard VM and click
Next
. -
Select the folder that contains the JDK 8 installation by clicking
Directory
. -
Click
Finish
. -
Select
Java/Installed JREs/Execution Environments
page. -
Click on
JavaSE-1.8
in the list on the left underExecution Environments:
. -
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. -
Click
OK
. -
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
. -
As described above, you must first build the target platform with Maven:
$ mvn -Pide-target-platform package
-
Open the
Preferences
dialog, go toPlug-in Development
>Target Platform
. -
Click
Add...
>Nothing
to create a new Target Platform. -
Name it
GCP IDE Target Platform
. -
Select
Add
>Software Site
. -
Select the
Add...
button (found beside theWork with:
field) and then selectLocal
to find a local repository. Navigate to.../eclipse/ide-target-platform/target/repository
, and clickOK
. -
Once the main content populates, check the
Uncategorized
item to pull in all items. ClickFinish
. -
Click
Finish
to complete the new target platform definition. -
Select your new target platform (instead of Running Platform) in the
Target Platform
preferences. -
Click
Apply and Finish
to load this new target platform. -
Eclipse will load the target.
-
Import the projects
-
Select
File/Import...
menu in Eclipse. -
Select
Existing Maven Projects
from the list. -
Click
Browse...
and select the directory that contains the project. -
Under
Projects:
thepom.xml
files representing modules should be displayed. Make sure that all of them are selected, and clickFinish
. -
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. -
Restart Eclipse when prompted.
-
Check the imported projects:
-
There should be no errors in the
Markers
orProblems
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.
-
Create and initialize a launch configuration:
-
Right-click the
gcloud-eclipse-tools.launch
file under thegoogle-cloud-eclipse
module in thePackage Explorer
. -
Select
Run As
>Run Configurations...
-
Set variables required for launch:
1. Go to the second tab for `Arguments`
1. Click the `Variables...` button for `VM argument:`
1. Click the `Edit variables...` button
1. Click `New...`
1. Set the name to `oauth_id`, and the value to the value you want to use
(description optional)
1. Click `OK`, the variable will appear in the list
1. Repeat steps 6-8 but use `oauth_secret` as the name and use the
corresponding value
1. Click `OK` to close the edit variables dialog
1. Click `Cancel` to close the variable selection dialog
1. Click `Apply` to apply the changes to the run config
-
From the
Run
menu, selectRun History > gcloud-eclipse-tools
-
A new instance of Eclipse launches with the plugin installed.
Updating Target Platforms
.target
files
Updating the 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:
- Eclipse Neon (4.6):
eclipse/neon/gcp-eclipse-neon.target
- Eclipse Oxygen (4.7):
eclipse/oxygen/gcp-eclipse-oxygen.target
- Eclipse Photon (4.8):
eclipse/photon/gcp-eclipse-photon.target
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 .target
s 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:
- Install the TPD Editor, if necessary
- Use Help > Install New Software and specify
http://mbarbero.github.io/fr.obeo.releng.targetplatform/p2/latest/
as the location. - Restart Eclipse when prompted
- Use Help > Install New Software and specify
- Open the
.tpd
file in Eclipse. - 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
).
- Note that the TPDs specify artifacts using their p2 identifiers.
Bundles are specified using their OSGi Bundle Symbolic Name (e.g.,
- 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:
mvn -Pide-target-platform package
- Preferences > Plug-in Development > Target Platforms
- Select your target ("GCP IDE Target Platform") and click Edit
- Select the location and click Reload to cause any cached info to be discarded.
- Click Edit and then select Uncategorized.
- 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 CI Builds
Note: this section is only relevant for configuring CI builds
We use Tycho's support for Maven Toolchains to ensure that Java 8
features do not creep into the code. This support is enabled by
compiling with the useJDK=BREE
setting that ensures bundles are compiled with a JDK that matches
the bundle's Bundle-RequiredExecutionEnvironment
, but configuring
tycho-surefire
to run the tests using the configured toolchain
(the default for
useJDK=SYSTEM
).
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 for a Java 8 toolchain on a Mac might be:
<?xml version="1.0"?>
<toolchains>
<toolchain>
<type>jdk</type>
<provides>
<id>JavaSE-1.8</id> <!-- the Execution Environment -->
<version>1.8</version>
<vendor>oracle</vendor>
</provides>
<configuration>
<jdkHome>/Library/Java/JavaVirtualMachines/jdk1.8.0_155.jdk/Contents/Home/jre</jdkHome>
</configuration>
</toolchain>
</toolchains>
Note that jdkHome above 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, 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.