1 | <?xml version="1.0" encoding="UTF-8"?>
|
---|
2 | <?xml-stylesheet type="text/css"
|
---|
3 | href="eclipseos2-xxe.css"
|
---|
4 | ?>
|
---|
5 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
---|
6 | "xhtml1-strict.dtd">
|
---|
7 | <html>
|
---|
8 | <head>
|
---|
9 | <link href="eclipseos2.css" rel="stylesheet" type="text/css" />
|
---|
10 |
|
---|
11 | <title>Eclipse for OS/2 Transitional Project Notes</title>
|
---|
12 | </head>
|
---|
13 |
|
---|
14 | <body>
|
---|
15 | <h1>Introduction</h1>
|
---|
16 |
|
---|
17 | <p>This document contains various notes about the structure and concepts
|
---|
18 | of the Eclipse SDK (<a href="www.eclipse.org">www.eclipse.org</a>)
|
---|
19 | relative to the Eclipse for OS/2 project, the discussion of porting
|
---|
20 | process, the roadmap of the project, the description of the current
|
---|
21 | project status and may be something else which that can be useful. The
|
---|
22 | content of this document assumes that someone is familiar enough with the
|
---|
23 | basics of Eclipse.</p>
|
---|
24 |
|
---|
25 | <p>These Notes are best viewed with Mozilla (since Netscape's CSS support
|
---|
26 | is terrible).</p>
|
---|
27 |
|
---|
28 | <p>To get a brief description of changes in the project go to the <a
|
---|
29 | href="whatsnew.html">whatsnew</a> section.</p>
|
---|
30 |
|
---|
31 | <p><i>Please note that this is an internal document intended for people
|
---|
32 | who work on this project (like sticky notes on a monitor) so any graceful
|
---|
33 | narration is not expected.</i></p>
|
---|
34 |
|
---|
35 | <h2>Porting strategy</h2>
|
---|
36 |
|
---|
37 | <p>Eclipse platform consists of several parts (components), each of them
|
---|
38 | implements one of the basic aspects of functionality. The most significant
|
---|
39 | part (from the porting point of view) is the Standard Widget Toolkit (SWT)
|
---|
40 | component, an alternative UI library that is used as a GUI base for all
|
---|
41 | other components of Eclipse, including the Eclipse JDT (Java Development
|
---|
42 | Tooling, an Eclipse IDE). The main goal of SWT is its "nativeness", as
|
---|
43 | opposed to the standard Java 2 Swing library. This means that it is based
|
---|
44 | on the mechanisms of the host platform's windowing system, directly using
|
---|
45 | its API from the native Java methods.</p>
|
---|
46 |
|
---|
47 | <p>So, the porting process can be divided into two main parts: porting of
|
---|
48 | SWT and then porting of all other platform sensitive parts (such as
|
---|
49 | workspace core classes, launcher, updater and so on). Each part, in turn,
|
---|
50 | is divided into small steps (for the easiness of porting and maintenance)
|
---|
51 | and has its own porting roadmap. The first one that must be ported is SWT:
|
---|
52 | it is completely independent from everything else in Eclipse, but many
|
---|
53 | other components depend on it.</p>
|
---|
54 |
|
---|
55 | <p>Here are:</p>
|
---|
56 |
|
---|
57 | <ul>
|
---|
58 | <li><a href="swt.html">notes on porting SWT</a></li>
|
---|
59 |
|
---|
60 | <li><a href="other.html">notes on porting other components</a></li>
|
---|
61 | </ul>
|
---|
62 |
|
---|
63 | <p>As a base for our work we decided to take the release 2.0.1 of Eclipse
|
---|
64 | SDK as the most recent release to the day we have started. The total size
|
---|
65 | of the Eclipse source code is about 100 MB and it's not necessary to keep
|
---|
66 | them all in our project because only a small part will be affected by the
|
---|
67 | porting process. So we will put in the project's repository only the
|
---|
68 | pieces that are changed by us and, of course, new ones we create for OS/2
|
---|
69 | support.</p>
|
---|
70 |
|
---|
71 | <h2>Repository structure</h2>
|
---|
72 |
|
---|
73 | <p>The <b>eclipseos2</b> repository has the following structure:</p>
|
---|
74 |
|
---|
75 | <table>
|
---|
76 | <tr>
|
---|
77 | <td><kbd>doc/</kbd></td>
|
---|
78 |
|
---|
79 | <td>Project documentation, including these Notes.</td>
|
---|
80 | </tr>
|
---|
81 |
|
---|
82 | <tr>
|
---|
83 | <td><kbd>src/</kbd></td>
|
---|
84 |
|
---|
85 | <td>The sources of Eclipse we are working with. It includes only the
|
---|
86 | sources that make an OS/2 platform support in Eclipse, but the
|
---|
87 | structure of this directory is similar to the original, which will
|
---|
88 | help to join the main stream in the future.</td>
|
---|
89 | </tr>
|
---|
90 |
|
---|
91 | <tr>
|
---|
92 | <td><kbd>tests/</kbd></td>
|
---|
93 |
|
---|
94 | <td>This contains our C and Java test suites.</td>
|
---|
95 | </tr>
|
---|
96 |
|
---|
97 | <tr>
|
---|
98 | <td><kbd>misc/</kbd></td>
|
---|
99 |
|
---|
100 | <td>Various tools, helper scripts, docs and other useful stuff.</td>
|
---|
101 | </tr>
|
---|
102 | </table>
|
---|
103 |
|
---|
104 | <h3>Tag policy</h3>
|
---|
105 |
|
---|
106 | <p>Original Eclipse sources, that are common for all platforms but need to
|
---|
107 | be changed to include OS/2 support, are placed on the
|
---|
108 | <kbd>eclipse-team</kbd> branch. Tags on that branch correspond to the
|
---|
109 | official Eclipse releases. Currently, there is only one release (that one
|
---|
110 | we are based on) in the repository tagged as <kbd>rel-2-0-1</kbd>. When we
|
---|
111 | add a new part of common Eclipse sources to our repository we put them
|
---|
112 | with this tag.</p>
|
---|
113 |
|
---|
114 | <p>Tags on the main trunk are composed according to the following scheme:
|
---|
115 | <kbd>tr-<ppp>-<NNN></kbd>, where <kbd>tr</kbd> means
|
---|
116 | transitional, <kbd><ppp></kbd> can be <kbd>swt </kbd>or <kbd>other
|
---|
117 | </kbd>and <kbd><NNN></kbd> is the step number. These tags are
|
---|
118 | assigned when the certain step is completely done.</p>
|
---|
119 |
|
---|
120 | <h3><a name="ordinary.checkins">Ordinary checkins</a></h3>
|
---|
121 |
|
---|
122 | <p>Ordinary checkins (commits) are done using the following rules:</p>
|
---|
123 |
|
---|
124 | <ul>
|
---|
125 | <li>On commit, all more or less significant changes must be placed to
|
---|
126 | the commit message of a file (or a group of files) being committed.
|
---|
127 | Every separate entry in the commit message starts with a dash (minus
|
---|
128 | sign) followed by a space. Sub-entries (if any) start with an asterisk
|
---|
129 | and a space. Every entry ends with a new line character (note: no new
|
---|
130 | line characters should be entered in the middle of the entry).</li>
|
---|
131 |
|
---|
132 | <li>For the group of files committed at once, if the message entry does
|
---|
133 | not apply to all of them, then it should start with a comma-separated
|
---|
134 | list of files it relates to, followed by a colon.</li>
|
---|
135 |
|
---|
136 | <li>In case of several sequental commits (a series of commits), these
|
---|
137 | commits should be done as close as possible to each other (in time), to
|
---|
138 | provide the repository consistensy. It is forbidden for the series of
|
---|
139 | relative commits to span two or more days. The repository contents must
|
---|
140 | be compiled without errors after every commit or the series of
|
---|
141 | commits.</li>
|
---|
142 |
|
---|
143 | <li>After every commit (or a series of commits) the <a
|
---|
144 | href="../ChangeLog">ChangeLog</a> must be updated (using the Perl
|
---|
145 | script, see below). All major changes must be briefly described in the
|
---|
146 | <a href="whatsnew.html">whatsnew</a> file. The conceptual changes and
|
---|
147 | other important information not suitable for the ChangeLog must be
|
---|
148 | placed to the corresponding step notes file (to the <b>Task notes</b>
|
---|
149 | section).</li>
|
---|
150 |
|
---|
151 | <li>ChangeLog, whatsnew and step notes must be committed immediately
|
---|
152 | after a series of relative commits, with an empty commit message. Every
|
---|
153 | whatsnew section must start with a date (in the format
|
---|
154 | <kbd>YYYY-MM-DD</kbd>) followed by a name of the contributor.</li>
|
---|
155 | </ul>
|
---|
156 |
|
---|
157 | <p>Here is an example of the typical message typed during commit:</p>
|
---|
158 |
|
---|
159 | <pre>- This is a common message to the entire commit operation.
|
---|
160 | - This is another common commit message, detailed like this:
|
---|
161 | * some detail;
|
---|
162 | * some another detail.
|
---|
163 | - o/e/swt/graphics/GC.java, o/e/swt/widgets/Control.java, Button.java: a commit message specific only to a subset of files being committed.
|
---|
164 | - o.e.swt.graphics.GC, o.e.swt.widgets.Control: java files can be alternatively listed like this.</pre>
|
---|
165 |
|
---|
166 | <p>The ChangeLog file must be always updated automatically by the Perl
|
---|
167 | script, <kbd>cvs2cl.pl.cmd</kbd>, that is located in the <kbd>/misc</kbd>
|
---|
168 | subdirectory of the repository. Manual ChangeLog changes will be simply
|
---|
169 | overwritten by the script. The preferred way to execute the script is to
|
---|
170 | use the <kbd>changelog</kbd> ant target (see below) that sets up necessary
|
---|
171 | command line arguments. Note: in order to be able to run the script you
|
---|
172 | must have Perl installed on your system. A recent OS/2 version of Perl can
|
---|
173 | be downloaded from here: <a
|
---|
174 | href="http://www.cpan.org/ports/os2/">http://www.cpan.org/ports/os2/</a>.
|
---|
175 | The script is tested to work well with at least v5.8.2 of Perl for
|
---|
176 | OS/2.</p>
|
---|
177 |
|
---|
178 | <h2><a name="conventions">Porting conventions</a></h2>
|
---|
179 |
|
---|
180 | <p>We use special marks in common source files (i.e. files which are
|
---|
181 | shared between all platforms) to flag the changes we made to add an OS/2
|
---|
182 | support. Also the special form of "todo" and "temp" markers is used. Here
|
---|
183 | is an example of usage of this stuff:</p>
|
---|
184 |
|
---|
185 | <pre><b>//@@OS2+</b>
|
---|
186 | lines added or changed for OS/2 begin here
|
---|
187 | ...
|
---|
188 | and up to here
|
---|
189 | <b>//@@OS2-</b>
|
---|
190 | ...
|
---|
191 | and here's a single added/changed line <b>//@@OS2</b>
|
---|
192 | ...
|
---|
193 | <b>//@@OS2:</b> and this is an OS/2 related comment
|
---|
194 | ...
|
---|
195 | ... <b>//@@TODO</b>: not to forget to check the value returned
|
---|
196 | ...
|
---|
197 | ... <b>//@@TEMP:</b> the section of code below is temporary and will be changed/removed in short</pre>
|
---|
198 |
|
---|
199 | <p>There are two attributes in the Eclipse terminology (plugin/package
|
---|
200 | naming conventions, build process and so on) to identify the platform
|
---|
201 | which the certain build of the Eclipse is intended to be run on. They are
|
---|
202 | <i>os</i> (operating system) and <i>ws</i> (windowing system of that
|
---|
203 | operating system). We decided the following is the best for OS/2: os =
|
---|
204 | <b>os2</b> and ws = <b>pm</b>.</p>
|
---|
205 |
|
---|
206 | <h2><a name="compilation">Compilation notes</a></h2>
|
---|
207 |
|
---|
208 | <p>Since we do not keep all the Eclipse sources in our repository, the
|
---|
209 | original Eclipse SDK release 2.0.1 <a
|
---|
210 | href="http://download.eclipse.org/downloads/drops/R-2.0.1-200208291828/download.php?dropFile=eclipse-sourceBuild-srcIncluded-2.0.1.zip">sources</a>
|
---|
211 | are needed in order to get something compiled -- components that are not
|
---|
212 | affected by our work are taken from there. The original sources should not
|
---|
213 | be placed under our project directory structure, but somewhere else.</p>
|
---|
214 |
|
---|
215 | <h3>Java code build</h3>
|
---|
216 |
|
---|
217 | <p>To build the Java code the Java Toolkit 1.3 or 1.3.1 for OS/2 is
|
---|
218 | required. Version 1.3 is recommended since it takes less memory during
|
---|
219 | execution and is free of the unpleasant OS/2=>Java clipboard bug.</p>
|
---|
220 |
|
---|
221 | <p>The build process is controlled by <a
|
---|
222 | href="http://jakarta.apache.org/ant/index.html">Ant</a>. The recommended
|
---|
223 | version is 1.5.4. Also a patch for this version is required (in order, to
|
---|
224 | use the <kbd>dll</kbd> target, see below). This patch can be found on the
|
---|
225 | repository (<kbd>$CVSROOT/misc/ant-1.5.4-patch-os2.jar</kbd>). See the
|
---|
226 | <kbd>readme.txt</kbd> file inside the jar on how to install it. The
|
---|
227 | <code><kbd>misc</kbd></code> directory of the repository also contains the
|
---|
228 | <kbd>ant.cmd</kbd> file, which can be used to run Ant and contains the
|
---|
229 | correct classpath definition needed to use the patch. This file can be
|
---|
230 | placed somewhere in the PATH -- just ensure that the <code>ant_home</code>
|
---|
231 | variable inside it points to the right Ant installation directory (correct
|
---|
232 | it if necessary) and that you have the <code>JAVA_HOME</code> environment
|
---|
233 | variable set.</p>
|
---|
234 |
|
---|
235 | <p>The main build file is <kbd>build.xml</kbd> located in the root of the
|
---|
236 | repository. The build process needs to be customized through the
|
---|
237 | <kbd>build.prp</kbd> properties file. This file does not present in the
|
---|
238 | repository (since it's user dependent) but the default one will be created
|
---|
239 | after the first launch of the build if it doesn't exist. See comments
|
---|
240 | inside of it on what to customize.</p>
|
---|
241 |
|
---|
242 | <p>The build process is started by launching Ant in the root of the
|
---|
243 | project, optionally with the target specified. There are the following
|
---|
244 | build targets exist:</p>
|
---|
245 |
|
---|
246 | <table>
|
---|
247 | <tr>
|
---|
248 | <td><kbd>compile</kbd></td>
|
---|
249 |
|
---|
250 | <td>Compile everything in development mode -- all <kbd>*.class</kbd>
|
---|
251 | files are placed to <kbd>$CVSROOT\-classes-</kbd> directory.</td>
|
---|
252 | </tr>
|
---|
253 |
|
---|
254 | <tr>
|
---|
255 | <td><kbd>test</kbd></td>
|
---|
256 |
|
---|
257 | <td>Run the default testcase as it set in the <kbd>build.prp</kbd>
|
---|
258 | file. The actual run is done via the <kbd>swt.test</kbd> target.</td>
|
---|
259 | </tr>
|
---|
260 |
|
---|
261 | <tr>
|
---|
262 | <td><kbd>clean</kbd></td>
|
---|
263 |
|
---|
264 | <td>Delete everything that is built by the main build process.</td>
|
---|
265 | </tr>
|
---|
266 |
|
---|
267 | <tr>
|
---|
268 | <td><kbd>swtNNN[_TT]</kbd> or
|
---|
269 | <kbd>swt.test -Dtest.step=NNN[_TT]</kbd></td>
|
---|
270 |
|
---|
271 | <td>Run the SWT testcase for the step number NNN, where TT is the
|
---|
272 | optional testcase number. If the corresponding value is set in the
|
---|
273 | <kbd>build.prp</kbd> compilation will be done if necessary. SWT
|
---|
274 | library and steps are compiled using
|
---|
275 | <kbd>$CVSROOT\tests\SWT\build.xml</kbd> file.</td>
|
---|
276 | </tr>
|
---|
277 |
|
---|
278 | <tr>
|
---|
279 | <td><kbd>swt.jar</kbd></td>
|
---|
280 |
|
---|
281 | <td>Compile (in the way used in the original source distribution) the
|
---|
282 | SWT library and place it to the
|
---|
283 | <kbd>$CVSROOT\src\plugins\org.eclipse.swt.pm\ws\pm\swt.jar</kbd>.
|
---|
284 | There are no dependencies regarded during compilation, every time the
|
---|
285 | build is made from scratch.</td>
|
---|
286 | </tr>
|
---|
287 |
|
---|
288 | <tr>
|
---|
289 | <td><kbd>dll</kbd></td>
|
---|
290 |
|
---|
291 | <td>Compile the <kbd>swt.dll</kbd> (see the <b>C (native) code
|
---|
292 | build</b> section below). Note that target requires the usage of Ant
|
---|
293 | 1.5.4 and the patch mentioned above.</td>
|
---|
294 | </tr>
|
---|
295 |
|
---|
296 | <tr>
|
---|
297 | <td><kbd>changelog</kbd></td>
|
---|
298 |
|
---|
299 | <td>Updates the ChangeLog file by calling a special Perl script (see
|
---|
300 | <a href="#ordinary.checkins">here</a>).</td>
|
---|
301 | </tr>
|
---|
302 | </table>
|
---|
303 |
|
---|
304 | <p>Any build target creates the <kbd>build.log</kbd> file in the root of
|
---|
305 | the project, that contains the full output of the build process, which is
|
---|
306 | overwritten every time the build is run. Also, every test case target
|
---|
307 | creates its own log at the same place, where an output of the test
|
---|
308 | execution is redirected to. Its name matches the name of the target, i.e.
|
---|
309 | <kbd>swt001.log</kbd> for the target <kbd>swt001</kbd>.</p>
|
---|
310 |
|
---|
311 | <p><b>Note.</b> Ant file masks and path-like structures seem to be case
|
---|
312 | sensitive under OS/2 (??), so all source directories should be in lower
|
---|
313 | case (except those that are in mixed case, if any). Also note that all
|
---|
314 | backslash chars in pathnames must be escaped (doubled).</p>
|
---|
315 |
|
---|
316 | <h3>C (native) code build</h3>
|
---|
317 |
|
---|
318 | <p>Native libraries are compiled by Visual Age C 4.0 for OS/2.</p>
|
---|
319 |
|
---|
320 | <p>Paths to Java libraries and headers are expected to present in the
|
---|
321 | <kbd>LIB</kbd> and <kbd>INCLUDE</kbd> environment variables (made by
|
---|
322 | default by the Java installer).</p>
|
---|
323 |
|
---|
324 | <p>There are makefiles used to control C build process, so
|
---|
325 | <kbd>nmake.exe</kbd> should be somewhere in <kbd>PATH</kbd>.</p>
|
---|
326 |
|
---|
327 | <p><kbd>VACPPMAIN</kbd> environment variable must point to the
|
---|
328 | installation directory of Visual Age C 4.0.</p>
|
---|
329 |
|
---|
330 | <p>SWT native DLL is built by the
|
---|
331 | <kbd>$CVSROOT\src\plugins\org.eclipse.swt\Eclipse SWT
|
---|
332 | PI\pm\library\build.cmd</kbd> file and placed to the
|
---|
333 | <kbd>$CVSROOT\src\plugins\org.eclipse.swt.pm\os\os2\x86</kbd> directory.
|
---|
334 | Please note that if there is a lot of changes since the last build it's
|
---|
335 | better first to clean everything (with <kbd>build.cmd clean</kbd>) and
|
---|
336 | then build it from scratch -- it will avoid potential VAC codestore
|
---|
337 | problems when it "forgets" to do some important things (such as type
|
---|
338 | checking).</p>
|
---|
339 |
|
---|
340 | <p>Also, as it shown in the above table, a special target <kbd>dll</kbd>
|
---|
341 | is now available in the main build file for convenience. It simply calls
|
---|
342 | the script mentioned above.</p>
|
---|
343 |
|
---|
344 | <h2><a name="documentation.tool">Documentation tool</a></h2>
|
---|
345 |
|
---|
346 | <p>To maintain these Notes we use the <a
|
---|
347 | href="http://www.xmlmind.com/xmleditor">XMLmind XML Editor Standard
|
---|
348 | Edition</a> (XXE) for Java, version V2.5p2. It requires JRE 1.4 and runs
|
---|
349 | well under <a
|
---|
350 | href="http://www.innotek.de/products/javaos2/javaos2general_e.html">Innotek
|
---|
351 | Java 1.4.2 for OS/2</a>.</p>
|
---|
352 |
|
---|
353 | <p>There is some stuff for it in the <kbd>\misc\xxe</kbd> directory: a
|
---|
354 | .cmd launcher, an OS/2 icon and a template for new pages of these
|
---|
355 | Notes.</p>
|
---|
356 |
|
---|
357 | <h2>Refactoring tool</h2>
|
---|
358 |
|
---|
359 | <p>Its useful to get various statistics (such as different aspects of the
|
---|
360 | usage of some symbol) on the source code when trying to understand what it
|
---|
361 | does. Since there are a lot of classes in the Eclipse sources, sometimes
|
---|
362 | it's hard to do it manually. Yes, Eclipse itself has worthy refactoring
|
---|
363 | capabilities, but we don't have it under OS/2 yet <). So, <a
|
---|
364 | href="http://www.refactorit.com">RefactorIT</a> is a good choice for that
|
---|
365 | purpose. We've been given a free time limited license from Aqris Software
|
---|
366 | AS to use it in this project.</p>
|
---|
367 |
|
---|
368 | <h1>EclipseOS2 Team</h1>
|
---|
369 |
|
---|
370 | <p>EclipseOS2 Team is a group of people who are working on this project on
|
---|
371 | their own time and budget. They are:</p>
|
---|
372 |
|
---|
373 | <ul>
|
---|
374 | <li>Dmitry A. Kuminov (<a href="mailto:dmik@hugaida.com">dmik@hugaida.com</a>),
|
---|
375 | known as dmik</li>
|
---|
376 |
|
---|
377 | <li>Eli Krakovsky (<a
|
---|
378 | href="mailto:eli@alfacom.net">eli@alfacom.net</a>), known as eli</li>
|
---|
379 | </ul>
|
---|
380 |
|
---|
381 | <p>The official team and project site is <a
|
---|
382 | href="http://eclipseos2.netlabs.org">http://eclipseos2.netlabs.org</a>.</p>
|
---|
383 |
|
---|
384 | <h1><a name="CopyrightNotice">Copyright notice</a></h1>
|
---|
385 |
|
---|
386 | <p>All changes and additions to the Eclipse source code that are contained
|
---|
387 | within this project are copyrighted by EclipseOS2 Team and made publicly
|
---|
388 | available through the CVS (see the official project site) under the terms
|
---|
389 | and conditions of the <a href="cpl-v10.html">Common Public License Version
|
---|
390 | 1.0</a> ("CPL"). A copy of the CPL is also available at <a
|
---|
391 | href="http://www.eclipse.org/legal/cpl-v10.html">http://www.eclipse.org/legal/cpl-v10.html</a>.</p>
|
---|
392 | </body>
|
---|
393 | </html>
|
---|