Useful files in OpenEdge Architect

This week is a little slow on posts so I thought I would post some information on how Progress Developer Studio organizes the files it uses to maintain project information.  You can find whatever I have to say here in the docs, but sometimes its nice to have it all in one place.  Some of this has changed a little bit through the different versions as new capabilities have been introduced so I'll just keep it to v11.  I think anyone who uses source code control might find this useful.  Or maybe it will just satisfy a bit of curiosity.

When a new OpenEdge project is created in PDS you get a chance to pick the project location and some of the features of the project.  This might include AppServer support, or Visual Designer support. Most of the project settings and configuration information is stored within the project itself.  In some cases simple bits of configuration information might be stored in the Eclipse metadata directory.

The .metadata directory is created underneath the workspace directory.  This directory is the "scratch" directory for all of the plugins in your Eclipse install.  It contains such things as information about projects in your workspace, your run configuration definitions, the workspace window layout information, preferences, and project properties.  Its also used by plugins to hold temporary information such as build results and file and help search indexes.  This directory is created new each time you create a new workspace.  The workspace isn't "sharable" and isn't considered source code.  It simply the local store of configuration for the workspace and it is specific to the location where it lives.

When a project is created the first thing that happen is a file named ".project" is created.  On unix file systems this will end up being a hidden file since it does not have a name, just an extension, but on windows you usually see it from the file system.  Eclipse normally filters this from the resources view so it isn't obvious it is there.  This is the project's definition.  It contains the name of the project, the builders that are registered to run on file changes, and the natures that are registered to the project. The .project file also contains definitions of any linked directories and files. Its an XML file and its usually kind of small.  One thing it doesn't contain is the physical location of the project.  Projects can live in different locations based on where you checked out code from your SCC system.   The location of the project only matters when its part of a project and that information is kept in the .metadata directory.

When PDS for OE creates a project it usually creates a .propath file in the root directory of the project.  This file is also hidden.  Its an xml file with your PROPATH directories and procedure libraries and source code directories for the project.  It also contains information about which files should be excluded from the build and which propath entries should be included based on the terminal settings (GUI vs TTY).  This file is really important to PDS, without it you get a default PROPATH for your project.  PDS for OE monitors this file for changes so any changes to it are reflected almost immediately in the build environment and AVM for the project.

If you project has a database connection assigned to it, then there will also be a .dbconnection file stored in the project's root directory.  This is a really simple file that contains the name of the database connection to associate to the AVM used for the project.  Note that if you are using a shared AVM for your project some these files are mostly ignored, but they might still exist.

If you create an OpenEdge project and use one of the special project configurations you will also see a directory called .settings created in the root of the project.  This directory contains information about the facets that are installed into the project.  Within this directory you'll see several files, usually ones for appserver and webspeed used to store directory structure for the modules, and one for the facet framework containing a list of which facets are installed.  There may be others depending on which facets are installed.  These are usually all .xml files.

OpenEdge projects that are used with GUI for .NET may also contain two other files: toolbox.xml and assemblies.xml.  The toolbox.xml file is stored in the project root with the other project configuration files.  This file contains the items that are displayed on the Visual Designer's palette.  It contains the list of palette drawers and complete class information on each item to be displayed in the VD palette.  The toolbox.xml file will only exist if you modified the palette.  By default the palette information is built from a set of defaults stored in PDS.  The other file, assemblies.xml, is built by the visual designer as you add controls to the forms within your project.  You can modify the contents of this file by hand using an editor such as the assembly maintenance tool, or a simple text editor, or even through the project properties page.  The assemblies.xml file contains references needed by the compiler and certain ABL language statements to resolve the class names referenced within the code.  You can specify an alternate assemblies.xml file using the -assemblies command line switch in the project settings and the OE plugins will use the file specified there instead of the one in the project directory.

When using a shared AVM instead of a project based AVM the .propath, .dbconnection, toolbox and assemblies.xml files within the project themselves are not used.  Instead PDS for OE uses copies of these same files that are stored in the workspace under a directory called .sharedavm.   Modifying the shared AVM's PROPATH or database connection settings will  update these files instead of the ones stored in the project.  If you are using a shared AVM you should version control these files you can have them checked into your SCC as a normal project.  You might notice there is a .project file in this .sharedavm directory.  You can import this directory as a normal Eclipse project and can use a standard Eclipse SCC plugin to maintian them.

All of the files talked about are part of a project's definition.  Each one of them plays an important role in setting up your OpenEdge project.  Each of them should be treated and maintained as regular source code.  They allow you to share your project configuration with team members so make sure you track all of them within your SCC system.

Thoughts? Questions?