| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html> |
| <head> |
| |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > |
| |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| <link REL="STYLESHEET" HREF="../../book.css" CHARSET="ISO-8859-1" TYPE="text/css"> |
| <title>Project description file</title> |
| </head> |
| <body link="#0000FF" vlink="#800080"> |
| |
| <h1 align="left"> |
| The project description file</h1> |
| <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> |
| |
| <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> |
| |
| <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> |
| |
| <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. |
| </p> |
| |
| <br> |
| <p><b><i>Configuration Markup:</i></b></p> |
| <p><tt> <!ELEMENT projectDescription (name, comment, projects, |
| buildSpec, natures, linkedResources)></tt></p> |
| <p><tt> <!ELEMENT name EMPTY></tt></p> |
| <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> |
| <p><tt> <!ELEMENT comment EMPTY></tt></p> |
| <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> |
| <p><tt> <!ELEMENT buildSpec (buildCommand)*></tt></p> |
| <p><tt> <!ELEMENT buildCommand (name, arguments)></tt> </p> |
| <p><tt> <!ELEMENT name EMPTY></tt> </p> |
| <p><tt> <!ELEMENT arguments (dictionary?)></tt></p> |
| <p><tt> <!ELEMENT dictionary (key, value)*></tt></p> |
| <p><tt> <!ELEMENT key EMPTY></tt></p> |
| <p><tt> <!ELEMENT value EMPTY></tt></p> |
| <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> |
| <p><tt> <!ELEMENT natures (nature)*></tt></p> |
| <p><tt> <!ELEMENT nature EMPTY></tt></p> |
| <ul> |
| <li> |
| <b>natures </b>- the names of the natures that are on this project. |
| Corresponds to <tt>IProjectDescription.getNatureIds().</tt></li> |
| <li><b>nature </b>- the name of a single natures on this project.</li> |
| </ul> |
| <p><tt> <!ELEMENT linkedResources (link)*></tt></p> |
| <p><tt> <!ELEMENT link (name, type, location)></tt></p> |
| <p><tt> <!ELEMENT name EMPTY></tt> </p> |
| <p><tt> <!ELEMENT type EMPTY></tt> </p> |
| <p><tt> <!ELEMENT location EMPTY></tt></p> |
| |
| <ul> |
| <li><b>linkedResources</b> - the list of linked resources for this project.</li> |
| <li><b>link</b> - the definition of a single linked resource.</li> |
| <li><b>name</b> - the project-relative path of the linked resource as it appears in the workspace.</li> |
| <li><b>type</b> - the resource type. Value values are: "1" for a file, |
| or "2" for a folder.</li> |
| <li><b>location</b> - the local file system path of the target of the linked resource. Either an |
| absolute path, or a relative path whose first segment is the name of a workspace |
| path variable.</li> |
| <li><b>locationURI</b> - if the file is not in the local file system, this attribute |
| contains the absolute URI of the resource in some backing file system. |
| </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></p> |
| <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> |
| </body> |
| </html> |
