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>

   <!ELEMENT comment EMPTY>

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

   <!ELEMENT buildSpec (buildCommand)*>

   <!ELEMENT buildCommand (name, arguments)>

   <!ELEMENT name EMPTY>

   <!ELEMENT arguments (dictionary?)>

   <!ELEMENT dictionary (key, value)*>

   <!ELEMENT key EMPTY>

   <!ELEMENT value EMPTY>

   <!ELEMENT natures (nature)*>

   <!ELEMENT nature EMPTY>

   <!ELEMENT linkedResources (link)*>

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

   <!ELEMENT name EMPTY>

   <!ELEMENT type EMPTY>

   <!ELEMENT location EMPTY>

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().