THE MDT HACKING MANUAL

¤ REPOSITORY STRUCTURE

¤¤ BACKGROUND BLURB

This section describes the folder structure of the repository, where the things
are stored and where they should be stored. The discussion starts at the root
of the MDT subversion repository. Refer to the MDT website for the URL to
the root of the repository.

¤¤ THE ROOT

 (repository root)
   + tags     release (and possiby other) tags 
      + 0.2   source code for 0.2 relese of MDT
   + trunk    the mainline brunch
   + docs     general documentation on the project

¤¤ PROJECS

Inside the trunk directory or root directory of any branch there is following
structure:

  (branch root)
    + org.modelica.mdt          THE plugin project
    + org.modelica.mdt.test     the regression tests
    + org.modelica.mdt.feature  the MDT feature that groups all plugins
    + org.modelica.mdt.site     the MDT update site

All folders are Eclipse projects and can be checked out into the root of
the eclipse workspace.

¤ BUILDING SOFTWARE

The only supported way to build mdt plugins, regression tests, feature and 
update site is through Eclipse. Normaly it is sufficient to import the
projects into the workspace and let the eclipse autobuilders do the job.
Building the feature and updatesite is a manul processdure and is documented
in the 'Making a release' section in this manual.

The only general requirment for all projects is Eclipse 3.* PDE environment. 
It should be noted that only Eclipse 3.1 and 3.1.1 have been tested and stuff
may not work as prescribed in earlier versions.


¤¤ BUILDING REGRESSION TESTS

To build (and run) the regression tests you need to download 'abbot for eclipse'
version 1.0rc1 or later plugin. It is available from 
http://prdownloads.sourceforge.net/abbot/abbot_1.0-rc1-eclipse-3.0.zip?download

¤ INSTRUMENTATION

The org.modelica.mdt plugin defines trace options. The options can be used
to get an insite on what the plugin is up to. So far only tracing communication 
with OMC is implemented.

The options can be enabled from the 'Run' dialog. Choose 'Run->Run...' from
the top menu. In the 'Run' dialog make sure your Eclipse Application run 
configuration is selected, the tracing options are available in the 'Tracing' 
tab.

¤¤ org.modelica.mdt/trace/omcCalls

When enabled writes calls to and replys from OMC to the standard out. Calls
are prefixed with ">>" and replyes are preseeded with "<<".

Actually the calls which a logged are the arguments to function sendExpression()
in the OMC which is called through the CORBA interface.
 
¤¤ org.modelica.mdt/trace/omcStatus

Loggs the status of the connection to an OMC instance. So far only the code
that sets up the OMC connection is covered.
 
¤ MAKING A RELEASE

¤¤ MOTIVATIONAL BLURB

The intention of this section is to serve as both a cheat sheet while making a 
release and to formalize the release building process. A more formal release
procedure should help avoid making stupid misstakes and hopefully improve the
quality of the releases. All in all, doesn't everyone love processes?

¤¤ THE RELEASE PROCEDURE

 * start with a clean workspace, e.g. use File->Switch Workspace and switch to
   an empty folder
   
 * checkout (as Plugin-Projects) from whatever branch/revision you want to make
   a release:
   
    - org.modelica.mdt
    - org.modelica.mdt.tests
    
 * run the regression tests
   If some of the tests fail, go back to the drawing board.
   
 * remove all projects from the workspace
 
 * make a version tag in the repository
 
 * checkout from version tag location in the repository:

    - org.modelica.mdt
    - org.modelica.mdt.feature
    - org.modelica.mdt.site
  
 * update version number in org.modelica.mdt/plugin.xml
 
 * run 'PDE tools'->'Build site' from the context menu of 
   org.modelica.mdt.site/site.xml

 * export the update site to a public webserver, use 'Export'->'File System'
   wizard. Make sure that both features and plugin directories are exported.     
   
 * test with a clean eclipse installation that the MDT-plugin installs correctly
   from the update site. Use the Help->'Software Updates'->'Find and Install...'
   Check that it runs as expected.
   
 * enjoy the release party!