Read Me
MinGW catgets README
$Id$
Copyright (C) 2007, 2008, Keith Marshall
Written by Keith Marshall <keithmarshall@users.sourceforge.net>
Last modification: 09-Jan-2008
This package provides a native Win32 implementation of the POSIX National
Language Support API, conforming generally to IEEE standard 1003.1-2001,
and SUSv3, for adding national language message catalogue support to user
applications. It comprises a development library, designated libcatgets.a
for static linking, or catgets-<n>.dll with accompanying libcatgets.dll.a
import library for dynamic linking, with supporting nl_types.h header file,
delivering Win32 implementations of the catopen(), catgets() and catclose()
functions, as required by the POSIX National Language Support API; this is
accompanied by a suitable, standards conformant `gencat' utility program,
which is used to generate the message catalogue files for deployment with
user applications making use of these library functions.
The MinGW catgets package is free software It is provided AS IS, in the
hope that it may be useful, but WITHOUT WARRANTY OF ANY KIND, not even an
IMPLIED WARRANTY of MERCHANTABILITY, nor of FITNESS FOR ANY PARTICULAR
PURPOSE.
Permission is granted to redistribute this software, either "as is" or
in modified form, under the terms of the GNU General Public License, as
published by the Free Software Foundation; either version 2, or (at your
option) any later version; see the file COPYING, for further details.
Packaging Options
-----------------
MinGW catgets is available for download in three package formats; (the
full text of this README file is included with each):--
1) mingw-catgets-<version>-bin.tar.gz
Provides only the pre-built dynamic link library, for use by client
applications which are delivered in binary format. The DLL is placed
in the `bin' subdirectory of the directory in which the package is
untarred; typically this should be the root of either the MinGW
tree, or the MSYS tree.
2) mingw-catgets-<version>-dev.tar.gz
Provides the header files and precompiled libraries, which are needed
to develop `catgets' client applications, together with the associated
`manpage' documentation, and the `gencat' tool which must be used to
compile compatible message catalogues. It should be untarred in the
root of the MinGW tree, and client applications should be linked with
the `-lcatgets' option, specified *after* the dependent object modules,
on the linking command line.
Note that this development kit is specifically intended for native use
on a Win32 platform. To deploy it, you must also have libiconv-2.dll,
installed in a directory named in your $PATH; you may build this from
the mingwPORT, as noted in the following section, `Prerequisites for
Building from Source', or you may download a precompiled version from
the `MSYS Supplementary Tools' collection, on the MinGW download page
on Sourceforge.
If you wish to develop `catgets' dependent MinGW applications, using
a cross-compiler suite hosted on a non-Win32 platform, then you can
not use this development kit; you should install the requisite tools
as described in the later section, `Building for Cross-Hosted Use'.
3) mingw-catgets-<version>-src.tar.gz
Provides the full source code from which the above two packages have
been built; it supports building for native deployment, as the above,
or for deployment as components of a cross-compiler tool chain.
Prerequisites for Building from Source
--------------------------------------
To build and install the catgets development libraries and tools, you
require a C compiler, and tool chain, such as that provided by MinGW, and
a build environment capable of running Bourne shell scripts, and the GNU
`make' utility, such as that provided by MSYS.
Before attempting to build MinGW catgets from source, you must ensure that
a suitable `iconv' implementation is installed. This is not normally the
case, with a standard MinGW/MSYS installation, but the requirement may be
satisfied by installing GNU libiconv; this *must* be libiconv-1.11 or later,
and it *must* incorporate the 2007-04-23 patch, correcting a Win32 specific
wchar_t conversion bug; you may ensure that this prerequisite is adequately
satisfied, by installing libiconv-1.11 using the mingwPORT script from
http://downloads.sourceforge.net/mingw/libiconv-1.11-mingwPORT-20070423-1.tar.bz2
Building from Source, for use "In Place" on Win32
-------------------------------------------------
The build procedure, using MinGW and MSYS, is as follows:--
1) Choose a suitable directory, where you will build the package; (it
must be a directory in which you have write permission). A typical
example might be `~/src'; create it if necessary...
mkdir -p ~/src
cd ~/src
2) Extract the source distribution tarball...
tar xzf [[/]path/to/]mingw-catgets-<version>.tar.gz
3) Create a build directory, and make it your working directory...
mkdir mingw-catgets-<version>/build
cd mingw-catgets-<version>/build
4) Configure the build...
../configure [options ...]
For a typical MinGW installation, you will probably want to set, at
least, the `--prefix=/mingw' option; if you don't, this setting will
default to `--prefix=/usr/local', which is not what you want if you
have installed MinGW and MSYS with their standard configurations.
To see other available options, try...
../configure --help
(You may wish to consider adjusting the `CFLAGS', or the `--mandir'
settings).
5) Build the installable components...
make
6) Install the basic development library components...
make install
7) Install documentation...
This step is optional, but recommended; if you have installed, or if
you plan to install, the `man' package then...
make install-man
will allow you to access the manpages for gencat(1), catopen(3),
catgets(3) and catclose(3) from any working directory.
Building for Cross-Hosted Use
-----------------------------
MinGW catgets may be built as a component of a cross-hosted compiler tool
chain; this is supported directly by the build system, when a `--target'
option differing from `--host' is specified at `configure' time.
To build as a cross tool, the cross-compiler suite must already have been
installed, and the `--target' option must be specified to match the prefix
used to identify, and invoke the cross-compiler itself. For example, this
is how I build it, for use with my GNU/Linux hosted i586-mingw32-gcc tool
chain, (which is identified by the prefix `i586-mingw32'):--
1) You may, if you wish, install GNU libiconv. However, your host may
already have a suitable iconv implementation, such as that provided by
glibc on GNU/Linux systems; if this is the case, it should suffice.
2) Create the working directory to host the source tree, as described in
steps (1) and (2) of the standard Win32 "In Place" build procedure.
3) Create a build directory, in which to progress the first stage of the
build, and make it your working directory...
mkdir mingw-catgets-<version>/build
cd mingw-catgets-<version>/build
4) Configure the build...
../configure [options ...] --prefix=<prefix> --target=i586-mingw32
As before, you may wish to review to options listed by...
../configure --help
and adjust any you consider to be appropriate; it is important that you
specify a <prefix> which matches the installation path of your cross
compiler tool chain, and that you set the --target to match the name of
your cross tools -- in my case, the cross compiler is i586-mingw32-gcc,
and the entire tool chain shares the i586-mingw32 target prefix.
5) Build and install the cross tool components...
make
make install
This results in building of the natively hosted tools, directly within
the build directory, together with the subset of the library components
which are needed to build these tools, and which are also compiled to
native object code. Additionally, in the cross-build subdirectory, the
appropriate target specific cross-compiler is invoked, to build the full
set of libraries, as they will be required when subsequently deploying
the cross-tools to create applications for the target platform.
On successful completion of this cross-tools build, the cross-tools and
the supporting cross-compiled libraries are installed into the prefix,
directory, as specified in the configure command; at installation time,
the names of the executable cross-tool programs are qualified by the
addition of a program name prefix, to match the specified target.
6) Install documentation...
As in the case of the natively built tool chain, step (5) does not
install the man pages which accompany the package. These may be
separately installed by issuing the command...
make install-man
In this case, the installed man pages retain the same basic names as
used in the natively compiled case. If preferred, the man pages may
be installed into an existing MANPATH directory, and distinguished
their similarly named native counterparts, by in the first instance
configuring with an explicit `--mandir=...' option, and then adding
a target specific man page name prefix, such as...
make man_prefix=i586-mingw32- install-man
7) Note that step (5) builds only the cross-compiled library components,
which are the minimum required to support deployment of the cross-tools
into an existing cross-compiler tool chain; in particular, it does not
create a tool chain for eventual deployment on the target platform. If
this is required, it may be prepared and packaged, without separate
configuration, by completing the partial build which has already
been initiated in the cross-build subdirectory...
cd cross-build
make && make bindist devdist
Linking MinGW Applications to use Message Catalogues
----------------------------------------------------
This package provides POSIX conformant national language support for
MinGW applications. Such support is added through calls to the POSIX
standard `catopen', `catgets' and `catclose' functions, as described
in the accompanying `man' pages. References to these functions are
resolved by addition of the `-lcatgets' option to the command line,
when linking the application; both static and dynamically linked
variants of the associated library are provided.
Preparing the Message Catalogues
--------------------------------
Message catalogues, for use with the MinGW `catgets' implementation,
are compiled using a POSIX conforming `gencat' tool; (when deployed as
a component of a cross-hosted tool chain, this tool is named so as to
maintain consistency with the cross-compiler naming convention; thus
when the cross-compiler is built for, say, an i586-mingw32 target,
invoked as i586-mingw32-gcc for example, then gencat would be
consistently invoked as i586-mingw32-gencat.
The command syntax, and the syntax for its message definition source
files, is described in the accompanying `gencat' man page.
$RCSfile$: end of file