source: trunk/doc/index.html@ 21

Last change on this file since 21 was 9, checked in by lpino, 18 years ago
  • Initial commit
File size: 17.6 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<?xml-stylesheet type="text/css"
3href="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-&lt;ppp&gt;-&lt;NNN&gt;</kbd>, where <kbd>tr</kbd> means
116 transitional, <kbd>&lt;ppp&gt;</kbd> can be <kbd>swt </kbd>or <kbd>other
117 </kbd>and <kbd>&lt;NNN&gt;</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=&gt;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&nbsp;-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 &lt;). 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>
Note: See TracBrowser for help on using the repository browser.