jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: GNU gettext utilities: 13. The Maintainer's View jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:
[ << ][ >> ]           [Top][Contents][Index][ ? ]
jpayne@68: jpayne@68:
jpayne@68: jpayne@68: jpayne@68:

13. The Maintainer's View

jpayne@68: jpayne@68:

The maintainer of a package has many responsibilities. One of them jpayne@68: is ensuring that the package will install easily on many platforms, jpayne@68: and that the magic we described earlier (see section The User's View) will work jpayne@68: for installers and end users. jpayne@68:

jpayne@68:

Of course, there are many possible ways by which GNU gettext jpayne@68: might be integrated in a distribution, and this chapter does not cover jpayne@68: them in all generality. Instead, it details one possible approach which jpayne@68: is especially adequate for many free software distributions following GNU jpayne@68: standards, or even better, Gnits standards, because GNU gettext jpayne@68: is purposely for helping the internationalization of the whole GNU jpayne@68: project, and as many other good free packages as possible. So, the jpayne@68: maintainer's view presented here presumes that the package already has jpayne@68: a ‘configure.ac’ file and uses GNU Autoconf. jpayne@68:

jpayne@68:

Nevertheless, GNU gettext may surely be useful for free packages jpayne@68: not following GNU standards and conventions, but the maintainers of such jpayne@68: packages might have to show imagination and initiative in organizing jpayne@68: their distributions so gettext work for them in all situations. jpayne@68: There are surely many, out there. jpayne@68:

jpayne@68:

Even if gettext methods are now stabilizing, slight adjustments jpayne@68: might be needed between successive gettext versions, so you jpayne@68: should ideally revise this chapter in subsequent releases, looking jpayne@68: for changes. jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.1 Flat or Non-Flat Directory Structures

jpayne@68: jpayne@68:

Some free software packages are distributed as tar files which unpack jpayne@68: in a single directory, these are said to be flat distributions. jpayne@68: Other free software packages have a one level hierarchy of subdirectories, using jpayne@68: for example a subdirectory named ‘doc/’ for the Texinfo manual and jpayne@68: man pages, another called ‘lib/’ for holding functions meant to jpayne@68: replace or complement C libraries, and a subdirectory ‘src/’ for jpayne@68: holding the proper sources for the package. These other distributions jpayne@68: are said to be non-flat. jpayne@68:

jpayne@68:

We cannot say much about flat distributions. A flat jpayne@68: directory structure has the disadvantage of increasing the difficulty jpayne@68: of updating to a new version of GNU gettext. Also, if you have jpayne@68: many PO files, this could somewhat pollute your single directory. jpayne@68: Also, GNU gettext's libintl sources consist of C sources, shell jpayne@68: scripts, sed scripts and complicated Makefile rules, which don't jpayne@68: fit well into an existing flat structure. For these reasons, we jpayne@68: recommend to use non-flat approach in this case as well. jpayne@68:

jpayne@68:

Maybe because GNU gettext itself has a non-flat structure, jpayne@68: we have more experience with this approach, and this is what will be jpayne@68: described in the remaining of this chapter. Some maintainers might jpayne@68: use this as an opportunity to unflatten their package structure. jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.2 Prerequisite Works

jpayne@68: jpayne@68:

There are some works which are required for using GNU gettext jpayne@68: in one of your package. These works have some kind of generality jpayne@68: that escape the point by point descriptions used in the remainder jpayne@68: of this chapter. So, we describe them here. jpayne@68:

jpayne@68: jpayne@68: jpayne@68:

It is worth adding here a few words about how the maintainer should jpayne@68: ideally behave with PO files submissions. As a maintainer, your role is jpayne@68: to authenticate the origin of the submission as being the representative jpayne@68: of the appropriate translating teams of the Translation Project (forward jpayne@68: the submission to ‘coordinator@translationproject.org’ in case of doubt), jpayne@68: to ensure that the PO file format is not severely broken and does not jpayne@68: prevent successful installation, and for the rest, to merely put these jpayne@68: PO files in ‘po/’ for distribution. jpayne@68:

jpayne@68:

As a maintainer, you do not have to take on your shoulders the jpayne@68: responsibility of checking if the translations are adequate or jpayne@68: complete, and should avoid diving into linguistic matters. Translation jpayne@68: teams drive themselves and are fully responsible of their linguistic jpayne@68: choices for the Translation Project. Keep in mind that translator teams are not jpayne@68: driven by maintainers. You can help by carefully redirecting all jpayne@68: communications and reports from users about linguistic matters to the jpayne@68: appropriate translation team, or explain users how to reach or join jpayne@68: their team. jpayne@68:

jpayne@68:

Maintainers should never ever apply PO file bug reports jpayne@68: themselves, short-cutting translation teams. If some translator has jpayne@68: difficulty to get some of her points through her team, it should not be jpayne@68: an option for her to directly negotiate translations with maintainers. jpayne@68: Teams ought to settle their problems themselves, if any. If you, as jpayne@68: a maintainer, ever think there is a real problem with a team, please jpayne@68: never try to solve a team's problem on your own. jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.3 Invoking the gettextize Program

jpayne@68: jpayne@68: jpayne@68:

The gettextize program is an interactive tool that helps the jpayne@68: maintainer of a package internationalized through GNU gettext. jpayne@68: It is used for two purposes: jpayne@68:

jpayne@68: jpayne@68: jpayne@68:

This program performs the following tasks: jpayne@68:

jpayne@68: jpayne@68: jpayne@68:

It can be invoked as follows: jpayne@68:

jpayne@68: jpayne@68: jpayne@68:
 
gettextize [ option… ] [ directory ]
jpayne@68: 
jpayne@68: jpayne@68:

and accepts the following options: jpayne@68:

jpayne@68:
jpayne@68:
-f
jpayne@68:
--force
jpayne@68:
jpayne@68: jpayne@68:

Force replacement of files which already exist. jpayne@68:

jpayne@68:
jpayne@68:
--po-dir=dir
jpayne@68:
jpayne@68:

Specify a directory containing PO files. Such a directory contains the jpayne@68: translations into various languages of a particular POT file. This jpayne@68: option can be specified multiple times, once for each translation domain. jpayne@68: If it is not specified, the directory named ‘po/’ is updated. jpayne@68:

jpayne@68:
jpayne@68:
--no-changelog
jpayne@68:
jpayne@68:

Don't update or create ChangeLog files. By default, gettextize jpayne@68: logs all changes (file additions, modifications and removals) in a jpayne@68: file called ‘ChangeLog’ in each affected directory. jpayne@68:

jpayne@68:
jpayne@68:
--symlink
jpayne@68:
jpayne@68:

Make symbolic links instead of copying the needed files. This can be jpayne@68: useful to save a few kilobytes of disk space, but it requires extra jpayne@68: effort to create self-contained tarballs, it may disturb some mechanism jpayne@68: the maintainer applies to the sources, and it is likely to introduce jpayne@68: bugs when a newer version of gettext is installed on the system. jpayne@68:

jpayne@68:
jpayne@68:
-n
jpayne@68:
--dry-run
jpayne@68:
jpayne@68: jpayne@68:

Print modifications but don't perform them. All actions that jpayne@68: gettextize would normally execute are inhibited and instead only jpayne@68: listed on standard output. jpayne@68:

jpayne@68:
jpayne@68:
--help
jpayne@68:
jpayne@68:

Display this help and exit. jpayne@68:

jpayne@68:
jpayne@68:
--version
jpayne@68:
jpayne@68:

Output version information and exit. jpayne@68:

jpayne@68:
jpayne@68:
jpayne@68: jpayne@68:

If directory is given, this is the top level directory of a jpayne@68: package to prepare for using GNU gettext. If not given, it jpayne@68: is assumed that the current directory is the top level directory of jpayne@68: such a package. jpayne@68:

jpayne@68:

The program gettextize provides the following files. However, jpayne@68: no existing file will be replaced unless the option --force jpayne@68: (-f) is specified. jpayne@68:

jpayne@68:
    jpayne@68:
  1. jpayne@68: The ‘ABOUT-NLS’ file is copied in the main directory of your package, jpayne@68: the one being at the top level. This file contains a reference to the jpayne@68: GNU gettext documentation. It also avoids an error from Automake in jpayne@68: packages that use the Automake option ‘gnu’ or ‘gnits’: jpayne@68: “error: required file './ABOUT-NLS' not found”. jpayne@68: jpayne@68:
  2. jpayne@68: A ‘po/’ directory is created for eventually holding jpayne@68: all translation files, but initially only containing the file jpayne@68: ‘po/Makefile.in.in’ from the GNU gettext distribution jpayne@68: (beware the double ‘.in’ in the file name) and a few auxiliary jpayne@68: files. If the ‘po/’ directory already exists, it will be preserved jpayne@68: along with the files it contains, and only ‘Makefile.in.in’ and jpayne@68: the auxiliary files will be overwritten. jpayne@68: jpayne@68:

    If ‘--po-dir’ has been specified, this holds for every directory jpayne@68: specified through ‘--po-dir’, instead of ‘po/’. jpayne@68:

    jpayne@68:
  3. jpayne@68: The file ‘config.rpath’ is copied into the directory containing jpayne@68: configuration support files. It is needed by the AM_GNU_GETTEXT jpayne@68: autoconf macro. jpayne@68: jpayne@68:
  4. jpayne@68: Only if the project is using GNU automake: jpayne@68: A set of autoconf macro files is copied into the package's jpayne@68: autoconf macro repository, usually in a directory called ‘m4/’. jpayne@68:
jpayne@68: jpayne@68:

If your site support symbolic links, gettextize will not jpayne@68: actually copy the files into your package, but establish symbolic jpayne@68: links instead. This avoids duplicating the disk space needed in jpayne@68: all packages. Merely using the ‘-h’ option while creating the jpayne@68: tar archive of your distribution will resolve each link by an jpayne@68: actual copy in the distribution archive. So, to insist, you really jpayne@68: should use ‘-h’ option with tar within your dist jpayne@68: goal of your main ‘Makefile.in’. jpayne@68:

jpayne@68:

Furthermore, gettextize will update all ‘Makefile.am’ files jpayne@68: in each affected directory, as well as the top level ‘configure.ac’ jpayne@68: or ‘configure.in’ file. jpayne@68:

jpayne@68:

It is interesting to understand that most new files for supporting jpayne@68: GNU gettext facilities in one package go in ‘po/’ and jpayne@68: ‘m4/’ subdirectories. Still, these directories will mostly jpayne@68: contain package dependent files. jpayne@68:

jpayne@68:

The gettextize program makes backup files for all files it jpayne@68: replaces or changes, and also write ChangeLog entries about these jpayne@68: changes. This way, the careful maintainer can check after running jpayne@68: gettextize whether its changes are acceptable to him, and jpayne@68: possibly adjust them. An exception to this rule is the ‘intl/’ jpayne@68: directory, which is removed as a whole if it still existed. jpayne@68:

jpayne@68:

It is important to understand that gettextize can not do the jpayne@68: entire job of adapting a package for using GNU gettext. The jpayne@68: amount of remaining work depends on whether the package uses GNU jpayne@68: automake or not. But in any case, the maintainer should still jpayne@68: read the section Files You Must Create or Alter after invoking gettextize. jpayne@68:

jpayne@68:

In particular, if after using ‘gettexize’, you get an error jpayne@68: ‘AC_COMPILE_IFELSE was called before AC_GNU_SOURCE’ or jpayne@68: ‘AC_RUN_IFELSE was called before AC_GNU_SOURCE’, you can fix it jpayne@68: by modifying ‘configure.ac’, as described in configure.ac’ at top level. jpayne@68:

jpayne@68:

It is also important to understand that gettextize is not part jpayne@68: of the GNU build system, in the sense that it should not be invoked jpayne@68: automatically, and not be invoked by someone who doesn't assume the jpayne@68: responsibilities of a package maintainer. For the latter purpose, a jpayne@68: separate tool is provided, see Invoking the autopoint Program. jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.4 Files You Must Create or Alter

jpayne@68: jpayne@68:

Besides files which are automatically added through gettextize, jpayne@68: there are many files needing revision for properly interacting with jpayne@68: GNU gettext. If you are closely following GNU standards for jpayne@68: Makefile engineering and auto-configuration, the adaptations should jpayne@68: be easier to achieve. Here is a point by point description of the jpayne@68: changes needed in each. jpayne@68:

jpayne@68:

So, here comes a list of files, each one followed by a description of jpayne@68: all alterations it needs. Many examples are taken out from the GNU jpayne@68: gettext 0.22.5 distribution itself, or from the GNU jpayne@68: hello distribution (https://www.gnu.org/software/hello). jpayne@68: You may indeed refer to the source code of the GNU gettext and jpayne@68: GNU hello packages, as they are intended to be good examples for jpayne@68: using GNU gettext functionality. jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.4.1 ‘POTFILES.in’ in ‘po/

jpayne@68: jpayne@68:

The ‘po/’ directory should receive a file named jpayne@68: ‘POTFILES.in’. This file tells which files, among all program jpayne@68: sources, have marked strings needing translation. Here is an example jpayne@68: of such a file: jpayne@68:

jpayne@68:
 
# List of source files containing translatable strings.
jpayne@68: # Copyright (C) 1995 Free Software Foundation, Inc.
jpayne@68: 
jpayne@68: # Common library files
jpayne@68: lib/error.c
jpayne@68: lib/getopt.c
jpayne@68: lib/xmalloc.c
jpayne@68: 
jpayne@68: # Package source files
jpayne@68: src/gettext.c
jpayne@68: src/msgfmt.c
jpayne@68: src/xgettext.c
jpayne@68: 
jpayne@68: jpayne@68:

Hash-marked comments and white lines are ignored. All other lines jpayne@68: list those source files containing strings marked for translation jpayne@68: (see section How Marks Appear in Sources), in a notation relative to the top level jpayne@68: of your whole distribution, rather than the location of the jpayne@68: ‘POTFILES.in’ file itself. jpayne@68:

jpayne@68:

When a C file is automatically generated by a tool, like flex or jpayne@68: bison, that doesn't introduce translatable strings by itself, jpayne@68: it is recommended to list in ‘po/POTFILES.in’ the real source file jpayne@68: (ending in ‘.l’ in the case of flex, or in ‘.y’ in the jpayne@68: case of bison), not the generated C file. jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.4.2 ‘LINGUAS’ in ‘po/

jpayne@68: jpayne@68:

The ‘po/’ directory should also receive a file named jpayne@68: ‘LINGUAS’. This file contains the list of available translations. jpayne@68: It is a whitespace separated list. Hash-marked comments and white lines jpayne@68: are ignored. Here is an example file: jpayne@68:

jpayne@68:
 
# Set of available languages.
jpayne@68: de fr
jpayne@68: 
jpayne@68: jpayne@68:

This example means that German and French PO files are available, so jpayne@68: that these languages are currently supported by your package. If you jpayne@68: want to further restrict, at installation time, the set of installed jpayne@68: languages, this should not be done by modifying the ‘LINGUAS’ file, jpayne@68: but rather by using the LINGUAS environment variable jpayne@68: (see section The Installer's and Distributor's View). jpayne@68:

jpayne@68:

It is recommended that you add the "languages" ‘en@quot’ and jpayne@68: ‘en@boldquot’ to the LINGUAS file. en@quot is a jpayne@68: variant of English message catalogs (en) which uses real quotation jpayne@68: marks instead of the ugly looking asymmetric ASCII substitutes ‘`’ jpayne@68: and ‘'’. en@boldquot is a variant of en@quot that jpayne@68: additionally outputs quoted pieces of text in a bold font, when used in jpayne@68: a terminal emulator which supports the VT100 escape sequences (such as jpayne@68: xterm or the Linux console, but not Emacs in M-x shell mode). jpayne@68:

jpayne@68:

These extra message catalogs ‘en@quot’ and ‘en@boldquot’ jpayne@68: are constructed automatically, not by translators; to support them, you jpayne@68: need the files ‘Rules-quot’, ‘quot.sed’, ‘boldquot.sed’, jpayne@68: ‘en@quot.header’, ‘en@boldquot.header’, ‘insert-header.sin’ jpayne@68: in the ‘po/’ directory. You can copy them from GNU gettext's ‘po/’ jpayne@68: directory; they are also installed by running gettextize. jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.4.3 ‘Makevars’ in ‘po/

jpayne@68: jpayne@68:

The ‘po/’ directory also has a file named ‘Makevars’. It jpayne@68: contains variables that are specific to your project. ‘po/Makevars’ jpayne@68: gets inserted into the ‘po/Makefile’ when the latter is created. jpayne@68: The variables thus take effect when the POT file is created or updated, jpayne@68: and when the message catalogs get installed. jpayne@68:

jpayne@68:

The first three variables can be left unmodified if your package has a jpayne@68: single message domain and, accordingly, a single ‘po/’ directory. jpayne@68: Only packages which have multiple ‘po/’ directories at different jpayne@68: locations need to adjust the three first variables defined in jpayne@68: ‘Makevars’. jpayne@68:

jpayne@68:

As an alternative to the XGETTEXT_OPTIONS variable, it is also jpayne@68: possible to specify xgettext options through the jpayne@68: AM_XGETTEXT_OPTION autoconf macro. See AM_XGETTEXT_OPTION in ‘po.m4. jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.4.4 Extending ‘Makefile’ in ‘po/

jpayne@68: jpayne@68:

All files called ‘Rules-*’ in the ‘po/’ directory get appended to jpayne@68: the ‘po/Makefile’ when it is created. They present an opportunity to jpayne@68: add rules for special PO files to the Makefile, without needing to mess jpayne@68: with ‘po/Makefile.in.in’. jpayne@68:

jpayne@68: jpayne@68: jpayne@68:

GNU gettext comes with a ‘Rules-quot’ file, containing rules for jpayne@68: building catalogs ‘en@quot.po’ and ‘en@boldquot.po’. The jpayne@68: effect of ‘en@quot.po’ is that people who set their LANGUAGE jpayne@68: environment variable to ‘en@quot’ will get messages with proper jpayne@68: looking symmetric Unicode quotation marks instead of abusing the ASCII jpayne@68: grave accent and the ASCII apostrophe for indicating quotations. To jpayne@68: enable this catalog, simply add en@quot to the ‘po/LINGUAS’ jpayne@68: file. The effect of ‘en@boldquot.po’ is that people who set jpayne@68: LANGUAGE to ‘en@boldquot’ will get not only proper quotation jpayne@68: marks, but also the quoted text will be shown in a bold font on terminals jpayne@68: and consoles. This catalog is useful only for command-line programs, not jpayne@68: GUI programs. To enable it, similarly add en@boldquot to the jpayne@68: ‘po/LINGUAS’ file. jpayne@68:

jpayne@68:

Similarly, you can create rules for building message catalogs for the jpayne@68: ‘sr@latin’ locale – Serbian written with the Latin alphabet – jpayne@68: from those for the ‘sr’ locale – Serbian written with Cyrillic jpayne@68: letters. See Invoking the msgfilter Program. jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.4.5 ‘configure.ac’ at top level

jpayne@68: jpayne@68:

configure.ac’ or ‘configure.in’ - this is the source from which jpayne@68: autoconf generates the ‘configure’ script. jpayne@68:

jpayne@68:
    jpayne@68:
  1. Declare the package and version. jpayne@68: jpayne@68: jpayne@68:

    This is done by a set of lines like these: jpayne@68:

    jpayne@68:
     
    PACKAGE=gettext
    jpayne@68: VERSION=0.22.5
    jpayne@68: AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE")
    jpayne@68: AC_DEFINE_UNQUOTED(VERSION, "$VERSION")
    jpayne@68: AC_SUBST(PACKAGE)
    jpayne@68: AC_SUBST(VERSION)
    jpayne@68: 
    jpayne@68: jpayne@68:

    or, if you are using GNU automake, by a line like this: jpayne@68:

    jpayne@68:
     
    AM_INIT_AUTOMAKE(gettext, 0.22.5)
    jpayne@68: 
    jpayne@68: jpayne@68:

    Of course, you replace ‘gettext’ with the name of your package, jpayne@68: and ‘0.22.5’ by its version numbers, exactly as they jpayne@68: should appear in the packaged tar file name of your distribution jpayne@68: (‘gettext-0.22.5.tar.gz’, here). jpayne@68:

    jpayne@68:
  2. Check for internationalization support. jpayne@68: jpayne@68:

    Here is the main m4 macro for triggering internationalization jpayne@68: support. Just add this line to ‘configure.ac’: jpayne@68:

    jpayne@68:
     
    AM_GNU_GETTEXT([external])
    jpayne@68: 
    jpayne@68: jpayne@68:

    This call is purposely simple, even if it generates a lot of configure jpayne@68: time checking and actions. jpayne@68:

    jpayne@68:
  3. Have output files created. jpayne@68: jpayne@68:

    The AC_OUTPUT directive, at the end of your ‘configure.ac’ jpayne@68: file, needs to be modified in two ways: jpayne@68:

    jpayne@68:
     
    AC_OUTPUT([existing configuration files po/Makefile.in],
    jpayne@68: [existing additional actions])
    jpayne@68: 
    jpayne@68: jpayne@68:

    The modification to the first argument to AC_OUTPUT asks jpayne@68: for substitution in the ‘po/’ directory. jpayne@68: Note the ‘.in’ suffix used for ‘po/’ only. This is because jpayne@68: the distributed file is really ‘po/Makefile.in.in’. jpayne@68:

    jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.4.6 ‘config.guess’, ‘config.sub’ at top level

jpayne@68: jpayne@68:

You need to add the GNU ‘config.guess’ and ‘config.sub’ files jpayne@68: to your distribution. They are needed because the AM_ICONV macro jpayne@68: contains knowledge about specific platforms and therefore needs to jpayne@68: identify the platform. jpayne@68:

jpayne@68:

You can obtain the newest version of ‘config.guess’ and jpayne@68: ‘config.sub’ from the ‘config’ project at jpayne@68: ‘https://savannah.gnu.org/’. The commands to fetch them are jpayne@68:

 
$ wget -O config.guess 'https://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD'
jpayne@68: $ wget -O config.sub 'https://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.sub;hb=HEAD'
jpayne@68: 
jpayne@68:

Less recent versions are also contained in the GNU automake and jpayne@68: GNU libtool packages. jpayne@68:

jpayne@68:

Normally, ‘config.guess’ and ‘config.sub’ are put at the jpayne@68: top level of a distribution. But it is also possible to put them in a jpayne@68: subdirectory, altogether with other configuration support files like jpayne@68: ‘install-sh’, ‘ltconfig’, ‘ltmain.sh’ or ‘missing’. jpayne@68: All you need to do, other than moving the files, is to add the following line jpayne@68: to your ‘configure.ac’. jpayne@68:

jpayne@68:
 
AC_CONFIG_AUX_DIR([subdir])
jpayne@68: 
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.4.7 ‘mkinstalldirs’ at top level

jpayne@68: jpayne@68:

With earlier versions of GNU gettext, you needed to add the GNU jpayne@68: ‘mkinstalldirs’ script to your distribution. This is not needed any jpayne@68: more. You can remove it. jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.4.8 ‘aclocal.m4’ at top level

jpayne@68: jpayne@68:

If you do not have an ‘aclocal.m4’ file in your distribution, jpayne@68: the simplest is to concatenate the files ‘build-to-host.m4’, jpayne@68: ‘gettext.m4’, ‘host-cpu-c-abi.m4’, ‘intlmacosx.m4’, jpayne@68: ‘iconv.m4’, ‘lib-ld.m4’, ‘lib-link.m4’, ‘lib-prefix.m4’, jpayne@68: ‘nls.m4’, ‘po.m4’, ‘progtest.m4’ from GNU gettext's jpayne@68: ‘m4/’ directory into a single file. jpayne@68:

jpayne@68:

If you already have an ‘aclocal.m4’ file, then you will have jpayne@68: to merge the said macro files into your ‘aclocal.m4’. Note that if jpayne@68: you are upgrading from a previous release of GNU gettext, you jpayne@68: should most probably replace the macros (AM_GNU_GETTEXT, jpayne@68: etc.), as they usually jpayne@68: change a little from one release of GNU gettext to the next. jpayne@68: Their contents may vary as we get more experience with strange systems jpayne@68: out there. jpayne@68:

jpayne@68:

You should be using GNU automake 1.9 or newer. With it, you need jpayne@68: to copy the files ‘build-to-host.m4’, ‘gettext.m4’, jpayne@68: ‘host-cpu-c-abi.m4’, ‘intlmacosx.m4’, ‘iconv.m4’, jpayne@68: ‘lib-ld.m4’, ‘lib-link.m4’, ‘lib-prefix.m4’, ‘nls.m4’, jpayne@68: ‘po.m4’, ‘progtest.m4’ from GNU gettext's ‘m4/’ jpayne@68: directory to a subdirectory named ‘m4/’ and add the line jpayne@68:

jpayne@68:
 
ACLOCAL_AMFLAGS = -I m4
jpayne@68: 
jpayne@68: jpayne@68:

to your top level ‘Makefile.am’. jpayne@68:

jpayne@68:

If you are using GNU automake 1.10 or newer, it is even easier: jpayne@68: Add the line jpayne@68:

jpayne@68:
 
ACLOCAL_AMFLAGS = --install -I m4
jpayne@68: 
jpayne@68: jpayne@68:

to your top level ‘Makefile.am’, and run ‘aclocal --install -I m4’. jpayne@68: This will copy the needed files to the ‘m4/’ subdirectory automatically, jpayne@68: before updating ‘aclocal.m4’. jpayne@68:

jpayne@68:

These macros check for the internationalization support functions jpayne@68: and related informations. Hopefully, once stabilized, these macros jpayne@68: might be integrated in the standard Autoconf set, because this jpayne@68: piece of m4 code will be the same for all projects using GNU jpayne@68: gettext. jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.4.9 ‘config.h.in’ at top level

jpayne@68: jpayne@68:

The include file template that holds the C macros to be defined by jpayne@68: configure is usually called ‘config.h.in’ and may be jpayne@68: maintained either manually or automatically. jpayne@68:

jpayne@68:

If it is maintained automatically, by use of the ‘autoheader’ jpayne@68: program, you need to do nothing about it. This is the case in particular jpayne@68: if you are using GNU automake. jpayne@68:

jpayne@68:

If it is maintained manually, you can get away by adding the jpayne@68: following lines to ‘config.h.in’: jpayne@68:

jpayne@68:
 
/* Define to 1 if translation of program messages to the user's
jpayne@68:    native language is requested. */
jpayne@68: #undef ENABLE_NLS
jpayne@68: 
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.4.10 ‘Makefile.in’ at top level

jpayne@68: jpayne@68:

Here are a few modifications you need to make to your main, top-level jpayne@68: ‘Makefile.in’ file. jpayne@68:

jpayne@68:
    jpayne@68:
  1. jpayne@68: Add the following lines near the beginning of your ‘Makefile.in’, jpayne@68: so the ‘dist:’ goal will work properly (as explained further down): jpayne@68: jpayne@68:
     
    PACKAGE = @PACKAGE@
    jpayne@68: VERSION = @VERSION@
    jpayne@68: 
    jpayne@68: jpayne@68:
  2. jpayne@68: Wherever you process subdirectories in your ‘Makefile.in’, be sure jpayne@68: you also process the subdirectory ‘po’. Special jpayne@68: rules in the ‘Makefiles’ take care for the case where no jpayne@68: internationalization is wanted. jpayne@68: jpayne@68:

    If you are using Makefiles, either generated by automake, or hand-written jpayne@68: so they carefully follow the GNU coding standards, the effected goals for jpayne@68: which the new subdirectories must be handled include ‘installdirs’, jpayne@68: ‘install’, ‘uninstall’, ‘clean’, ‘distclean’. jpayne@68:

    jpayne@68:

    Here is an example of a canonical order of processing. In this jpayne@68: example, we also define SUBDIRS in Makefile.in for it jpayne@68: to be further used in the ‘dist:’ goal. jpayne@68:

    jpayne@68:
     
    SUBDIRS = doc lib src po
    jpayne@68: 
    jpayne@68: jpayne@68:
  3. jpayne@68: A delicate point is the ‘dist:’ goal, as ‘po/Makefile’ will later jpayne@68: assume that the proper directory has been set up from the main ‘Makefile’. jpayne@68: Here is an example at what the ‘dist:’ goal might look like: jpayne@68: jpayne@68:
     
    distdir = $(PACKAGE)-$(VERSION)
    jpayne@68: dist: Makefile
    jpayne@68: 	rm -fr $(distdir)
    jpayne@68: 	mkdir $(distdir)
    jpayne@68: 	chmod 777 $(distdir)
    jpayne@68: 	for file in $(DISTFILES); do \
    jpayne@68: 	  ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \
    jpayne@68: 	done
    jpayne@68: 	for subdir in $(SUBDIRS); do \
    jpayne@68: 	  mkdir $(distdir)/$$subdir || exit 1; \
    jpayne@68: 	  chmod 777 $(distdir)/$$subdir; \
    jpayne@68: 	  (cd $$subdir && $(MAKE) $@) || exit 1; \
    jpayne@68: 	done
    jpayne@68: 	tar chozf $(distdir).tar.gz $(distdir)
    jpayne@68: 	rm -fr $(distdir)
    jpayne@68: 
    jpayne@68: jpayne@68:
jpayne@68: jpayne@68:

Note that if you are using GNU automake, ‘Makefile.in’ is jpayne@68: automatically generated from ‘Makefile.am’, and all needed changes jpayne@68: to ‘Makefile.am’ are already made by running ‘gettextize’. jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.4.11 ‘Makefile.in’ in ‘src/

jpayne@68: jpayne@68:

Some of the modifications made in the main ‘Makefile.in’ will jpayne@68: also be needed in the ‘Makefile.in’ from your package sources, jpayne@68: which we assume here to be in the ‘src/’ subdirectory. Here are jpayne@68: all the modifications needed in ‘src/Makefile.in’: jpayne@68:

jpayne@68:
    jpayne@68:
  1. jpayne@68: In view of the ‘dist:’ goal, you should have these lines near the jpayne@68: beginning of ‘src/Makefile.in’: jpayne@68: jpayne@68:
     
    PACKAGE = @PACKAGE@
    jpayne@68: VERSION = @VERSION@
    jpayne@68: 
    jpayne@68: jpayne@68:
  2. jpayne@68: If not done already, you should guarantee that top_srcdir jpayne@68: gets defined. This will serve for cpp include files. Just add jpayne@68: the line: jpayne@68: jpayne@68:
     
    top_srcdir = @top_srcdir@
    jpayne@68: 
    jpayne@68: jpayne@68:
  3. jpayne@68: You might also want to define subdir as ‘src’, later jpayne@68: allowing for almost uniform ‘dist:’ goals in all your jpayne@68: ‘Makefile.in’. At list, the ‘dist:’ goal below assume that jpayne@68: you used: jpayne@68: jpayne@68:
     
    subdir = src
    jpayne@68: 
    jpayne@68: jpayne@68:
  4. jpayne@68: The main function of your program will normally call jpayne@68: bindtextdomain (see see section Triggering gettext Operations), like this: jpayne@68: jpayne@68:
     
    bindtextdomain (PACKAGE, LOCALEDIR);
    jpayne@68: textdomain (PACKAGE);
    jpayne@68: 
    jpayne@68: jpayne@68:

    On native Windows platforms, the main function may call jpayne@68: wbindtextdomain instead of bindtextdomain. jpayne@68:

    jpayne@68:

    To make LOCALEDIR known to the program, add the following lines to jpayne@68: ‘Makefile.in’: jpayne@68:

    jpayne@68:
     
    datadir = @datadir@
    jpayne@68: datarootdir= @datarootdir@
    jpayne@68: localedir = @localedir@
    jpayne@68: DEFS = -DLOCALEDIR=$(localedir_c_make) @DEFS@
    jpayne@68: 
    jpayne@68: jpayne@68:

    $(localedir_c_make) expands to the value of localedir, in jpayne@68: C syntax, escaped for use in a Makefile. jpayne@68: Note that @datadir@ defaults to ‘$(prefix)/share’, and jpayne@68: $(localedir) defaults to ‘$(prefix)/share/locale’. jpayne@68:

    jpayne@68:
  5. jpayne@68: You should ensure that the final linking will use @LIBINTL@ or jpayne@68: @LTLIBINTL@ as a library. @LIBINTL@ is for use without jpayne@68: libtool, @LTLIBINTL@ is for use with libtool. An jpayne@68: easy way to achieve this is to manage that it gets into LIBS, like jpayne@68: this: jpayne@68: jpayne@68:
     
    LIBS = @LIBINTL@ @LIBS@
    jpayne@68: 
    jpayne@68: jpayne@68:

    In most packages internationalized with GNU gettext, one will jpayne@68: find a directory ‘lib/’ in which a library containing some helper jpayne@68: functions will be build. (You need at least the few functions which the jpayne@68: GNU gettext Library itself needs.) However some of the functions jpayne@68: in the ‘lib/’ also give messages to the user which of course should be jpayne@68: translated, too. Taking care of this, the support library (say jpayne@68: ‘libsupport.a’) should be placed before @LIBINTL@ and jpayne@68: @LIBS@ in the above example. So one has to write this: jpayne@68:

    jpayne@68:
     
    LIBS = ../lib/libsupport.a @LIBINTL@ @LIBS@
    jpayne@68: 
    jpayne@68: jpayne@68:
  6. jpayne@68: Your ‘dist:’ goal has to conform with others. Here is a jpayne@68: reasonable definition for it: jpayne@68: jpayne@68:
     
    distdir = ../$(PACKAGE)-$(VERSION)/$(subdir)
    jpayne@68: dist: Makefile $(DISTFILES)
    jpayne@68: 	for file in $(DISTFILES); do \
    jpayne@68: 	  ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir) || exit 1; \
    jpayne@68: 	done
    jpayne@68: 
    jpayne@68: jpayne@68:
jpayne@68: jpayne@68:

Note that if you are using GNU automake, ‘Makefile.in’ is jpayne@68: automatically generated from ‘Makefile.am’, and the first three jpayne@68: changes and the last change are not necessary. The remaining needed jpayne@68: ‘Makefile.am’ modifications are the following: jpayne@68:

jpayne@68:
    jpayne@68:
  1. jpayne@68: To make LOCALEDIR known to the program, add the following to jpayne@68: ‘Makefile.am’: jpayne@68: jpayne@68:
     
    <module>_CPPFLAGS = -DLOCALEDIR=$(localedir_c_make)
    jpayne@68: 
    jpayne@68: jpayne@68:

    for each specific module or compilation unit, or jpayne@68:

    jpayne@68:
     
    AM_CPPFLAGS = -DLOCALEDIR=$(localedir_c_make)
    jpayne@68: 
    jpayne@68: jpayne@68:

    for all modules and compilation units together. jpayne@68:

    jpayne@68:
  2. jpayne@68: To ensure that the final linking will use @LIBINTL@ or jpayne@68: @LTLIBINTL@ as a library, add the following to jpayne@68: ‘Makefile.am’: jpayne@68: jpayne@68:
     
    <program>_LDADD = @LIBINTL@
    jpayne@68: 
    jpayne@68: jpayne@68:

    for each specific program, or jpayne@68:

    jpayne@68:
     
    LDADD = @LIBINTL@
    jpayne@68: 
    jpayne@68: jpayne@68:

    for all programs together. Remember that when you use libtool jpayne@68: to link a program, you need to use @LTLIBINTL@ instead of @LIBINTL@ jpayne@68: for that program. jpayne@68:

    jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.4.12 ‘gettext.h’ in ‘lib/

jpayne@68: jpayne@68:

Internationalization of packages, as provided by GNU gettext, is jpayne@68: optional. It can be turned off in two situations: jpayne@68:

jpayne@68: jpayne@68: jpayne@68:

A C preprocessor macro can be used to detect these two cases. Usually, jpayne@68: when libintl.h was found and not explicitly disabled, the jpayne@68: ENABLE_NLS macro will be defined to 1 in the autoconf generated jpayne@68: configuration file (usually called ‘config.h’). In the two negative jpayne@68: situations, however, this macro will not be defined, thus it will evaluate jpayne@68: to 0 in C preprocessor expressions. jpayne@68:

jpayne@68: jpayne@68:

gettext.h’ is a convenience header file for conditional use of jpayne@68: ‘<libintl.h>’, depending on the ENABLE_NLS macro. If jpayne@68: ENABLE_NLS is set, it includes ‘<libintl.h>’; otherwise it jpayne@68: defines no-op substitutes for the libintl.h functions. We recommend jpayne@68: the use of "gettext.h" over direct use of ‘<libintl.h>’, jpayne@68: so that portability to older systems is guaranteed and installers can jpayne@68: turn off internationalization if they want to. In the C code, you will jpayne@68: then write jpayne@68:

jpayne@68:
 
#include "gettext.h"
jpayne@68: 
jpayne@68: jpayne@68:

instead of jpayne@68:

jpayne@68:
 
#include <libintl.h>
jpayne@68: 
jpayne@68: jpayne@68:

The location of gettext.h is usually in a directory containing jpayne@68: auxiliary include files. In many GNU packages, there is a directory jpayne@68: ‘lib/’ containing helper functions; ‘gettext.h’ fits there. jpayne@68: In other packages, it can go into the ‘src’ directory. jpayne@68:

jpayne@68:

Do not install the gettext.h file in public locations. Every jpayne@68: package that needs it should contain a copy of it on its own. jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.5 Autoconf macros for use in ‘configure.ac

jpayne@68: jpayne@68:

GNU gettext installs macros for use in a package's jpayne@68: ‘configure.ac’ or ‘configure.in’. jpayne@68: See (autoconf)Top section `Introduction' in The Autoconf Manual. jpayne@68: The primary macro is, of course, AM_GNU_GETTEXT. jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.5.1 AM_GNU_GETTEXT in ‘gettext.m4

jpayne@68: jpayne@68:

The AM_GNU_GETTEXT macro tests for the presence of the GNU gettext jpayne@68: function family in either the C library or a separate libintl jpayne@68: library (shared or static libraries are both supported). It also invokes jpayne@68: AM_PO_SUBDIRS, thus preparing the ‘po/’ directories of the jpayne@68: package for building. jpayne@68:

jpayne@68:

AM_GNU_GETTEXT accepts up to two optional arguments. The general jpayne@68: syntax is jpayne@68:

jpayne@68:
 
AM_GNU_GETTEXT([intlsymbol], [needsymbol])
jpayne@68: 
jpayne@68: jpayne@68:

intlsymbol should always be ‘external’. jpayne@68:

jpayne@68:

If needsymbol is specified and is ‘need-ngettext’, then GNU jpayne@68: gettext implementations (in libc or libintl) without the ngettext() jpayne@68: function will be ignored. If needsymbol is specified and is jpayne@68: ‘need-formatstring-macros’, then GNU gettext implementations that don't jpayne@68: support the ISO C 99 ‘<inttypes.h>’ formatstring macros will be ignored. jpayne@68: Only one needsymbol can be specified. These requirements can also be jpayne@68: specified by using the macro AM_GNU_GETTEXT_NEED elsewhere. To specify jpayne@68: more than one requirement, just specify the strongest one among them, or jpayne@68: invoke the AM_GNU_GETTEXT_NEED macro several times. The hierarchy jpayne@68: among the various alternatives is as follows: ‘need-formatstring-macros’ jpayne@68: implies ‘need-ngettext’. jpayne@68:

jpayne@68:

The AM_GNU_GETTEXT macro determines whether GNU gettext is jpayne@68: available and should be used. If so, it sets the USE_NLS variable jpayne@68: to ‘yes’; it defines ENABLE_NLS to 1 in the autoconf jpayne@68: generated configuration file (usually called ‘config.h’); it sets jpayne@68: the variables LIBINTL and LTLIBINTL to the linker options jpayne@68: for use in a Makefile (LIBINTL for use without libtool, jpayne@68: LTLIBINTL for use with libtool); it adds an ‘-I’ option to jpayne@68: CPPFLAGS if necessary. In the negative case, it sets jpayne@68: USE_NLS to ‘no’; it sets LIBINTL and LTLIBINTL jpayne@68: to empty and doesn't change CPPFLAGS. jpayne@68:

jpayne@68:

The complexities that AM_GNU_GETTEXT deals with are the following: jpayne@68:

jpayne@68: jpayne@68: jpayne@68:

Additionally, the AM_GNU_GETTEXT macro sets two variables, for jpayne@68: convenience. Both are derived from the --localedir configure jpayne@68: option. They are correct even on native Windows, where directories jpayne@68: frequently contain backslashes. jpayne@68:

jpayne@68:
localedir_c
jpayne@68:

This is the value of localedir, in C syntax. This variable is jpayne@68: meant to be substituted into C or C++ code through jpayne@68: AC_CONFIG_FILES. jpayne@68:

jpayne@68:
jpayne@68:
localedir_c_make
jpayne@68:

This is the value of localedir, in C syntax, escaped for use in jpayne@68: a Makefile. This variable is meant to be used in Makefiles, jpayne@68: for example for defining a C macro named LOCALEDIR: jpayne@68:

 
AM_CPPFLAGS = ... -DLOCALEDIR=$(localedir_c_make) ...
jpayne@68: 
jpayne@68:
jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.5.2 AM_GNU_GETTEXT_VERSION in ‘gettext.m4

jpayne@68: jpayne@68:

The AM_GNU_GETTEXT_VERSION macro declares the version number of jpayne@68: the GNU gettext infrastructure that is used by the package. jpayne@68:

jpayne@68:

The use of this macro is optional; only the autopoint program makes jpayne@68: use of it (see section Integrating with Version Control Systems). jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.5.3 AM_GNU_GETTEXT_NEED in ‘gettext.m4

jpayne@68: jpayne@68:

The AM_GNU_GETTEXT_NEED macro declares a constraint regarding the jpayne@68: GNU gettext implementation. The syntax is jpayne@68:

jpayne@68:
 
AM_GNU_GETTEXT_NEED([needsymbol])
jpayne@68: 
jpayne@68: jpayne@68:

If needsymbol is ‘need-ngettext’, then GNU gettext implementations jpayne@68: (in libc or libintl) without the ngettext() function will be ignored. jpayne@68: If needsymbol is ‘need-formatstring-macros’, then GNU gettext jpayne@68: implementations that don't support the ISO C 99 ‘<inttypes.h>’ jpayne@68: formatstring macros will be ignored. jpayne@68:

jpayne@68:

The optional second argument of AM_GNU_GETTEXT is also taken into jpayne@68: account. jpayne@68:

jpayne@68:

The AM_GNU_GETTEXT_NEED invocations can occur before or after jpayne@68: the AM_GNU_GETTEXT invocation; the order doesn't matter. jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.5.4 AM_PO_SUBDIRS in ‘po.m4

jpayne@68: jpayne@68:

The AM_PO_SUBDIRS macro prepares the ‘po/’ directories of the jpayne@68: package for building. This macro should be used in internationalized jpayne@68: programs written in other programming languages than C, C++, Objective C, jpayne@68: for example sh, Python, Lisp. See Other Programming Languages for a list of programming languages that support localization jpayne@68: through PO files. jpayne@68:

jpayne@68:

The AM_PO_SUBDIRS macro determines whether internationalization jpayne@68: should be used. If so, it sets the USE_NLS variable to ‘yes’, jpayne@68: otherwise to ‘no’. It also determines the right values for Makefile jpayne@68: variables in each ‘po/’ directory. jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.5.5 AM_XGETTEXT_OPTION in ‘po.m4

jpayne@68: jpayne@68:

The AM_XGETTEXT_OPTION macro registers a command-line option to be jpayne@68: used in the invocations of xgettext in the ‘po/’ directories jpayne@68: of the package. jpayne@68:

jpayne@68:

For example, if you have a source file that defines a function jpayne@68: ‘error_at_line’ whose fifth argument is a format string, you can use jpayne@68:

 
AM_XGETTEXT_OPTION([--flag=error_at_line:5:c-format])
jpayne@68: 
jpayne@68:

to instruct xgettext to mark all translatable strings in ‘gettext’ jpayne@68: invocations that occur as fifth argument to this function as ‘c-format’. jpayne@68:

jpayne@68:

See Invoking the xgettext Program for the list of options that xgettext jpayne@68: accepts. jpayne@68:

jpayne@68:

The use of this macro is an alternative to the use of the jpayne@68: ‘XGETTEXT_OPTIONS’ variable in ‘po/Makevars’. jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.5.6 AM_ICONV in ‘iconv.m4

jpayne@68: jpayne@68:

The AM_ICONV macro tests for the presence of the POSIX/XSI jpayne@68: iconv function family in either the C library or a separate jpayne@68: libiconv library. If found, it sets the am_cv_func_iconv jpayne@68: variable to ‘yes’; it defines HAVE_ICONV to 1 in the autoconf jpayne@68: generated configuration file (usually called ‘config.h’); it defines jpayne@68: ICONV_CONST to ‘const’ or to empty, depending on whether the jpayne@68: second argument of iconv() is of type ‘const char **’ or jpayne@68: ‘char **’; it sets the variables LIBICONV and jpayne@68: LTLIBICONV to the linker options for use in a Makefile jpayne@68: (LIBICONV for use without libtool, LTLIBICONV for use with jpayne@68: libtool); it adds an ‘-I’ option to CPPFLAGS if jpayne@68: necessary. If not found, it sets LIBICONV and LTLIBICONV to jpayne@68: empty and doesn't change CPPFLAGS. jpayne@68:

jpayne@68:

The complexities that AM_ICONV deals with are the following: jpayne@68:

jpayne@68: jpayne@68: jpayne@68:

iconv.m4’ is distributed with the GNU gettext package because jpayne@68: ‘gettext.m4’ relies on it. jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.6 Integrating with Version Control Systems

jpayne@68: jpayne@68:

Many projects use version control systems for distributed development jpayne@68: and source backup. This section gives some advice how to manage the jpayne@68: uses of gettextize, autopoint and autoconf on jpayne@68: version controlled files. jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.6.1 Avoiding version mismatch in distributed development

jpayne@68: jpayne@68:

In a project development with multiple developers, there should be a jpayne@68: single developer who occasionally - when there is desire to upgrade to jpayne@68: a new gettext version - runs gettextize and performs the jpayne@68: changes listed in Files You Must Create or Alter, and then commits his changes jpayne@68: to the repository. jpayne@68:

jpayne@68:

It is highly recommended that all developers on a project use the same jpayne@68: version of GNU gettext in the package. In other words, if a jpayne@68: developer runs gettextize, he should go the whole way, make the jpayne@68: necessary remaining changes and commit his changes to the repository. jpayne@68: Otherwise the following damages will likely occur: jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.6.2 Files to put under version control

jpayne@68: jpayne@68:

There are basically three ways to deal with generated files in the jpayne@68: context of a version controlled repository, such as ‘configure’ jpayne@68: generated from ‘configure.ac’, parser.c generated jpayne@68: from parser.y, or po/Makefile.in.in autoinstalled jpayne@68: by gettextize or autopoint. jpayne@68:

jpayne@68:
    jpayne@68:
  1. jpayne@68: All generated files are always committed into the repository. jpayne@68: jpayne@68:
  2. jpayne@68: All generated files are committed into the repository occasionally, jpayne@68: for example each time a release is made. jpayne@68: jpayne@68:
  3. jpayne@68: Generated files are never committed into the repository. jpayne@68:
jpayne@68: jpayne@68:

Each of these three approaches has different advantages and drawbacks. jpayne@68:

jpayne@68:
    jpayne@68:
  1. jpayne@68: The advantage is that anyone can check out the source at any moment and jpayne@68: gets a working build. The drawbacks are: 1a. It requires some frequent jpayne@68: "push" actions by the maintainers. 1b. The repository grows in size jpayne@68: quite fast. jpayne@68: jpayne@68:
  2. jpayne@68: The advantage is that anyone can check out the source, and the usual jpayne@68: "./configure; make" will work. The drawbacks are: 2a. The one who jpayne@68: checks out the repository needs tools like GNU automake, GNU jpayne@68: autoconf, GNU m4 installed in his PATH; sometimes he jpayne@68: even needs particular versions of them. 2b. When a release is made jpayne@68: and a commit is made on the generated files, the other developers get jpayne@68: conflicts on the generated files when merging the local work back to jpayne@68: the repository. Although these conflicts are easy to resolve, they jpayne@68: are annoying. jpayne@68: jpayne@68:
  3. jpayne@68: The advantage is less work for the maintainers. The drawback is that jpayne@68: anyone who checks out the source not only needs tools like GNU jpayne@68: automake, GNU autoconf, GNU m4 installed in his jpayne@68: PATH, but also that he needs to perform a package specific pre-build jpayne@68: step before being able to "./configure; make". jpayne@68:
jpayne@68: jpayne@68:

For the first and second approach, all files modified or brought in jpayne@68: by the occasional gettextize invocation and update should be jpayne@68: committed into the repository. jpayne@68:

jpayne@68:

For the third approach, the maintainer can omit from the repository jpayne@68: all the files that gettextize mentions as "copy". Instead, he jpayne@68: adds to the ‘configure.ac’ or ‘configure.in’ a line of the jpayne@68: form jpayne@68:

jpayne@68:
 
AM_GNU_GETTEXT_VERSION(0.22.4)
jpayne@68: 
jpayne@68: jpayne@68:

and adds to the package's pre-build script an invocation of jpayne@68: ‘autopoint’. For everyone who checks out the source, this jpayne@68: autopoint invocation will copy into the right place the jpayne@68: gettext infrastructure files that have been omitted from the repository. jpayne@68:

jpayne@68:

The version number used as argument to AM_GNU_GETTEXT_VERSION is jpayne@68: the version of the gettext infrastructure that the package wants jpayne@68: to use. It is also the minimum version number of the ‘autopoint’ jpayne@68: program. So, if you write AM_GNU_GETTEXT_VERSION(0.11.5) then the jpayne@68: developers can have any version >= 0.11.5 installed; the package will work jpayne@68: with the 0.11.5 infrastructure in all developers' builds. When the jpayne@68: maintainer then runs gettextize from, say, version 0.12.1 on the package, jpayne@68: the occurrence of AM_GNU_GETTEXT_VERSION(0.11.5) will be changed jpayne@68: into AM_GNU_GETTEXT_VERSION(0.12.1), and all other developers that jpayne@68: use the CVS will henceforth need to have GNU gettext 0.12.1 or newer jpayne@68: installed. jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.6.3 Put PO Files under Version Control

jpayne@68: jpayne@68:

Since translations are valuable assets as well as the source code, it jpayne@68: would make sense to put them under version control. The GNU gettext jpayne@68: infrastructure supports two ways to deal with translations in the jpayne@68: context of a version controlled repository. jpayne@68:

jpayne@68:
    jpayne@68:
  1. jpayne@68: Both POT file and PO files are committed into the repository. jpayne@68: jpayne@68:
  2. jpayne@68: Only PO files are committed into the repository. jpayne@68: jpayne@68:
jpayne@68: jpayne@68:

If a POT file is absent when building, it will be generated by jpayne@68: scanning the source files with xgettext, and then the PO files jpayne@68: are regenerated as a dependency. On the other hand, some maintainers jpayne@68: want to keep the POT file unchanged during the development phase. So, jpayne@68: even if a POT file is present and older than the source code, it won't jpayne@68: be updated automatically. You can manually update it with make jpayne@68: $(DOMAIN).pot-update, and commit it at certain point. jpayne@68:

jpayne@68:

Special advices for particular version control systems: jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.6.4 Invoking the autopoint Program

jpayne@68: jpayne@68: jpayne@68:
 
autopoint [option]...
jpayne@68: 
jpayne@68: jpayne@68:

The autopoint program copies standard gettext infrastructure files jpayne@68: into a source package. It extracts from a macro call of the form jpayne@68: AM_GNU_GETTEXT_VERSION(version), found in the package's jpayne@68: ‘configure.in’ or ‘configure.ac’ file, the gettext version jpayne@68: used by the package, and copies the infrastructure files belonging to jpayne@68: this version into the package. jpayne@68:

jpayne@68:

To extract the latest available infrastructure which satisfies a version jpayne@68: requirement, then you can use the form jpayne@68: AM_GNU_GETTEXT_REQUIRE_VERSION(version) instead. For jpayne@68: example, if gettext 0.22.4 is installed on your system jpayne@68: and 0.19.1 is requested, then the infrastructure files of version jpayne@68: 0.22.4 will be copied into a source package. jpayne@68:

jpayne@68: jpayne@68: jpayne@68:

13.6.4.1 Options

jpayne@68: jpayne@68:
jpayne@68:
-f
jpayne@68:
--force
jpayne@68:
jpayne@68: jpayne@68:

Force overwriting of files that already exist. jpayne@68:

jpayne@68:
jpayne@68:
-n
jpayne@68:
--dry-run
jpayne@68:
jpayne@68: jpayne@68:

Print modifications but don't perform them. All file copying actions that jpayne@68: autopoint would normally execute are inhibited and instead only jpayne@68: listed on standard output. jpayne@68:

jpayne@68:
jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.6.4.2 Informative output

jpayne@68: jpayne@68:
jpayne@68:
--help
jpayne@68:
jpayne@68:

Display this help and exit. jpayne@68:

jpayne@68:
jpayne@68:
--version
jpayne@68:
jpayne@68:

Output version information and exit. jpayne@68:

jpayne@68:
jpayne@68:
jpayne@68: jpayne@68:

autopoint supports the GNU gettext versions from 0.10.35 jpayne@68: to the current one, 0.22.4. In order to apply jpayne@68: autopoint to a package using a gettext version newer than jpayne@68: 0.22.4, you need to install this same version of GNU jpayne@68: gettext at least. jpayne@68:

jpayne@68:

In packages using GNU automake, an invocation of autopoint jpayne@68: should be followed by invocations of aclocal and then autoconf jpayne@68: and autoheader. The reason is that autopoint installs some jpayne@68: autoconf macro files, which are used by aclocal to create jpayne@68: ‘aclocal.m4’, and the latter is used by autoconf to create the jpayne@68: package's ‘configure’ script and by autoheader to create the jpayne@68: package's ‘config.h.in’ include file template. jpayne@68:

jpayne@68:

The name ‘autopoint’ is an abbreviation of ‘auto-po-intl-m4’; jpayne@68: in earlier versions, the tool copied or updated mostly files in the ‘po’, jpayne@68: ‘intl’, ‘m4’ directories. jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68:

13.7 Creating a Distribution Tarball

jpayne@68: jpayne@68:

In projects that use GNU automake, the usual commands for creating jpayne@68: a distribution tarball, ‘make dist’ or ‘make distcheck’, jpayne@68: automatically update the PO files as needed. jpayne@68:

jpayne@68:

If GNU automake is not used, the maintainer needs to perform this jpayne@68: update before making a release: jpayne@68:

jpayne@68:
 
$ ./configure
jpayne@68: $ (cd po; make update-po)
jpayne@68: $ make distclean
jpayne@68: 
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:
[ << ][ >> ]           [Top][Contents][Index][ ? ]
jpayne@68:

jpayne@68: jpayne@68: This document was generated by Bruno Haible on February, 21 2024 using texi2html 1.78a. jpayne@68: jpayne@68:
jpayne@68: jpayne@68:

jpayne@68: jpayne@68: