source: tags/wse/doc/README.OS2

Last change on this file was 290, checked in by dmik, 9 years ago

release: Readme/changelog updates for WSE build.

File size: 12.3 KB
Line 
1OpenJDK 6 for OS/2 and eCS
2
3Version 1.6.0 Build 22 WSE (2011-05-12)
4
5This is a special Warpstock Europe 2011 build that contains some important
6improvements over RC2.
7
8
9
10INTRODUCTION
11
12This document contains a brief information on the OS/2 version of the
13OpenJDK 6 product. Please read it carefully before starting your work.
14You may also visit the project page at
15
16  http://svn.netlabs.org/java/wiki
17
18to get more information and the latest news and also to report bugs.
19
20To get a brief list of OS/2-specific changes from release to release
21please see the CHANGES.OS2 file included in this distribution.
22
23
24
25REQUIREMENTS
26
27In order to use this version of OpenJDK, you will need the following:
28
29  - A OS/2 Warp 4 Fixpack 16+, OS/2 Warp 4.5 or eComStation operating system.
30
31  - Odin32 library version 0.6.21632 (2011-05-12) or above:
32
33    ftp://ftp.netlabs.org/pub/odin/odin32bin-20110512-release.wpi
34
35  - Extended system tray widget for XCenter version 0.1.1 or above (optional,
36    but required for system tray support in Java applications):
37
38    ftp://ftp.netlabs.org/pub/qt4/xsystray/xsystray-0_1_1.wpi
39
40
41
42INSTALLATION
43
44  The OpenJDK product is distributed in two packages: the JRE and the SDK
45  (which includes a copy of JRE). Simply take a necessary package and unzip it
46  to a directory of your choice. You will need to add the \bin subdirectory
47  inside this directory to PATH and BEGINLIBPATH to allow for starting Java
48  executables from an arbitrary location:
49
50    set PATH=<directory>\bin;%PATH%
51    set BEGINLIBPATH=<directory>\bin;%BEGINLIBPATH%
52
53  Also make sure there are no traces of other Java installations in the
54  environment because this is known to make problems (in particular, this means
55  that the CLASSPATH/JAVA_HOME/SWING_HOME environment variables should not be
56  set).
57
58  Alternatively, you may add this subdirectory to PATH and LIBPATH statements
59  of your CONFIG.SYS (and reboot) to make the given Java installation the
60  default one.
61
62  Please read the further sections (especially the "CURRENT LIMITATIONS" section
63  below) to make sure that you are aware of possible problems you may run into
64  while running Java applications using this product.
65
66
67
68FONT SELECTION
69
70  OpenJDK comes with no fonts and uses the system fonts by default. On OS/2,
71  these fonts are Helvetica, Times New Roman and Courier -- they are are
72  present in any version of OS/2. However, these are very old Type1 fonts with
73  many glyphs having poor quality which can be seen even with font anti-aliasing
74  turned on.
75
76  For this reason, OpenJDK for OS/2 provides an alternative font configuration
77  that uses a freely available Liberation font family: Liberation Sans,
78  Liberation Serif and Liberation Mono (with font metrics close to a widely
79  used set of Monotype TTF fonts: Arial, Times New Roman and Courier New,
80  respectively). In order to use the Liberation font family instead of the
81  default Type1 fonts, do the following:
82
83  1. Download the latest binary (TTF) archive of Liberation fonts from:
84
85     https://fedorahosted.org/liberation-fonts/
86
87  2. Copy all *.TTF files from the archive to a directory and install them
88     normally (for example, using the OS/2 Font Palette object).
89
90  3. Go to the directory "<SDK>\bin\jre\lib" (where <SDK> is where you installed
91     SDK package) or "<JRE>\lib" (where <JRE is where you installed the JRE
92     package) and copy the file "fontconfig.liberation.bfc" to "fontconfig.bfc".
93     It is safe to overwrite the target file.
94
95  In order to return back to the default fonts, go to "<OpenJDK>\bin\jre\lib"
96  (or to "<JRE>\lib") again and copy the file "fontconfig.default.bfc" to
97  "fontconfig.bfc".
98
99  Note that you need to restart all Java applications to let them pick up the
100  new fonts.
101
102  Font Anti-Aliasing
103
104  In the current release, due to the low quality of the standard OS/2 Type1
105  fonts, both AWT and Swing Java GUI toolkits use subpixel font anti-aliasing by
106  default for all standard components.
107
108  If you want to change this behavior, you may use the following Java command
109  line option:
110
111       -Dawt.useSystemAAFontSettings=<mode>
112
113  where <mode> is one of the following anti-aliasing modes:
114
115  off              Turns anti-aliasing off
116  on               Turns on monochrome anti-aliasing
117  lcd | lcd_hrgb * Turns on subpixel anti-aliasing optimized for HRGB LCD panels
118  lcd_hbgr         Turns on subpixel anti-aliasing optimized for HBGR LCD panels
119  lcd_vrgb         Turns on subpixel anti-aliasing optimized for VRGB LCD panels
120  lcd_vbgr         Turns on subpixel anti-aliasing optimized for VBGR LCD panels
121
122  The setting marked with * is the default anti-aliasing value as it is suitable
123  for the majority of the modern display hardware.
124
125
126
127MEMORY REQUIREMENTS
128
129  Sometimes you may find out that starting a Java application fails with the
130  following error message:
131
132     Error occured during initialization of VM
133     Could not reserve enough space for object heap
134     Could not create the Java virtual machine.
135
136  This means that the amount of memory Java wants to reserve for its heap is
137  bigger than the maximum free block of memory available to the Java process.
138  Note that the size of this free block does not directly depend on the amount
139  of physical RAM installed in your computer (because the physical RAM may be
140  extended using the swap file, for instance). It rather depends on the virtual
141  address limit set by OS/2 for the process. In older OS/2 versions that don't
142  support high memory (e.g. the ones based on pre-WSeB kernels) this limit
143  is known to be 512M. In later versions it is controlled by the
144  VIRTUALADDRESSLIMIT parameter in CONFIG.SYS (which is specified in megabytes
145  and defaults to 1024).
146
147  Furthermore, not all memory within the virtual address limit is available to
148  the process. Some small fraction of it is used by the kernel and the rest is
149  divided in two more or less equal parts: the private arena and the shared
150  arena. As said, the size of these arenas does not depend on the amount of
151  physical RAM and can be approximated using the following table. Note that the
152  values in the table are not the initial arena sizes but rather the sizes of
153  the maximum free block of memory available in the corresponding arena to a
154  dummy process that does nothing but queries these system values (all numbers
155  are in MB, the first column is for systems with no high memory support):
156
157  VIRTUALADDRESSLIMIT                *512 | 1024 | 1536 | 2048 | 3072
158  -------------------------------------------------------------------
159  Max free block in private arena     267 |  432 |  880 | 1328 | 2224
160  Max free block in shared arena      228 |  404 |  852 | 1230 | 2196
161
162  Note that these values are gathered on a default eCS 2.0 GA system and may
163  vary depending on what system DLLs get loaded into each process; they are
164  given only as an example. You may get the real values on your system with
165  a variety of tools gathering system information, such as THESEUS.
166
167  On the other hand, when calculating the default amount of memory to reserve
168  for the heap (which is called the maximum heap size in the documentation),
169  Java uses the physical RAM size as a base, not the the size of the free block
170  in the private arena (where Java actually allocates the heap). Below is a
171  simplified version of the algorithm for these calculations:
172
173  1. Use MIN (MaxRAM, <physical_RAM>) as the base RAM value. MaxRAM is a Java
174     constant that defaults to 1G for the client (default) Java virtual machine
175     and to 4G for the server JVM.
176
177  2. Divide this base RAM value by MaxRAMFraction (4 by default) and assign the
178     result as the default value for the maximum heap size (MaxHeapSize).
179
180  3. Use the MaxHeapSize value increased by 20-30% (for the needs other than the
181     Java heap) as the size of the memory block to allocate in the private
182     arena.
183
184  So, if your machine has, say, 2G of RAM and you attempt to start a Java
185  application Java server mode (using the -server command line option), Java
186  will want 512M (2G/4) plus additional 20-30%. This would obviously not fit
187  into 432M of free private memory available for the process when
188  VIRTUALADDRESSLIMIT is set to 1024 and this was the case with earlier releases
189  of OpenJDK 6 for OS/2 as well as with the releases of InnoTek Java 1.4.x for
190  OS/2.
191
192  Starting with version 6 Beta 2, OpenJDK for OS/2 solves this problem by
193  limiting the amount of memory Java wants for the heap to the actual size of
194  the available memory block in the private arena. So, in the above case Java
195  will actually get about 310M in server mode (instead of performing a failed
196  attempt to allocate 512M). You may change this limit by changing the
197  VIRTUALADDRESSLIMIT value in CONFIG.SYS (according to the table above), but
198  please note that values higher than 1024 may cause problems with some drivers
199  (for example, it is known that JFS and HPFS386 drivers cannot allocate a disk
200  cache of the big size if the VIRTUALADDRESSLIMIT value is too high).
201
202  In either case, the above describes how Java calculates the defaulut maximum
203  heap size. You may always override this default using the -Xmx<size> Java
204  command line option if you are not satisfied with the default value for some
205  reason or if your applcation gives you the "Could not reserve enough space for
206  object heap" error message at startup. However, keep in mind that if you
207  specify a -Xmx value which is, increased by 20-30% as described in step 3
208  above, bigger than the maximum free block in the private arena, you will get
209  the same memory allocation error which indicates that you should use a smaller
210  value.
211
212
213
214DLL NAMES
215
216  In the environment necessary to run OpenJDK on OS/2, the directory containing
217  JDK DLLs is listed in either LIBPATH or BEGINLIBPATH variable which makes
218  these DLLs available to Java processes as well as to any other process running
219  in the same environment. The original versions of OpenJDK use very generic DLL
220  names for some components (such as jpeg.dll, zip.dll) which may create name
221  conflicts with system DLLs and cause the Java DLLs to be loaded by programs
222  instead of the system ones leading to program malfunction.
223
224  To reduce the possibility of such conflicts, all Java DLLs that didn't have
225  a 'j' prefix in their names were renamed by prepending 'j' to the original
226  DLL name.
227
228  Besides adding the 'j' prefix, some DLLs were also renamed further to fit the
229  8 character DLL name length limit forced by the OS/2 kernel loader.
230
231  This rename operation is transparent to all Java applications except a few
232  cases which involve custom agent libraries used to enhance the functionality
233  of JDK or JVM. These libraries in particular include:
234
235  Original Name            New Name
236  --------------------------------------------
237  hprof.dll                jhprof.dll
238  dt_shmem.dll             jdtshmem.dll
239  dt_socket.dll            jdtsock.dll
240
241  In order to use the renamed libraries, you need to substitute the old name
242  with the new name wherever the old name is used in Java documentation,
243  configuration files or command line options. For example, to use the profiler
244  library, you will have to write "-agentlib:jhprof.dll" on the command line
245  instead of "-agentlib:hprof.dll" and so on.
246
247
248
249CURRENT LIMITATIONS
250
251  1. OpenJDK will not work correctly under the OS/2 SMP kernel (Java process
252     hangs are very likely). This is a known problem of Odin32 which will be
253     addressed in further releases. The workaround is to use the OS/2 UNI or
254     Warp4 kernel instead.
255
256  2. The com.sun.tools.attach package (API to attach to a Java virtual machine)
257     is missing.
258
259  See the project roadmap for more information on the current progress and
260  future plans:
261
262    http://svn.netlabs.org/java/roadmap
263
264  Feel free to request new features and report bugs using the project bug
265  tracker abaialble at:
266
267    http://svn.netlabs.org/java/report
268
269
270
271CREDITS
272
273Dmitriy Kuminov (development)
274Silvan Scherrer (management)
275
276netlabs.org (hosting & support)
277
278Oracle Corporation (original OpenJDK product)
279
280We also want to THANK all individuals and organizations who made the donations
281to this project and helped to make it happen.
282
283
284Oracle and Java are registered trademarks of Oracle and/or its affiliates.
285OS/2 and OS/2 Warp are trademarks of the IBM Corporation and/or its subsidiary(-ies).
286eComStation is a trademark of Serenity Systems International and/or its subsidiary(-ies).
287Other names may be trademarks of their respective owners.
Note: See TracBrowser for help on using the repository browser.