Eclipse Plug-in Developer Guide
Previous Page	Home	Next Page

Platform Plug-in Developer Guide Reference Other reference information

The project description file

Description: 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 DESCRIPTION_FILE_NAME on org.eclipse.core.resources.IProjectDescription.

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.

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 IProject.setDescription.

Modifications to the project description file have mostly the same effect as changing the project description via IProject.setDescription. 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.

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.

Configuration Markup:

<!ELEMENT projectDescription (name, comment, projects, buildSpec, natures, linkedResources)>

<!ELEMENT name EMPTY>

name - the name of the project. Ignored if it does match the name of the project using this description. Corresponds to IProjectDescription.getName().

<!ELEMENT comment EMPTY>

comment - a comment for the project. The comment can have arbitrary contents that are not interpreted by the project or workspace. Corresponds to IProjectDescription.getComment().

<!ELEMENT projects (project)*>
<!ELEMENT project EMPTY>

projects - the names of the projects that are referenced by this project. Corresponds to IProjectDescription.getReferencedProjects().

<!ELEMENT buildSpec (buildCommand)*>

<!ELEMENT buildCommand (name, arguments)>

<!ELEMENT name EMPTY>

<!ELEMENT arguments (dictionary?)>

<!ELEMENT dictionary (key, value)*>

<!ELEMENT key EMPTY>

<!ELEMENT value EMPTY>

buildSpec - the ordered list of build commands for this project. Corresponds to IProjectDescription.getBuildSpec().
buildCommand - a single build commands for this project. Corresponds to org.eclipse.core.resources.ICommand.
name - the symbolic name of an incremental project builder. Corresponds to ICommand.getBuilderName().
arguments - optional arguments that may be passed to the project builder. Corresponds to ICommand.getArguments().
dictionary - a list of <key, value> pairs in the argument list. Analagous to java.util.Map.

<!ELEMENT natures (nature)*>

<!ELEMENT nature EMPTY>

natures - the names of the natures that are on this project. Corresponds to IProjectDescription.getNatureIds().
nature - the name of a single natures on this project.

<!ELEMENT linkedResources (link)*>

<!ELEMENT link (name, type, location)>

<!ELEMENT name EMPTY>

<!ELEMENT type EMPTY>

<!ELEMENT location EMPTY>

linkedResources - the list of linked resources for this project.
link - the definition of a single linked resource.
name - the project-relative path of the linked resource as it appears in the workspace.
type - the resource type. Value values are: "1" for a file, or "2" for a folder.
location - 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.
locationURI - if the file is not in the local file system, this attribute contains the absolute URI of the resource in some backing file system.

Examples: The following is a sample project description file. The project has a single nature and builder configured, and some project references.

<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
    <name>WinterProject</name>
    <comment>This is a cool project.</comment>
    <projects>
        <project>org.seasons.sdt</project>
        <project>CoolStuff</project>
    </projects>
    <buildSpec>
        <buildCommand>
            <name>org.seasons.sdt.seasonBuilder</name>
            <arguments>
                <dictionary>
                    <key>climate</key>
                    <value>cold</value>
                </dictionary>
            </arguments>
        </buildCommand>
    </buildSpec>
    <natures>
        <nature>org.seasons.sdt.seasonNature</nature>
    </natures>
</projectDescription>

API Information: The contents of the project description file map to the org.eclipse.core.resources.IProjectDescription interface. The project description file can be overwritten by the method IProject.setDescription().