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