                        
                          KYLIX 3.0
                        RELEASE NOTES

=======================================================

This file contains important supplementary and late-
breaking information that may not appear in the main
product documentation. We recommend that you read this
file in its entirety.

For information on new features in this release, choose
"What's New" in the online Help contents.

The following text files are included on your Kylix CD and
copied to your Kylix install directory. They contain late-breaking
release information not included in the printed documentation or
Help files.

    README
        Contains general Kylix release notes.

    PREINSTALL
        Describes steps necessary to qualify a system to run
        Kylix and Kylix applications.

    INSTALL
        Contains notes on installing Kylix.

    DEPLOY
        Contains notes on deploying Kylix applications.



CONTENTS
-------------------------------------------------------
 
 WHAT'S IN KYLIX
 NOTES AND ISSUES
 RUNNING KYLIX
 COMPILER, LINKER, AND ASSEMBLER
 RUNTIME LIBRARY
 DATABASE DEVELOPMENT
 WEB DEVELOPMENT
 INTERNATIONAL/CHARACTER SETS/LOCALE ISSUES
 THE FREECLX PROJECT
 

       
===============
WHAT'S IN KYLIX
===============

Kylix includes 2 IDEs, one for the Delphi language and one for
C++. These environments include visual Form Designers and debugging
tools, the dcc and bc++ compilers, runtime libraries, CLX, database
drivers, database components, documentation, and sample
applications. Kylix 3 can be used to create software using
either the Delphi language, or C++.

NOTE: The default installation location for Kylix is beneath the 
      home directory of the installing user, or, if installing as
      root, /usr/local/kylix3.

If you install as root, the sample application files (located in
the /examples directory under your installation directory) will not be 
writable by other users. Before the sample applications can be 
compiled or modified by other users, the non-root user must make
writable copies of the files, or shared access to the sample
directories must be established.


================
NOTES AND ISSUES 
================
 
Linux distribution certification
--------------------------------

Kylix 3 is certified on the following Linux distributions:

* Red Hat 7.2
* SuSE 7.3
* Mandrake 8.2
 
 
Web App Debugger
----------------
If Web App Debugger has problems launching the default browser, change 
the value in the Browser field to point to another browser (e.g. 
"konqueror" instead of "mozilla").

Web App Debugger executables run under the IDE debugger will report a
EIdConnClosedGracefully exception. This exception is normal and will only
happen from within the IDE.  If you do not want to see this exception, add
this exception to the Tools/Debugger Options  as an exception to ignore.
For more information about this exception, see comments in

    source/indy/IdTCPConnection.pas.

The section titled "If this is a server" applies to Web App Debugger 
executables.


Apache issues
-------------

NOTE: Due to a known bug with Apache 1.3.22, do not develop CGI 
      programs or shared objects for this version.
      
      See http://bugs.apache.org/index.cgi/full/8538
      
To create Apache modules you will need to:

  1) Add /usr/local/apache/include to the projects include path
  2) Add /usr/local/apache/libexec to the library path
  3) Move /usr/include from the bottom of the include paths to the top
  
To do this, open the Project|Options dialog and click on the
Directories/Conditionals tab. Click on "..." next to Include path.
Select /usr/include at the bottom of the list and use the Upp
arrow to move /usr/include to the top of the list.

Next, enter /usr/local/apache/include in the edit box and click Add.
Enter /usr/local/apache/libexec and click Add.

For Apache modules to work properly you will need to add the following
line to the Apache httpd.conf file:

   SetEnv LD_LIBRARY_PATH <path to kylix bin>

NOTE:  The included Apache demos do not work with Apache 2.0


Debugger
--------

When debugging a multi-threaded application, an exception 

  EThread: 'Thread creation error: Resource temporarily
            unavailable'

may be raised after many threads have been created and destroyed.

This may be due to the Linux kernel not sending a termination
notification signal to code that is being debugged; the glibc
linuxthreads package then cannot destroy any thread processes.


WebSnap and non-root users
--------------------------
On systems where Kylix 3 has been installed by the root user in a
location that is not writable by standard users, standard users
cannot build a WebSnap application until after the root user. Users 
who try will receive the following message:

   [Fatal Error] JSTypes.pas(1136): 
   Could not create output file '/usr/local/kylix3/lib/JSTypes.dcu' 

If the root user builds a WebSnap application first, the problem 
does not occur.


Importing WEAKPACKAGEUNIT and initialized variables and constants
-----------------------------------------------------------------

When using an initialized variable or constant from a unit that has 
been compiled with the WEAKPACKAGEUNIT compiler directive, linking a
project with the package that contains this unit will result in an
internal linker error. This primarily affects some initialized
variables in the Libc unit.

As a work-around, either copy the declaration of the variable or
constant from the unit directly into your project, or do not use 
runtime packages.

Divide by Zero Exception
------------------------

If the result of an integer division is too large to fit into the 
result destination, an EDivByZero exception will be raised instead 
of an EIntOverflow exception. This is due to the Linux kernel 
flagging a generic "Divide Error" and not an overflow condition.

Passing an "array of consts" by value
-------------------------------------

Raising an exception from a routine that takes an "array of const"
parameter by value

  procedure AProcedure(Data: array of const);

causes failure in the exception unwinding code if an exception is thrown
from such a routine. As a work-around, apply the const modifier to the
parameter

  procedure AProcedure(const Data: array of const);


Qt library issues
-----------------

NOTE: libqt.so replaced by libborqt.so

By default, Kylix applications will dynamically link with libborqt.so 
instead of libqtintf.so and libqt.so. libborqt.so is a single library 
containing the Kylix interface to Qt along with a patched, Borland 
supported version of Qt 2.3.0. There have been problems in previous 
versions where the libqt.so.2 symlink on certain distributions points to 
a version of Qt not supported by Borland, and concerns about 
redistributing two shared libraries: one with a possible naming conflict.
It is still possible to link with libqtintf and either the Borland 
supplied libqt or an existing libqt version 2.3.x: In Delphi, this is 
controlled at runtime by defining the environment variable 
CLX_USE_LIBQT, and in C++ by compiling with a compiler define of 
the same name.

Printing in a C++ CLX application with a non-Borland libqt.so may 
cause a SIGPIPE and terminate the application in the shipping TrollTech Qt 
library. This behavior will not occur in the Borland supplied libqt.so 
and libborqt.so.


TTcpServer and TIdSMTPServer issues
-----------------------------------

On some Linux distributions, the TTcpServer and TIdSMTPServer components
will cause an Access Violation in Kylix 3 for C++ when dropped on the
Form Designer.

The suggested workaround is to create these components programatically 
(see the Internet/Netchat demo).  Alternately, exporting LD_BIND_NOW=1 
before starting BCB will allow these components to be dropped but may 
cause issues with running your application under the integrated 
debugger. To do this, start Kylix from the command line with the
following command:

   LD_BIND_NOW=1 <Kylix directory>/bin/startbcb

XML Issues
----------

Non-existent xml files, zero size xml files and certain Japanese
or Chinese encoded files can crash the IDE via Xmldocument or Xml 
Data Binding Wizard on certain Linux platforms.


SOAP Servers
------------

1.  Users need chose Project|Add xercesxmldom.o to SOAP server 
    projects to ensure that initialization code gets called.

2.  Soap midas clients: there is a known problem in that 
    exceptions are getting returned without the error message. 
    
    You can get a 'Safecall exception' with no information about
    what problem is.

Label caption tip
-----------------

The first letter of a label caption is dropped when the label's
WordWrap property is set to True, ShowAccelChar is True, and AutoSize 
is False. Note: The problem only occurs if the caption contains
the accelerator character (&), contains no spaces, and is long 
enough to trigger word wrapping.

IDE File Open dialog
--------------------

If you attempt to browse a directory with the File Open dialog
box, and you do not have read access to that directory, the IDE
does not report an error. Instead, it silently changes your
navigation to the root directory.


Development Library Files
-------------------------

If an error occurs regarding missing library files when compiling
a C++ application (such as: Cannot find "libX11.so"), make sure 
you have installed your distribution's development packages of
the related library files. For instance, on RedHat 7.3, the package 
containing libX11.so is XFree86-devel.


C++Builder 
----------

CLX projects created in C++Builder 6.0 cannot be directly
opened in the Kylix 3 C++ IDE, but can be adapted for use in Kylix 
by one of the following techniques. The easier technique is to add 
the forms to a default project and use an event handler to show 
the forms. 

Another technique is to create a skeleton project with the same 
number of forms (but no additional components), where you give 
each form the same name as that used in your C++Builder project, 
and save the project using the same unit names and project name 
as those used in that project. If you then overwrite just the 
original project's <projectname>.bpr and <projectname>.cpp files 
with the ones you just created, you should be able to use 
your project just as you would in C++Builder 6.0. 


Changes in StrUtils
-------------------

The StrUtils unit contains three sets of changes, all relating to 
multi-byte character set (MBCS) support.

   * Previously, LeftStr, RightStr, and MidStr each took and 
     returned AnsiString values, and did not support MBCS 
     strings. Each of these functions has been replaced by 
     a pair of overloaded functions, one that takes and returns 
     AnsiString, and one that takes and returns WideString. The 
     new functions correctly handle MBCS strings. This change 
     breaks code that uses these functions to store and retrieve 
     byte values in AnsiStrings. Such code should use the new 
     byte-level functions described below.

   * New functions LeftBStr, RightBStr, and MidBStr provide the 
     byte-level manipulation previously provided by LeftStr, RightStr, 
     and MidStr.

   * New functions AnsiLeftStr, AnsiRightStr, and AnsiMidStr are the 
     same as the new AnsiStr LeftStr, RightStr, and MidStr functions, 
     except that they are not overloaded with equivalent WideString 
     functions.
     
Cannot statically link CLX or RTL code into C(++) shared objects
----------------------------------------------------------------

This version of Kylix for C++ does not support the static linking of CLX
or the RTL into shared objects (and Apache DSOs) from the IDE.

If you are creating a shared object or Apache DSO in C++ that requires
the use of CLX or the RTL, make sure "Build with runtime packages" is
checked in the Project|Options -> Packages dialog.

gcc and bc++ command line syntax
--------------------------------

The options -I, -L and -o when used with gcc accepts an optional 
space before the following filename.  In bc++, these same options must
not have a space before the filename.

With gcc, as with most Linux commands, switches to the command line can 
appear in any order.  With bc++, all switches must appear before 
the first source file name.


Borland Make and GNU Make
-------------------------

Due to differences in the way Borland Make and GNU Make resolve 
implicit targets, the use of the "Intermediate output directory" 
option is not supported in an exported makefile. This project 
option will work correctly for projects built within the Kylix IDE.


XML DOM Vendors
---------------

Kylix 3 includes support for 3 separate XML DOM implementations:

Name                    Vendor                Unit Name

Xerces XML           Apache                   xercesxmldom.pas
XML4C                Apache/IBM               xercesxmldom.pas
Open XML             Dieter Koehler           oxmldom.pas

The default DOM as installed with the product is the IBM XML4C version
based on Xerces.

Switching Between Xerces and IBM XML DOM's
------------------------------------------

The IBM XML4C DOM is actually based on Xerces DOM with support for
additional encodings.  Below is an excerpt from

   http://xml.apache.org/xerces-c/faq-distrib.html#faq-2 

which explains the differences:

"Xerces-C has intrinsic support for ASCII, UTF-8, UTF-16 (Big/Small 
Endian), UCS4 (Big/Small Endian), EBCDIC code pages IBM037 and IBM1140 
encodings, ISO-8859-1 (aka Latin1) and Windows-1252. This means that 
it can parse input XML files in these above mentioned encodings.
However, if you wish to parse XML files in any other encodings, say 
in Shift-JIS, Big5 etc., then you cannot use Xerces-C. XML4C addresses 
this need. It combines Xerces-C and International Components for 
Unicode (ICU) and provides support for over 100 different encodings."

The Apache Xerces-C and IBM XML4C distributions each use the same 
filename for the shared object which implements the DOM (called 
libxerces-c1_6_0.so) even though they are actually different files.  
To provide a choice for developers, the file from each vendor has been 
renamed and a symlink is used to select which implementation to use.  
Here are the relevant files:

Name                                Description

libxerces-c1_6_0.so.ibm             DOM library from IBM XML4C
libxerces-c1_6_0.so.apache          DOM library from Apache
libxerces-c1_6_0.so                 Symlink which points to
                                     libxerces-c1_6_0.so.ibm 
                                     by default
 
If you do not need the additional encoding support offered by the
IBM XML4C DOM you can replace the default symlink with one that
points to the Apache library using the following command in the 
directory containing these libraries (should be your bin directory):

   ln -sf libxerces-c1_6_0.so.apache libxerces-c1_6_0.so

to switch back to the IBM XML4C DOM use this command:

   ln -sf libxerces-c1_6_0.so.ibm libxerces-c1_6_0.so

You will need to shutdown and restart the IDE after making these 
changes.

Setting the DefaultDOMVendor
----------------------------

In addition to the symlink described above, the default DOM vendor 
can be changed at runtime for using the supplied Open XML DOM. This is
accomplished by setting a global variable called DefaultDOMVendor in 
code before performing XML processing.  To make Open XML the default 
DOM you would add "xmldom" and "oxmldom" to your projects uses clause 
and then add the following line of code before the Application.Run:

   DefaultDOMVendor := 'Open XML';

If you are using the TXMLDocument component, you can set the DOMVendor
property on the component itself.

To change the default DOM used at design time you can edit the 
delphi69rc (or bcb69rc for BCB) and use "Open XML" in the [Global] 
section for the DefaultDOMVendor key.   Xerces is the only DOM which 
supports XSLT, so if you change the default the TXSLPageProducer 
components preview pane will not function properly.

Redistributing applications that use XML
----------------------------------------

Depending on which DOM vendor your application uses, you may need to
redistribute additional files with your application.  The Open XML DOM 
is written entirely in Delphi and has no external dependencies.   
Here are the others

Xerces XML

Filename                      Description

libxerces-c1_6_0.so           Apache Xerces-C Library*
libxercesxmldom.so.1.0        Delphi Xerces xmldom wrapper library
libxercesxmldom.so.1          Symlink to libxercesxmldom.so.1.0


The following are needed only if you require XSLT support:

libxalan-c1_3.so             Apache Xalan-C runtime shared object
libxercesxsldom.so.1.0       Delphi XSLT wrapper library
libxercesxsldom.so.1         Symlink to libxercesxxldom.so.1.0

* For redistribution, copy the libxerces-c1_6_0.so.apache file as
  libxerces-c1_6_0.so

IBM XML (With no XSLT support required)

Filename                    Description

libxerces-c1_6_0.so         IBM XML4C Library**
libxercesxmldom.so.1.0      Delphi Xerces xmldom wrapper library
libxercesxmldom.so.1        Symlink to libxercesxmldom.so.1.0
libicudt20l.so              IBM ICU runtime shared object
libicudata.so               Symlink to libicudt20l.so
libicuuc.so.20.2            IBM ICU runtime shared object
libicuuc.so.20              Symlink to libicuuc.so.20.2
libicuuc.so                 Symlink to libicuuc.so.20.2


The following are needed only if you require XSLT support:

libxalan-c1_3.so            Apache Xalan-C runtime shared object
libxercesxsldom.so.1.0      Delphi XSLT wrapper library
libxercesxsldom.so.1        Symlink to libxercesxxldom.so.1.0

** For redistribution, copy the libxerces-c1_6_0.so.ibm file as
   libxerces-c1_6_0.so

     
=============
RUNNING KYLIX
=============

If you selected the "Desktop menu items" option during
installation, you should have a Borland Kylix 3 option
in your start menu. Selecting this will give you 2 options
for starting Kylix:
   
* Kylix 3 (C++ IDE)
* Kylix 3 (Delphi IDE)

These menu items point to the startbcb and startdelphi scripts
in the bin directory of your Kylix installation. Always start 
the IDE by running the startdelphi or the startbcb script 
rather than running the executables directly. (Both scripts 
and executables are located in the bin subdirectory under 
the Kylix installation directory.) The startdelphi and
startbcb scripts set up certain environment variables used
by Kylix before starting the IDE.

NOTE: If you encounter a Runtime error 230 when running 
      the startup scripts (before a splash screen appears), 
      please check your LD_LIBRARY_PATH and ensure that 
      <install dir>/bin _precedes_ the qt/lib directory reference.
      If you edit your /etc/profile manually, you may need 
      to exit from X windows and restart it before running
      Kylix.

Code editor fonts
-----------------

If text does not display properly in the Code editor, try 
experimenting with the font settings (Tools|Editor Options|
Display) until you find something satisfactory.

Running Kylix with default KDE color schemes
--------------------------------------------

If Kylix is run on an X Windows server with a color depth of 
8 bits (256 colors), visual artifacts may appear, depending 
on the color scheme in use. This may be a particular problem when
using Kylix with the KDE 2.2 default color scheme. To resolve the
problem, change the color scheme, or run your X Windows server
at a color depth of 16 bits (65535 colors) or 32 bits
(16 million colors). 

Running console applications
----------------------------

Linux does not automatically provide a new window to interact with
console applications. To debug a console application, you must 
provide a terminal window for the application  to run in. There are 
two ways you can do this. 

1) Run the IDE from a terminal window using the startdelphi or 
   startbcb scripts (The startkylix script is now deprecated). The 
   application will run in this same terminal window. 

2) Configure the IDE to start the application from a new terminal 
   window. To do this, choose, Run|Parameters and select "Use 
   launcher application." 
   

Compiling from the command line
-------------------------------

Before compiling from the shell command line, source the
kylixpath bash shell script to set up your PATH and other
environment variables. To source the script, go to the bin
subdirectory under the Kylix installation directory and enter

  source kylixpath

You must source kylixpath every time you open a new shell; you 
can automate the procedure by placing the inclusion of kylixpath 
into the current shell instance, like this:

  source <directory>/bin/kylixpath >/dev/null

where <directory> is the full path to the directory where Kylix 
is installed.

(If you copy the compiler and libraries to a different location, 
you can set up the environment by entering

  source kylixpath <new directory>

where <new directory> is the full path to the directory where 
the compiler and libraries reside.)

If you use a shell other than bash, look at the kylixpath 
script to see how the PATH, LD_LIBRARY_PATH, HHHOME, and 
XPPATH variables are set.

The command-line Pascal compiler, dcc, has a default
configuration file that specifies unit and library search paths.
(If Kylix was installed by root, the default dcc configuration
file is /usr/local/etc/dcc.conf. Otherwise, the default dcc
configuration file is .dcc in the installing user's home
directory.) You can override the default settings for all projects
in a given directory by placing a dcc.conf file in your project 
directory. To override settings for a project, use the 
<project name>.conf file (automatically generated by the IDE). 
If you list search paths on the command line, specify multiple 
directories with separate -U or -O switches, as shown here:

Delphi language example

  dcc -U<path1> -U<path2> -O<path3> -O<path4> MyProject.dpr

NOTE: bc++ is the command line compiler for the C++ language. The 
      default include and lib directories for bc++ are the same as
      that of the IDE. Additional search paths can be appended by 
      using the -L or -I flags.

NOTE: The command-line Delphi compiler has an undocumented switch,
      "-ls<entry>". This switch adds <entry> to the executable's
      DT_NEEDED list, with <entry> being the name of a shared object 
      dependency.

Running applications
--------------------

To run a compiled Kylix application separately from the IDE, 
you need to have your LD_LIBRARY_PATH variable set 
to <directory>/bin (where <directory> is the full path to 
the Kylix installation directory). You can do this by 
sourcing the kylixpath script described above. This will
make the runtime packages and CLX libraries available to your
application.

For details on deploying your applications see the DEPLOY file.


Copy and paste under Linux
--------------------------

Under Linux, simply selecting text in an application window
immediately makes that text available for pasting. Unfortunately,
this feature uses the same global data area as the CLX clipboard.
So if your application puts information on the clipboard using
the AsText or AssignTo properties of Clipboard, this information is
overwritten if the user selects text in any window.

Pasting text into the Object Inspector
--------------------------------------

Object Inspector property fields have a limit of 2K characters.
Keep this limitation in mind when pasting long strings (such
as SQL statements) into these fields.

GNOME's inactivity warning dialog
---------------------------------

If the GNOME inactivity warning ("SaveYourself") dialog appears 
while your registration dialog is open (or while performing any
other work in Kylix, such as running a debug session), simply 
Cancel the GNOME dialog. 

Do NOT click "Remove Program."

TThread and Suspend/Resume
--------------------------

The TThread class under Linux does not support nested calls 
to the Resume and Suspend methods. Calling .Resume (.Suspend) 
will always resume (suspend) the thread, regardless of how 
often .Resume or .Suspend has already been called on that 
thread instance.


DPI recommendation
------------------

The recommended DPI resolution for correct display of Kylix
IDE elements is 75 X 75 or higher. Please configure your X Windows
server to use the recommended resolution. Consult your Linux
distribution's documentation for details.

Conflicts with window manager key bindings
------------------------------------------

Some window managers have key bindings that conflict with the standard
key bindings for Kylix. For instance, 

Ctrl+Alt+v

normally pulls up the event log for the debugger in Kylix. In KDE
however, this same key combination pulls up the klipper popup menu
by default. This can be changed in KDE by opening the Control
Center, selecting Look & Feel|Key Bindings|Show klipper popupmenu.
To change the default setting, chose the Custom Key radio button,
click on the button that displays the key combination, and type
the key combination that you want to use instead of the default.

NOTE: Other window managers may have similar conflicts. Check the
      documentation and settings for your window manager to change
      the default key bindings on your system.
 
 

 
Exceptions in an exception handling statement
---------------------------------------------

In the Delphi language, your application may terminate unexpectedly if
an exception is thrown and handled in the "except" or "finally" part of
an exception handling statement. Examples:

   try
     raise Exception.Create('1');
   except
     try
       raise Exception.Create('2');
     finally  // <--- handle exception in expect part
     end;
   end;

or

   try
     raise Exception.Create('1');
   finally
     try
       raise Exception.Create('2');
     except  // <--- handle exception in finally part
       raise;      
     end;
   end;

To avoid the unexpected behaviour, do not throw *and* handle
exceptions inside the "finally" or "except" part of an exception
handling statement.

  
For C++, try..finally is not implemented for this release.


Kylix and GNOME window managers
-------------------------------

When running GNOME and the Sawfish window manager (and possibly 
also other window managers under GNOME), Kylix IDE elements 
can appear in unexpected places even after you have saved your 
desktop environment.

If you encounter this behavior:
1. Open the GNOME Control Center 
   (Menu/Programs/Settings/GNOME Control Center). 
2. Choose Sawfish window manager|Placement.
3. Select 'none' as the Method of placing windows.
4. Select 'none' as the Method of placing dialog windows.

Open Tools API limitations
--------------------------

The Open Tools API provides a method for extending IDE functionality. 
The non-GUI portions of the Open Tools API are available on Kylix. 
Do not attempt to perform GUI development with the Open Tools API 
due to thread synchronization issues. You could potentially cause 
crashes in the IDE.

Multi-byte Characters in the Debugger
-------------------------------------

The default terminal for the Kylix debugger is xterm, which cannot
display multi-byte characters found in MBCS locales. For these to 
display properly use a terminal that supports these locales (such 
as kterm). Select Run|Parameters, check Use Launcher Application, 
and enter the path to your kterm executable.


===============================
COMPILER, LINKER, AND ASSEMBLER
===============================

The Delphi built-in assembler supports additional opcodes, 
including the Pentium Pro instruction set, Intel MMX extensions,
Intel Streaming SIMD Extensions (SSE), and AMD 3DNow! extensions.

The compiler supplies GDB (STABS) debug info. The only limitation
is that within a local function or procedure, local symbols
declared in an outer scope and global variables are not available.
(However, symbols on the call stack are still available.) In the
IDE, STABS generation is off by default. The STABS option is on
the Linker tab of the Project Options dialog; choose 
Project|Options.

In unit declarations and uses clauses, unit names must match
file names in case. In other contexts (such as qualified
identifiers), unit names are case-insensitive. To avoid problems
with unit references, refer to the unit source file explicitly:

    uses MyUnit in "myunit.pas";

If such an explicit reference appears in the project file, other
source files can refer to the unit with a simple uses clause
that does not need to match case:

   uses Myunit;

The following features are NOT supported:

 - Generating and linking with .a files.

 - Absolute addresses in variable declarations. 
   (But you can still use the absolute directive to refer to the 
   name of another variable (e.g., var Var2: Byte absolute Var1;).

 - TASM. You cannot import external assembler routines unless 
   they use syntax supported by an assembler such as NASM (Netwide 
   Assembler, one of the free, portable x86 assemblers supported by
   Kylix; information: http://nasm.2y.net/ or 
   http://www.web-sites.co.uk/nasm/).

 - Borland's make utility. Use the GNU make utility instead.

 - "Resource introspection." Applications must know at compile
   time the names of all resources they will use. Resources
   cannot be browsed dynamically.

Sharing methods between languages is more complicated than 
sharing global functions, since it requires use of a common 
application binary interface (ABI). Kylix virtual method 
tables (VMTs) conform to the currently proposed UNIX ABI 
specification. To make gcc generate conforming VMTs for C++ 
objects, you must use gcc version 2.95 or later and specify 
the COM_INTERFACE attribute in the C++ class declaration. 
Without this attribute, gcc may insert information that changes 
the VMT offsets and makes Kylix calls to C++ methods fail.

In addition, the Kylix interface or class declaration must 
use the same calling convention as the C++ class declaration. 
The recommended calling convention is stdcall, though Kylix 
also supports cdecl.

NOTE: You can receive linker errors if you attempt to use
      the ~ shortcut in the paths you enter in your 
      directories paths. Make sure to use complete paths
      in the Project|Options|Directories/Conditionals
      dialog.


Exporting functions from a .o file to the
interface section
-----------------------------------------

The Delphi compiler can only export a single function into the interface
section from an .o file that is statically linked into a Delphi unit via
the $LINK or $L directive. Trying to do so 

  unit LinkFile;

  interface

  procedure ExternalRoutine1; external;
  procedure ExternalRoutine2; external;

  implementation 

  {$LINK ExternalFile.o}

  end.

will result in an internal compiler error.

As a workaround, do not export these functions directly to the unit's
interface section, but use them in the implementation section only.


Statically linking libraries with packages
------------------------------------------

A Kylix program may not run if it statically links a library, and
both the program and the library are built as Kylix packages. This
occurs because the library is initialized before glibc. 

There are two ways to statically link libraries with packages. 
One is to rebuild the library as a package. The other is to compile 
the program using the dcc command line compiler, specifying the
option "-lsbplbaseclx.so.6".

Changing Pascal Linker Options
-----------------------

After changing the Pascal linker options (from using dpu to using C/C++
object files) you should manually delete the dpu files before you
rebuild.

Stripping C++ executables
---------------------------

Binaries produced by the bc++ compiler that are built with runtime 
packages may not function properly if they are stripped of their 
symbols with a utility such as GNU strip. Instead, a -Gs option is 
available in the linker to not emit a symbol table into the resulting 
ELF file


Building Delphi components in the C++ IDE
-----------------------------------------

NOTE: You cannot build a Delphi component implementing an interface 
      within the C++ IDE.


===============
RUNTIME LIBRARY
===============

All Delphi RTL functions are supported, except for routines 
whose purpose or functionality is Windows-specific (such as 
RaiseLastWin32Error). The glibc memory manager replaces BorlandMM 
and the ShareMem unit. Some functions have been moved from other 
units into the System unit, while all Variants functions have been
moved into the Variants unit (matching the scheme in Delphi 6.0).

Because of limitations in the glibc strcoll() function, avoid 
passing large strings (>50K) to AnsiCompareStr, AnsiStrComp, or 
other routines that depend on these functions. This limitation 
should be removed in glibc 2.1.91 (beta) and 2.2.

WideString types are now reference-counted, just like AnsiString.

Readln and Writeln now support WideString and WideChar types. 
WideString data are converted from or to the locale-specific 
character set. Text file I/O does not support Unicode text files, 
but you can read or write locale-specific character sets from or 
to WideString variables.

Date formats now support calendars that use era-based dates. This
feature is based on UNIX standards that have not been implemented
in glibc.

The DefaultTextLineBreakStyle variable in System.pas determines 
how text file routines find or mark the end of a line and the end 
of a file. Affected routines include Read, Write, Readln, Writeln, 
Eof, Eoln, SeekEof, and SeekEoln. If DefaultTextLineBreakStyle is 
tlbsCRLF, line breaks are indicated by a carriage return and a 
line feed (CR+LF), and EOF (ASCII 26) is returned as the last 
character in a file. If DefaultTextLineBreakStyle is tlbsLF (the 
standard condition for Linux), line breaks are indicated by a 
line feed alone and EOF is treated like any other character. 
You can override DefaultTextLineBreakStyle by calling the 
SetLineBreakStyle procedure; for example,

  SetLineBreakStyle(MyFile, tlbsCRLF);

enables DOS-style line breaks and EOF markers for MyFile.

File dates are stored in UNIX format. This change does not 
affect code that performs simple date comparisons or calls 
standard conversion functions such as FileDateToDateTime. 
However, code that directly packs or unpacks the data 
structure contained in DOS date-time values will not work.

Results returned by FileAge and FileGetDate are ambiguous. Both 
functions return -1 to indicate an error, but under Linux the 
return value may contain -1 as a date/time.

Variants have been reimplemented with OS-independent Pascal 
code. Your application must use the Variants unit if it uses 
variants.

You can now define custom data types for variants. To create 
a new variant type, declare a class that descends from 
Variants.TCustomVariantType, then implement all required behavior 
(including type conversion rules) in the new class.
(Note: Variant arrays of custom variant types are not supported.)

The following features are NOT supported:

 - VT_DECIMAL in variants.
 - UNC file names (\\server\directory\...).

     
====================
DATABASE DEVELOPMENT
====================

Kylix provides lightweight, native SQL drivers that use
TSQLConnection to manage database connections. The Enterprise
version includes drivers for InterBase, MySQL, DB2, Oracle,
Informix, and PostgreSQL (new since Kylix 2 Update version). 

Before working with these drivers, edit your 
.borland/dbxconnections file so that it contains valid settings 
for the database you are using. For example, if you are using 
InterBase, the [IBConnection] section must contain a path to a .gdb 
file to which you have write access, a valid user name,  and a 
valid password.  You can test data access by running the 
DbxDataClxProj sample application, which displays a list of aliases 
from your .borland/dbxconnections file and loads the appropriate 
driver with the alias you select.

NOTE: All dbExpress LibraryName settings have been changed to follow 
      a standard sym link .so naming convention.

        Interbase - libsqlib.so
        MySQL - libsqlmy.so
        PosgreSQL - libsqlpg.so
        DB2 - libsqldb2.so
        Oracle - libsqlora.so
        Informix - libsqlinf.so

      Previously the symbolic links had a .so.1 extension.


Dataset components include TSQLDataSet, TSQLStoredProc,
TSQLTable, and TSQLQuery. These are unidirectional, read-only
components that provide fast access to large amounts of data but
do not provide buffering or updating. For buffering and
read-write functionality, use these components with
TClientDataset and TDataSetProvider.

The TSQLMonitor component provides aid in debugging 
communication between your application and the database 
server. 

For an overview of Kylix database components, see dlx2dbd.hlp 
and the instructions under DOCUMENTATION below.

Known problems and limitations
------------------------------

When a database-property or component editor connects to a
database through a TSQLConnection object, it leaves
TSQLConnection.Connected set to True. If you need this property
to be False, set it back to False before saving the unit.

Client dataset table and column names are limited to 31 bytes.
Exceeding these limits causes an exception to be thrown.

Indices created with an option of ixCaseInsensitive do not
collate Unicode data correctly.

The following features are NOT supported:
 - The BDE. There is no support for Paradox or dBASE.
 - SQL Explorer, SQL Builder, and the stand-alone SQL Monitor.
 - Database connection components based on IDispatch or DCOM. There 
   is no TDCOMConnection, TSocketConnection, scktsrvr.exe, or 
   httpintr.dll.
 - ADO.
 - Data Dictionary.
 - Decision Cube components.

When launching a database application developed in the Delphi
language from the console, it may be necessary to precede the
project name with an absolute or relative path, such as:

  ./Project1
  
Failure to do so may result in a runtime error.

  

dbExpress
---------

TSQLDataSet and TSQLClientDataSet now have 
DefaultRowsetSize = 20 (Oracle only). To use a different 
RowSetSize, add the RowSetSize property manually 
(e.g., "RowsetSize = 200") to dbxconnections, for existing 
connections, or set a new value when creating a new connection. 
RowsetSize can be modified in code, as shown here (Delphi 
language example):

  SQLConnection1.Params.Values['RowsetSize'] := '200';
 
 
dbExpress components and MySQL transactions
-------------------------------------------

MySQL doesn't support more than one active statement per 
connection. To perform multiple SQL requests with a single 
TSQLConnection the dbExpress components clone connection. 
There is a bug in maintaining state information on the no.of 
active statements with respect to a TSQLConnection. This might
cause serious failures in transaction as the transaction might 
be started on one connection and commit or rollback might be 
happening on another connection.

Workaround:  Before you start a MySQL transaction make sure
TSQLConnection.ActiveStatements is 0. If its not 0 then close 
the TSQLConnection and reopen it and that should clear it. All 
your transaction activity should then go on a single connection.
 
 

Informix
--------

Kylix 3 is certified with Informix 9.21 server, Informix SE 7.2,
and the Informix commercial client iConnect 2.6.

Informix BLOB/CLOB fields
------------------------------

A new global variable, InformixLob, is available to allow
you to work with Informix BLOB and CLOB fields.

The variable is required because Informix BLOB (fldBLOB,
fldstHBINARY) and CLOB (fldBLOB, fldstHMEMO) fields are
mapped as ftOraBlob and ftOraClob, respectively, and the
DataSnap resolver performs special query generation when
resolving Oracle BLOB/CLOB fields, but not when resolving
Informix BLOB/CLOBs. To address this issue, set InformixLob
to True when using Informix BLOB/CLOBs, and switch it back
to False (the default) when using Oracle BLOB/CLOBs.

InterBase
---------

The InterBase driver has been tested with InterBase 6.5.
For more information about InterBase, see 
http://www.borland.com/interbase.

Currently, the driver does not support the ARRAY type.

If the server gives an error of "Cannot attach to database
password," make sure that you are starting the server as root.
  
InterBase Superserver and Red Hat 7.1 and 7.2
---------------------------------------------

Starting InterBase 6.01 SuperServer on Red Hat with the command

   ibmgr -start -forever

causes the following error:

'/opt/interbase/bin/ibmgr.bin: error while loading shared libraries:
libncurses.so.4: cannot load shared object file: No such file or
directory'

Workaround:
   Install ncurses4-5.0-2.i386.rpm from Red Hat.
   
MIDAS resolver query generation
-------------------------------

MIDAS resolver query generation is only skipping BLOB columns from 
the update. Instead, you should call SQLCursor->isSearchable() to skip 
TIMESTAMP columns. 

Workaround: Set the Update  Mode to WhereKey.

MySQL certification
-------------------

The MySQL driver is now certified for use with MySQL version 
3.23.49. Use the libmysqlclient.so.10.0 library with this
version.

MySQL limitation
----------------

MySQL can't filter with FLOAT fields in the WHERE clause. Since
this limitation prevents updates with TClientDataset and
TDataSetProvider, use DOUBLE instead. For more information, see
the MySQL documentation.

Huge Text in MySQL
------------------

MySQL Server has a startup parameter called max-allowed-packet that,
by default, is set to 1 megabyte for most MySQL servers. Increase the
value of max-allowed-packet if you encounter difficulty writing large
amounts of data (such as large strings) to MySQL.

DB2
---

The DB2 driver is certified for DB2 version 7.2. The client
version and server version must be the same.

Because of a known DB2 bug, the DB2 client returns only one 
record at a time when a request for a block fetch is made, 
even with RowsetSize option > 1.

DB2 requires the shared library libdb2.so installed under 
/usr/IBMdb2/V7.1/lib
Do not use the libdb2.so located in /usr/lib.


Timestamp issues
----------------

The dbExpress DB2 driver rounds the TIMESTAMP fractional value 
and there could be some precision lost depending upon the data 
retrieved. When you apply back changes the old value will not 
match the one on the server and ApplyUpdates() will fail.

Workaround:

Make sure DB2 TIMESTAMP is not part of indexed columns and set
the DataSetProvider Update mode to WhereKey instead of WhereAll.

Oracle
------

The driver is certified for Oracle 9i. The client version 
and server version must be the same.

You need to have the location of libclntsh.so in your 
LD_LIBRARY_PATH variable to use the Oracle driver. 
(Note: libclntsh.so is part of the Oracle Linux client access 
libraries, available from Oracle.) 

The size of LONG and LONG RAW fields cannot be determined without
fetching the whole field. So if BLOB SIZE is set to -1, LONG and
LONG RAW fields are truncated to 64K. We recommend that BLOB SIZE
be set to your best estimate of the blob size.

Oracle OS authentication
------------------------

To get the correct list of tables and other schema objects in the
dbExpress components, set the User_Name to OPS$XXX, where XXX is
the OS Authenticated user.

Oracle duplicate transaction error
----------------------------------

If an application fails during an Oracle transaction, subsequent 
attempts to start new transactions or apply updates on the same 
server may fail with "ORA-24757: duplicate transaction identifier."

To work around this problem, kill the session on the server.

Oracle types
------------

ORACLE 9i types TIMESTAMP (introduced for JDK 1.3.1 compliance) and
other types like XML Type, Temp tables, etc. are not supported.
Use "DATE" instead.

Configuring driver files
------------------------
The Oracle driver now supports Trim Char, Multiple Transaction 
and OS Authentication. You need to add these settings to your dbxdrivers 
for new aliases and/or update dbxconnections in order to include these 
settings for old aliases. 

Please append the following at the end of dbxdrivers file if you are
using a driver file from an earlier version of Kylix: 

[Multiple Transaction] 
False=0 
True=1 
[Trim Char] 
False=0 
True=1 
[OS Authentication] 
False=0 
True=1 

And the following under [Oracle] section in dbxdrivers and under your 
existent Oracle alias. 

OS Authentication=False
Multiple Transaction=False 
Trim Char=False 

PostgreSQL
----------
PostgreSQL is a new driver and you need to add its section under 
dbxconnections and dbxdrivers in case you have these files already 
in your system. 

Please add the following line under [Installed Drivers] section in 
your dbxdrivers file. 

PostgreSQL=1 

and the following section in dbxdrivers: 

[PostgreSQL] 
GetDriverFunc=getSQLDriverPGSQL 
LibraryName=libsqlpg.so
VendorLib=libpq.so 
HostName=ServerName 
Database=test 
User_Name=user 
Password=password 
BlobSize=-1 
ErrorResourceFile=./DbxPGSQLErr.msg 
LocaleCode=0000
Server Port=

PostgreSQL Data Types
---------------------

Unsupported data types:
  -OID
  -ARRAY
  -network types
  -geometric types

MONEY and BYTEA are deprecated types for PostgreSQL. We  recommend
not using these, as known problems exist.

Can't create local dataset with SQLClientDataset
------------------------------------------------

Errors can occur when local datasets are created using a
SQLClientDataset component. Note that this component is
designed for provider datasets. For local datasets, use a
ClientDataset component.

Specifying PostgreSQL Client Encoding
-------------------------------------

If a client machine and a PostgreSQL database use different encodings,
you need to execute the "set names" or the "set client_encoding to" 
command to specify the encoding of the client.  For example, if the
client machine is using en_US locale and the database is UNICODE
based, set CommandText property like:

   set names 'LATIN1'; select * from tbl
   
   
Linking Tables in PostgreSQL
----------------------------

NOTE: Avoid linking tables by a serial field type.

===============
WEB DEVELOPMENT
===============

WebSnap session support unavailable
-----------------------------------
[Enterprise edition only]

WebSnap session support (as implemented in TSessionsService)
is not available on Linux. 

Detail: As they are in Windows DLLs, global variables in Linux shared 
objects are shared across all threads that use the shared object, and each 
process that loads the shared object gets its own copy of the data 
segment. On Windows, IIS spawns threads to allow the sharing of global 
objects in DLLs. On Linux, however, Apache spawns new processes, each of 
which has its own data segment and global variables. Since session support, 
as implemented in TSessionsService, is dependent on the sharing of global 
variables, it cannot work on Linux.

Browser Preview feature issues
------------------------------

The Mozilla Preview Widget is required for browser previews.
If you choose not to install the widget, you will get no response
if you attempt to Preview an HTML or XML document in the code editor.

In addition, the Preview does not support secure socket transport 
(https://...). This is not an issue for previewing local HTML files,
but if the file to be previewed contains a link that uses a secure socket, 
the link will not work.

Some window managers have problems with embedding the Mozilla-based
previewer. To work around this, the previewer can work in a non-
embedded mode. To activate this, go to Tools|Environment Options,
click on the Internet tab and uncheck Embed HTML Preview Browser.

WARNING: Do not attempt to open an html document that includes
         frames with the Mozilla Preview Widget. This can crash
         the X Window system.

Secure sockets not supported in WSDL Importer
---------------------------------------------

WSDL Importer fails if the Address is a secure connection 
(https).

Example:

File|New WebServices|Soap Importer
Enter a WSDL from a secure connection
  https://mySite/WebServices/NetWebService/SimpleDocumentService.asmx?WSDL
Expected:
  Source code generation
Actual:
  Error: "Could not open file (URL)"
  
Workaround:
1. Use your browser to view the WSDL file.
2. Save the source to a local file.
3. Import the local file.

WSDL Importer & Red Hat 7.3
----------------------------

Because of binary incompatibilities between Red Hat 7.3 and the other Linux
distributions, including previous Red Hat releases, the C++ WSDL wizard may
fail when trying to import remote WSDL documents.

*   in the WSDL importer if you give it a URL and then hit <next>.

*   with the THTTPRio if you give its WSDLLocation property a URL and then
    attempt to set the Service or Port property.

The work-around is to first import the Location with your browser and then
save it to disk.  You can import that file, or set the WSDLLocation to that
file.  For the THTTPRio component, you can also set the URL property
instead of the WSDLLocation, in which case you don't need the Service/Port.

The problem occurs at design-time only, and you can successfully run from
the IDE or as stand-alone applications.


Apache configuration
--------------------

WebBroker supports Apache version 1.3.9 and later (excluding 2.x 
versions).

To run the CgiServer demo, create a script directory named 
"scripts" that points to the physical directory in which the CGI 
executable is located. To do this, add the following line to the 
httpd.conf file:   

  ScriptAlias /scripts/ "/<directory>/httpd/cgi-bin/"

where <directory> is the full path to the directory in which 
Apache is installed. Do not omit the trailing slash.

Next, verify that the physical directory has the ExecCGI option
set to allow execution of programs. httpd.conf should contain 
lines similar to the following:

<Directory "/<directory>/httpd/cgi-bin">
    AllowOverride None
    Options ExecCGI
    Order allow,deny
    Allow from all
</Directory>

httpd.conf must also contain:

  SetEnv LD_LIBRARY_PATH <install directory>/bin

where <install directory> is the full path to the Kylix 
installation directory.

For database web application development, httpd.conf must also 
contain:

    SetEnv HOME <home directory>

where <home directory> is the full path to the location 
of a .borland directory (or the .borland directory of the
account under which Apache runs). If you omit this setting, 
the database drivers will use the default configuration files 
located in /usr/local/etc/.

For other problems, check the Apache error_log file.

Default handler names and Apache
--------------------------------

Apache only recognizes the default handler name of a project
in lower case. For instance, for a project, Project1, the
default handler that Apache will recognize is project1-handler.

Web Service and cdecl
---------------------

Recommendation: Avoid using the cdecl calling convention in 
Web Service server methods.

DataSnap tip
------------

A CGI server will correctly handle a SOAP request if you set
a LANG environment variable in your httpd.conf file, as follows:

    SetEnv LANG en_US

X Windows requirement for JPEG
------------------------------

The $DISPLAY variable must point to an available and running
X Windows server to enable JPEG support in NetCLX.

ThreadCacheSize and connection count
------------------------------------

ThreadCacheSize should always be set to a value that matches
or exceeds the number of anticipated concurrent connections.

Other Web development issues
----------------------------

The socket classes implement blocking I/O. Use a separate 
thread to implement nonblocking behavior.

TTcpClient and TTcpServer implement the TCP/IP SOCK_STREAM socket 
type. The server starts a new thread for each connection. Socket 
ports below 1024 require root permission to accept connections.
(Recommendation: Develop and debug with ports 1024 and above, 
and deploy with ports below 1024).

SOAP/WSDL issue
---------------

If an Apache server (httpd.conf) is configured to listen on port 8080, 
running the soapserver/wsdl generates a link without the correct port
information appended.

TXMLDocument note
-----------------

If you set the DOMVendor property of a TXMLDocument component to
OpenXML, you must also add oxmldom to your uses clause.


==========================================
INTERNATIONAL/CHARACTER SETS/LOCALE ISSUES
==========================================

Japanese locale/IME issue
-------------------------

When X Server's "backing-store" setting is "NO" (the default),
the system's Input Method Editor (IME) may behave abnormally,
causing it to flash, and window and form captions may not
accept multibyte characters correctly.

To correct this problem when using a Japanese locale (ONLY), 
set the backing-store value to "YES" by typing this command in 
a console window:

    startx -- +bs

To check the current backing-store value on your system, type

    xdpyinfo|grep "backing-store"

in a console window.

Caldera OpenLinux 3.1.1 MBCS/glyph issue
----------------------------------------

If you are running Kylix under OpenLinux 3.1.1, you may encounter
a failure in rendering the correct glyphs for multibyte character
sets (MBCS).

Workaround: Use an X11 font server. OpenLinux does not, by default,
start a font server, but you can set the X11 font server at any time
by executing the following shell command sequence:

    xfs &   
    sleep 3
    xset +fp unix/:7100
    xset fp rehash

AnsiUpperCase, AnsiLowerCase, and MBCS
--------------------------------------

AnsiUpperCase and AnsiLowerCase functions can only use characters
that exist in the current locale. Thus, if any of the characters
being converted do not have an opposite case equivalent in the
current locale, the functions (and all functions that call these
functions) will not work as expected.

MBCS and the default character set
----------------------------------

If you intend to display multibyte characters in your 
application, set the Font.Charset property to fcsDefaultCharSet 
in your main form.


TTextBrowser and Asian HTML
---------------------------

TTextBrowser may not display HTML with Asian characters
correctly. A workaround is to force the proper encoding at 
runtime:

    TextBrowser1.Factory.RegisterMimeType('html',
        'text/html;charset=SJIS'); // change encoding
    TextBrowser1.LoadFromFile(TextBrowser1.FileName);   // reload

Unable to run IDE under some locales
------------------------------------

If you attempt to run the Kylix IDE under the tr_TR locale, the
program may abort with the message "could not find useable fonts
for this locale". This is due to a problem accessing ISO 8859-9
fonts and might affect other locales. 

Workaround: Use a different locale.

Code Editor problem with some non-Latin1 fonts
----------------------------------------------

The code editor sometimes displays the Latin1 character set, even
though a non-Latin1 locale (such as pl_PL) is in use. This
problem does not affect all fonts, so you can work around it by
changing the font used:

1. Choose Tools|Editor Options, then choose the Display tab in
   the Editor Properties dialog.
   
2. In the Editor font drop-down list, select a different font.

3. Click OK. 

If the code editor is still using the Latin1 character set,
repeat the above steps and choose a different font.


Locales and form editing
------------------------

Exercise care when editing forms as text when the form contains 
string data specific to a certain locale character set. If you edit a 
form as text in a different locale that cannot represent the characters 
of the original locale, the data in the form will be corrupted.

This is a general issue with code pages, not specific to form files 
or to Linux. The issue arises because the Kylix IDE attempts to 
convert Unicode strings stored in the text form into locale characters
when you view a form as text. This conversion may lose information if, 
for example, a form contains European accented characters and you try to 
view it as text on a machine running a Chinese locale character set.

Missing charsets in bg_BG locale
--------------------------------

For Suse 7.3 users in the bg_BG locale there is an error related to missing
charsets. To get around this, set your environment to use bg_BG.ISO-8859-5
instead of bg_BG. Add the following to your .bash_profile:

export LC_ALL=bg_BG.ISO-8859-5
export LANG=bg_BG.ISO-8859-5


***************

===================
THE FREECLX PROJECT
===================
At the time of release of Kylix 3, the FreeCLX project has not 
yet been updated with the latest CLX developments.

FreeCLX is the Open Source project for Borland's CLX
Component Library for Linux. The project allows you to
collaborate in the continued development of CLX library
elements and to rebuild and redeploy the Open Source library
in any manner you want*.

The FreeCLX project uses SourceForge to allow for anonymous
CVS access, bug reports, and patch submissions. The project
home site is http://freeclx.sourceforge.net/

* In order to maintain compatibility with applications
  developed and distributed against the official Borland
  Kylix CLX libraries, modified binary runtime packages
  must be distributed under names other than those
  deployed officially from Borland.

-------------------------------------------------------
Copyright (c) 2002 Borland Software Corporation. 
All rights reserved.
-------------------------------------------------------

