The maintainer of a package has many responsibilities. One of them is ensuring that the package will install easily on many platforms, and that the magic we described earlier (see section 9 The User's View) will work for installers and end users.
Of course, there are many possible ways by which GNU
gettext
might be integrated in a distribution, and
this chapter does not cover them in all generality. Instead, it
details one possible approach which is especially adequate for many
free software distributions following GNU standards, or even
better, Gnits standards, because GNU gettext
is
purposely for helping the internationalization of the whole GNU
project, and as many other good free packages as possible. So, the
maintainer's view presented here presumes that the package already
has a `configure.in´ file and uses GNU Autoconf.
Nevertheless, GNU gettext
may surely be useful for
free packages not following GNU standards and conventions, but the
maintainers of such packages might have to show imagination and
initiative in organizing their distributions so
gettext
work for them in all situations. There are
surely many, out there.
Even if gettext
methods are now stabilizing, slight
adjustments might be needed between successive gettext
versions, so you should ideally revise this chapter in subsequent
releases, looking for changes.
Some free software packages are distributed as tar
files which unpack in a single directory, these are said to be
flat distributions. Other free software packages have a
one level hierarchy of subdirectories, using for example a
subdirectory named `doc/´ for the Texinfo manual and
man pages, another called `lib/´ for holding
functions meant to replace or complement C libraries, and a
subdirectory `src/´ for holding the proper sources
for the package. These other distributions are said to be
non-flat.
We cannot say much about flat distributions. A flat directory
structure has the disadvantage of increasing the difficulty of
updating to a new version of GNU gettext
. Also, if you
have many PO files, this could somewhat pollute your single
directory. Also, GNU gettext
's libintl sources consist
of C sources, shell scripts, sed
scripts and
complicated Makefile rules, which don't fit well into an existing
flat structure. For these reasons, we recommend to use non-flat
approach in this case as well.
Maybe because GNU gettext
itself has a non-flat
structure, we have more experience with this approach, and this is
what will be described in the remaining of this chapter. Some
maintainers might use this as an opportunity to unflatten their
package structure.
There are some works which are required for using GNU
gettext
in one of your package. These works have some
kind of generality that escape the point by point descriptions used
in the remainder of this chapter. So, we describe them here.
gettextize
you should
install some other packages first. Ensure that recent versions of
GNU m4
, GNU Autoconf and GNU gettext
are
already installed at your site, and if not, proceed to do this
first. If you get to install these things, beware that GNU
m4
must be fully installed before GNU Autoconf is even
configured. To further ease the task of a package
maintainer the automake
package was designed and
implemented. GNU gettext
now uses this tool and the
`Makefile´s in the `intl/´ and
`po/´ therefore know about all the goals necessary
for using automake
and `libintl´ in one
project. Those four packages are only needed by you, as a
maintainer; the installers of your own package and end users do not
really need any of GNU m4
, GNU Autoconf, GNU
gettext
, or GNU automake
for successfully
installing and running your package, with messages properly
translated. But this is not completely true if you provide
internationalized shell scripts within your own package: GNU
gettext
shall then be installed at the user site if
the end users want to see the translation of shell script
messages.It is worth adding here a few words about how the maintainer should ideally behave with PO files submissions. As a maintainer, your role is to authenticate the origin of the submission as being the representative of the appropriate translating teams of the Translation Project (forward the submission to `translation@iro.umontreal.ca´ in case of doubt), to ensure that the PO file format is not severely broken and does not prevent successful installation, and for the rest, to merely put these PO files in `po/´ for distribution.
As a maintainer, you do not have to take on your shoulders the responsibility of checking if the translations are adequate or complete, and should avoid diving into linguistic matters. Translation teams drive themselves and are fully responsible of their linguistic choices for the Translation Project. Keep in mind that translator teams are not driven by maintainers. You can help by carefully redirecting all communications and reports from users about linguistic matters to the appropriate translation team, or explain users how to reach or join their team. The simplest might be to send them the `ABOUT-NLS´ file.
Maintainers should never ever apply PO file bug reports themselves, short-cutting translation teams. If some translator has difficulty to get some of her points through her team, it should not be an option for her to directly negotiate translations with maintainers. Teams ought to settle their problems themselves, if any. If you, as a maintainer, ever think there is a real problem with a team, please never try to solve a team's problem on your own.
gettextize
ProgramThe gettextize
program is an interactive tool that
helps the maintainer of a package internationalized through GNU
gettext
. It is used for two purposes:
gettext
for the first time.gettext
support in a package from a previous to a newer version of GNU
gettext
.This program performs the following tasks:
gettext
.gettext
versions to the form recommended for the
current GNU gettext
version.gettextize
.It can be invoked as follows:
gettextize [ option... ] [ directory ]
and accepts the following options:
gettext
code available on the system, but it might
disturb some mechanism the maintainer is used to apply to the
sources. Because running gettextize
is easy there
shouldn't be problems with using copies.AM_GNU_GETTEXT
in `configure.in´ should
read: `AM_GNU_GETTEXT([external])´, and
internationalization will not be enabled on systems lacking GNU
gettext.gettextize
logs all
changes (file additions, modifications and removals) in a file
called `ChangeLog´ in each affected
directory.gettextize
would normally execute are
inhibited and instead only listed on standard output.If directory is given, this is the top level
directory of a package to prepare for using GNU
gettext
. If not given, it is assumed that the current
directory is the top level directory of such a package.
The program gettextize
provides the following
files. However, no existing file will be replaced unless the option
--force
(-f
) is specified.
gettextize
, if you have
one handy. You may also fetch a more recent copy of file
`ABOUT-NLS´ from Translation Project sites, and from
most GNU archive sites.gettext
distribution (beware the double
`.in´ in the file name) and a few auxiliary
files. If the `po/´ directory already exists, it will
be preserved along with the files it contains, and only
`Makefile.in.in´ and the auxiliary files will be
overwritten.gettext
distribution. Also, if option
--force
(-f
) is given, the
`intl/´ directory is emptied first.AM_GNU_GETTEXT
autoconf macro.automake
: A set
of autoconf
macro files is copied into the package's
autoconf
macro repository, usually in a directory
called `m4/´.If your site support symbolic links, gettextize
will not actually copy the files into your package, but establish
symbolic links instead. This avoids duplicating the disk space
needed in all packages. Merely using the `-h´
option while creating the tar
archive of your
distribution will resolve each link by an actual copy in the
distribution archive. So, to insist, you really should use
`-h´ option with tar
within your
dist
goal of your main
`Makefile.in´.
Furthermore, gettextize
will update all
`Makefile.am´ files in each affected directory, as
well as the top level `configure.in´ or
`configure.ac´ file.
It is interesting to understand that most new files for
supporting GNU gettext
facilities in one package go in
`intl/´, `po/´ and `m4/´
subdirectories. One distinction between `intl/´ and
the two other directories is that `intl/´ is meant to
be completely identical in all packages using GNU
gettext
, while the other directories will mostly
contain package dependent files.
The gettextize
program makes backup files for all
files it replaces or changes, and also write ChangeLog entries
about these changes. This way, the careful maintainer can check
after running gettextize
whether its changes are
acceptable to him, and possibly adjust them. An exception to this
rule is the `intl/´ directory, which is added or
replaced or removed as a whole.
It is important to understand that gettextize
can
not do the entire job of adapting a package for using GNU
gettext
. The amount of remaining work depends on
whether the package uses GNU automake
or not. But in
any case, the maintainer should still read the section section 12.4 Files You Must Create or
Alter after invoking gettextize
.
It is also important to understand that gettextize
is not part of the GNU build system, in the sense that it should
not be invoked automatically, and not be invoked by someone who
doesn't assume the responsibilities of a package maintainer. For
the latter purpose, a separate tool is provided, see section 12.6.3 Invoking the
autopoint
Program.
Besides files which are automatically added through
gettextize
, there are many files needing revision for
properly interacting with GNU gettext
. If you are
closely following GNU standards for Makefile engineering and
auto-configuration, the adaptations should be easier to achieve.
Here is a point by point description of the changes needed in
each.
So, here comes a list of files, each one followed by a
description of all alterations it needs. Many examples are taken
out from the GNU gettext
0.12.1 distribution itself,
or from the GNU hello
distribution (http://www.franken.de/users/gnu/ke/hello
or http://www.gnu.franken.de/ke/hello/)
You may indeed refer to the source code of the GNU
gettext
and GNU hello
packages, as they
are intended to be good examples for using GNU gettext
functionality.
The `po/´ directory should receive a file named `POTFILES.in´. This file tells which files, among all program sources, have marked strings needing translation. Here is an example of such a file:
# List of source files containing translatable strings. # Copyright (C) 1995 Free Software Foundation, Inc. # Common library files lib/error.c lib/getopt.c lib/xmalloc.c # Package source files src/gettext.c src/msgfmt.c src/xgettext.c
Hash-marked comments and white lines are ignored. All other lines list those source files containing strings marked for translation (see section 3.3 How Marks Appear in Sources), in a notation relative to the top level of your whole distribution, rather than the location of the `POTFILES.in´ file itself.
When a C file is automatically generated by a tool, like
flex
or bison
, that doesn't introduce
translatable strings by itself, it is recommended to list in
`po/POTFILES.in´ the real source file (ending in
`.l´ in the case of flex
, or in
`.y´ in the case of bison
), not the
generated C file.
The `po/´ directory should also receive a file named `LINGUAS´. This file contains the list of available translations. It is a whitespace separated list. Hash-marked comments and white lines are ignored. Here is an example file:
# Set of available languages. de fr
This example means that German and French PO files are
available, so that these languages are currently supported by your
package. If you want to further restrict, at installation time, the
set of installed languages, this should not be done by modifying
the `LINGUAS´ file, but rather by using the
LINGUAS
environment variable (see section 9.2 Magic for Installers).
It is recommended that you add the "languages"
`en@quot´ and `en@boldquot´ to
the LINGUAS
file. en@quot
is a variant of
English message catalogs (en
) which uses real
quotation marks instead of the ugly looking asymmetric ASCII
substitutes ``´ and `'´.
en@boldquot
is a variant of en@quot
that
additionally outputs quoted pieces of text in a bold font, when
used in a terminal emulator which supports the VT100 escape
sequences (such as xterm
or the Linux console, but not
Emacs in M-x shell mode).
These extra message catalogs `en@quot´ and
`en@boldquot´ are constructed automatically, not
by translators; to support them, you need the files
`Rules-quot´, `quot.sed´,
`boldquot.sed´, `en@quot.header´,
`en@boldquot.header´,
`insert-header.sin´ in the `po/´
directory. You can copy them from GNU gettext's `po/´
directory; they are also installed by running
gettextize
.
The `po/´ directory also has a file named `Makevars´. It can be left unmodified if your package has a single message domain and, accordingly, a single `po/´ directory. Only packages which have multiple `po/´ directories at different locations need to adjust the three variables defined in `Makevars´.
`po/Makevars´ gets inserted into the `po/Makefile´ when the latter is created. At the same time, all files called `Rules-*´ in the `po/´ directory get appended to the `po/Makefile´. They present an opportunity to add rules for special PO files to the Makefile, without needing to mess with `po/Makefile.in.in´.
GNU gettext comes with a
`Rules-quot´ file, containing rules for building
catalogs `en@quot.po´ and
`en@boldquot.po´. The effect of
`en@quot.po´ is that people who set their
LANGUAGE
environment variable to
`en@quot´ will get messages with proper looking
symmetric Unicode quotation marks instead of abusing the ASCII
grave accent and the ASCII apostrophe for indicating quotations. To
enable this catalog, simply add en@quot
to the
`po/LINGUAS´ file. The effect of
`en@boldquot.po´ is that people who set
LANGUAGE
to `en@boldquot´ will get
not only proper quotation marks, but also the quoted text will be
shown in a bold font on terminals and consoles. This catalog is
useful only for command-line programs, not GUI programs. To enable
it, similarly add en@boldquot
to the
`po/LINGUAS´ file.
`configure.in´ or `configure.ac´ -
this is the source from which autoconf
generates the
`configure´ script.
PACKAGE=gettext VERSION=0.12.1 AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE") AC_DEFINE_UNQUOTED(VERSION, "$VERSION") AC_SUBST(PACKAGE) AC_SUBST(VERSION)or, if you are using GNU
automake
, by a line like
this:
AM_INIT_AUTOMAKE(gettext, 0.12.1)Of course, you replace `gettext´ with the name of your package, and `0.12.1´ by its version numbers, exactly as they should appear in the packaged
tar
file name of your distribution
(`gettext-0.12.1.tar.gz´, here).m4
macro for triggering internationalization support.
Just add this line to `configure.in´:
AM_GNU_GETTEXTThis call is purposely simple, even if it generates a lot of configure time checking and actions. If you have suppressed the `intl/´ subdirectory by calling
gettextize
without `--intl´ option,
this call should read
AM_GNU_GETTEXT([external])
AC_OUTPUT
directive, at the end of your `configure.in´ file,
needs to be modified in two ways:
AC_OUTPUT([existing configuration files intl/Makefile po/Makefile.in], [existing additional actions])The modification to the first argument to
AC_OUTPUT
asks for substitution in the `intl/´ and
`po/´ directories. Note the `.in´
suffix used for `po/´ only. This is because the
distributed file is really `po/Makefile.in.in´. If
you have suppressed the `intl/´ subdirectory by
calling gettextize
without `--intl´
option, then you don't need to add intl/Makefile
to
the AC_OUTPUT
line.If you haven't suppressed the `intl/´ subdirectory, you need to add the GNU `config.guess´ and `config.sub´ files to your distribution. They are needed because the `intl/´ directory has platform dependent support for determining the locale's character encoding and therefore needs to identify the platform.
You can obtain the newest version of
`config.guess´ and `config.sub´ from
`ftp://ftp.gnu.org/pub/gnu/config/´. Less recent
versions are also contained in the GNU automake
and
GNU libtool
packages.
Normally, `config.guess´ and `config.sub´ are put at the top level of a distribution. But it is also possible to put them in a subdirectory, altogether with other configuration support files like `install-sh´, `ltconfig´, `ltmain.sh´, `mkinstalldirs´ or `missing´. All you need to do, other than moving the files, is to add the following line to your `configure.in´.
AC_CONFIG_AUX_DIR([subdir])
If gettextize
has not already done it, you need to
add the GNU `mkinstalldirs´ script to your
distribution. It is needed because `mkdir -p´ is
not portable enough. You find this script in the GNU
automake
distribution.
Normally, `mkinstalldirs´ is put at the top level of a distribution. But it is also possible to put it in a subdirectory, altogether with other configuration support files like `install-sh´, `ltconfig´, `ltmain.sh´ or `missing´. All you need to do, other than moving the files, is to add the following line to your `configure.in´.
AC_CONFIG_AUX_DIR([subdir])
If you do not have an `aclocal.m4´ file in your
distribution, the simplest is to concatenate the files
`codeset.m4´, `gettext.m4´,
`glibc21.m4´, `iconv.m4´,
`intdiv0.m4´, `inttypes.m4´,
`inttypes_h.m4´, `inttypes-pri.m4´,
`isc-posix.m4´, `lcmessage.m4´,
`lib-ld.m4´, `lib-link.m4´,
`lib-prefix.m4´, `progtest.m4´,
`stdint_h.m4´, `uintmax_t.m4´,
`ulonglong.m4´ from GNU gettext
's
`m4/´ directory into a single file. If you have
suppressed the `intl/´ directory, only
`gettext.m4´, `iconv.m4´,
`lib-ld.m4´, `lib-link.m4´,
`lib-prefix.m4´, `progtest.m4´ need to
be concatenated.
If you already have an `aclocal.m4´ file, then you
will have to merge the said macro files into your
`aclocal.m4´. Note that if you are upgrading from a
previous release of GNU gettext
, you should most
probably replace the macros (AM_GNU_GETTEXT
,
etc.), as they usually change a little from one release of GNU
gettext
to the next. Their contents may vary as we get
more experience with strange systems out there.
If you are using GNU automake
1.5 or newer, it is
enough to put these macro files into a subdirectory named
`m4/´ and add the line
ACLOCAL_AMFLAGS = -I m4
to your top level `Makefile.am´.
These macros check for the internationalization support
functions and related informations. Hopefully, once stabilized,
these macros might be integrated in the standard Autoconf set,
because this piece of m4
code will be the same for all
projects using GNU gettext
.
Earlier GNU gettext
releases required to put
definitions for ENABLE_NLS
, HAVE_GETTEXT
and HAVE_LC_MESSAGES
, HAVE_STPCPY
,
PACKAGE
and VERSION
into an
`acconfig.h´ file. This is not needed any more; you
can remove them from your `acconfig.h´ file unless
your package uses them independently from the `intl/´
directory.
The include file template that holds the C macros to be defined
by configure
is usually called
`config.h.in´ and may be maintained either manually
or automatically.
If it is maintained automatically, by use of the
`autoheader´ program, you need to do nothing
about it. This is the case in particular if you are using GNU
automake
.
If it is maintained manually, and if gettextize
has
created an `intl/´ directory, you should switch to
using `autoheader´. The list of C macros to be
added for the sake of the `intl/´ directory is just
too long to be maintained manually; it also changes between
different versions of GNU gettext
.
If it is maintained manually, and if on the other hand you have
suppressed the `intl/´ directory by calling
gettextize
without `--intl´ option,
then you can get away by adding the following lines to
`config.h.in´:
/* Define to 1 if translation of program messages to the user's native language is requested. */ #undef ENABLE_NLS
Here are a few modifications you need to make to your main, top-level `Makefile.in´ file.
PACKAGE = @PACKAGE@ VERSION = @VERSION@
DISTFILES
definition, so the file gets
distributed.SUBDIRS
in Makefile.in
for it to be
further used in the `dist:´ goal.
SUBDIRS = doc intl lib src poNote that you must arrange for `make´ to descend into the
intl
directory before descending into other
directories containing code which make use of the
libintl.h
header file. For this reason, here we
mention intl
before lib
and
src
.distdir = $(PACKAGE)-$(VERSION) dist: Makefile rm -fr $(distdir) mkdir $(distdir) chmod 777 $(distdir) for file in $(DISTFILES); do \ ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \ done for subdir in $(SUBDIRS); do \ mkdir $(distdir)/$$subdir || exit 1; \ chmod 777 $(distdir)/$$subdir; \ (cd $$subdir && $(MAKE) $@) || exit 1; \ done tar chozf $(distdir).tar.gz $(distdir) rm -fr $(distdir)
Note that if you are using GNU automake
,
`Makefile.in´ is automatically generated from
`Makefile.am´, and all needed changes to
`Makefile.am´ are already made by running
`gettextize´.
Some of the modifications made in the main `Makefile.in´ will also be needed in the `Makefile.in´ from your package sources, which we assume here to be in the `src/´ subdirectory. Here are all the modifications needed in `src/Makefile.in´:
PACKAGE = @PACKAGE@ VERSION = @VERSION@
top_srcdir
gets defined. This will serve for
cpp
include files. Just add the line:
top_srcdir = @top_srcdir@
subdir
as
`src´, later allowing for almost uniform
`dist:´ goals in all your
`Makefile.in´. At list, the `dist:´
goal below assume that you used:
subdir = src
main
function of your program will normally
call bindtextdomain
(see see section 3.1 Triggering gettext
Operations), like this:
bindtextdomain (PACKAGE, LOCALEDIR); textdomain (PACKAGE);To make LOCALEDIR known to the program, add the following lines to Makefile.in:
datadir = @datadir@ localedir = $(datadir)/locale DEFS = -DLOCALEDIR=\"$(localedir)\" @DEFS@Note that
@datadir@
defaults to
`$(prefix)/share´, thus $(localedir)
defaults to `$(prefix)/share/locale´.@LIBINTL@
or @LTLIBINTL@
as a library.
@LIBINTL@
is for use without libtool
,
@LTLIBINTL@
is for use with libtool
. An
easy way to achieve this is to manage that it gets into
LIBS
, like this:
LIBS = @LIBINTL@ @LIBS@In most packages internationalized with GNU
gettext
,
one will find a directory `lib/´ in which a library
containing some helper functions will be build. (You need at least
the few functions which the GNU gettext
Library itself
needs.) However some of the functions in the `lib/´
also give messages to the user which of course should be
translated, too. Taking care of this, the support library (say
`libsupport.a´) should be placed before
@LIBINTL@
and @LIBS@
in the above
example. So one has to write this:
LIBS = ../lib/libsupport.a @LIBINTL@ @LIBS@
distdir = ../$(PACKAGE)-$(VERSION)/$(subdir) dist: Makefile $(DISTFILES) for file in $(DISTFILES); do \ ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \ done
Internationalization of packages, as provided by GNU
gettext
, is optional. It can be turned off in two
situations:
intl/
subdirectory, and the libintl.h header (with its associated libintl
library, if any) is not already installed on the system, it is
preferrable that the package builds without internationalization
support, rather than to give a compilation error.A C preprocessor macro can be used to detect these two cases.
Usually, when libintl.h
was found and not explicitly
disabled, the ENABLE_NLS
macro will be defined to 1 in
the autoconf generated configuration file (usually called
`config.h´). In the two negative situations, however,
this macro will not be defined, thus it will evaluate to 0 in C
preprocessor expressions.
`gettext.h´ is a
convenience header file for conditional use of
`<libintl.h>´, depending on the
ENABLE_NLS
macro. If ENABLE_NLS
is set,
it includes `<libintl.h>´; otherwise it defines
no-op substitutes for the libintl.h functions. We recommend the use
of "gettext.h"
over direct use of
`<libintl.h>´, so that portability to older
systems is guaranteed and installers can turn off
internationalization if they want to. In the C code, you will then
write
#include "gettext.h"
instead of
#include <libintl.h>
The location of gettext.h
is usually in a directory
containing auxiliary include files. In many GNU packages, there is
a directory `lib/´ containing helper functions;
`gettext.h´ fits there. In other packages, it can go
into the `src´ directory.
Do not install the gettext.h
file in public
locations. Every package that needs it should contain a copy of it
on its own.
GNU gettext
installs macros for use in a package's
`configure.in´ or `configure.ac´. See
section `Introduction' in The Autoconf Manual. The
primary macro is, of course, AM_GNU_GETTEXT
.
The
AM_GNU_GETTEXT
macro tests for the presence of the GNU
gettext function family in either the C library or a separate
libintl
library (shared or static libraries are both
supported) or in the package's `intl/´ directory. It
also invokes AM_PO_SUBDIRS
, thus preparing the
`po/´ directories of the package for building.
AM_GNU_GETTEXT
accepts up to three optional
arguments. The general syntax is
AM_GNU_GETTEXT([intlsymbol], [needsymbol], [intldir])
intlsymbol can be `external´ or
`no-libtool´. The default (if it is not specified
or empty) is `no-libtool´. intlsymbol
should be `external´ for packages with no
`intl/´ directory, and `no-libtool´
for packages with an `intl/´ directory. In the latter
case, a static library $(top_builddir)/intl/libintl.a
will be created.
If needsymbol is specified and is
`need-ngettext´, then GNU gettext implementations
(in libc or libintl) without the ngettext()
function
will be ignored. If needsymbol is specified and is
`need-formatstring-macros´, then GNU gettext
implementations that don't support the ISO C 99
`<inttypes.h>´ formatstring macros will be
ignored. Only one needsymbol can be specified. To
specify more than one requirement, just specify the strongest one
among them. The hierarchy among the various alternatives is as
follows: `need-formatstring-macros´ implies
`need-ngettext´.
intldir is used to find the intl libraries. If empty, the value `$(top_builddir)/intl/´ is used.
The AM_GNU_GETTEXT
macro determines whether GNU
gettext is available and should be used. If so, it sets the
USE_NLS
variable to `yes´; it
defines ENABLE_NLS
to 1 in the autoconf generated
configuration file (usually called `config.h´); it
sets the variables LIBINTL
and LTLIBINTL
to the linker options for use in a Makefile (LIBINTL
for use without libtool, LTLIBINTL
for use with
libtool); it adds an `-I´ option to
CPPFLAGS
if necessary. In the negative case, it sets
USE_NLS
to `no´; it sets
LIBINTL
and LTLIBINTL
to empty and
doesn't change CPPFLAGS
.
The complexities that AM_GNU_GETTEXT
deals with are
the following:
gettext
in the C library, for example glibc. Some have
it in a separate library libintl
. GNU
libintl
might have been installed as part of the GNU
gettext
package.libintl
, if installed, is not necessarily
already in the search path (CPPFLAGS
for the include
file search path, LDFLAGS
for the library search
path).gettext
cannot exploit the GNU mo files, doesn't have
the necessary locale dependency features, and cannot convert
messages from the catalog's text encoding to the user's locale
encoding.libintl
, if installed, is not necessarily
already in the run time library search path. To avoid the need for
setting an environment variable like LD_LIBRARY_PATH
,
the macro adds the appropriate run time search path options to the
LIBINTL
and LTLIBINTL
variables. This
works on most systems, but not on some operating systems with
limited shared library support, like SCO.libintl
relies on POSIX/XSI
iconv
. The macro checks for linker options needed to
use iconv and appends them to the LIBINTL
and
LTLIBINTL
variables. The
AM_GNU_GETTEXT_VERSION
macro declares the version
number of the GNU gettext infrastructure that is used by the
package.
The use of this macro is optional; only the
autopoint
program makes use of it (see section 12.6 Integrating with CVS).
The AM_PO_SUBDIRS
macro prepares the `po/´ directories of the package
for building. This macro should be used in internationalized
programs written in other programming languages than C, C++,
Objective C, for example sh
, Python
,
Lisp
. See section 13
Other Programming Languages for a list of programming languages
that support localization through PO files.
The AM_PO_SUBDIRS
macro determines whether
internationalization should be used. If so, it sets the
USE_NLS
variable to `yes´, otherwise
to `no´. It also determines the right values for
Makefile variables in each `po/´ directory.
The AM_ICONV
macro tests for the presence of the POSIX/XSI iconv
function family in either the C library or a separate
libiconv
library. If found, it sets the
am_cv_func_iconv
variable to `yes´;
it defines HAVE_ICONV
to 1 in the autoconf generated
configuration file (usually called `config.h´); it
defines ICONV_CONST
to `const´ or to
empty, depending on whether the second argument of
iconv()
is of type `const char **´
or `char **´; it sets the variables
LIBICONV
and LTLIBICONV
to the linker
options for use in a Makefile (LIBICONV
for use
without libtool, LTLIBICONV
for use with libtool); it
adds an `-I´ option to CPPFLAGS
if
necessary. If not found, it sets LIBICONV
and
LTLIBICONV
to empty and doesn't change
CPPFLAGS
.
The complexities that AM_ICONV
deals with are the
following:
iconv
in the C library, for example glibc. Some have
it in a separate library libiconv
, for example OSF/1
or FreeBSD. Regardless of the operating system, GNU
libiconv
might have been installed. In that case, it
should be used instead of the operating system's native
iconv
.libiconv
, if installed, is not necessarily
already in the search path (CPPFLAGS
for the include
file search path, LDFLAGS
for the library search
path).libiconv
is binary incompatible with some
operating system's native iconv
, for example on
FreeBSD. Use of an `iconv.h´ and
`libiconv.so´ that don't fit together would produce
program crashes.libiconv
, if installed, is not necessarily
already in the run time library search path. To avoid the need for
setting an environment variable like LD_LIBRARY_PATH
,
the macro adds the appropriate run time search path options to the
LIBICONV
variable. This works on most systems, but not
on some operating systems with limited shared library support, like
SCO.`iconv.m4´ is distributed with the GNU gettext package because `gettext.m4´ relies on it.
Many projects use CVS for distributed development, version
control and source backup. This section gives some advice how to
manage the uses of cvs
, gettextize
,
autopoint
and autoconf
.
In a project development with multiple developers, using CVS,
there should be a single developer who occasionally - when there is
desire to upgrade to a new gettext
version - runs
gettextize
and performs the changes listed in section
12.4 Files You Must Create or
Alter, and then commits his changes to the CVS.
It is highly recommended that all developers on a project use
the same version of GNU gettext
in the package. In
other words, if a developer runs gettextize
, he should
go the whole way, make the necessary remaining changes and commit
his changes to the CVS. Otherwise the following damages will likely
occur:
gettext
specific portions in
`configure.in´, `configure.ac´ and
Makefile.am
, Makefile.in
files depend on
the gettext
version, the use of infrastructure files
belonging to different gettext
versions can easily
lead to build errors.gettext
than the other
developers, the distribution will be less well tested than if all
had been using the same gettext
version. For example,
it is possible that a platform specific bug goes undiscovered due
to this constellation.There are basically three ways to deal with generated files in
the context of a CVS repository, such as `configure´
generated from `configure.in´,
parser.c
generated from
parser.y
, or po/Makefile.in.in
autoinstalled by gettextize
or
autopoint
.
Each of these three approaches has different advantages and drawbacks.
automake
, GNU autoconf
, GNU
m4
installed in his PATH; sometimes he even needs
particular versions of them. 2b. When a release is made and a
commit is made on the generated files, the other developers get
conflicts on the generated files after doing "cvs update". Although
these conflicts are easy to resolve, they are annoying.automake
, GNU autoconf
, GNU
m4
installed in his PATH, but also that he needs to
perform a package specific pre-build step before being able to
"./configure; make".For the first and second approach, all files modified or brought
in by the occasional gettextize
invocation and update
should be committed into the CVS.
For the third approach, the maintainer can omit from the CVS
repository all the files that gettextize
mentions as
"copy". Instead, he adds to the `configure.in´ or
`configure.ac´ a line of the form
AM_GNU_GETTEXT_VERSION(0.12.1)
and adds to the package's pre-build script an invocation of
`autopoint´. For everyone who checks out the CVS,
this autopoint
invocation will copy into the right
place the gettext
infrastructure files that have been
omitted from the CVS.
autopoint
Programautopoint [option]...
The autopoint
program copies standard gettext
infrastructure files into a source package. It extracts from a
macro call of the form
AM_GNU_GETTEXT_VERSION(version)
, found in
the package's `configure.in´ or
`configure.ac´ file, the gettext version used by the
package, and copies the infrastructure files belonging to this
version into the package.
autopoint
would normally
execute are inhibited and instead only listed on standard
output.autopoint
supports the GNU gettext
versions from 0.10.35 to the current one, 0.12.1. In order to apply
autopoint
to a package using a gettext
version newer than 0.12.1, you need to install this same version of
GNU gettext
at least.
In packages using GNU automake
, an invocation of
autopoint
should be followed by invocations of
aclocal
and then autoconf
and
autoheader
. The reason is that autopoint
installs some autoconf macro files, which are used by
aclocal
to create `aclocal.m4´, and the
latter is used by autoconf
to create the package's
`configure´ script and by autoheader
to
create the package's `config.h.in´ include file
template.
The name `autopoint´ is an abbreviation of `auto-po-intl-m4´; the tool copies or updates mostly files in the `po´, `intl´, `m4´ directories.
Go to the first, previous, next, last section, table of contents.