.1 Electric Cloud ElectricCommander Technical Notes Eclipse Integration version 1.2.1 September 2010 This document contains information about the ElectricCommander integration with Eclipse for Eclipse (plugin) versions 3.3, 3.4, 3.5, and 3.6. These Eclipse versions are fully tested by Electric Cloud. However, other Eclipse versions may be compatible as well. Topics include: Overview... 2 Prerequisites... 2 Installing the Eclipse Plugin... 3 Configuring the Eclipse Plugin... 5 Using the Eclipse Plugin... 12 Troubleshooting and Getting Help... 14 1
Overview Overview ElectricCommander integrates with Eclipse Plugin versions 3.3, 3.4, 3.5, and 3.6. Eclipse is an open software platform comprised of extensible application frameworks, tools, and a runtime library for software development and management. Eclipse is written primarily in Java and provides software developers and administrators an integrated development environment (IDE). The ElectricCommander Eclipse Plugin Integration provides the following capabilities: Initiate a pre-defined Preflight Build, which allows users to "snapshot" code and run a build to test new code before their changes are committed Initiate a typical ElectricCommander procedure Monitor the status of a running or completed ElectricCommander job Initiate a connection to the ElectricCommander web server and perform any user or administrator task This document describes features, installation, configuration, and use of ElectricCommander s Eclipse Plugin Integration. Note: Installation and configuration instructions for each Eclipse version may be slightly different. This document displays installation screens from Eclipse 3.6. Prerequisites ElectricCommander s Eclipse Plugin Integration requires the following: Access to an ElectricCommander v3.2 server or higher Eclipse 3.3 (Europa), 3.4 (Ganymede), 3.5 (Galileo), and 3.6 (Helios) Note: These Eclipse versions are fully tested by Electric Cloud. However, other Eclipse versions may be compatible as well. JRE 5 or higher Windows XP, Vista, and Windows 7, or Redhat Enterprise Linux 4.0 or higher, or Ubuntu 8.04 or higher For preflight build functionality, you must use one of the following Source Code Management Systems: AccuRev, ClearCase, Perforce, or Subversion Note: If you are using Perforce or Subversion, you must go to those respective websites and download either the Perforce Plugin for Eclipse or the Subclipse plugin for Subversion. 2
Installing the Eclipse Plugin Installing the Eclipse Plugin Download the Eclipse Plugin from the Electric Cloud FTP site. After logging into the FTP site, go to /commander/release_3.x/<commander release>/integrations/eclipse_x and download the ElectricCommanderEclipsePlugin_1.2.1.zip file. Extract the ZIP file. The Eclipse Plugin can be installed locally or remotely. For a multiple user installation, you may want to put the Eclipse Plugin on a web server. Eclipse 3.6 Plugin 1. Start the Software Updates and Add-ons wizard by selecting Help > Install New Software... 2. In the new window, select the Add button to see the Add Repository screen. 3
Installing the Eclipse Plugin 3. On the next Add Repository screen, supply any name of your choice for the Repository Name. 4. Choose one of the following actions: Enter the remote URL if this is a remote or shared installation. Select Local to navigate to the Eclipse Update Site directory (extracted from the ZIP file). Select the Archive button, then browse to select the ZIP file and click OK. 5. Click Next on the following screen to continue. 6. Read and accept the terms of the license agreement and then click Finish. 4
Configuring the Eclipse Plugin Configuring the Eclipse Plugin After successfully installing the ElectricCommander Eclipse Plugin, your Eclipse Integrated Development Environment (IDE) provides a new run configuration named CommanderProcedure, which enables multiple run configurations associated with your workspace. The ElectricCommander Eclipse Plugin is configured on a "per run configuration" basis. This means you can configure multiple run configurations for different Eclipse projects, ElectricCommander projects, SCM options, and ElectricCommander procedure parameters. This section describes Eclipse Plugin configuration options. Creating a run configuration After you open an Eclipse workspace, you can create a "run configuration" using one of the following methods: Opening a run configuration in Eclipse 3.6 Select the small down-arrow on the right-side of the round "play" button in the Eclipse toolbar and select Run Configurations... 5
Configuring the Eclipse Plugin Creating a new run configuration From this point forward, configuration of the Eclipse Plugin between Eclipse 3.3, 3.4, 3.5, and 3.6 is the same except for the name in the title bar. In the Run (or Run Configurations) window, select the run configuration named ElectricCommanderProcedure and select the "New" icon in the upper left of the window (it looks like a blank sheet of paper with a yellow plus-sign in the upper right corner) or just double-click the ElectricCommanderProcedure name. Notice the leaf node under ElectricCommanderProcedure click this icon to display a multi-tabbed form on the right side of the page. Configuring a new run configuration Now you are on the Procedure screen the Procedure tab is highlighted. See the screen example on the next page. Procedure tab This screen displays all options specific to the ElectricCommander server you are using. You may need to ask your ElectricCommander administrator for assistance with filling-in these values. The only "non-electriccommander-specific" option is the field labeled Eclipse Project. This configuration is specific to your current workspace so this field is meant for you to choose a specific Eclipse project you are working on. When you supply an Eclipse Project name, the "Specify Project" error message will disappear. Default values are supplied, but you must: In the Name field, change the name of "Procedure1" (your ElectricCommander procedure name) to something more meaningful for your purpose. Change the Hostname to your ElectricCommander server name. Change the Base URL to the URL you need. In the Procedure Settings section, add your ElectricCommander Project Name, Procedure Name, and ElectricCommander Username. When all fields contain the appropriate information, you do not need to select any of the buttons at the bottom of the screen. Instead: Select the Parameters tab if you need to supply one or more parameters, or if no parameters are needed, skip the Parameters tab and... Select the Preflight Settings tab. 6
Configuring the Eclipse Plugin. Parameters tab The Parameters tab allows you to supply parameters to pass to the ElectricCommander project specified on the Procedure tab page. For help in understanding which parameters are applicable for your ElectricCommander procedure, you may need to ask your ElectricCommander Administrator. See the next illustration for an example of the Parameters screen. 7
Configuring the Eclipse Plugin Use the buttons on the right-side of the screen to Add... one or more parameters. If you supply a parameter that needs updating or you need to delete it, use the corresponding Edit... or Remove... buttons for those tasks. When this screen contains the appropriate information, you do not need to select any of the buttons at the bottom of the screen. Instead, select the Preflight Settings tab to configure your Preflight Builds. 8
Configuring the Eclipse Plugin Preflight Settings tab The ElectricCommander Eclipse Plugin can auto-detect the Source Code Management (SCM) system you are using. On the Preflight Settings page, you have the option of selecting the Run Procedure tab, which will run a normal ElectricCommander procedure, or you can choose to configure your SCM by selecting the tab that represents your specific SCM system. Currently, the Eclipse Plugin works with Perforce, Subversion, ClearCase, and AccuRev. For help configuring specific SCM settings, contact your SCM administrator. If you select an SCM specific tab as your default configuration, the last option is a Commit changes on successful preflight checkbox. Commit Select the Commit changes on successful preflight checkbox only if you have specified your SCM on this page. When you run a build, the Eclipse Plugin uses the configuration information you provided and calls a script named ecclientpreflight. When "Commit..." is "unchecked" (the default), ecclientpreflight communicates with the ElectricCommander server for the sole purpose of 9
Configuring the Eclipse Plugin retrieving a "job ID" to allow you to manually monitor build status. After the job ID is retrieved, a hyperlink is displayed in the job console window and the ecclientpreflight script ends. If "Commit..." is "checked," the ecclientpreflight script does not immediately exit. Instead, ecclientpreflight continues to run in the background and monitors the status of the submitted job, waiting for it to complete. If the ElectricCommander job completes successfully, the ecclientpreflight script executes the appropriate commit message on the developer's workstation. If the commit is attempted, certain configuration options in your SCM configuration may be required (for example, a commit message in the case of Perforce). Important: If a job with "Commit" is set, Commit will not occur in the following circumstances: The ElectricCommander job fails The developer severs the connection to the ElectricCommander server from their local workstation The developer "kills" the ecclientpreflight script The SCM rejects the submission Click Run after supplying the information you need, or select the Common tab to take advantage of additional features. 10
Configuring the Eclipse Plugin Common tab This tab is associated with any Eclipse run configuration (not specifically the ElectricCommander Eclipse Plugin) based on which SCM your Eclipse project is using. Selecting this tab allows you to add this Run Configuration to your Favorites menu and other equally useful options. For example, if you select the Shared file radio button, you have the option to save the Run Configuration inside your Eclipse workspace. Refer to Eclipse Help for more information. In the Display in Favorites menu box, select the items you want to see in your Favorites menu. Click Run if you want to run the configuration at this time... or at a later time, go back to the small down-arrow [on the toolbar] on the right-side of the round "play" button to access the list of available configurations to run or create a new one. 11
Using the Eclipse Plugin Using the Eclipse Plugin After an Eclipse project has the ElectricCommander Eclipse Plugin run command associated with it, you can leverage the power of ElectricCommander within Eclipse. Running a procedure Select the Run Configurations option configured from the Eclipse Run Dialog dropdown menu and the ElectricCommander Eclipse Plugin starts an ElectricCommander job. Job output is sent to the Eclipse Console window. After the job is submitted successfully, a link to the job is displayed in the Console window along with the output from ecclientpreflight. Checking job status After a job is submitted: You can monitor the job in the Eclipse Console window. A link is created for you to open the ElectricCommander Job Details web page. Note: By default, the ElectricCommander web page is opened in your Eclipse IDE and does not require you to switch applications. See the following page for an Eclipse/ElectricCommander screen example. 12
Using the Eclipse Plugin An example of the ElectricCommander Job Details web page as viewed with the Eclipse Plugin: 13
Troubleshooting and Getting Help Troubleshooting and Getting Help Contacting Technical Support: Before you contact our technical support staff, please have the following information available. Your name, title, company name, phone number, fax number, and email address Operating system and version number Product name and release version Problem description Hours: 8AM - 5PM PST (Monday-Friday, except Holidays) Phone: 408-419-4300, Option #2 Email: support@electric-cloud.com Copyright 2006-2010 Electric Cloud, Inc. All rights reserved. Electric Cloud believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. THE INFORMATION IN THIS PUBLICATION IS PROVIDED AS IS. ELECTRIC CLOUD, INC. MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Use, copying, and distribution of any Electric Cloud software described in this publication requires an applicable software license. Trademarks Electric Cloud, ElectricAccelerator, ElectricCommander, ElectricInsight, Electric Make, and SparkBuild are registered trademarks or trademarks of Electric Cloud, Incorporated. Electric Cloud products ElectricAccelerator, ElectricCommander, ElectricInsight, and Electric Make are commonly referred to by their "short names" Accelerator, Commander, Insight, and emake throughout various types of Electric Cloud product-specific documentation. All other trademarks used herein are the property of their respective owners. 14