The porting of XCIN-2.5 to HP-UX operating system:
=================================================
XCIN-2.5 is originally developed under GNU/Linux environment and
also have porting to FreeBSD system. Both system use XFree86 as
their X Window environment, which follows the X11R6.X standard.
Therefore the porting between both systems is only different in
the system libc level and the locale environments they support.
The situation is very similar for HP-UX operating system. Its
X Window environment is the same as that of XFree86. The only
difference is the installation path. Besides, XCIN needs many
POSIX standard function calls (especially the I18N related calls).
These function calls are automatically available in GNU/Linux
system, because its libc --- the GNU glibc --- is fully POSIX
compliant. In HP-UX, we have to define some macros to include
these POSIX function calls when compiling. Of course the locale
environments are a little different in HP-UX. Besides these,
the HP-UX environment is very similar to that of GNU/Linux or
FreeBSD. So the porting work is not very hard.
To describe the porting to HP-UX, we first introduce the components
of the XCIN source code. If you obtain the recent XCIN source package
(e.g., ftp://xcin.linux.org.tw/pub/xcin/xcin/xcin-2.5.2.1.tar.gz) and
ungzip, untar it, it will have the following components:
configure An auto-configuration script before compiling.
src/ The source tree of XCIN program.
cin/ The source of input method tables.
etc/ The configuration files of XCIN.
po/ The message translations.
script/ The source to generate configure script.
doc/ The documentations.
In the following the porting work of each component will be described.
A. configure and script/:
-------------------------
XCIN use GNU autoconf facility to do auto-configuration before compilation.
This facility will generate a script called "configure" according to your
requirement to determine your system type and setup all the required
parameters for compilation. The GNU autoconf package is widely available
in GNU/Linux and FreeBSD systems. I think it should also has a HP-UX porting.
The source of configure script is in the directory "script". The programmer
should provide these source according to their requirement, and excute GNU
autoconf package to generate the configure script. The GNU autoconf package
can determine many kinds of operating system type, including GNU/Linux,
FreeBSD, and HP-UX. After the type of system is determined, it will setup
several default parameters, but it is still not enough. So we should provide
our commands here.
The main source of configure script is "configure.in". Reading its contents
one will understand what checks will be performed in the generated configure
script. For the parts related to HP-UX system, the first check is the
compiler type. If will first check if the GNU C compiler works or not,
if not, it will check if an ANSI C compiler is available or not. If yes,
then it will set the needed optimization and other options for ANSI C
compiler, and so does that for GNU C compiler. From here we know that XCIN
only has two kinds of compilers porting, one for GNU C, and anthor for
ANSI C (and most likely, the ANSI C for HP-UX).
(see: "Check compiler:" for details)
Another special check is the "install" program. We need a BSD compatible
"install" program for package installation, so by default the GNU autoconf
will search for the BSD compatible "install". If it can't find, it will
use a "install-sh" script instead (it is also provided in the same directory).
The "install" program of HP-UX can pass the check of autoconf. However, it
still lack an "-d <directory name>" option. So it is still a little not
compatible. Therefore, I add additional check for "-d" option of "install"
program.
(see: "Check for programs." for details)
Now comes the operating system special configurations. It will take the value
of "$host_os" and setup the needed parameters directly. These parameters are
most likely related to the dynamic object/library loading facilities. These
are special for different operating systems. For HP-UX, because currently
XCIN still does not have a porting to use its dynamic object loading facility,
although here the correct parameters are set, but they are not actually used.
They will be preserved for future usage (when XCIN has a completed porting).
Now for HP-UX porting, all the dynamically loadable objects (e.g., the input
method modules) are statically linked with the main program. The settings for
HP-UX are listed here:
hp*)
dl_unsupport=1
cf_sharelib='-n +Z'
ld_sharelib='ld -b +h $@'
ld_shareexe='-Wl,+s'
slib_ext='sl'
env_libpath='SHLIB_PATH'
os_type=HPUX
AC_DEFINE(HPUX)
;;
where the first line: "dl_unsupport=1" indicates that the dynamically object
loading is not supported and will be statically linked, and the others are
compilation and linking options for dynamic loading facility of HP-UX. They
will be used in the future. The last two lines the symbol "HPUX" is defined.
The "os_type=HPUX" will appear in some of the Makefiles after configuration,
while the "AC_DEFINE(HPUX)" will have a syntax "#define HPUX" in the config.h
after configuration (see below).
(see: "Checks for Host type & Dynamic library & options." for details)
In the following we will check a lot of system function calls. Some of them
are default check for GNU autoconf, and the others are special checks for
XCIN and for different operating system. For HP-UX, a special check is the
function "snprintf". In GNU/Linux, this function has a prototype:
int snprintf(char *str, size_t size, const char *format, ...);
The difference between snprintf() and sprintf() is that it has additional
"size" arguement. This arguement will prevent the buffer overflow problem
so that using it instead of using sprintf() will be more secure. It is
very encouraged to use this function. However, at least in HP-UX B.10.XX
system it does not provide this function (but in HP-UX B.11.XX this function
is available). Therefore I write a simple one in the xcin source code in case
that if it is not available in the system, we can also link with my simple
version (see below). However, my simple version is buggy and also have a
potentially buffer overflow problem. But in theory it will rarely happen.
So currently I just left it there and in the future I may improve it.
Finally the configure script will generate all the Makefiles for each
components of XCIN source and a "config.h" file. The "config.h" will be
included in most of the XCIN source codes. Therefore, all the configuration
information will provided here, hence the compilation of the whole program
should run smoothly.
B. src/:
--------
The "src/" directory contains the source codes of XCIN program. It has several
sub-components as listed here:
src/include/ The header files of XCIN source code.
src/Cinput/ The input method modules.
src/lib/xcintool/ The basic tool library.
src/lib/siod/ The Lisp/Scheme interpreter library.
src/lib/IMdkit/ The XIM processing kernel.
src/util/ The utilities of XCIN system.
src/*.c The main program codes.
Here only the HP-UX porting part is mentioned. All these parts will have
the syntax "#ifdef HPUX" symbol in the top of the C source codes. And the
symbol "HPUX" will be defined in the "config.h" generated by configure
script if under the HP-UX operating system.
B.1. src/Cinput:
----------------
The Makefiles generated by configure script will determine to create the
dynamically loadable module or not. In HP-UX, it is not. In fact, this
is not HP-UX specialized, because many other operating system also do
not support the dynamically loading facility very well. So the determination
here will serve for general cases.
B.2. src/lib/xcintool:
----------------------
There are several parts related to the HP-UX porting. The first is my
implementation of snprintf() function. In fact it can also serve for general
cases, because there might be many other systems which lack this function.
So the configure script will determine it, and record the result in the
"config.h" file. Hence in "src/include/xcintool.h" there is a simple macro
#ifndef HAVE_SNPRINTF
# define snprintf xcin_snprintf
extern int xcin_snprintf(char *str, size_t size, const char *format, ...);
#endif
to decide to use my implementation of snprintf() or use the system provided
one.
(see: "src/lib/xcintool/snprintf.c" for details)
Another part is in "src/lib/xcintool/check_file_exist.c". In this function
we need stat() system call and macros to determine the file type. These are
POSIX sources. So in HP-UX we have to define "_INCLUDE_POSIX_SOURCE" macro.
Finally in "src/lib/xcintool/set_locale.c", we need the nl_langinfo()
function call and its "CODESET" macro. This belongs to the XOpen source,
so in HP-UX we have to define "_INCLUDE_XOPEN_SOURCE" macro.
B.3. src/lib/siod:
------------------
The siod library is adopted from other Free Software project. In this library
it needs some system time related functions. So in HP-UX we need these codes:
#ifdef HPUX
# define _INCLUDE_POSIX_SOURCE
# include <sys/times.h>
#endif
(see: "src/lib/siod/siod.c" for details)
B.4. src/util/cin2tab:
----------------------
The "cin2tab" utility is used for input-method table compiling. This program
use the standard "getopt()" function call to parse the command line arguements.
To use this function, some external variables like "optarg", "opterr", ....
are needed. In many other operating systems, they are declared directly in
the system header files, but in HP-UX we have to manually declare them. So
we have these codes:
#ifdef HPUX
extern char *optarg;
extern int opterr, optopt, optind;
#endif
(see: "src/util/cin2tab/cin2tab.c" for details)
B.5. src/util/testprog:
-----------------------
The "testprog" is a very simple test program for I18N and Xi18n environment.
It will not be installed into the system, but if you find that XCIN cannot
input characters into your XIM clients, then it is a good idea to test the
"testprog" for character input from XCIN and try to figure out the problem.
Similarly to the setlocale mentioned above, in this program it will also
call the "nl_langinfo()" function, so the "#define _INCLUDE_XOPEN_SOURCE"
is needed for HP-UX system.
B.6. src/xcin_main.c:
---------------------
This is the main program of XCIN. It also calls the "getopt()" function,
so we have to manually declare the needed external variables here. And
similarly the define of "_INCLUDE_POSIX_SOURCE" is also needed.
Besides of these, when calling for "strdup()" function, we have to manually
add the (char *) syntax in front of it, otherwise the ANSI C compiler will
give a warning message. This is not a problem. So for every calls of strdup()
we just add it to avoid any warning messages.
C. cin:
-------
The cin directory contains the input method tables of XCIN system. These
tables are classified in terms of the character set encoding. There are
mainly 2 kinds of encodings which XCIN supports: big5 and gb. Where "big5"
includes Big5 (CP950) standard and Big5 HKSCS standard; while "gb" includes
GB2312 standard and GBK standard (starting the support in a very early
stage).
However, the encoding name may be different for various operating system,
because the locale name of various operating system might be different.
For example, the Taiwan Big5 locale name is called "zh_TW.big5" in HP-UX,
and the Mainland China GB2312 locale name is called "zh_CN.hp15CN", also the
HongKong Big5 locale name will be called "zh_HK.hkbig5". So after installation
in HP-UX, the Big5 (CP950) tables should be installed in the "big5/"
sub-directory, while the GB2312 tables should be installed in the "hp15cn"
sub-directory, and the Big5 HKSCS tables should be installed in the "hkbig5"
sub-directory. The similar case also happens for other operating systems.
Therefore, the installation process of the input method tables is changed
to match the general case. That is, it will determine the current operating
system type and install the input method tables into correct places.
D. etc:
-------
The xcin configuration files "xcinrc" are kept here. For different operating
systems the contents of "xcinrc" should be modified properly. This is also
due to the different locale names supported by various operating systems.
Therefore, in "xcinrc" the locale related settings, e.g., the FontSet names
and encoding names, should be set correctly.
The major changes of this part is very similar to those in "cin/" part. The
installation process will determine the operating system type and pick up
the correct xcinrc sample file for default xcinrc. For HP-UX system, the
sample file is named as "xcinrc.HPUX".
E. po:
------
The XCIN message translation files are placed here. This is related to the
"LC_MESSAGES" category of locale environment. Currently it only contains
one message translation: the Big5 Taiwan translation. In the future we may
include more.
The major problem of this part is that XCIN now only adopt the GNU Gettext
as its default message translation interface. It has the prototype defined
in the GNU glibc / libintl:
char *gettext(const char *__msgid);
However, gettext() function is not a standard of HP-UX. There are two
approaches to work around:
1. The standard interface in HP-UX is the X/Open catgets() function. We
might need to port XCIN to use this interface. But we haven't done this.
2. Install the GNU Gettext package into HP-UX system. GNU Gettext is hightly
portable to all kinds of UNIX systems, and the installation process is
very obvious. It will add a libintl to provide the gettext() interface.
If in some UNIX systems they already have the gettext() or catgets()
interfaces, the GNU Gettext will use them as its engine by default and
will not install its implementation into the system. If both gettext()
and catgets() are not found, then its fully implementation will be installed
to provide the message translation facility.
For HP-UX, because the catgets() is already available, so GNU Gettext
will use it directly and simply add a layer to provide the gettext()
interface. Therefore XCIN installation process will automatically detect
the gettext() function and libintl library (provided by GNU Gettext) and
link with it. This approach is very straightforward and works very well.
F. doc:
-------
Here a comprehensive documentations of XCIN package is provided. Of course
many HP-UX related materials are added, including the installation guide,
the special notes for usage, .... etc. Because XCIN source code has been
written to consider the most general cases as possible, so the installation
process and usage is not too different for HP-UX and other operating systems.
In the following the installation guide in HP-UX is briefly mentioned here.
For details please refer to "xcin-2.5/doc/En/SETUP.En".
1. Install Berkeley DB2 library. This is the basic engine of libtabe. It is
available in
http://www.sleepycat.com
ftp://xcin.linux.org.tw/pub/xcin/misc/db-2.7.4.tar.gz
The installation steps are well documented inside this package.
2. Install libtabe. This is the basic engine of XCIN bimsphone module. It is
available in
ftp://xcin.linux.org.tw/pub/xcin/libtabe/libtabe-0.1.9.tar.gz
The installation steps are well documented inside this package. In short:
gzip -dc libtabe-<version>.tar.gz | tar -xvf -
cd libtabe
./configure --prefix=<path> --enable-shared \
--with-dbinc=<path of Berkeley DB2 header files> \
--with-dblib=<path of Berkeley DB2 library>
make install
3. Install GNU Gettext (optional). If you do not need the translated message
facility of XCIN, you can skip this. The GNU Gettext is available in
ftp://ftp.gnu.org/gnu/gettext/
The installation steps are well documented inside this package. In short,
the following steps are recommanded:
gzip -dc gettext-<version>.tar.gz | tar -xvf -
cd gettext
./configure --prefix=<path> --disable-nls
make install
make distclean
./configure --prefix=<path>
make install
For details please refer to the README document of this package.
4. Install the XCIN package. The stable release is available in
ftp://xcin.linux.org.tw/pub/xcin/xcin/
or the under-development (experimental) versions is available in
ftp://xcin.linux.org.tw/pub/xcin/xcin/devel/
The installation process is
gzip -dc xcin-<version>.tar.gz | tar -xvf -
cd xcin-2.5
./configure --prefix=<path> \
--with-extra-prefix=<path>
make install
For details, please refer to "xcin-2.5/doc/En/SETUP.En".
5. A special note for HP-UX: Before running xcin, it is better to check the
xmodmap of your CDE environment. Please run "xmodmap" and exam its output.
If you read a line:
mod1 Meta_L (0x22), Meta_R (0x42), Mode_switch (0x84)
then you have to run the command:
xmodmap -e "remove mod1 = Mode_switch"
to remove the "Mode_switch" for "mod1", otherwise some of the function
keys of XCIN will not be available.
6. Now you can run XCIN as usual:
a. set locale, example: export LANG=zh_TW.big5
b. run XCIN, example: xcin -x xcin &
c. set XMODIFIERS, according to above: export XMODIFIERS="@im=xcin"
d. run any XIM clients you like.
For details, please refer to "xcin-2.5/doc/En/UserGuide.En".
By Tung-Han Hsieh <thhsieh@linux.org.tw>
-------------------------------------------------------------------
Ph.D. student of Physics Department, National Taiwan University.
XCIN Project maintainer: http://xcin.linux.org.tw
mailing list: xcin@linux.org.tw