source: docs/HACKING @ 576

Last change on this file since 576 was 434, checked in by boris, 19 years ago
  • minor updates to HACKING manual
File size: 5.9 KB
RevLine 
[169]1THE MDT HACKING MANUAL
[168]2
[309]3� THESIS REPORT
[241]4
5The thesis report will hopefully contain some usefull information for
6developers of MDT. Here someone will add a list of section to read there.
7
[309]8� REPOSITORY STRUCTURE
[168]9
[309]10�� BACKGROUND BLURB
[168]11
[169]12This section describes the folder structure of the repository, where the things
13are stored and where they should be stored. The discussion starts at the root
14of the MDT subversion repository. Refer to the MDT website for the URL to
15the root of the repository.
16
[309]17�� THE ROOT
[169]18
19 (repository root)
20   + tags     release (and possiby other) tags
[241]21      + 0.2   source code for 0.2 release of MDT
[169]22   + trunk    the mainline brunch
23   + docs     general documentation on the project
24
[309]25�� PROJECS
[169]26
27Inside the trunk directory or root directory of any branch there is following
28structure:
29
30  (branch root)
[276]31    + org.modelica.mdt.core     The core plugin project
[247]32    + org.modelica.mdt.ui       the UI contributions of the MDT plugin
[241]33    + org.modelica.mdt.omc      the OMC 'driver'
[169]34    + org.modelica.mdt.test     the regression tests
35    + org.modelica.mdt.feature  the MDT feature that groups all plugins
36    + org.modelica.mdt.site     the MDT update site
37
38All folders are Eclipse projects and can be checked out into the root of
39the eclipse workspace.
40
[309]41� BUILDING SOFTWARE
[169]42
43The only supported way to build mdt plugins, regression tests, feature and
44update site is through Eclipse. Normaly it is sufficient to import the
45projects into the workspace and let the eclipse autobuilders do the job.
46Building the feature and updatesite is a manul processdure and is documented
47in the 'Making a release' section in this manual.
48
49The only general requirment for all projects is Eclipse 3.* PDE environment.
50It should be noted that only Eclipse 3.1 and 3.1.1 have been tested and stuff
51may not work as prescribed in earlier versions.
52
53
[309]54�� BUILDING REGRESSION TESTS
[169]55
56To build (and run) the regression tests you need to download 'abbot for eclipse'
57version 1.0rc1 or later plugin. It is available from
58http://prdownloads.sourceforge.net/abbot/abbot_1.0-rc1-eclipse-3.0.zip?download
[173]59
[309]60�� PROJECTS FOR REGRESSION TESTS
[264]61
62Many test cases need to create a projects to setup the environment for testing.
63Becouse all the tests are run in the same workspace there is a risk of
64conflicts in the projects namespace between different test cases. To avoid this
65and to simplify maintainance of the tests, following scheme should be used apon
66creation of guinnia pig projects.
67
68For each created project a constant PROJECT_NAME_n must be created. The constant
69should be assigned value of TestCaseName.class.getName() + "1". For example test
70case TestFoo, which will create two project will contain following constant
71declaration:
72
73public class TestFoo extends TestCase
74{
75    private static final String PROJECT_NAME_1 =
76        TestFoo.class.getName() + "1";
77
78    private static final String PROJECT_NAME_2 =
79        TestFoo.class.getName() + "2";
80   
81    // .....
82}
83
[309]84� INSTRUMENTATION
[173]85
[241]86The org.modelica.mdt.omc plugin defines trace options. The options can be used
[185]87to get an insite on what the plugin is up to. So far only tracing communication
88with OMC is implemented.
[173]89
[185]90The options can be enabled from the 'Run' dialog. Choose 'Run->Run...' from
91the top menu. In the 'Run' dialog make sure your Eclipse Application run
92configuration is selected, the tracing options are available in the 'Tracing'
93tab.
94
[309]95�� org.modelica.mdt.omc/trace/omcCalls
[173]96
97When enabled writes calls to and replys from OMC to the standard out. Calls
98are prefixed with ">>" and replyes are preseeded with "<<".
99
100Actually the calls which a logged are the arguments to function sendExpression()
101in the OMC which is called through the CORBA interface.
[169]102 
[309]103�� org.modelica.mdt.omc/trace/omcStatus
[185]104
105Loggs the status of the connection to an OMC instance. So far only the code
106that sets up the OMC connection is covered.
107 
[309]108� MAKING A RELEASE
[169]109
[309]110�� MOTIVATIONAL BLURB
[169]111
[168]112The intention of this section is to serve as both a cheat sheet while making a
113release and to formalize the release building process. A more formal release
114procedure should help avoid making stupid misstakes and hopefully improve the
115quality of the releases. All in all, doesn't everyone love processes?
116
[309]117�� THE RELEASE PROCEDURE
[168]118
119 * start with a clean workspace, e.g. use File->Switch Workspace and switch to
120   an empty folder
121   
122 * checkout (as Plugin-Projects) from whatever branch/revision you want to make
123   a release:
124   
[309]125    - org.modelica.mdt.core
126    - org.modelica.mdt.omc
127    - org.modelica.mdt.ui
[420]128    - org.modelica.mdt.feature
129    - org.modelica.mdt.site
130    - org.modelica.mdt.test
131
132 * if you have trouble building do this:
133   - update classpath on core, omc, ui and test plugins
134     (PDE Tools -> Update classpath... from context menu on project node)
135   - make sure Java Compiler is set to version 5 (1.5) on projects or globaly
[168]136   
137 * run the regression tests
138   If some of the tests fail, go back to the drawing board.
139
[420]140 * update version number in:
141    org.modelica.mdt.core/plugin.xml
142    org.modelica.mdt.omc/plugin.xml
143    org.modelica.mdt.ui/plugin.xml
144    org.modelica.mdt.feature/feature.xml
145
[434]146* add the new version feature to the update site
[168]147 
148 * run 'PDE tools'->'Build site' from the context menu of
149   org.modelica.mdt.site/site.xml
150
[420]151 * export the update site to a test location on a webserver, use
152   'Export'->'File System' wizard. Make sure that both features and plugin
153   directories are exported.   
[168]154   
155 * test with a clean eclipse installation that the MDT-plugin installs correctly
156   from the update site. Use the Help->'Software Updates'->'Find and Install...'
157   Check that it runs as expected.
[434]158
159 * commit changes
[168]160   
[420]161 * upload the binaries to the offical update site
[434]162
163 * make a version tag in <..>/tags folder in repository after the
164   relase is made public
[420]165   
[168]166 * enjoy the release party!
167 
Note: See TracBrowser for help on using the repository browser.