This document contains various notes about the structure and concepts of the Eclipse SDK (www.eclipse.org) relative to the Eclipse for OS/2 project, the discussion of porting process, the roadmap of the project, the description of the current project status and may be something else which that can be useful. The content of this document assumes that someone is familiar enough with the basics of Eclipse.
These Notes are best viewed with Mozilla (since Netscape's CSS support is terrible).
To get a brief description of changes in the project go to the whatsnew section.
Please note that this is an internal document intended for people who work on this project (like sticky notes on a monitor) so any graceful narration is not expected.
Eclipse platform consists of several parts (components), each of them implements one of the basic aspects of functionality. The most significant part (from the porting point of view) is the Standard Widget Toolkit (SWT) component, an alternative UI library that is used as a GUI base for all other components of Eclipse, including the Eclipse JDT (Java Development Tooling, an Eclipse IDE). The main goal of SWT is its "nativeness", as opposed to the standard Java 2 Swing library. This means that it is based on the mechanisms of the host platform's windowing system, directly using its API from the native Java methods.
So, the porting process can be divided into two main parts: porting of SWT and then porting of all other platform sensitive parts (such as workspace core classes, launcher, updater and so on). Each part, in turn, is divided into small steps (for the easiness of porting and maintenance) and has its own porting roadmap. The first one that must be ported is SWT: it is completely independent from everything else in Eclipse, but many other components depend on it.
Here are:
As a base for our work we decided to take the release 2.0.1 of Eclipse SDK as the most recent release to the day we have started. The total size of the Eclipse source code is about 100 MB and it's not necessary to keep them all in our project because only a small part will be affected by the porting process. So we will put in the project's repository only the pieces that are changed by us and, of course, new ones we create for OS/2 support.
The eclipseos2 repository has the following structure:
| doc/ | Project documentation, including these Notes. |
| src/ | The sources of Eclipse we are working with. It includes only the sources that make an OS/2 platform support in Eclipse, but the structure of this directory is similar to the original, which will help to join the main stream in the future. |
| tests/ | This contains our C and Java test suites. |
| misc/ | Various tools, helper scripts, docs and other useful stuff. |
Original Eclipse sources, that are common for all platforms but need to be changed to include OS/2 support, are placed on the eclipse-team branch. Tags on that branch correspond to the official Eclipse releases. Currently, there is only one release (that one we are based on) in the repository tagged as rel-2-0-1. When we add a new part of common Eclipse sources to our repository we put them with this tag.
Tags on the main trunk are composed according to the following scheme: tr-<ppp>-<NNN>, where tr means transitional, <ppp> can be swt or other and <NNN> is the step number. These tags are assigned when the certain step is completely done.
Ordinary checkins (commits) are done using the following rules:
Here is an example of the typical message typed during commit:
- This is a common message to the entire commit operation. - This is another common commit message, detailed like this: * some detail; * some another detail. - 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. - o.e.swt.graphics.GC, o.e.swt.widgets.Control: java files can be alternatively listed like this.
The ChangeLog file must be always updated automatically by the Perl script, cvs2cl.pl.cmd, that is located in the /misc subdirectory of the repository. Manual ChangeLog changes will be simply overwritten by the script. The preferred way to execute the script is to use the changelog ant target (see below) that sets up necessary command line arguments. Note: in order to be able to run the script you must have Perl installed on your system. A recent OS/2 version of Perl can be downloaded from here: http://www.cpan.org/ports/os2/. The script is tested to work well with at least v5.8.2 of Perl for OS/2.
We use special marks in common source files (i.e. files which are shared between all platforms) to flag the changes we made to add an OS/2 support. Also the special form of "todo" and "temp" markers is used. Here is an example of usage of this stuff:
//@@OS2+
lines added or changed for OS/2 begin here
...
and up to here
//@@OS2-
...
and here's a single added/changed line //@@OS2
...
//@@OS2: and this is an OS/2 related comment
...
... //@@TODO: not to forget to check the value returned
...
... //@@TEMP: the section of code below is temporary and will be changed/removed in short
There are two attributes in the Eclipse terminology (plugin/package naming conventions, build process and so on) to identify the platform which the certain build of the Eclipse is intended to be run on. They are os (operating system) and ws (windowing system of that operating system). We decided the following is the best for OS/2: os = os2 and ws = pm.
Since we do not keep all the Eclipse sources in our repository, the original Eclipse SDK release 2.0.1 sources are needed in order to get something compiled -- components that are not affected by our work are taken from there. The original sources should not be placed under our project directory structure, but somewhere else.
To build the Java code the Java Toolkit 1.3 or 1.3.1 for OS/2 is required. Version 1.3 is recommended since it takes less memory during execution and is free of the unpleasant OS/2=>Java clipboard bug.
The build process is controlled by Ant. The recommended
version is 1.5.4. Also a patch for this version is required (in order, to
use the dll target, see below). This patch can be found on the
repository ($CVSROOT/misc/ant-1.5.4-patch-os2.jar). See the
readme.txt file inside the jar on how to install it. The
misc directory of the repository also contains the
ant.cmd file, which can be used to run Ant and contains the
correct classpath definition needed to use the patch. This file can be
placed somewhere in the PATH -- just ensure that the ant_home
variable inside it points to the right Ant installation directory (correct
it if necessary) and that you have the JAVA_HOME environment
variable set.
The main build file is build.xml located in the root of the repository. The build process needs to be customized through the build.prp properties file. This file does not present in the repository (since it's user dependent) but the default one will be created after the first launch of the build if it doesn't exist. See comments inside of it on what to customize.
The build process is started by launching Ant in the root of the project, optionally with the target specified. There are the following build targets exist:
| compile | Compile everything in development mode -- all *.class files are placed to $CVSROOT\-classes- directory. |
| test | Run the default testcase as it set in the build.prp file. The actual run is done via the swt.test target. |
| clean | Delete everything that is built by the main build process. |
| swtNNN[_TT] or swt.test -Dtest.step=NNN[_TT] | Run the SWT testcase for the step number NNN, where TT is the optional testcase number. If the corresponding value is set in the build.prp compilation will be done if necessary. SWT library and steps are compiled using $CVSROOT\tests\SWT\build.xml file. |
| swt.jar | Compile (in the way used in the original source distribution) the SWT library and place it to the $CVSROOT\src\plugins\org.eclipse.swt.pm\ws\pm\swt.jar. There are no dependencies regarded during compilation, every time the build is made from scratch. |
| dll | Compile the swt.dll (see the C (native) code build section below). Note that target requires the usage of Ant 1.5.4 and the patch mentioned above. |
| changelog | Updates the ChangeLog file by calling a special Perl script (see here). |
Any build target creates the build.log file in the root of the project, that contains the full output of the build process, which is overwritten every time the build is run. Also, every test case target creates its own log at the same place, where an output of the test execution is redirected to. Its name matches the name of the target, i.e. swt001.log for the target swt001.
Note. Ant file masks and path-like structures seem to be case sensitive under OS/2 (??), so all source directories should be in lower case (except those that are in mixed case, if any). Also note that all backslash chars in pathnames must be escaped (doubled).
Native libraries are compiled by Visual Age C 4.0 for OS/2.
Paths to Java libraries and headers are expected to present in the LIB and INCLUDE environment variables (made by default by the Java installer).
There are makefiles used to control C build process, so nmake.exe should be somewhere in PATH.
VACPPMAIN environment variable must point to the installation directory of Visual Age C 4.0.
SWT native DLL is built by the $CVSROOT\src\plugins\org.eclipse.swt\Eclipse SWT PI\pm\library\build.cmd file and placed to the $CVSROOT\src\plugins\org.eclipse.swt.pm\os\os2\x86 directory. Please note that if there is a lot of changes since the last build it's better first to clean everything (with build.cmd clean) and then build it from scratch -- it will avoid potential VAC codestore problems when it "forgets" to do some important things (such as type checking).
Also, as it shown in the above table, a special target dll is now available in the main build file for convenience. It simply calls the script mentioned above.
To maintain these Notes we use the XMLmind XML Editor Standard Edition (XXE) for Java, version V2.5p2. It requires JRE 1.4 and runs well under Innotek Java 1.4.2 for OS/2.
There is some stuff for it in the \misc\xxe directory: a .cmd launcher, an OS/2 icon and a template for new pages of these Notes.
Its useful to get various statistics (such as different aspects of the usage of some symbol) on the source code when trying to understand what it does. Since there are a lot of classes in the Eclipse sources, sometimes it's hard to do it manually. Yes, Eclipse itself has worthy refactoring capabilities, but we don't have it under OS/2 yet <). So, RefactorIT is a good choice for that purpose. We've been given a free time limited license from Aqris Software AS to use it in this project.
EclipseOS2 Team is a group of people who are working on this project on their own time and budget. They are:
The official team and project site is http://eclipseos2.netlabs.org.
All changes and additions to the Eclipse source code that are contained within this project are copyrighted by EclipseOS2 Team and made publicly available through the CVS (see the official project site) under the terms and conditions of the Common Public License Version 1.0 ("CPL"). A copy of the CPL is also available at http://www.eclipse.org/legal/cpl-v10.html.