| <!doctype html public "-//w3c//dtd html 4.0 transitional//en"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| <meta name="GENERATOR" content="Mozilla/4.75 [en] (Windows NT 5.0; U) [Netscape]"> |
| <title>Workbench Extension Points</title> |
| </head> |
| <body link="#0000FF" vlink="#800080"> |
| |
| <center> |
| <h1> |
| The Project Description File</h1></center> |
| <b><i>Description:</i></b> When a project is created in the workspace, |
| a project description file is automatically generated that describes the |
| project. The purpose of this file is to make the project self-describing, |
| so that a project that is zipped up or released to a server can be correctly |
| recreated in another workspace. This file is always called ".project", |
| and is located as a direct member of the project's content area. |
| The name of the file is exposed through the static field <tt>DESCRIPTION_FILE_NAME</tt> |
| on <tt>org.eclipse.core.resources.IProjectDescription.</tt> |
| <p>The name, location, and content of this file are part of the workspace |
| API. This means they are guaranteed not to change in a way that would |
| break existing users of the file. However, the right to add additional |
| elements and attributes to the markup is reserved for possible future additions |
| to the file. For this reason, clients that read the description file |
| contents should tolerate unknown elements and attributes. |
| <p>Clients that modify, delete, or replace the project description file |
| do so at their own risk. Projects with invalid or missing description |
| files will not be generally usable. If a project with an invalid |
| description file is discovered on workspace startup, the project is closed, |
| and it will not be possible to open it until the project description file |
| has been repaired. The workspace will not generally attempt to automatically |
| repair a missing or invalid description file. One exception is that |
| missing project description files will be regenerated during workspace |
| save and on calls to <tt>IProject.setDescription</tt>. |
| <p>Modifications to the project description file have mostly the same effect |
| as changing the project description via <tt>IProject.setDescription</tt>. |
| One exception is that adding or removing project natures will not trigger |
| the corresponding nature's configure or deconfigure method. Another |
| exception is that changes to the project name are ignored. |
| <p>If a new project is created at a location that contains an existing |
| project description file, the contents of that description file will be |
| honoured as the project description. One exception is that the project |
| name in the file will be ignored if it does not match the name of the project |
| being created. If the description file on disk is invalid, the project |
| creation will fail. |
| <br> |
| <p><b><i>Configuration Markup:</i></b> |
| <p><tt> <!ELEMENT projectDescription (name, comment, projects, |
| buildSpec, natures)></tt><tt></tt> |
| <p><tt> <!ELEMENT name EMPTY></tt> |
| <ul> |
| <li> |
| <b>name </b>- the name of the project. Ignored if it does match the |
| name of the project using this description. Corresponds to <tt>IProjectDescription.getName()</tt>.</li> |
| </ul> |
| <tt> <!ELEMENT comment EMPTY></tt> |
| <ul> |
| <li> |
| <b>comment</b> - a comment for the project. The comment can have |
| arbitrary contents that are not interpreted by the project or workspace. |
| Corresponds to <tt>IProjectDescription.getComment()</tt>.</li> |
| </ul> |
| <tt> <!ELEMENT projects (project)*></tt> |
| <br><tt> <!ELEMENT project EMPTY></tt> |
| <ul> |
| <li> |
| <b>projects</b> - the names of the projects that are referenced by this |
| project. Corresponds to <tt>IProjectDescription.getReferencedProjects().</tt></li> |
| </ul> |
| <tt> <!ELEMENT buildSpec (buildCommand)*></tt> |
| <br><tt> <!ELEMENT buildCommand (name, arguments)></tt> |
| <br><tt> <!ELEMENT name EMPTY></tt> |
| <br><tt> <!ELEMENT arguments (dictionary?)></tt> |
| <br><tt> <!ELEMENT dictionary (key, value)*></tt> |
| <br><tt> <!ELEMENT key EMPTY></tt> |
| <br><tt> <!ELEMENT value EMPTY></tt> |
| <ul> |
| <li> |
| <b>buildSpec</b> - the ordered list of build commands for this project. |
| Corresponds to <tt>IProjectDescription.getBuildSpec().</tt></li> |
| |
| <li> |
| <b>buildCommand </b>- a single build commands for this project. Corresponds |
| to <tt>org.eclipse.core.resources.ICommand.</tt></li> |
| |
| <li> |
| <b>name</b> - the symbolic name of an incremental project builder. |
| Corresponds to <tt>ICommand.getBuilderName().</tt></li> |
| |
| <li> |
| <b>arguments</b> - optional arguments that may be passed to the project |
| builder. Corresponds to <tt>ICommand.getArguments()</tt>.</li> |
| |
| <li> |
| <b>dictionary</b> - a list of <key, value> pairs in the argument list. |
| Analagous to <tt>java.util.Map.</tt></li> |
| </ul> |
| <tt> <!ELEMENT natures (nature)*></tt> |
| <br><tt> <!ELEMENT nature EMPTY></tt> |
| <ul> |
| <li> |
| <b>natures </b>- the names of the natures that are on this project. |
| Corresponds to <tt>IProjectDescription.getNatureIds().</tt></li> |
| </ul> |
| <b><i>Examples: </i></b>The following is a sample project description file. |
| The project has a single nature and builder configured, and some project |
| references. |
| <p><tt><?xml version="1.0" encoding="UTF-8"?></tt> |
| <br><tt><projectDescription></tt> |
| <br><tt> <name>WinterProject</name></tt> |
| <br><tt> <comment>This is a cool project.</comment></tt> |
| <br><tt> <projects></tt> |
| <br><tt> <project>org.seasons.sdt</project></tt> |
| <br><tt> <project>CoolStuff</project></tt> |
| <br><tt> </projects></tt> |
| <br><tt> <buildSpec></tt> |
| <br><tt> <buildCommand></tt> |
| <br><tt> |
| <name>org.seasons.sdt.seasonBuilder</name></tt> |
| <br><tt> |
| <arguments></tt> |
| <br><tt> |
| <dictionary></tt> |
| <br><tt> |
| <key>climate</key></tt> |
| <br><tt> |
| <value>cold</value></tt> |
| <br><tt> |
| </dictionary></tt> |
| <br><tt> |
| </arguments></tt> |
| <br><tt> </buildCommand></tt> |
| <br><tt> </buildSpec></tt> |
| <br><tt> <natures></tt> |
| <br><tt> <nature>org.seasons.sdt.seasonNature</nature></tt> |
| <br><tt> </natures></tt> |
| <br><tt></projectDescription></tt> |
| <br> <b><i></i></b> |
| <p><b><i>API Information:</i></b> The contents of the project description |
| file map to the <tt>org.eclipse.core.resources.IProjectDescription</tt> |
| interface. The project description file can be overwritten by the method |
| <tt>IProject.setDescription()</tt>. |
| <p><a href="hglegal.htm"><img SRC="ngibmcpy.gif" ALT="Copyright IBM Corp. 2000, 2002. All Rights Reserved." BORDER=0 height=12 width=195></a> |
| </body> |
| </html> |