|
|
| (29 intermediate revisions by one other user not shown) |
| Line 1: |
Line 1: |
| − | This document describes how to set up a development environment suitable for working on the EMF, SDO and XSD components. It is '''not intended for people who just want to use these tools''': the target audience are those who want to contribute to their development by adding features, fixing bugs, etc.
| + | #REDIRECT [[EMF/Setting_up_a_development_environment]] |
| − | | + | |
| − | We assume some familiarity with CVS concepts and some experience working with the Eclipse workbench.
| + | |
| − | | + | |
| − | ==Intricacies of working on EMF components==
| + | |
| − | | + | |
| − | This section discusses some special considerations that need to be taken into account when working on EMF tools.
| + | |
| − | | + | |
| − | ===Workbench instances and workspaces===
| + | |
| − | | + | |
| − | The Eclipse IDE platform is a highly customizable and extensible set of development tools. An Eclipse platform installation comprises of a set of plug-ins, each of which contributes some functionality to it. When Eclipse is launched, a ''workbench instance'' is created, making the contributed tools available for use by the developer. Active workbench instances each have a ''workspace'' associated with them. The workspace contains the resources (files, folders, etc.) that comprise the projects that a developer works on. The tools contained in the platform installation from which the workbench instance was launched can be used to work with the projects in the workspace.
| + | |
| − | | + | |
| − | ===Developing eclipse tools===
| + | |
| − | | + | |
| − | The Eclipse tools platform can be used to develop new tools for the platform. In such a scenario, a workbench instance is launched and within its associated workspace, new projects are created that contain projects intended to extend the platform by providing new tools.
| + | |
| − | | + | |
| − | To access these new tools being developed, one needs to launch a new workbench instance, in which the newly developed plug-ins from the workspace are included, so that they will be made available for use. Therefore, a developer working on extending the Eclipse IDE, will typically work using two workbench instances and two workspaces:
| + | |
| − | | + | |
| − | * Development workbench instance A with its associated workspace X.
| + | |
| − | * Testing workbench instance B with its associated workspace Y.
| + | |
| − | | + | |
| − | As an example, assume you have downloaded and installed the Eclipse IDE in <tt>C:\eclipse</tt>. When you launch eclipse you select as location <tt>C:\myWorkspace</tt> as your X workspace location and workbench instance A is then created and associated with with it. The tools installed in <tt>C:\eclipse</tt> are available in workbench instance X for you to work with.
| + | |
| − | | + | |
| − | Since your work in workspace X is creating new tools for the Eclipse platform (such as EMF), in order to test your work you need to launch a new workbench instance B: one which in addtion to the tools installed in <tt>C:\eclipse</tt> will include your tools located in workspace X (i.e. <tt>C:\myWorkspace</tt>). Eclipse allows you to create launch configurations that will launch a ''nested'' workbench instance. The nested instance has its own workspace location Y (defined as part of the launch configuration) and can include all tools installed in the parent workbench instance, as well as those in the parent workbench instance's workspace X. You may then create projects in workspace Y using (in addition to the standard tools in <tt>C:\eclipse</tt>) the tools from workspace X.
| + | |
| − | | + | |
| − | ===The notorious bug 109137===
| + | |
| − | | + | |
| − | ==Software Environment==
| + | |
| − | | + | |
| − | In order to develop on the EMF, SDO and XSD projects, you need [[EMF/FAQ#What_version_of_Eclipse_do_I_need_for_EMF.2C_SDO_and_XSD.3F_Which_EMF_version_will_run_on_my_Eclipse_version.3F | Eclipse]] and [[EMF/FAQ#What_minimum_version_of_Java_do_I_need.3F | an appropriate JRE]].
| + | |
| − | | + | |
| − | When specifying directory paths on your system, remember to compensate for any difference between the environment presented in this article and your development environment.
| + | |
| − | | + | |
| − | | + | |
| − | ==Setting up the Eclipse Workspace==
| + | |
| − | | + | |
| − | ===Configuring the plug-in environment===
| + | |
| − | | + | |
| − | | + | |
| − | You need to specify where Eclipse should look for required plug-ins if they do not exist in the current workspace. To do this:
| + | |
| − | | + | |
| − | * In the Preferences dialog (<b>Window > Preferences</b>), with <b>Plug-In Development</b> expanded, select <b>Target Platform</b>.
| + | |
| − | * Click <b>Select All</b> so that all the plug-ins are selected.
| + | |
| − | * Click <b>OK</b> to close the Preferences dialog.
| + | |
| − | | + | |
| − | [[Image:EMF_getting_sources_img1.jpg]]
| + | |
| − | | + | |
| − | ===Configuring the the Eclipse CVS preferences===
| + | |
| − | | + | |
| − | It is highly recommended to prune empty directories when extracting the code from the CVS repository. This is how you
| + | |
| − | can set Eclipse to do that:
| + | |
| − | | + | |
| − | * Select <b>Windows > Preferences > Team</b>.
| + | |
| − | * Open <b>CVS</b> and select the <b>Files and Folders</b> tab, then select <b>Prune empty directories</b>.
| + | |
| − | * Click <b>OK</b> to close the Preferences dialog.
| + | |
| − | | + | |
| − | [[Image:EMF_getting_sources_img2.jpg]]
| + | |
| − | | + | |
| − | | + | |
| − | ==Understanding the CVS Structure==
| + | |
| − | | + | |
| − | If you are unfamiliar with CVS concepts, there is a good list of resources on the [http://dev.eclipse.org/viewcvs/index.cgi/?cvsroot=Modeling_Project CVS repository] page.
| + | |
| − | | + | |
| − | ===Modules structure===
| + | |
| − | | + | |
| − | The EMF, SDO and XSD sources are divided into three modules in CVS.
| + | |
| − | | + | |
| − | <table cellspacing="0" cellpadding="5" border="1">
| + | |
| − | <tr>
| + | |
| − | <td><b>CVS Repository</b></td>
| + | |
| − | <td><b>Module</b></td>
| + | |
| − | <td colspan="2"><b>Directories</b></td>
| + | |
| − | </tr>
| + | |
| − | <tr>
| + | |
| − | <td rowspan="6" valign="top">/cvsroot/modeling</td>
| + | |
| − | <td rowspan="6" valign="top">org.eclipse.emf/org.eclipse.emf</td>
| + | |
| − | </tr>
| + | |
| − | <tr>
| + | |
| − | <td>plugins</td>
| + | |
| − | <td>contains the EMF plug-ins</td>
| + | |
| − | </tr>
| + | |
| − | <tr>
| + | |
| − | <td>[[EMF_2.3_New_Features_Migration_Guide | features]]</td>
| + | |
| − | <td>contains the EMF features</td>
| + | |
| − | </tr>
| + | |
| − | <tr>
| + | |
| − | <td>doc</td>
| + | |
| − | <td>contains the EMF documentation plug-ins and features</td>
| + | |
| − | </tr>
| + | |
| − | <tr>
| + | |
| − | <td>tests</td>
| + | |
| − | <td>contains the EMF, SDO and XSD automated tests plug-ins and features</td>
| + | |
| − | </tr>
| + | |
| − | <tr>
| + | |
| − | <td>examples</td>
| + | |
| − | <td>contains the EMF examples</td>
| + | |
| − | </tr>
| + | |
| − | <tr>
| + | |
| − | <td rowspan="4" valign="top">/cvsroot/modeling</td>
| + | |
| − | <td rowspan="4" valign="top">org.eclipse.emf/org.eclipse.emf.ecore.sdo</td>
| + | |
| − | </tr>
| + | |
| − | <tr>
| + | |
| − | <td>plugins</td>
| + | |
| − | <td>contains the SDO plug-ins</td>
| + | |
| − | </tr>
| + | |
| − | <tr>
| + | |
| − | <td>[[EMF_2.3_New_Features_Migration_Guide | features]]</td>
| + | |
| − | <td>contains the SDO features</td>
| + | |
| − | </tr>
| + | |
| − | <tr>
| + | |
| − | <td>doc</td>
| + | |
| − | <td>contains the SDO documentation plug-ins and features</td>
| + | |
| − | </tr>
| + | |
| − | <tr>
| + | |
| − | <td rowspan="5" valign="top">/cvsroot/modeling</td>
| + | |
| − | <td rowspan="5" valign="top">org.eclipse.mdt/org.eclipse.xsd</td>
| + | |
| − | </tr>
| + | |
| − | <tr>
| + | |
| − | <td>plugins</td>
| + | |
| − | <td>contains the XSD plug-ins</td>
| + | |
| − | </tr>
| + | |
| − | <tr>
| + | |
| − | <td>[[EMF_2.3_New_Features_Migration_Guide | features]]</td>
| + | |
| − | <td>contains the XSD features</td>
| + | |
| − | </tr>
| + | |
| − | <tr>
| + | |
| − | <td>doc</td>
| + | |
| − | <td>contains the XSD documentation plug-ins and features</td>
| + | |
| − | </tr>
| + | |
| − | <tr>
| + | |
| − | <td>examples</td>
| + | |
| − | <td>contains the XSD examples</td>
| + | |
| − | </tr>
| + | |
| − | </table>
| + | |
| − | | + | |
| − | EMF and SDO are components of the [http://www.eclipse.org/modeling/emf/ EMF Project]. XSD is a component of the [http://www.eclipse.org/modeling/mdt/ MDT Project].
| + | |
| − | | + | |
| − | ===Build tag and branch naming conventions===
| + | |
| − | | + | |
| − | For each build, a new CVS tag is created. The name of the CVS tag follows this convention:
| + | |
| − | | + | |
| − | build_<build id>
| + | |
| − | | + | |
| − | where <build id> is usually the build timestamp in the yyyyMMddhhmmss format (for example, 20040211140643).
| + | |
| − | | + | |
| − | The HEAD branch always contains the latest file versions, which are currently under active development. If a fix is required for a particular past build (typically a release), a branch will be created. The branch naming convention is:
| + | |
| − | | + | |
| − | branch_<build id>
| + | |
| − | | + | |
| − | The structure of the CVS repository is shown below:
| + | |
| − | | + | |
| − | [[Image:EMF_getting_sources_img3.jpg]]
| + | |
| − | | + | |
| − | If for some reason you need to get files from a certain build, look under "Versions" for the tag that identifies that build.
| + | |
| − | | + | |
| − | | + | |
| − | ==Checking Out Code as an Anonymous User==
| + | |
| − | | + | |
| − | An anonymous user has access only to check out files from the CVS repository. This user does not have the privileges to check in files.
| + | |
| − | | + | |
| − | ===Configuring the CVS client to check out files===
| + | |
| − | | + | |
| − | * Open the CVS perspective in the Eclipse Workbench by selecting <b>Windows > Open Perspective > CVS Repository Exploring</b>.
| + | |
| − | | + | |
| − | * Right click on the CVS Repositories view as shown below, and select <b>New > Repository Location...</b>
| + | |
| − | | + | |
| − | [[Image:EMF_getting_sources_img4.jpg]]
| + | |
| − | | + | |
| − | * Enter the information as shown below in the Add CVS Repository dialog and click <b>Finish</b>. This will establish a connection with the /cvsroot/modeling repository located on dev.eclipse.org, using the anonymous user ID. Make sure you set the connection type to pserver and use the default port, as shown.
| + | |
| − | | + | |
| − | [[Image:EMF_getting_sources_img5.jpg]]
| + | |
| − | | + | |
| − | | + | |
| − | ==Checking Out Code==
| + | |
| − | | + | |
| − | If you followed the instructions in the previous section, you should see a new repository entry in the CVS Repositories view.
| + | |
| − | | + | |
| − | To check out code, you have two options. Either check out the projects automatically using a [[#Using Team Project Set File (.psf)|Team Project Set File]], or [[#Manual Checkout|manually]].
| + | |
| − | | + | |
| − | ===Using Team Project Set File (.psf)===
| + | |
| − | | + | |
| − | * Download the [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/psf/?root=Modeling_Project PSF file] and save it somewhere memorable, like your desktop. You might also want a PSF for [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.ecore.sdo/psf/?root=Modeling_Project SDO] or [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.xsd/psf/?root=Modeling_Project XSD].
| + | |
| − | * Back in Eclipse, switch to the Java perspective.
| + | |
| − | * From the File menu or Project Explorer context menu, select '''Import'''.
| + | |
| − | * Choose '''Team > Team Project Set''', then click Next.
| + | |
| − | | + | |
| − | [[Image:EMF_getting_sources_img9.jpg]]
| + | |
| − | | + | |
| − | * Browse for the .psf file you want to use, downloaded from [[Media:EMF_Team_Project_Sets.zip|EMF_Team_Project_Sets.zip]]. Click Finish.
| + | |
| − | | + | |
| − | * Each feature & plugin will then be checked out as a project in the workspace.
| + | |
| − | | + | |
| − | ===Manual Checkout===
| + | |
| − | * Switch to the CVS perspective if not already there.
| + | |
| − | * Expand the repository node.
| + | |
| − | * Expand the HEAD node, as shown below, to view all the modules in the repository.
| + | |
| − | * Scroll down and expand the <code>org.eclipse.emf/org.eclipse.emf</code> module, as shown below. Select the subdirectories of the features, plugins, docs, tests, and examples directories that you want to retrieve.
| + | |
| − | * Repeat for <code>org.eclipse.emf/org.eclipse.emf.ecore.sdo</code> and <code>org.eclipse.mdt/org.eclipse.xsd</code>
| + | |
| − | * Right click and select the <b>Check Out</b> menu option.
| + | |
| − | | + | |
| − | [[Image:EMF_getting_sources_img6.jpg]]
| + | |
| − | | + | |
| − | * Each selected directory as is checked out as a project in the workspace. Once the operation is complete, you can switch to the Java perspective to work with the projects.
| + | |
| − | | + | |
| − | ==Resolving Dependency Problems==
| + | |
| − | | + | |
| − | You may find that the projects have compilation errors after you check them out. To resolve these, update the classpath. Right click on the project and select the <b>PDE Tools > Update Classpath...</b> menu option as shown below. The Java Classpath dialog appears.
| + | |
| − | | + | |
| − | [[Image:EMF_getting_sources_img7.jpg]]
| + | |
| − | | + | |
| − | Ensure that any projects with dependency problems are checked in the list of available plug-ins and fragments, and then click <b>Finish</b>.
| + | |
| − | | + | |
| − | [[Image:EMF_getting_sources_img8.jpg]]
| + | |
| − | | + | |
| − | | + | |
| − | ==Synchronizing your Local Sandbox with the HEAD Branch==
| + | |
| − | | + | |
| − | * As described above, the HEAD branch contains the latest verision of the code. To synchronize your local changes with the HEAD, right click on the resource that you want to synchronize, and then select:
| + | |
| − | | + | |
| − | Team > Synchronize with Repository
| + | |
| − | | + | |
| − | * This opens the Synchronize view. For more on using this view, see [http://help.eclipse.org/stable/index.jsp?topic=/org.eclipse.platform.doc.user/reference/ref-33.htm CVS Workspace Synchronization].
| + | |
| − | | + | |
| − | * You can merge in the changes from the HEAD manually or automatically. To merge automatically, right click on the resource you want to merge. Select:
| + | |
| − | | + | |
| − | Team > Update
| + | |
| − | | + | |
| − | * If there are conflicts that cannot be resolved automatically, CVS will insert special markup in the file to indicate that those lines could not be merged. You will need to resolve the conflicts manually. See also [http://help.eclipse.org/stable/index.jsp?topic=/org.eclipse.platform.doc.user/tasks/tasks-113b.htm Resolving conflicts]
| + | |
| − | | + | |
| − | | + | |
| − | ==More Info==
| + | |
| − | | + | |
| − | * For more information on CVS, see:
| + | |
| − | | + | |
| − | :* [http://dev.eclipse.org/viewcvs/index.cgi CVS repository]
| + | |
| − | :* [http://help.eclipse.org/stable/index.jsp?topic=/org.eclipse.platform.doc.user/reference/ref-40a.htm help.eclipse.org CVS tutorial]
| + | |
| − | :* [[CVS FAQ]]
| + | |
| − | | + | |
| − | [[Category:EMF]]
| + | |
