1*946379e7Schristos<HTML> 2*946379e7Schristos<HEAD> 3*946379e7Schristos<!-- This HTML file has been created by texi2html 1.52b 4*946379e7Schristos from gettext.texi on 27 November 2006 --> 5*946379e7Schristos 6*946379e7Schristos<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8"> 7*946379e7Schristos<TITLE>GNU gettext utilities - 13 The Maintainer's View</TITLE> 8*946379e7Schristos</HEAD> 9*946379e7Schristos<BODY> 10*946379e7SchristosGo to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_12.html">previous</A>, <A HREF="gettext_14.html">next</A>, <A HREF="gettext_25.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. 11*946379e7Schristos<P><HR><P> 12*946379e7Schristos 13*946379e7Schristos 14*946379e7Schristos<H1><A NAME="SEC196" HREF="gettext_toc.html#TOC196">13 The Maintainer's View</A></H1> 15*946379e7Schristos<P> 16*946379e7Schristos<A NAME="IDX1056"></A> 17*946379e7Schristos 18*946379e7Schristos</P> 19*946379e7Schristos<P> 20*946379e7SchristosThe maintainer of a package has many responsibilities. One of them 21*946379e7Schristosis ensuring that the package will install easily on many platforms, 22*946379e7Schristosand that the magic we described earlier (see section <A HREF="gettext_2.html#SEC7">2 The User's View</A>) will work 23*946379e7Schristosfor installers and end users. 24*946379e7Schristos 25*946379e7Schristos</P> 26*946379e7Schristos<P> 27*946379e7SchristosOf course, there are many possible ways by which GNU <CODE>gettext</CODE> 28*946379e7Schristosmight be integrated in a distribution, and this chapter does not cover 29*946379e7Schristosthem in all generality. Instead, it details one possible approach which 30*946379e7Schristosis especially adequate for many free software distributions following GNU 31*946379e7Schristosstandards, or even better, Gnits standards, because GNU <CODE>gettext</CODE> 32*946379e7Schristosis purposely for helping the internationalization of the whole GNU 33*946379e7Schristosproject, and as many other good free packages as possible. So, the 34*946379e7Schristosmaintainer's view presented here presumes that the package already has 35*946379e7Schristosa <TT>‘configure.in’</TT> file and uses GNU Autoconf. 36*946379e7Schristos 37*946379e7Schristos</P> 38*946379e7Schristos<P> 39*946379e7SchristosNevertheless, GNU <CODE>gettext</CODE> may surely be useful for free packages 40*946379e7Schristosnot following GNU standards and conventions, but the maintainers of such 41*946379e7Schristospackages might have to show imagination and initiative in organizing 42*946379e7Schristostheir distributions so <CODE>gettext</CODE> work for them in all situations. 43*946379e7SchristosThere are surely many, out there. 44*946379e7Schristos 45*946379e7Schristos</P> 46*946379e7Schristos<P> 47*946379e7SchristosEven if <CODE>gettext</CODE> methods are now stabilizing, slight adjustments 48*946379e7Schristosmight be needed between successive <CODE>gettext</CODE> versions, so you 49*946379e7Schristosshould ideally revise this chapter in subsequent releases, looking 50*946379e7Schristosfor changes. 51*946379e7Schristos 52*946379e7Schristos</P> 53*946379e7Schristos 54*946379e7Schristos 55*946379e7Schristos 56*946379e7Schristos<H2><A NAME="SEC197" HREF="gettext_toc.html#TOC197">13.1 Flat or Non-Flat Directory Structures</A></H2> 57*946379e7Schristos 58*946379e7Schristos<P> 59*946379e7SchristosSome free software packages are distributed as <CODE>tar</CODE> files which unpack 60*946379e7Schristosin a single directory, these are said to be <EM>flat</EM> distributions. 61*946379e7SchristosOther free software packages have a one level hierarchy of subdirectories, using 62*946379e7Schristosfor example a subdirectory named <TT>‘doc/’</TT> for the Texinfo manual and 63*946379e7Schristosman pages, another called <TT>‘lib/’</TT> for holding functions meant to 64*946379e7Schristosreplace or complement C libraries, and a subdirectory <TT>‘src/’</TT> for 65*946379e7Schristosholding the proper sources for the package. These other distributions 66*946379e7Schristosare said to be <EM>non-flat</EM>. 67*946379e7Schristos 68*946379e7Schristos</P> 69*946379e7Schristos<P> 70*946379e7SchristosWe cannot say much about flat distributions. A flat 71*946379e7Schristosdirectory structure has the disadvantage of increasing the difficulty 72*946379e7Schristosof updating to a new version of GNU <CODE>gettext</CODE>. Also, if you have 73*946379e7Schristosmany PO files, this could somewhat pollute your single directory. 74*946379e7SchristosAlso, GNU <CODE>gettext</CODE>'s libintl sources consist of C sources, shell 75*946379e7Schristosscripts, <CODE>sed</CODE> scripts and complicated Makefile rules, which don't 76*946379e7Schristosfit well into an existing flat structure. For these reasons, we 77*946379e7Schristosrecommend to use non-flat approach in this case as well. 78*946379e7Schristos 79*946379e7Schristos</P> 80*946379e7Schristos<P> 81*946379e7SchristosMaybe because GNU <CODE>gettext</CODE> itself has a non-flat structure, 82*946379e7Schristoswe have more experience with this approach, and this is what will be 83*946379e7Schristosdescribed in the remaining of this chapter. Some maintainers might 84*946379e7Schristosuse this as an opportunity to unflatten their package structure. 85*946379e7Schristos 86*946379e7Schristos</P> 87*946379e7Schristos 88*946379e7Schristos 89*946379e7Schristos<H2><A NAME="SEC198" HREF="gettext_toc.html#TOC198">13.2 Prerequisite Works</A></H2> 90*946379e7Schristos<P> 91*946379e7Schristos<A NAME="IDX1057"></A> 92*946379e7Schristos<A NAME="IDX1058"></A> 93*946379e7Schristos<A NAME="IDX1059"></A> 94*946379e7Schristos 95*946379e7Schristos</P> 96*946379e7Schristos<P> 97*946379e7SchristosThere are some works which are required for using GNU <CODE>gettext</CODE> 98*946379e7Schristosin one of your package. These works have some kind of generality 99*946379e7Schristosthat escape the point by point descriptions used in the remainder 100*946379e7Schristosof this chapter. So, we describe them here. 101*946379e7Schristos 102*946379e7Schristos</P> 103*946379e7Schristos 104*946379e7Schristos<UL> 105*946379e7Schristos<LI> 106*946379e7Schristos 107*946379e7SchristosBefore attempting to use <CODE>gettextize</CODE> you should install some 108*946379e7Schristosother packages first. 109*946379e7SchristosEnsure that recent versions of GNU <CODE>m4</CODE>, GNU Autoconf and GNU 110*946379e7Schristos<CODE>gettext</CODE> are already installed at your site, and if not, proceed 111*946379e7Schristosto do this first. If you get to install these things, beware that 112*946379e7SchristosGNU <CODE>m4</CODE> must be fully installed before GNU Autoconf is even 113*946379e7Schristos<EM>configured</EM>. 114*946379e7Schristos 115*946379e7SchristosTo further ease the task of a package maintainer the <CODE>automake</CODE> 116*946379e7Schristospackage was designed and implemented. GNU <CODE>gettext</CODE> now uses this 117*946379e7Schristostool and the <TT>‘Makefile’</TT>s in the <TT>‘intl/’</TT> and <TT>‘po/’</TT> 118*946379e7Schristostherefore know about all the goals necessary for using <CODE>automake</CODE> 119*946379e7Schristosand <TT>‘libintl’</TT> in one project. 120*946379e7Schristos 121*946379e7SchristosThose four packages are only needed by you, as a maintainer; the 122*946379e7Schristosinstallers of your own package and end users do not really need any of 123*946379e7SchristosGNU <CODE>m4</CODE>, GNU Autoconf, GNU <CODE>gettext</CODE>, or GNU <CODE>automake</CODE> 124*946379e7Schristosfor successfully installing and running your package, with messages 125*946379e7Schristosproperly translated. But this is not completely true if you provide 126*946379e7Schristosinternationalized shell scripts within your own package: GNU 127*946379e7Schristos<CODE>gettext</CODE> shall then be installed at the user site if the end users 128*946379e7Schristoswant to see the translation of shell script messages. 129*946379e7Schristos 130*946379e7Schristos<LI> 131*946379e7Schristos 132*946379e7SchristosYour package should use Autoconf and have a <TT>‘configure.in’</TT> or 133*946379e7Schristos<TT>‘configure.ac’</TT> file. 134*946379e7SchristosIf it does not, you have to learn how. The Autoconf documentation 135*946379e7Schristosis quite well written, it is a good idea that you print it and get 136*946379e7Schristosfamiliar with it. 137*946379e7Schristos 138*946379e7Schristos<LI> 139*946379e7Schristos 140*946379e7SchristosYour C sources should have already been modified according to 141*946379e7Schristosinstructions given earlier in this manual. See section <A HREF="gettext_4.html#SEC11">4 Preparing Program Sources</A>. 142*946379e7Schristos 143*946379e7Schristos<LI> 144*946379e7Schristos 145*946379e7SchristosYour <TT>‘po/’</TT> directory should receive all PO files submitted to you 146*946379e7Schristosby the translator teams, each having <TT>‘<VAR>ll</VAR>.po’</TT> as a name. 147*946379e7SchristosThis is not usually easy to get translation 148*946379e7Schristoswork done before your package gets internationalized and available! 149*946379e7SchristosSince the cycle has to start somewhere, the easiest for the maintainer 150*946379e7Schristosis to start with absolutely no PO files, and wait until various 151*946379e7Schristostranslator teams get interested in your package, and submit PO files. 152*946379e7Schristos 153*946379e7Schristos</UL> 154*946379e7Schristos 155*946379e7Schristos<P> 156*946379e7SchristosIt is worth adding here a few words about how the maintainer should 157*946379e7Schristosideally behave with PO files submissions. As a maintainer, your role is 158*946379e7Schristosto authenticate the origin of the submission as being the representative 159*946379e7Schristosof the appropriate translating teams of the Translation Project (forward 160*946379e7Schristosthe submission to <TT>‘translation@iro.umontreal.ca’</TT> in case of doubt), 161*946379e7Schristosto ensure that the PO file format is not severely broken and does not 162*946379e7Schristosprevent successful installation, and for the rest, to merely put these 163*946379e7SchristosPO files in <TT>‘po/’</TT> for distribution. 164*946379e7Schristos 165*946379e7Schristos</P> 166*946379e7Schristos<P> 167*946379e7SchristosAs a maintainer, you do not have to take on your shoulders the 168*946379e7Schristosresponsibility of checking if the translations are adequate or 169*946379e7Schristoscomplete, and should avoid diving into linguistic matters. Translation 170*946379e7Schristosteams drive themselves and are fully responsible of their linguistic 171*946379e7Schristoschoices for the Translation Project. Keep in mind that translator teams are <EM>not</EM> 172*946379e7Schristosdriven by maintainers. You can help by carefully redirecting all 173*946379e7Schristoscommunications and reports from users about linguistic matters to the 174*946379e7Schristosappropriate translation team, or explain users how to reach or join 175*946379e7Schristostheir team. The simplest might be to send them the <TT>‘ABOUT-NLS’</TT> file. 176*946379e7Schristos 177*946379e7Schristos</P> 178*946379e7Schristos<P> 179*946379e7SchristosMaintainers should <EM>never ever</EM> apply PO file bug reports 180*946379e7Schristosthemselves, short-cutting translation teams. If some translator has 181*946379e7Schristosdifficulty to get some of her points through her team, it should not be 182*946379e7Schristosan option for her to directly negotiate translations with maintainers. 183*946379e7SchristosTeams ought to settle their problems themselves, if any. If you, as 184*946379e7Schristosa maintainer, ever think there is a real problem with a team, please 185*946379e7Schristosnever try to <EM>solve</EM> a team's problem on your own. 186*946379e7Schristos 187*946379e7Schristos</P> 188*946379e7Schristos 189*946379e7Schristos 190*946379e7Schristos<H2><A NAME="SEC199" HREF="gettext_toc.html#TOC199">13.3 Invoking the <CODE>gettextize</CODE> Program</A></H2> 191*946379e7Schristos 192*946379e7Schristos<P> 193*946379e7SchristosThe <CODE>gettextize</CODE> program is an interactive tool that helps the 194*946379e7Schristosmaintainer of a package internationalized through GNU <CODE>gettext</CODE>. 195*946379e7SchristosIt is used for two purposes: 196*946379e7Schristos 197*946379e7Schristos</P> 198*946379e7Schristos 199*946379e7Schristos<UL> 200*946379e7Schristos<LI> 201*946379e7Schristos 202*946379e7SchristosAs a wizard, when a package is modified to use GNU <CODE>gettext</CODE> for 203*946379e7Schristosthe first time. 204*946379e7Schristos 205*946379e7Schristos<LI> 206*946379e7Schristos 207*946379e7SchristosAs a migration tool, for upgrading the GNU <CODE>gettext</CODE> support in 208*946379e7Schristosa package from a previous to a newer version of GNU <CODE>gettext</CODE>. 209*946379e7Schristos</UL> 210*946379e7Schristos 211*946379e7Schristos<P> 212*946379e7SchristosThis program performs the following tasks: 213*946379e7Schristos 214*946379e7Schristos</P> 215*946379e7Schristos 216*946379e7Schristos<UL> 217*946379e7Schristos<LI> 218*946379e7Schristos 219*946379e7SchristosIt copies into the package some files that are consistently and 220*946379e7Schristosidentically needed in every package internationalized through 221*946379e7SchristosGNU <CODE>gettext</CODE>. 222*946379e7Schristos 223*946379e7Schristos<LI>It performs as many of the tasks mentioned in the next section 224*946379e7Schristos 225*946379e7Schristossection <A HREF="gettext_13.html#SEC200">13.4 Files You Must Create or Alter</A> as can be performed automatically. 226*946379e7Schristos 227*946379e7Schristos<LI>It removes obsolete files and idioms used for previous GNU 228*946379e7Schristos 229*946379e7Schristos<CODE>gettext</CODE> versions to the form recommended for the current GNU 230*946379e7Schristos<CODE>gettext</CODE> version. 231*946379e7Schristos 232*946379e7Schristos<LI>It prints a summary of the tasks that ought to be done manually 233*946379e7Schristos 234*946379e7Schristosand could not be done automatically by <CODE>gettextize</CODE>. 235*946379e7Schristos</UL> 236*946379e7Schristos 237*946379e7Schristos<P> 238*946379e7SchristosIt can be invoked as follows: 239*946379e7Schristos 240*946379e7Schristos</P> 241*946379e7Schristos<P> 242*946379e7Schristos<A NAME="IDX1060"></A> 243*946379e7Schristos<A NAME="IDX1061"></A> 244*946379e7Schristos 245*946379e7Schristos<PRE> 246*946379e7Schristosgettextize [ <VAR>option</VAR>... ] [ <VAR>directory</VAR> ] 247*946379e7Schristos</PRE> 248*946379e7Schristos 249*946379e7Schristos<P> 250*946379e7Schristosand accepts the following options: 251*946379e7Schristos 252*946379e7Schristos</P> 253*946379e7Schristos<DL COMPACT> 254*946379e7Schristos 255*946379e7Schristos<DT><SAMP>‘-f’</SAMP> 256*946379e7Schristos<DD> 257*946379e7Schristos<DT><SAMP>‘--force’</SAMP> 258*946379e7Schristos<DD> 259*946379e7Schristos<A NAME="IDX1062"></A> 260*946379e7Schristos<A NAME="IDX1063"></A> 261*946379e7SchristosForce replacement of files which already exist. 262*946379e7Schristos 263*946379e7Schristos<DT><SAMP>‘--intl’</SAMP> 264*946379e7Schristos<DD> 265*946379e7Schristos<A NAME="IDX1064"></A> 266*946379e7SchristosInstall the libintl sources in a subdirectory named <TT>‘intl/’</TT>. 267*946379e7SchristosThis libintl will be used to provide internationalization on systems 268*946379e7Schristosthat don't have GNU libintl installed. If this option is omitted, 269*946379e7Schristosthe call to <CODE>AM_GNU_GETTEXT</CODE> in <TT>‘configure.in’</TT> should read: 270*946379e7Schristos<SAMP>‘AM_GNU_GETTEXT([external])’</SAMP>, and internationalization will not 271*946379e7Schristosbe enabled on systems lacking GNU gettext. 272*946379e7Schristos 273*946379e7Schristos<DT><SAMP>‘--no-changelog’</SAMP> 274*946379e7Schristos<DD> 275*946379e7Schristos<A NAME="IDX1065"></A> 276*946379e7SchristosDon't update or create ChangeLog files. By default, <CODE>gettextize</CODE> 277*946379e7Schristoslogs all changes (file additions, modifications and removals) in a 278*946379e7Schristosfile called <SAMP>‘ChangeLog’</SAMP> in each affected directory. 279*946379e7Schristos 280*946379e7Schristos<DT><SAMP>‘--symlink’</SAMP> 281*946379e7Schristos<DD> 282*946379e7Schristos<A NAME="IDX1066"></A> 283*946379e7SchristosMake symbolic links instead of copying the needed files. This can be 284*946379e7Schristosuseful to save a few kilobytes of disk space, but it requires extra 285*946379e7Schristoseffort to create self-contained tarballs, it may disturb some mechanism 286*946379e7Schristosthe maintainer applies to the sources, and it is likely to introduce 287*946379e7Schristosbugs when a newer version of <CODE>gettext</CODE> is installed on the system. 288*946379e7Schristos 289*946379e7Schristos<DT><SAMP>‘-n’</SAMP> 290*946379e7Schristos<DD> 291*946379e7Schristos<DT><SAMP>‘--dry-run’</SAMP> 292*946379e7Schristos<DD> 293*946379e7Schristos<A NAME="IDX1067"></A> 294*946379e7Schristos<A NAME="IDX1068"></A> 295*946379e7SchristosPrint modifications but don't perform them. All actions that 296*946379e7Schristos<CODE>gettextize</CODE> would normally execute are inhibited and instead only 297*946379e7Schristoslisted on standard output. 298*946379e7Schristos 299*946379e7Schristos<DT><SAMP>‘--help’</SAMP> 300*946379e7Schristos<DD> 301*946379e7Schristos<A NAME="IDX1069"></A> 302*946379e7SchristosDisplay this help and exit. 303*946379e7Schristos 304*946379e7Schristos<DT><SAMP>‘--version’</SAMP> 305*946379e7Schristos<DD> 306*946379e7Schristos<A NAME="IDX1070"></A> 307*946379e7SchristosOutput version information and exit. 308*946379e7Schristos 309*946379e7Schristos</DL> 310*946379e7Schristos 311*946379e7Schristos<P> 312*946379e7SchristosIf <VAR>directory</VAR> is given, this is the top level directory of a 313*946379e7Schristospackage to prepare for using GNU <CODE>gettext</CODE>. If not given, it 314*946379e7Schristosis assumed that the current directory is the top level directory of 315*946379e7Schristossuch a package. 316*946379e7Schristos 317*946379e7Schristos</P> 318*946379e7Schristos<P> 319*946379e7SchristosThe program <CODE>gettextize</CODE> provides the following files. However, 320*946379e7Schristosno existing file will be replaced unless the option <CODE>--force</CODE> 321*946379e7Schristos(<CODE>-f</CODE>) is specified. 322*946379e7Schristos 323*946379e7Schristos</P> 324*946379e7Schristos 325*946379e7Schristos<OL> 326*946379e7Schristos<LI> 327*946379e7Schristos 328*946379e7SchristosThe <TT>‘ABOUT-NLS’</TT> file is copied in the main directory of your package, 329*946379e7Schristosthe one being at the top level. This file gives the main indications 330*946379e7Schristosabout how to install and use the Native Language Support features 331*946379e7Schristosof your program. You might elect to use a more recent copy of this 332*946379e7Schristos<TT>‘ABOUT-NLS’</TT> file than the one provided through <CODE>gettextize</CODE>, 333*946379e7Schristosif you have one handy. You may also fetch a more recent copy of file 334*946379e7Schristos<TT>‘ABOUT-NLS’</TT> from Translation Project sites, and from most GNU 335*946379e7Schristosarchive sites. 336*946379e7Schristos 337*946379e7Schristos<LI> 338*946379e7Schristos 339*946379e7SchristosA <TT>‘po/’</TT> directory is created for eventually holding 340*946379e7Schristosall translation files, but initially only containing the file 341*946379e7Schristos<TT>‘po/Makefile.in.in’</TT> from the GNU <CODE>gettext</CODE> distribution 342*946379e7Schristos(beware the double <SAMP>‘.in’</SAMP> in the file name) and a few auxiliary 343*946379e7Schristosfiles. If the <TT>‘po/’</TT> directory already exists, it will be preserved 344*946379e7Schristosalong with the files it contains, and only <TT>‘Makefile.in.in’</TT> and 345*946379e7Schristosthe auxiliary files will be overwritten. 346*946379e7Schristos 347*946379e7Schristos<LI> 348*946379e7Schristos 349*946379e7SchristosOnly if <SAMP>‘--intl’</SAMP> has been specified: 350*946379e7SchristosA <TT>‘intl/’</TT> directory is created and filled with most of the files 351*946379e7Schristosoriginally in the <TT>‘intl/’</TT> directory of the GNU <CODE>gettext</CODE> 352*946379e7Schristosdistribution. Also, if option <CODE>--force</CODE> (<CODE>-f</CODE>) is given, 353*946379e7Schristosthe <TT>‘intl/’</TT> directory is emptied first. 354*946379e7Schristos 355*946379e7Schristos<LI> 356*946379e7Schristos 357*946379e7SchristosThe file <TT>‘config.rpath’</TT> is copied into the directory containing 358*946379e7Schristosconfiguration support files. It is needed by the <CODE>AM_GNU_GETTEXT</CODE> 359*946379e7Schristosautoconf macro. 360*946379e7Schristos 361*946379e7Schristos<LI> 362*946379e7Schristos 363*946379e7SchristosOnly if the project is using GNU <CODE>automake</CODE>: 364*946379e7SchristosA set of <CODE>autoconf</CODE> macro files is copied into the package's 365*946379e7Schristos<CODE>autoconf</CODE> macro repository, usually in a directory called <TT>‘m4/’</TT>. 366*946379e7Schristos</OL> 367*946379e7Schristos 368*946379e7Schristos<P> 369*946379e7SchristosIf your site support symbolic links, <CODE>gettextize</CODE> will not 370*946379e7Schristosactually copy the files into your package, but establish symbolic 371*946379e7Schristoslinks instead. This avoids duplicating the disk space needed in 372*946379e7Schristosall packages. Merely using the <SAMP>‘-h’</SAMP> option while creating the 373*946379e7Schristos<CODE>tar</CODE> archive of your distribution will resolve each link by an 374*946379e7Schristosactual copy in the distribution archive. So, to insist, you really 375*946379e7Schristosshould use <SAMP>‘-h’</SAMP> option with <CODE>tar</CODE> within your <CODE>dist</CODE> 376*946379e7Schristosgoal of your main <TT>‘Makefile.in’</TT>. 377*946379e7Schristos 378*946379e7Schristos</P> 379*946379e7Schristos<P> 380*946379e7SchristosFurthermore, <CODE>gettextize</CODE> will update all <TT>‘Makefile.am’</TT> files 381*946379e7Schristosin each affected directory, as well as the top level <TT>‘configure.in’</TT> 382*946379e7Schristosor <TT>‘configure.ac’</TT> file. 383*946379e7Schristos 384*946379e7Schristos</P> 385*946379e7Schristos<P> 386*946379e7SchristosIt is interesting to understand that most new files for supporting 387*946379e7SchristosGNU <CODE>gettext</CODE> facilities in one package go in <TT>‘intl/’</TT>, 388*946379e7Schristos<TT>‘po/’</TT> and <TT>‘m4/’</TT> subdirectories. One distinction between 389*946379e7Schristos<TT>‘intl/’</TT> and the two other directories is that <TT>‘intl/’</TT> is 390*946379e7Schristosmeant to be completely identical in all packages using GNU <CODE>gettext</CODE>, 391*946379e7Schristoswhile the other directories will mostly contain package dependent 392*946379e7Schristosfiles. 393*946379e7Schristos 394*946379e7Schristos</P> 395*946379e7Schristos<P> 396*946379e7SchristosThe <CODE>gettextize</CODE> program makes backup files for all files it 397*946379e7Schristosreplaces or changes, and also write ChangeLog entries about these 398*946379e7Schristoschanges. This way, the careful maintainer can check after running 399*946379e7Schristos<CODE>gettextize</CODE> whether its changes are acceptable to him, and 400*946379e7Schristospossibly adjust them. An exception to this rule is the <TT>‘intl/’</TT> 401*946379e7Schristosdirectory, which is added or replaced or removed as a whole. 402*946379e7Schristos 403*946379e7Schristos</P> 404*946379e7Schristos<P> 405*946379e7SchristosIt is important to understand that <CODE>gettextize</CODE> can not do the 406*946379e7Schristosentire job of adapting a package for using GNU <CODE>gettext</CODE>. The 407*946379e7Schristosamount of remaining work depends on whether the package uses GNU 408*946379e7Schristos<CODE>automake</CODE> or not. But in any case, the maintainer should still 409*946379e7Schristosread the section section <A HREF="gettext_13.html#SEC200">13.4 Files You Must Create or Alter</A> after invoking <CODE>gettextize</CODE>. 410*946379e7Schristos 411*946379e7Schristos</P> 412*946379e7Schristos<P> 413*946379e7SchristosIn particular, if after using <SAMP>‘gettexize’</SAMP>, you get an error 414*946379e7Schristos<SAMP>‘AC_COMPILE_IFELSE was called before AC_GNU_SOURCE’</SAMP> or 415*946379e7Schristos<SAMP>‘AC_RUN_IFELSE was called before AC_GNU_SOURCE’</SAMP>, you can fix it 416*946379e7Schristosby modifying <TT>‘configure.ac’</TT>, as described in section <A HREF="gettext_13.html#SEC205">13.4.5 <TT>‘configure.in’</TT> at top level</A>. 417*946379e7Schristos 418*946379e7Schristos</P> 419*946379e7Schristos<P> 420*946379e7SchristosIt is also important to understand that <CODE>gettextize</CODE> is not part 421*946379e7Schristosof the GNU build system, in the sense that it should not be invoked 422*946379e7Schristosautomatically, and not be invoked by someone who doesn't assume the 423*946379e7Schristosresponsibilities of a package maintainer. For the latter purpose, a 424*946379e7Schristosseparate tool is provided, see section <A HREF="gettext_13.html#SEC224">13.6.3 Invoking the <CODE>autopoint</CODE> Program</A>. 425*946379e7Schristos 426*946379e7Schristos</P> 427*946379e7Schristos 428*946379e7Schristos 429*946379e7Schristos<H2><A NAME="SEC200" HREF="gettext_toc.html#TOC200">13.4 Files You Must Create or Alter</A></H2> 430*946379e7Schristos<P> 431*946379e7Schristos<A NAME="IDX1071"></A> 432*946379e7Schristos 433*946379e7Schristos</P> 434*946379e7Schristos<P> 435*946379e7SchristosBesides files which are automatically added through <CODE>gettextize</CODE>, 436*946379e7Schristosthere are many files needing revision for properly interacting with 437*946379e7SchristosGNU <CODE>gettext</CODE>. If you are closely following GNU standards for 438*946379e7SchristosMakefile engineering and auto-configuration, the adaptations should 439*946379e7Schristosbe easier to achieve. Here is a point by point description of the 440*946379e7Schristoschanges needed in each. 441*946379e7Schristos 442*946379e7Schristos</P> 443*946379e7Schristos<P> 444*946379e7SchristosSo, here comes a list of files, each one followed by a description of 445*946379e7Schristosall alterations it needs. Many examples are taken out from the GNU 446*946379e7Schristos<CODE>gettext</CODE> 0.16.1 distribution itself, or from the GNU 447*946379e7Schristos<CODE>hello</CODE> distribution (<A HREF="http://www.franken.de/users/gnu/ke/hello">http://www.franken.de/users/gnu/ke/hello</A> 448*946379e7Schristosor <A HREF="http://www.gnu.franken.de/ke/hello/">http://www.gnu.franken.de/ke/hello/</A>) You may indeed 449*946379e7Schristosrefer to the source code of the GNU <CODE>gettext</CODE> and GNU <CODE>hello</CODE> 450*946379e7Schristospackages, as they are intended to be good examples for using GNU 451*946379e7Schristosgettext functionality. 452*946379e7Schristos 453*946379e7Schristos</P> 454*946379e7Schristos 455*946379e7Schristos 456*946379e7Schristos 457*946379e7Schristos<H3><A NAME="SEC201" HREF="gettext_toc.html#TOC201">13.4.1 <TT>‘POTFILES.in’</TT> in <TT>‘po/’</TT></A></H3> 458*946379e7Schristos<P> 459*946379e7Schristos<A NAME="IDX1072"></A> 460*946379e7Schristos 461*946379e7Schristos</P> 462*946379e7Schristos<P> 463*946379e7SchristosThe <TT>‘po/’</TT> directory should receive a file named 464*946379e7Schristos<TT>‘POTFILES.in’</TT>. This file tells which files, among all program 465*946379e7Schristossources, have marked strings needing translation. Here is an example 466*946379e7Schristosof such a file: 467*946379e7Schristos 468*946379e7Schristos</P> 469*946379e7Schristos 470*946379e7Schristos<PRE> 471*946379e7Schristos# List of source files containing translatable strings. 472*946379e7Schristos# Copyright (C) 1995 Free Software Foundation, Inc. 473*946379e7Schristos 474*946379e7Schristos# Common library files 475*946379e7Schristoslib/error.c 476*946379e7Schristoslib/getopt.c 477*946379e7Schristoslib/xmalloc.c 478*946379e7Schristos 479*946379e7Schristos# Package source files 480*946379e7Schristossrc/gettext.c 481*946379e7Schristossrc/msgfmt.c 482*946379e7Schristossrc/xgettext.c 483*946379e7Schristos</PRE> 484*946379e7Schristos 485*946379e7Schristos<P> 486*946379e7SchristosHash-marked comments and white lines are ignored. All other lines 487*946379e7Schristoslist those source files containing strings marked for translation 488*946379e7Schristos(see section <A HREF="gettext_4.html#SEC15">4.4 How Marks Appear in Sources</A>), in a notation relative to the top level 489*946379e7Schristosof your whole distribution, rather than the location of the 490*946379e7Schristos<TT>‘POTFILES.in’</TT> file itself. 491*946379e7Schristos 492*946379e7Schristos</P> 493*946379e7Schristos<P> 494*946379e7SchristosWhen a C file is automatically generated by a tool, like <CODE>flex</CODE> or 495*946379e7Schristos<CODE>bison</CODE>, that doesn't introduce translatable strings by itself, 496*946379e7Schristosit is recommended to list in <TT>‘po/POTFILES.in’</TT> the real source file 497*946379e7Schristos(ending in <TT>‘.l’</TT> in the case of <CODE>flex</CODE>, or in <TT>‘.y’</TT> in the 498*946379e7Schristoscase of <CODE>bison</CODE>), not the generated C file. 499*946379e7Schristos 500*946379e7Schristos</P> 501*946379e7Schristos 502*946379e7Schristos 503*946379e7Schristos<H3><A NAME="SEC202" HREF="gettext_toc.html#TOC202">13.4.2 <TT>‘LINGUAS’</TT> in <TT>‘po/’</TT></A></H3> 504*946379e7Schristos<P> 505*946379e7Schristos<A NAME="IDX1073"></A> 506*946379e7Schristos 507*946379e7Schristos</P> 508*946379e7Schristos<P> 509*946379e7SchristosThe <TT>‘po/’</TT> directory should also receive a file named 510*946379e7Schristos<TT>‘LINGUAS’</TT>. This file contains the list of available translations. 511*946379e7SchristosIt is a whitespace separated list. Hash-marked comments and white lines 512*946379e7Schristosare ignored. Here is an example file: 513*946379e7Schristos 514*946379e7Schristos</P> 515*946379e7Schristos 516*946379e7Schristos<PRE> 517*946379e7Schristos# Set of available languages. 518*946379e7Schristosde fr 519*946379e7Schristos</PRE> 520*946379e7Schristos 521*946379e7Schristos<P> 522*946379e7SchristosThis example means that German and French PO files are available, so 523*946379e7Schristosthat these languages are currently supported by your package. If you 524*946379e7Schristoswant to further restrict, at installation time, the set of installed 525*946379e7Schristoslanguages, this should not be done by modifying the <TT>‘LINGUAS’</TT> file, 526*946379e7Schristosbut rather by using the <CODE>LINGUAS</CODE> environment variable 527*946379e7Schristos(see section <A HREF="gettext_14.html#SEC228">14 The Installer's and Distributor's View</A>). 528*946379e7Schristos 529*946379e7Schristos</P> 530*946379e7Schristos<P> 531*946379e7SchristosIt is recommended that you add the "languages" <SAMP>‘en@quot’</SAMP> and 532*946379e7Schristos<SAMP>‘en@boldquot’</SAMP> to the <CODE>LINGUAS</CODE> file. <CODE>en@quot</CODE> is a 533*946379e7Schristosvariant of English message catalogs (<CODE>en</CODE>) which uses real quotation 534*946379e7Schristosmarks instead of the ugly looking asymmetric ASCII substitutes <SAMP>‘`’</SAMP> 535*946379e7Schristosand <SAMP>‘'’</SAMP>. <CODE>en@boldquot</CODE> is a variant of <CODE>en@quot</CODE> that 536*946379e7Schristosadditionally outputs quoted pieces of text in a bold font, when used in 537*946379e7Schristosa terminal emulator which supports the VT100 escape sequences (such as 538*946379e7Schristos<CODE>xterm</CODE> or the Linux console, but not Emacs in <KBD>M-x shell</KBD> mode). 539*946379e7Schristos 540*946379e7Schristos</P> 541*946379e7Schristos<P> 542*946379e7SchristosThese extra message catalogs <SAMP>‘en@quot’</SAMP> and <SAMP>‘en@boldquot’</SAMP> 543*946379e7Schristosare constructed automatically, not by translators; to support them, you 544*946379e7Schristosneed the files <TT>‘Rules-quot’</TT>, <TT>‘quot.sed’</TT>, <TT>‘boldquot.sed’</TT>, 545*946379e7Schristos<TT>‘en@quot.header’</TT>, <TT>‘en@boldquot.header’</TT>, <TT>‘insert-header.sin’</TT> 546*946379e7Schristosin the <TT>‘po/’</TT> directory. You can copy them from GNU gettext's <TT>‘po/’</TT> 547*946379e7Schristosdirectory; they are also installed by running <CODE>gettextize</CODE>. 548*946379e7Schristos 549*946379e7Schristos</P> 550*946379e7Schristos 551*946379e7Schristos 552*946379e7Schristos<H3><A NAME="SEC203" HREF="gettext_toc.html#TOC203">13.4.3 <TT>‘Makevars’</TT> in <TT>‘po/’</TT></A></H3> 553*946379e7Schristos<P> 554*946379e7Schristos<A NAME="IDX1074"></A> 555*946379e7Schristos 556*946379e7Schristos</P> 557*946379e7Schristos<P> 558*946379e7SchristosThe <TT>‘po/’</TT> directory also has a file named <TT>‘Makevars’</TT>. It 559*946379e7Schristoscontains variables that are specific to your project. <TT>‘po/Makevars’</TT> 560*946379e7Schristosgets inserted into the <TT>‘po/Makefile’</TT> when the latter is created. 561*946379e7SchristosThe variables thus take effect when the POT file is created or updated, 562*946379e7Schristosand when the message catalogs get installed. 563*946379e7Schristos 564*946379e7Schristos</P> 565*946379e7Schristos<P> 566*946379e7SchristosThe first three variables can be left unmodified if your package has a 567*946379e7Schristossingle message domain and, accordingly, a single <TT>‘po/’</TT> directory. 568*946379e7SchristosOnly packages which have multiple <TT>‘po/’</TT> directories at different 569*946379e7Schristoslocations need to adjust the three first variables defined in 570*946379e7Schristos<TT>‘Makevars’</TT>. 571*946379e7Schristos 572*946379e7Schristos</P> 573*946379e7Schristos 574*946379e7Schristos 575*946379e7Schristos<H3><A NAME="SEC204" HREF="gettext_toc.html#TOC204">13.4.4 Extending <TT>‘Makefile’</TT> in <TT>‘po/’</TT></A></H3> 576*946379e7Schristos<P> 577*946379e7Schristos<A NAME="IDX1075"></A> 578*946379e7Schristos 579*946379e7Schristos</P> 580*946379e7Schristos<P> 581*946379e7SchristosAll files called <TT>‘Rules-*’</TT> in the <TT>‘po/’</TT> directory get appended to 582*946379e7Schristosthe <TT>‘po/Makefile’</TT> when it is created. They present an opportunity to 583*946379e7Schristosadd rules for special PO files to the Makefile, without needing to mess 584*946379e7Schristoswith <TT>‘po/Makefile.in.in’</TT>. 585*946379e7Schristos 586*946379e7Schristos</P> 587*946379e7Schristos<P> 588*946379e7Schristos<A NAME="IDX1076"></A> 589*946379e7Schristos<A NAME="IDX1077"></A> 590*946379e7SchristosGNU gettext comes with a <TT>‘Rules-quot’</TT> file, containing rules for 591*946379e7Schristosbuilding catalogs <TT>‘en@quot.po’</TT> and <TT>‘en@boldquot.po’</TT>. The 592*946379e7Schristoseffect of <TT>‘en@quot.po’</TT> is that people who set their <CODE>LANGUAGE</CODE> 593*946379e7Schristosenvironment variable to <SAMP>‘en@quot’</SAMP> will get messages with proper 594*946379e7Schristoslooking symmetric Unicode quotation marks instead of abusing the ASCII 595*946379e7Schristosgrave accent and the ASCII apostrophe for indicating quotations. To 596*946379e7Schristosenable this catalog, simply add <CODE>en@quot</CODE> to the <TT>‘po/LINGUAS’</TT> 597*946379e7Schristosfile. The effect of <TT>‘en@boldquot.po’</TT> is that people who set 598*946379e7Schristos<CODE>LANGUAGE</CODE> to <SAMP>‘en@boldquot’</SAMP> will get not only proper quotation 599*946379e7Schristosmarks, but also the quoted text will be shown in a bold font on terminals 600*946379e7Schristosand consoles. This catalog is useful only for command-line programs, not 601*946379e7SchristosGUI programs. To enable it, similarly add <CODE>en@boldquot</CODE> to the 602*946379e7Schristos<TT>‘po/LINGUAS’</TT> file. 603*946379e7Schristos 604*946379e7Schristos</P> 605*946379e7Schristos<P> 606*946379e7SchristosSimilarly, you can create rules for building message catalogs for the 607*946379e7Schristos<TT>‘sr@latin’</TT> locale -- Serbian written with the Latin alphabet -- 608*946379e7Schristosfrom those for the <TT>‘sr’</TT> locale -- Serbian written with Cyrillic 609*946379e7Schristosletters. See section <A HREF="gettext_9.html#SEC95">9.4 Invoking the <CODE>msgfilter</CODE> Program</A>. 610*946379e7Schristos 611*946379e7Schristos</P> 612*946379e7Schristos 613*946379e7Schristos 614*946379e7Schristos<H3><A NAME="SEC205" HREF="gettext_toc.html#TOC205">13.4.5 <TT>‘configure.in’</TT> at top level</A></H3> 615*946379e7Schristos 616*946379e7Schristos<P> 617*946379e7Schristos<TT>‘configure.in’</TT> or <TT>‘configure.ac’</TT> - this is the source from which 618*946379e7Schristos<CODE>autoconf</CODE> generates the <TT>‘configure’</TT> script. 619*946379e7Schristos 620*946379e7Schristos</P> 621*946379e7Schristos 622*946379e7Schristos<OL> 623*946379e7Schristos<LI>Declare the package and version. 624*946379e7Schristos 625*946379e7Schristos<A NAME="IDX1078"></A> 626*946379e7Schristos 627*946379e7SchristosThis is done by a set of lines like these: 628*946379e7Schristos 629*946379e7Schristos 630*946379e7Schristos<PRE> 631*946379e7SchristosPACKAGE=gettext 632*946379e7SchristosVERSION=0.16.1 633*946379e7SchristosAC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE") 634*946379e7SchristosAC_DEFINE_UNQUOTED(VERSION, "$VERSION") 635*946379e7SchristosAC_SUBST(PACKAGE) 636*946379e7SchristosAC_SUBST(VERSION) 637*946379e7Schristos</PRE> 638*946379e7Schristos 639*946379e7Schristosor, if you are using GNU <CODE>automake</CODE>, by a line like this: 640*946379e7Schristos 641*946379e7Schristos 642*946379e7Schristos<PRE> 643*946379e7SchristosAM_INIT_AUTOMAKE(gettext, 0.16.1) 644*946379e7Schristos</PRE> 645*946379e7Schristos 646*946379e7SchristosOf course, you replace <SAMP>‘gettext’</SAMP> with the name of your package, 647*946379e7Schristosand <SAMP>‘0.16.1’</SAMP> by its version numbers, exactly as they 648*946379e7Schristosshould appear in the packaged <CODE>tar</CODE> file name of your distribution 649*946379e7Schristos(<TT>‘gettext-0.16.1.tar.gz’</TT>, here). 650*946379e7Schristos 651*946379e7Schristos<LI>Check for internationalization support. 652*946379e7Schristos 653*946379e7SchristosHere is the main <CODE>m4</CODE> macro for triggering internationalization 654*946379e7Schristossupport. Just add this line to <TT>‘configure.in’</TT>: 655*946379e7Schristos 656*946379e7Schristos 657*946379e7Schristos<PRE> 658*946379e7SchristosAM_GNU_GETTEXT 659*946379e7Schristos</PRE> 660*946379e7Schristos 661*946379e7SchristosThis call is purposely simple, even if it generates a lot of configure 662*946379e7Schristostime checking and actions. 663*946379e7Schristos 664*946379e7SchristosIf you have suppressed the <TT>‘intl/’</TT> subdirectory by calling 665*946379e7Schristos<CODE>gettextize</CODE> without <SAMP>‘--intl’</SAMP> option, this call should read 666*946379e7Schristos 667*946379e7Schristos 668*946379e7Schristos<PRE> 669*946379e7SchristosAM_GNU_GETTEXT([external]) 670*946379e7Schristos</PRE> 671*946379e7Schristos 672*946379e7Schristos<LI>Have output files created. 673*946379e7Schristos 674*946379e7SchristosThe <CODE>AC_OUTPUT</CODE> directive, at the end of your <TT>‘configure.in’</TT> 675*946379e7Schristosfile, needs to be modified in two ways: 676*946379e7Schristos 677*946379e7Schristos 678*946379e7Schristos<PRE> 679*946379e7SchristosAC_OUTPUT([<VAR>existing configuration files</VAR> intl/Makefile po/Makefile.in], 680*946379e7Schristos[<VAR>existing additional actions</VAR>]) 681*946379e7Schristos</PRE> 682*946379e7Schristos 683*946379e7SchristosThe modification to the first argument to <CODE>AC_OUTPUT</CODE> asks 684*946379e7Schristosfor substitution in the <TT>‘intl/’</TT> and <TT>‘po/’</TT> directories. 685*946379e7SchristosNote the <SAMP>‘.in’</SAMP> suffix used for <TT>‘po/’</TT> only. This is because 686*946379e7Schristosthe distributed file is really <TT>‘po/Makefile.in.in’</TT>. 687*946379e7Schristos 688*946379e7SchristosIf you have suppressed the <TT>‘intl/’</TT> subdirectory by calling 689*946379e7Schristos<CODE>gettextize</CODE> without <SAMP>‘--intl’</SAMP> option, then you don't need to 690*946379e7Schristosadd <CODE>intl/Makefile</CODE> to the <CODE>AC_OUTPUT</CODE> line. 691*946379e7Schristos 692*946379e7Schristos</OL> 693*946379e7Schristos 694*946379e7Schristos<P> 695*946379e7SchristosIf, after doing the recommended modifications, a command like 696*946379e7Schristos<SAMP>‘aclocal -I m4’</SAMP> or <SAMP>‘autoconf’</SAMP> or <SAMP>‘autoreconf’</SAMP> fails with 697*946379e7Schristosa trace similar to this: 698*946379e7Schristos 699*946379e7Schristos</P> 700*946379e7Schristos 701*946379e7Schristos<PRE> 702*946379e7Schristosconfigure.ac:44: warning: AC_COMPILE_IFELSE was called before AC_GNU_SOURCE 703*946379e7Schristos../../lib/autoconf/specific.m4:335: AC_GNU_SOURCE is expanded from... 704*946379e7Schristosm4/lock.m4:224: gl_LOCK is expanded from... 705*946379e7Schristosm4/gettext.m4:571: gt_INTL_SUBDIR_CORE is expanded from... 706*946379e7Schristosm4/gettext.m4:472: AM_INTL_SUBDIR is expanded from... 707*946379e7Schristosm4/gettext.m4:347: AM_GNU_GETTEXT is expanded from... 708*946379e7Schristosconfigure.ac:44: the top level 709*946379e7Schristosconfigure.ac:44: warning: AC_RUN_IFELSE was called before AC_GNU_SOURCE 710*946379e7Schristos</PRE> 711*946379e7Schristos 712*946379e7Schristos<P> 713*946379e7Schristosyou need to add an explicit invocation of <SAMP>‘AC_GNU_SOURCE’</SAMP> in the 714*946379e7Schristos<TT>‘configure.ac’</TT> file - after <SAMP>‘AC_PROG_CC’</SAMP> but before 715*946379e7Schristos<SAMP>‘AM_GNU_GETTEXT’</SAMP>, most likely very close to the <SAMP>‘AC_PROG_CC’</SAMP> 716*946379e7Schristosinvocation. This is necessary because of ordering restrictions imposed 717*946379e7Schristosby GNU autoconf. 718*946379e7Schristos 719*946379e7Schristos</P> 720*946379e7Schristos 721*946379e7Schristos 722*946379e7Schristos<H3><A NAME="SEC206" HREF="gettext_toc.html#TOC206">13.4.6 <TT>‘config.guess’</TT>, <TT>‘config.sub’</TT> at top level</A></H3> 723*946379e7Schristos 724*946379e7Schristos<P> 725*946379e7SchristosIf you haven't suppressed the <TT>‘intl/’</TT> subdirectory, 726*946379e7Schristosyou need to add the GNU <TT>‘config.guess’</TT> and <TT>‘config.sub’</TT> files 727*946379e7Schristosto your distribution. They are needed because the <TT>‘intl/’</TT> directory 728*946379e7Schristoshas platform dependent support for determining the locale's character 729*946379e7Schristosencoding and therefore needs to identify the platform. 730*946379e7Schristos 731*946379e7Schristos</P> 732*946379e7Schristos<P> 733*946379e7SchristosYou can obtain the newest version of <TT>‘config.guess’</TT> and 734*946379e7Schristos<TT>‘config.sub’</TT> from the CVS of the <SAMP>‘config’</SAMP> project at 735*946379e7Schristos<TT>‘http://savannah.gnu.org/’</TT>. The commands to fetch them are 736*946379e7Schristos 737*946379e7Schristos<PRE> 738*946379e7Schristos$ wget 'http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.guess' 739*946379e7Schristos$ wget 'http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.sub' 740*946379e7Schristos</PRE> 741*946379e7Schristos 742*946379e7Schristos<P> 743*946379e7SchristosLess recent versions are also contained in the GNU <CODE>automake</CODE> and 744*946379e7SchristosGNU <CODE>libtool</CODE> packages. 745*946379e7Schristos 746*946379e7Schristos</P> 747*946379e7Schristos<P> 748*946379e7SchristosNormally, <TT>‘config.guess’</TT> and <TT>‘config.sub’</TT> are put at the 749*946379e7Schristostop level of a distribution. But it is also possible to put them in a 750*946379e7Schristossubdirectory, altogether with other configuration support files like 751*946379e7Schristos<TT>‘install-sh’</TT>, <TT>‘ltconfig’</TT>, <TT>‘ltmain.sh’</TT> or <TT>‘missing’</TT>. 752*946379e7SchristosAll you need to do, other than moving the files, is to add the following line 753*946379e7Schristosto your <TT>‘configure.in’</TT>. 754*946379e7Schristos 755*946379e7Schristos</P> 756*946379e7Schristos 757*946379e7Schristos<PRE> 758*946379e7SchristosAC_CONFIG_AUX_DIR([<VAR>subdir</VAR>]) 759*946379e7Schristos</PRE> 760*946379e7Schristos 761*946379e7Schristos 762*946379e7Schristos 763*946379e7Schristos<H3><A NAME="SEC207" HREF="gettext_toc.html#TOC207">13.4.7 <TT>‘mkinstalldirs’</TT> at top level</A></H3> 764*946379e7Schristos<P> 765*946379e7Schristos<A NAME="IDX1079"></A> 766*946379e7Schristos 767*946379e7Schristos</P> 768*946379e7Schristos<P> 769*946379e7SchristosWith earlier versions of GNU gettext, you needed to add the GNU 770*946379e7Schristos<TT>‘mkinstalldirs’</TT> script to your distribution. This is not needed any 771*946379e7Schristosmore. You can remove it if you not also using an automake version older than 772*946379e7Schristosautomake 1.9. 773*946379e7Schristos 774*946379e7Schristos</P> 775*946379e7Schristos 776*946379e7Schristos 777*946379e7Schristos<H3><A NAME="SEC208" HREF="gettext_toc.html#TOC208">13.4.8 <TT>‘aclocal.m4’</TT> at top level</A></H3> 778*946379e7Schristos<P> 779*946379e7Schristos<A NAME="IDX1080"></A> 780*946379e7Schristos 781*946379e7Schristos</P> 782*946379e7Schristos<P> 783*946379e7SchristosIf you do not have an <TT>‘aclocal.m4’</TT> file in your distribution, 784*946379e7Schristosthe simplest is to concatenate the files <TT>‘codeset.m4’</TT>, 785*946379e7Schristos<TT>‘gettext.m4’</TT>, <TT>‘glibc2.m4’</TT>, <TT>‘glibc21.m4’</TT>, <TT>‘iconv.m4’</TT>, 786*946379e7Schristos<TT>‘intdiv0.m4’</TT>, <TT>‘intl.m4’</TT>, <TT>‘intldir.m4’</TT>, <TT>‘intmax.m4’</TT>, 787*946379e7Schristos<TT>‘inttypes_h.m4’</TT>, <TT>‘inttypes-pri.m4’</TT>, <TT>‘lcmessage.m4’</TT>, 788*946379e7Schristos<TT>‘lib-ld.m4’</TT>, <TT>‘lib-link.m4’</TT>, <TT>‘lib-prefix.m4’</TT>, <TT>‘lock.m4’</TT>, 789*946379e7Schristos<TT>‘longdouble.m4’</TT>, <TT>‘longlong.m4’</TT>, <TT>‘nls.m4’</TT>, <TT>‘po.m4’</TT>, 790*946379e7Schristos<TT>‘printf-posix.m4’</TT>, <TT>‘progtest.m4’</TT>, <TT>‘size_max.m4’</TT>, 791*946379e7Schristos<TT>‘stdint_h.m4’</TT>, <TT>‘uintmax_t.m4’</TT>, <TT>‘ulonglong.m4’</TT>, 792*946379e7Schristos<TT>‘visibility.m4’</TT>, <TT>‘wchar_t.m4’</TT>, <TT>‘wint_t.m4’</TT>, <TT>‘xsize.m4’</TT> 793*946379e7Schristosfrom GNU <CODE>gettext</CODE>'s 794*946379e7Schristos<TT>‘m4/’</TT> directory into a single file. If you have suppressed the 795*946379e7Schristos<TT>‘intl/’</TT> directory, only <TT>‘gettext.m4’</TT>, <TT>‘iconv.m4’</TT>, 796*946379e7Schristos<TT>‘lib-ld.m4’</TT>, <TT>‘lib-link.m4’</TT>, <TT>‘lib-prefix.m4’</TT>, 797*946379e7Schristos<TT>‘nls.m4’</TT>, <TT>‘po.m4’</TT>, <TT>‘progtest.m4’</TT> need to be concatenated. 798*946379e7Schristos 799*946379e7Schristos</P> 800*946379e7Schristos<P> 801*946379e7SchristosIf you are not using GNU <CODE>automake</CODE> 1.8 or newer, you will need to 802*946379e7Schristosadd a file <TT>‘mkdirp.m4’</TT> from a newer automake distribution to the 803*946379e7Schristoslist of files above. 804*946379e7Schristos 805*946379e7Schristos</P> 806*946379e7Schristos<P> 807*946379e7SchristosIf you already have an <TT>‘aclocal.m4’</TT> file, then you will have 808*946379e7Schristosto merge the said macro files into your <TT>‘aclocal.m4’</TT>. Note that if 809*946379e7Schristosyou are upgrading from a previous release of GNU <CODE>gettext</CODE>, you 810*946379e7Schristosshould most probably <EM>replace</EM> the macros (<CODE>AM_GNU_GETTEXT</CODE>, 811*946379e7Schristosetc.), as they usually 812*946379e7Schristoschange a little from one release of GNU <CODE>gettext</CODE> to the next. 813*946379e7SchristosTheir contents may vary as we get more experience with strange systems 814*946379e7Schristosout there. 815*946379e7Schristos 816*946379e7Schristos</P> 817*946379e7Schristos<P> 818*946379e7SchristosIf you are using GNU <CODE>automake</CODE> 1.5 or newer, it is enough to put 819*946379e7Schristosthese macro files into a subdirectory named <TT>‘m4/’</TT> and add the line 820*946379e7Schristos 821*946379e7Schristos</P> 822*946379e7Schristos 823*946379e7Schristos<PRE> 824*946379e7SchristosACLOCAL_AMFLAGS = -I m4 825*946379e7Schristos</PRE> 826*946379e7Schristos 827*946379e7Schristos<P> 828*946379e7Schristosto your top level <TT>‘Makefile.am’</TT>. 829*946379e7Schristos 830*946379e7Schristos</P> 831*946379e7Schristos<P> 832*946379e7SchristosThese macros check for the internationalization support functions 833*946379e7Schristosand related informations. Hopefully, once stabilized, these macros 834*946379e7Schristosmight be integrated in the standard Autoconf set, because this 835*946379e7Schristospiece of <CODE>m4</CODE> code will be the same for all projects using GNU 836*946379e7Schristos<CODE>gettext</CODE>. 837*946379e7Schristos 838*946379e7Schristos</P> 839*946379e7Schristos 840*946379e7Schristos 841*946379e7Schristos<H3><A NAME="SEC209" HREF="gettext_toc.html#TOC209">13.4.9 <TT>‘acconfig.h’</TT> at top level</A></H3> 842*946379e7Schristos<P> 843*946379e7Schristos<A NAME="IDX1081"></A> 844*946379e7Schristos 845*946379e7Schristos</P> 846*946379e7Schristos<P> 847*946379e7SchristosEarlier GNU <CODE>gettext</CODE> releases required to put definitions for 848*946379e7Schristos<CODE>ENABLE_NLS</CODE>, <CODE>HAVE_GETTEXT</CODE> and <CODE>HAVE_LC_MESSAGES</CODE>, 849*946379e7Schristos<CODE>HAVE_STPCPY</CODE>, <CODE>PACKAGE</CODE> and <CODE>VERSION</CODE> into an 850*946379e7Schristos<TT>‘acconfig.h’</TT> file. This is not needed any more; you can remove 851*946379e7Schristosthem from your <TT>‘acconfig.h’</TT> file unless your package uses them 852*946379e7Schristosindependently from the <TT>‘intl/’</TT> directory. 853*946379e7Schristos 854*946379e7Schristos</P> 855*946379e7Schristos 856*946379e7Schristos 857*946379e7Schristos<H3><A NAME="SEC210" HREF="gettext_toc.html#TOC210">13.4.10 <TT>‘config.h.in’</TT> at top level</A></H3> 858*946379e7Schristos<P> 859*946379e7Schristos<A NAME="IDX1082"></A> 860*946379e7Schristos 861*946379e7Schristos</P> 862*946379e7Schristos<P> 863*946379e7SchristosThe include file template that holds the C macros to be defined by 864*946379e7Schristos<CODE>configure</CODE> is usually called <TT>‘config.h.in’</TT> and may be 865*946379e7Schristosmaintained either manually or automatically. 866*946379e7Schristos 867*946379e7Schristos</P> 868*946379e7Schristos<P> 869*946379e7SchristosIf <CODE>gettextize</CODE> has created an <TT>‘intl/’</TT> directory, this file 870*946379e7Schristosmust be called <TT>‘config.h.in’</TT> and must be at the top level. If, 871*946379e7Schristoshowever, you have suppressed the <TT>‘intl/’</TT> directory by calling 872*946379e7Schristos<CODE>gettextize</CODE> without <SAMP>‘--intl’</SAMP> option, then you can choose the 873*946379e7Schristosname of this file and its location freely. 874*946379e7Schristos 875*946379e7Schristos</P> 876*946379e7Schristos<P> 877*946379e7SchristosIf it is maintained automatically, by use of the <SAMP>‘autoheader’</SAMP> 878*946379e7Schristosprogram, you need to do nothing about it. This is the case in particular 879*946379e7Schristosif you are using GNU <CODE>automake</CODE>. 880*946379e7Schristos 881*946379e7Schristos</P> 882*946379e7Schristos<P> 883*946379e7SchristosIf it is maintained manually, and if <CODE>gettextize</CODE> has created an 884*946379e7Schristos<TT>‘intl/’</TT> directory, you should switch to using <SAMP>‘autoheader’</SAMP>. 885*946379e7SchristosThe list of C macros to be added for the sake of the <TT>‘intl/’</TT> 886*946379e7Schristosdirectory is just too long to be maintained manually; it also changes 887*946379e7Schristosbetween different versions of GNU <CODE>gettext</CODE>. 888*946379e7Schristos 889*946379e7Schristos</P> 890*946379e7Schristos<P> 891*946379e7SchristosIf it is maintained manually, and if on the other hand you have 892*946379e7Schristossuppressed the <TT>‘intl/’</TT> directory by calling <CODE>gettextize</CODE> 893*946379e7Schristoswithout <SAMP>‘--intl’</SAMP> option, then you can get away by adding the 894*946379e7Schristosfollowing lines to <TT>‘config.h.in’</TT>: 895*946379e7Schristos 896*946379e7Schristos</P> 897*946379e7Schristos 898*946379e7Schristos<PRE> 899*946379e7Schristos/* Define to 1 if translation of program messages to the user's 900*946379e7Schristos native language is requested. */ 901*946379e7Schristos#undef ENABLE_NLS 902*946379e7Schristos</PRE> 903*946379e7Schristos 904*946379e7Schristos 905*946379e7Schristos 906*946379e7Schristos<H3><A NAME="SEC211" HREF="gettext_toc.html#TOC211">13.4.11 <TT>‘Makefile.in’</TT> at top level</A></H3> 907*946379e7Schristos 908*946379e7Schristos<P> 909*946379e7SchristosHere are a few modifications you need to make to your main, top-level 910*946379e7Schristos<TT>‘Makefile.in’</TT> file. 911*946379e7Schristos 912*946379e7Schristos</P> 913*946379e7Schristos 914*946379e7Schristos<OL> 915*946379e7Schristos<LI> 916*946379e7Schristos 917*946379e7SchristosAdd the following lines near the beginning of your <TT>‘Makefile.in’</TT>, 918*946379e7Schristosso the <SAMP>‘dist:’</SAMP> goal will work properly (as explained further down): 919*946379e7Schristos 920*946379e7Schristos 921*946379e7Schristos<PRE> 922*946379e7SchristosPACKAGE = @PACKAGE@ 923*946379e7SchristosVERSION = @VERSION@ 924*946379e7Schristos</PRE> 925*946379e7Schristos 926*946379e7Schristos<LI> 927*946379e7Schristos 928*946379e7SchristosAdd file <TT>‘ABOUT-NLS’</TT> to the <CODE>DISTFILES</CODE> definition, so the file gets 929*946379e7Schristosdistributed. 930*946379e7Schristos 931*946379e7Schristos<LI> 932*946379e7Schristos 933*946379e7SchristosWherever you process subdirectories in your <TT>‘Makefile.in’</TT>, be sure 934*946379e7Schristosyou also process the subdirectories <SAMP>‘intl’</SAMP> and <SAMP>‘po’</SAMP>. Special 935*946379e7Schristosrules in the <TT>‘Makefiles’</TT> take care for the case where no 936*946379e7Schristosinternationalization is wanted. 937*946379e7Schristos 938*946379e7SchristosIf you are using Makefiles, either generated by automake, or hand-written 939*946379e7Schristosso they carefully follow the GNU coding standards, the effected goals for 940*946379e7Schristoswhich the new subdirectories must be handled include <SAMP>‘installdirs’</SAMP>, 941*946379e7Schristos<SAMP>‘install’</SAMP>, <SAMP>‘uninstall’</SAMP>, <SAMP>‘clean’</SAMP>, <SAMP>‘distclean’</SAMP>. 942*946379e7Schristos 943*946379e7SchristosHere is an example of a canonical order of processing. In this 944*946379e7Schristosexample, we also define <CODE>SUBDIRS</CODE> in <CODE>Makefile.in</CODE> for it 945*946379e7Schristosto be further used in the <SAMP>‘dist:’</SAMP> goal. 946*946379e7Schristos 947*946379e7Schristos 948*946379e7Schristos<PRE> 949*946379e7SchristosSUBDIRS = doc intl lib src po 950*946379e7Schristos</PRE> 951*946379e7Schristos 952*946379e7SchristosNote that you must arrange for <SAMP>‘make’</SAMP> to descend into the 953*946379e7Schristos<CODE>intl</CODE> directory before descending into other directories containing 954*946379e7Schristoscode which make use of the <CODE>libintl.h</CODE> header file. For this 955*946379e7Schristosreason, here we mention <CODE>intl</CODE> before <CODE>lib</CODE> and <CODE>src</CODE>. 956*946379e7Schristos 957*946379e7Schristos<LI> 958*946379e7Schristos 959*946379e7SchristosA delicate point is the <SAMP>‘dist:’</SAMP> goal, as both 960*946379e7Schristos<TT>‘intl/Makefile’</TT> and <TT>‘po/Makefile’</TT> will later assume that the 961*946379e7Schristosproper directory has been set up from the main <TT>‘Makefile’</TT>. Here is 962*946379e7Schristosan example at what the <SAMP>‘dist:’</SAMP> goal might look like: 963*946379e7Schristos 964*946379e7Schristos 965*946379e7Schristos<PRE> 966*946379e7Schristosdistdir = $(PACKAGE)-$(VERSION) 967*946379e7Schristosdist: Makefile 968*946379e7Schristos rm -fr $(distdir) 969*946379e7Schristos mkdir $(distdir) 970*946379e7Schristos chmod 777 $(distdir) 971*946379e7Schristos for file in $(DISTFILES); do \ 972*946379e7Schristos ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \ 973*946379e7Schristos done 974*946379e7Schristos for subdir in $(SUBDIRS); do \ 975*946379e7Schristos mkdir $(distdir)/$$subdir || exit 1; \ 976*946379e7Schristos chmod 777 $(distdir)/$$subdir; \ 977*946379e7Schristos (cd $$subdir && $(MAKE) $@) || exit 1; \ 978*946379e7Schristos done 979*946379e7Schristos tar chozf $(distdir).tar.gz $(distdir) 980*946379e7Schristos rm -fr $(distdir) 981*946379e7Schristos</PRE> 982*946379e7Schristos 983*946379e7Schristos</OL> 984*946379e7Schristos 985*946379e7Schristos<P> 986*946379e7SchristosNote that if you are using GNU <CODE>automake</CODE>, <TT>‘Makefile.in’</TT> is 987*946379e7Schristosautomatically generated from <TT>‘Makefile.am’</TT>, and all needed changes 988*946379e7Schristosto <TT>‘Makefile.am’</TT> are already made by running <SAMP>‘gettextize’</SAMP>. 989*946379e7Schristos 990*946379e7Schristos</P> 991*946379e7Schristos 992*946379e7Schristos 993*946379e7Schristos<H3><A NAME="SEC212" HREF="gettext_toc.html#TOC212">13.4.12 <TT>‘Makefile.in’</TT> in <TT>‘src/’</TT></A></H3> 994*946379e7Schristos 995*946379e7Schristos<P> 996*946379e7SchristosSome of the modifications made in the main <TT>‘Makefile.in’</TT> will 997*946379e7Schristosalso be needed in the <TT>‘Makefile.in’</TT> from your package sources, 998*946379e7Schristoswhich we assume here to be in the <TT>‘src/’</TT> subdirectory. Here are 999*946379e7Schristosall the modifications needed in <TT>‘src/Makefile.in’</TT>: 1000*946379e7Schristos 1001*946379e7Schristos</P> 1002*946379e7Schristos 1003*946379e7Schristos<OL> 1004*946379e7Schristos<LI> 1005*946379e7Schristos 1006*946379e7SchristosIn view of the <SAMP>‘dist:’</SAMP> goal, you should have these lines near the 1007*946379e7Schristosbeginning of <TT>‘src/Makefile.in’</TT>: 1008*946379e7Schristos 1009*946379e7Schristos 1010*946379e7Schristos<PRE> 1011*946379e7SchristosPACKAGE = @PACKAGE@ 1012*946379e7SchristosVERSION = @VERSION@ 1013*946379e7Schristos</PRE> 1014*946379e7Schristos 1015*946379e7Schristos<LI> 1016*946379e7Schristos 1017*946379e7SchristosIf not done already, you should guarantee that <CODE>top_srcdir</CODE> 1018*946379e7Schristosgets defined. This will serve for <CODE>cpp</CODE> include files. Just add 1019*946379e7Schristosthe line: 1020*946379e7Schristos 1021*946379e7Schristos 1022*946379e7Schristos<PRE> 1023*946379e7Schristostop_srcdir = @top_srcdir@ 1024*946379e7Schristos</PRE> 1025*946379e7Schristos 1026*946379e7Schristos<LI> 1027*946379e7Schristos 1028*946379e7SchristosYou might also want to define <CODE>subdir</CODE> as <SAMP>‘src’</SAMP>, later 1029*946379e7Schristosallowing for almost uniform <SAMP>‘dist:’</SAMP> goals in all your 1030*946379e7Schristos<TT>‘Makefile.in’</TT>. At list, the <SAMP>‘dist:’</SAMP> goal below assume that 1031*946379e7Schristosyou used: 1032*946379e7Schristos 1033*946379e7Schristos 1034*946379e7Schristos<PRE> 1035*946379e7Schristossubdir = src 1036*946379e7Schristos</PRE> 1037*946379e7Schristos 1038*946379e7Schristos<LI> 1039*946379e7Schristos 1040*946379e7SchristosThe <CODE>main</CODE> function of your program will normally call 1041*946379e7Schristos<CODE>bindtextdomain</CODE> (see see section <A HREF="gettext_4.html#SEC13">4.2 Triggering <CODE>gettext</CODE> Operations</A>), like this: 1042*946379e7Schristos 1043*946379e7Schristos 1044*946379e7Schristos<PRE> 1045*946379e7Schristosbindtextdomain (<VAR>PACKAGE</VAR>, LOCALEDIR); 1046*946379e7Schristostextdomain (<VAR>PACKAGE</VAR>); 1047*946379e7Schristos</PRE> 1048*946379e7Schristos 1049*946379e7SchristosTo make LOCALEDIR known to the program, add the following lines to 1050*946379e7Schristos<TT>‘Makefile.in’</TT>: 1051*946379e7Schristos 1052*946379e7Schristos 1053*946379e7Schristos<PRE> 1054*946379e7Schristosdatadir = @datadir@ 1055*946379e7Schristoslocaledir = $(datadir)/locale 1056*946379e7SchristosDEFS = -DLOCALEDIR=\"$(localedir)\" @DEFS@ 1057*946379e7Schristos</PRE> 1058*946379e7Schristos 1059*946379e7SchristosNote that <CODE>@datadir@</CODE> defaults to <SAMP>‘$(prefix)/share’</SAMP>, thus 1060*946379e7Schristos<CODE>$(localedir)</CODE> defaults to <SAMP>‘$(prefix)/share/locale’</SAMP>. 1061*946379e7Schristos 1062*946379e7Schristos<LI> 1063*946379e7Schristos 1064*946379e7SchristosYou should ensure that the final linking will use <CODE>@LIBINTL@</CODE> or 1065*946379e7Schristos<CODE>@LTLIBINTL@</CODE> as a library. <CODE>@LIBINTL@</CODE> is for use without 1066*946379e7Schristos<CODE>libtool</CODE>, <CODE>@LTLIBINTL@</CODE> is for use with <CODE>libtool</CODE>. An 1067*946379e7Schristoseasy way to achieve this is to manage that it gets into <CODE>LIBS</CODE>, like 1068*946379e7Schristosthis: 1069*946379e7Schristos 1070*946379e7Schristos 1071*946379e7Schristos<PRE> 1072*946379e7SchristosLIBS = @LIBINTL@ @LIBS@ 1073*946379e7Schristos</PRE> 1074*946379e7Schristos 1075*946379e7SchristosIn most packages internationalized with GNU <CODE>gettext</CODE>, one will 1076*946379e7Schristosfind a directory <TT>‘lib/’</TT> in which a library containing some helper 1077*946379e7Schristosfunctions will be build. (You need at least the few functions which the 1078*946379e7SchristosGNU <CODE>gettext</CODE> Library itself needs.) However some of the functions 1079*946379e7Schristosin the <TT>‘lib/’</TT> also give messages to the user which of course should be 1080*946379e7Schristostranslated, too. Taking care of this, the support library (say 1081*946379e7Schristos<TT>‘libsupport.a’</TT>) should be placed before <CODE>@LIBINTL@</CODE> and 1082*946379e7Schristos<CODE>@LIBS@</CODE> in the above example. So one has to write this: 1083*946379e7Schristos 1084*946379e7Schristos 1085*946379e7Schristos<PRE> 1086*946379e7SchristosLIBS = ../lib/libsupport.a @LIBINTL@ @LIBS@ 1087*946379e7Schristos</PRE> 1088*946379e7Schristos 1089*946379e7Schristos<LI> 1090*946379e7Schristos 1091*946379e7SchristosYou should also ensure that directory <TT>‘intl/’</TT> will be searched for 1092*946379e7SchristosC preprocessor include files in all circumstances. So, you have to 1093*946379e7Schristosmanage so both <SAMP>‘-I../intl’</SAMP> and <SAMP>‘-I$(top_srcdir)/intl’</SAMP> will 1094*946379e7Schristosbe given to the C compiler. 1095*946379e7Schristos 1096*946379e7Schristos<LI> 1097*946379e7Schristos 1098*946379e7SchristosYour <SAMP>‘dist:’</SAMP> goal has to conform with others. Here is a 1099*946379e7Schristosreasonable definition for it: 1100*946379e7Schristos 1101*946379e7Schristos 1102*946379e7Schristos<PRE> 1103*946379e7Schristosdistdir = ../$(PACKAGE)-$(VERSION)/$(subdir) 1104*946379e7Schristosdist: Makefile $(DISTFILES) 1105*946379e7Schristos for file in $(DISTFILES); do \ 1106*946379e7Schristos ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir) || exit 1; \ 1107*946379e7Schristos done 1108*946379e7Schristos</PRE> 1109*946379e7Schristos 1110*946379e7Schristos</OL> 1111*946379e7Schristos 1112*946379e7Schristos<P> 1113*946379e7SchristosNote that if you are using GNU <CODE>automake</CODE>, <TT>‘Makefile.in’</TT> is 1114*946379e7Schristosautomatically generated from <TT>‘Makefile.am’</TT>, and the first three 1115*946379e7Schristoschanges and the last change are not necessary. The remaining needed 1116*946379e7Schristos<TT>‘Makefile.am’</TT> modifications are the following: 1117*946379e7Schristos 1118*946379e7Schristos</P> 1119*946379e7Schristos 1120*946379e7Schristos<OL> 1121*946379e7Schristos<LI> 1122*946379e7Schristos 1123*946379e7SchristosTo make LOCALEDIR known to the program, add the following to 1124*946379e7Schristos<TT>‘Makefile.am’</TT>: 1125*946379e7Schristos 1126*946379e7Schristos 1127*946379e7Schristos<PRE> 1128*946379e7Schristos<module>_CPPFLAGS = -DLOCALEDIR=\"$(localedir)\" 1129*946379e7Schristos</PRE> 1130*946379e7Schristos 1131*946379e7Schristosfor each specific module or compilation unit, or 1132*946379e7Schristos 1133*946379e7Schristos 1134*946379e7Schristos<PRE> 1135*946379e7SchristosAM_CPPFLAGS = -DLOCALEDIR=\"$(localedir)\" 1136*946379e7Schristos</PRE> 1137*946379e7Schristos 1138*946379e7Schristosfor all modules and compilation units together. Furthermore, add this 1139*946379e7Schristosline to define <SAMP>‘localedir’</SAMP>: 1140*946379e7Schristos 1141*946379e7Schristos 1142*946379e7Schristos<PRE> 1143*946379e7Schristoslocaledir = $(datadir)/locale 1144*946379e7Schristos</PRE> 1145*946379e7Schristos 1146*946379e7Schristos<LI> 1147*946379e7Schristos 1148*946379e7SchristosTo ensure that the final linking will use <CODE>@LIBINTL@</CODE> or 1149*946379e7Schristos<CODE>@LTLIBINTL@</CODE> as a library, add the following to 1150*946379e7Schristos<TT>‘Makefile.am’</TT>: 1151*946379e7Schristos 1152*946379e7Schristos 1153*946379e7Schristos<PRE> 1154*946379e7Schristos<program>_LDADD = @LIBINTL@ 1155*946379e7Schristos</PRE> 1156*946379e7Schristos 1157*946379e7Schristosfor each specific program, or 1158*946379e7Schristos 1159*946379e7Schristos 1160*946379e7Schristos<PRE> 1161*946379e7SchristosLDADD = @LIBINTL@ 1162*946379e7Schristos</PRE> 1163*946379e7Schristos 1164*946379e7Schristosfor all programs together. Remember that when you use <CODE>libtool</CODE> 1165*946379e7Schristosto link a program, you need to use @LTLIBINTL@ instead of @LIBINTL@ 1166*946379e7Schristosfor that program. 1167*946379e7Schristos 1168*946379e7Schristos<LI> 1169*946379e7Schristos 1170*946379e7SchristosIf you have an <TT>‘intl/’</TT> directory, whose contents is created by 1171*946379e7Schristos<CODE>gettextize</CODE>, then to ensure that it will be searched for 1172*946379e7SchristosC preprocessor include files in all circumstances, add something like 1173*946379e7Schristosthis to <TT>‘Makefile.am’</TT>: 1174*946379e7Schristos 1175*946379e7Schristos 1176*946379e7Schristos<PRE> 1177*946379e7SchristosAM_CPPFLAGS = -I../intl -I$(top_srcdir)/intl 1178*946379e7Schristos</PRE> 1179*946379e7Schristos 1180*946379e7Schristos</OL> 1181*946379e7Schristos 1182*946379e7Schristos 1183*946379e7Schristos 1184*946379e7Schristos<H3><A NAME="SEC213" HREF="gettext_toc.html#TOC213">13.4.13 <TT>‘gettext.h’</TT> in <TT>‘lib/’</TT></A></H3> 1185*946379e7Schristos<P> 1186*946379e7Schristos<A NAME="IDX1083"></A> 1187*946379e7Schristos<A NAME="IDX1084"></A> 1188*946379e7Schristos<A NAME="IDX1085"></A> 1189*946379e7Schristos 1190*946379e7Schristos</P> 1191*946379e7Schristos<P> 1192*946379e7SchristosInternationalization of packages, as provided by GNU <CODE>gettext</CODE>, is 1193*946379e7Schristosoptional. It can be turned off in two situations: 1194*946379e7Schristos 1195*946379e7Schristos</P> 1196*946379e7Schristos 1197*946379e7Schristos<UL> 1198*946379e7Schristos<LI> 1199*946379e7Schristos 1200*946379e7SchristosWhen the installer has specified <SAMP>‘./configure --disable-nls’</SAMP>. This 1201*946379e7Schristoscan be useful when small binaries are more important than features, for 1202*946379e7Schristosexample when building utilities for boot diskettes. It can also be useful 1203*946379e7Schristosin order to get some specific C compiler warnings about code quality with 1204*946379e7Schristossome older versions of GCC (older than 3.0). 1205*946379e7Schristos 1206*946379e7Schristos<LI> 1207*946379e7Schristos 1208*946379e7SchristosWhen the package does not include the <CODE>intl/</CODE> subdirectory, and the 1209*946379e7Schristoslibintl.h header (with its associated libintl library, if any) is not 1210*946379e7Schristosalready installed on the system, it is preferable that the package builds 1211*946379e7Schristoswithout internationalization support, rather than to give a compilation 1212*946379e7Schristoserror. 1213*946379e7Schristos</UL> 1214*946379e7Schristos 1215*946379e7Schristos<P> 1216*946379e7SchristosA C preprocessor macro can be used to detect these two cases. Usually, 1217*946379e7Schristoswhen <CODE>libintl.h</CODE> was found and not explicitly disabled, the 1218*946379e7Schristos<CODE>ENABLE_NLS</CODE> macro will be defined to 1 in the autoconf generated 1219*946379e7Schristosconfiguration file (usually called <TT>‘config.h’</TT>). In the two negative 1220*946379e7Schristossituations, however, this macro will not be defined, thus it will evaluate 1221*946379e7Schristosto 0 in C preprocessor expressions. 1222*946379e7Schristos 1223*946379e7Schristos</P> 1224*946379e7Schristos<P> 1225*946379e7Schristos<A NAME="IDX1086"></A> 1226*946379e7Schristos<TT>‘gettext.h’</TT> is a convenience header file for conditional use of 1227*946379e7Schristos<TT>‘<libintl.h>’</TT>, depending on the <CODE>ENABLE_NLS</CODE> macro. If 1228*946379e7Schristos<CODE>ENABLE_NLS</CODE> is set, it includes <TT>‘<libintl.h>’</TT>; otherwise it 1229*946379e7Schristosdefines no-op substitutes for the libintl.h functions. We recommend 1230*946379e7Schristosthe use of <CODE>"gettext.h"</CODE> over direct use of <TT>‘<libintl.h>’</TT>, 1231*946379e7Schristosso that portability to older systems is guaranteed and installers can 1232*946379e7Schristosturn off internationalization if they want to. In the C code, you will 1233*946379e7Schristosthen write 1234*946379e7Schristos 1235*946379e7Schristos</P> 1236*946379e7Schristos 1237*946379e7Schristos<PRE> 1238*946379e7Schristos#include "gettext.h" 1239*946379e7Schristos</PRE> 1240*946379e7Schristos 1241*946379e7Schristos<P> 1242*946379e7Schristosinstead of 1243*946379e7Schristos 1244*946379e7Schristos</P> 1245*946379e7Schristos 1246*946379e7Schristos<PRE> 1247*946379e7Schristos#include <libintl.h> 1248*946379e7Schristos</PRE> 1249*946379e7Schristos 1250*946379e7Schristos<P> 1251*946379e7SchristosThe location of <CODE>gettext.h</CODE> is usually in a directory containing 1252*946379e7Schristosauxiliary include files. In many GNU packages, there is a directory 1253*946379e7Schristos<TT>‘lib/’</TT> containing helper functions; <TT>‘gettext.h’</TT> fits there. 1254*946379e7SchristosIn other packages, it can go into the <TT>‘src’</TT> directory. 1255*946379e7Schristos 1256*946379e7Schristos</P> 1257*946379e7Schristos<P> 1258*946379e7SchristosDo not install the <CODE>gettext.h</CODE> file in public locations. Every 1259*946379e7Schristospackage that needs it should contain a copy of it on its own. 1260*946379e7Schristos 1261*946379e7Schristos</P> 1262*946379e7Schristos 1263*946379e7Schristos 1264*946379e7Schristos<H2><A NAME="SEC214" HREF="gettext_toc.html#TOC214">13.5 Autoconf macros for use in <TT>‘configure.in’</TT></A></H2> 1265*946379e7Schristos<P> 1266*946379e7Schristos<A NAME="IDX1087"></A> 1267*946379e7Schristos 1268*946379e7Schristos</P> 1269*946379e7Schristos<P> 1270*946379e7SchristosGNU <CODE>gettext</CODE> installs macros for use in a package's 1271*946379e7Schristos<TT>‘configure.in’</TT> or <TT>‘configure.ac’</TT>. 1272*946379e7SchristosSee section ‘Introduction’ in <CITE>The Autoconf Manual</CITE>. 1273*946379e7SchristosThe primary macro is, of course, <CODE>AM_GNU_GETTEXT</CODE>. 1274*946379e7Schristos 1275*946379e7Schristos</P> 1276*946379e7Schristos 1277*946379e7Schristos 1278*946379e7Schristos 1279*946379e7Schristos<H3><A NAME="SEC215" HREF="gettext_toc.html#TOC215">13.5.1 AM_GNU_GETTEXT in <TT>‘gettext.m4’</TT></A></H3> 1280*946379e7Schristos 1281*946379e7Schristos<P> 1282*946379e7Schristos<A NAME="IDX1088"></A> 1283*946379e7SchristosThe <CODE>AM_GNU_GETTEXT</CODE> macro tests for the presence of the GNU gettext 1284*946379e7Schristosfunction family in either the C library or a separate <CODE>libintl</CODE> 1285*946379e7Schristoslibrary (shared or static libraries are both supported) or in the package's 1286*946379e7Schristos<TT>‘intl/’</TT> directory. It also invokes <CODE>AM_PO_SUBDIRS</CODE>, thus preparing 1287*946379e7Schristosthe <TT>‘po/’</TT> directories of the package for building. 1288*946379e7Schristos 1289*946379e7Schristos</P> 1290*946379e7Schristos<P> 1291*946379e7Schristos<CODE>AM_GNU_GETTEXT</CODE> accepts up to three optional arguments. The general 1292*946379e7Schristossyntax is 1293*946379e7Schristos 1294*946379e7Schristos</P> 1295*946379e7Schristos 1296*946379e7Schristos<PRE> 1297*946379e7SchristosAM_GNU_GETTEXT([<VAR>intlsymbol</VAR>], [<VAR>needsymbol</VAR>], [<VAR>intldir</VAR>]) 1298*946379e7Schristos</PRE> 1299*946379e7Schristos 1300*946379e7Schristos<P> 1301*946379e7Schristos<VAR>intlsymbol</VAR> can be <SAMP>‘external’</SAMP> or <SAMP>‘no-libtool’</SAMP>. The default 1302*946379e7Schristos(if it is not specified or empty) is <SAMP>‘no-libtool’</SAMP>. <VAR>intlsymbol</VAR> 1303*946379e7Schristosshould be <SAMP>‘external’</SAMP> for packages with no <TT>‘intl/’</TT> directory. 1304*946379e7SchristosFor packages with an <TT>‘intl/’</TT> directory, you can either use an 1305*946379e7Schristos<VAR>intlsymbol</VAR> equal to <SAMP>‘no-libtool’</SAMP>, or you can use <SAMP>‘external’</SAMP> 1306*946379e7Schristosand override by using the macro <CODE>AM_GNU_GETTEXT_INTL_SUBDIR</CODE> elsewhere. 1307*946379e7SchristosThe two ways to specify the existence of an <TT>‘intl/’</TT> directory are 1308*946379e7Schristosequivalent. At build time, a static library 1309*946379e7Schristos<CODE>$(top_builddir)/intl/libintl.a</CODE> will then be created. 1310*946379e7Schristos 1311*946379e7Schristos</P> 1312*946379e7Schristos<P> 1313*946379e7SchristosIf <VAR>needsymbol</VAR> is specified and is <SAMP>‘need-ngettext’</SAMP>, then GNU 1314*946379e7Schristosgettext implementations (in libc or libintl) without the <CODE>ngettext()</CODE> 1315*946379e7Schristosfunction will be ignored. If <VAR>needsymbol</VAR> is specified and is 1316*946379e7Schristos<SAMP>‘need-formatstring-macros’</SAMP>, then GNU gettext implementations that don't 1317*946379e7Schristossupport the ISO C 99 <TT>‘<inttypes.h>’</TT> formatstring macros will be ignored. 1318*946379e7SchristosOnly one <VAR>needsymbol</VAR> can be specified. These requirements can also be 1319*946379e7Schristosspecified by using the macro <CODE>AM_GNU_GETTEXT_NEED</CODE> elsewhere. To specify 1320*946379e7Schristosmore than one requirement, just specify the strongest one among them, or 1321*946379e7Schristosinvoke the <CODE>AM_GNU_GETTEXT_NEED</CODE> macro several times. The hierarchy 1322*946379e7Schristosamong the various alternatives is as follows: <SAMP>‘need-formatstring-macros’</SAMP> 1323*946379e7Schristosimplies <SAMP>‘need-ngettext’</SAMP>. 1324*946379e7Schristos 1325*946379e7Schristos</P> 1326*946379e7Schristos<P> 1327*946379e7Schristos<VAR>intldir</VAR> is used to find the intl libraries. If empty, the value 1328*946379e7Schristos<SAMP>‘$(top_builddir)/intl/’</SAMP> is used. 1329*946379e7Schristos 1330*946379e7Schristos</P> 1331*946379e7Schristos<P> 1332*946379e7SchristosThe <CODE>AM_GNU_GETTEXT</CODE> macro determines whether GNU gettext is 1333*946379e7Schristosavailable and should be used. If so, it sets the <CODE>USE_NLS</CODE> variable 1334*946379e7Schristosto <SAMP>‘yes’</SAMP>; it defines <CODE>ENABLE_NLS</CODE> to 1 in the autoconf 1335*946379e7Schristosgenerated configuration file (usually called <TT>‘config.h’</TT>); it sets 1336*946379e7Schristosthe variables <CODE>LIBINTL</CODE> and <CODE>LTLIBINTL</CODE> to the linker options 1337*946379e7Schristosfor use in a Makefile (<CODE>LIBINTL</CODE> for use without libtool, 1338*946379e7Schristos<CODE>LTLIBINTL</CODE> for use with libtool); it adds an <SAMP>‘-I’</SAMP> option to 1339*946379e7Schristos<CODE>CPPFLAGS</CODE> if necessary. In the negative case, it sets 1340*946379e7Schristos<CODE>USE_NLS</CODE> to <SAMP>‘no’</SAMP>; it sets <CODE>LIBINTL</CODE> and <CODE>LTLIBINTL</CODE> 1341*946379e7Schristosto empty and doesn't change <CODE>CPPFLAGS</CODE>. 1342*946379e7Schristos 1343*946379e7Schristos</P> 1344*946379e7Schristos<P> 1345*946379e7SchristosThe complexities that <CODE>AM_GNU_GETTEXT</CODE> deals with are the following: 1346*946379e7Schristos 1347*946379e7Schristos</P> 1348*946379e7Schristos 1349*946379e7Schristos<UL> 1350*946379e7Schristos<LI> 1351*946379e7Schristos 1352*946379e7Schristos<A NAME="IDX1089"></A> 1353*946379e7SchristosSome operating systems have <CODE>gettext</CODE> in the C library, for example 1354*946379e7Schristosglibc. Some have it in a separate library <CODE>libintl</CODE>. GNU <CODE>libintl</CODE> 1355*946379e7Schristosmight have been installed as part of the GNU <CODE>gettext</CODE> package. 1356*946379e7Schristos 1357*946379e7Schristos<LI> 1358*946379e7Schristos 1359*946379e7SchristosGNU <CODE>libintl</CODE>, if installed, is not necessarily already in the search 1360*946379e7Schristospath (<CODE>CPPFLAGS</CODE> for the include file search path, <CODE>LDFLAGS</CODE> for 1361*946379e7Schristosthe library search path). 1362*946379e7Schristos 1363*946379e7Schristos<LI> 1364*946379e7Schristos 1365*946379e7SchristosExcept for glibc, the operating system's native <CODE>gettext</CODE> cannot 1366*946379e7Schristosexploit the GNU mo files, doesn't have the necessary locale dependency 1367*946379e7Schristosfeatures, and cannot convert messages from the catalog's text encoding 1368*946379e7Schristosto the user's locale encoding. 1369*946379e7Schristos 1370*946379e7Schristos<LI> 1371*946379e7Schristos 1372*946379e7SchristosGNU <CODE>libintl</CODE>, if installed, is not necessarily already in the 1373*946379e7Schristosrun time library search path. To avoid the need for setting an environment 1374*946379e7Schristosvariable like <CODE>LD_LIBRARY_PATH</CODE>, the macro adds the appropriate 1375*946379e7Schristosrun time search path options to the <CODE>LIBINTL</CODE> and <CODE>LTLIBINTL</CODE> 1376*946379e7Schristosvariables. This works on most systems, but not on some operating systems 1377*946379e7Schristoswith limited shared library support, like SCO. 1378*946379e7Schristos 1379*946379e7Schristos<LI> 1380*946379e7Schristos 1381*946379e7SchristosGNU <CODE>libintl</CODE> relies on POSIX/XSI <CODE>iconv</CODE>. The macro checks for 1382*946379e7Schristoslinker options needed to use iconv and appends them to the <CODE>LIBINTL</CODE> 1383*946379e7Schristosand <CODE>LTLIBINTL</CODE> variables. 1384*946379e7Schristos</UL> 1385*946379e7Schristos 1386*946379e7Schristos 1387*946379e7Schristos 1388*946379e7Schristos<H3><A NAME="SEC216" HREF="gettext_toc.html#TOC216">13.5.2 AM_GNU_GETTEXT_VERSION in <TT>‘gettext.m4’</TT></A></H3> 1389*946379e7Schristos 1390*946379e7Schristos<P> 1391*946379e7Schristos<A NAME="IDX1090"></A> 1392*946379e7SchristosThe <CODE>AM_GNU_GETTEXT_VERSION</CODE> macro declares the version number of 1393*946379e7Schristosthe GNU gettext infrastructure that is used by the package. 1394*946379e7Schristos 1395*946379e7Schristos</P> 1396*946379e7Schristos<P> 1397*946379e7SchristosThe use of this macro is optional; only the <CODE>autopoint</CODE> program makes 1398*946379e7Schristosuse of it (see section <A HREF="gettext_13.html#SEC221">13.6 Integrating with CVS</A>). 1399*946379e7Schristos 1400*946379e7Schristos</P> 1401*946379e7Schristos 1402*946379e7Schristos 1403*946379e7Schristos 1404*946379e7Schristos<H3><A NAME="SEC217" HREF="gettext_toc.html#TOC217">13.5.3 AM_GNU_GETTEXT_NEED in <TT>‘gettext.m4’</TT></A></H3> 1405*946379e7Schristos 1406*946379e7Schristos<P> 1407*946379e7Schristos<A NAME="IDX1091"></A> 1408*946379e7SchristosThe <CODE>AM_GNU_GETTEXT_NEED</CODE> macro declares a constraint regarding the 1409*946379e7SchristosGNU gettext implementation. The syntax is 1410*946379e7Schristos 1411*946379e7Schristos</P> 1412*946379e7Schristos 1413*946379e7Schristos<PRE> 1414*946379e7SchristosAM_GNU_GETTEXT_NEED([<VAR>needsymbol</VAR>]) 1415*946379e7Schristos</PRE> 1416*946379e7Schristos 1417*946379e7Schristos<P> 1418*946379e7SchristosIf <VAR>needsymbol</VAR> is <SAMP>‘need-ngettext’</SAMP>, then GNU gettext implementations 1419*946379e7Schristos(in libc or libintl) without the <CODE>ngettext()</CODE> function will be ignored. 1420*946379e7SchristosIf <VAR>needsymbol</VAR> is <SAMP>‘need-formatstring-macros’</SAMP>, then GNU gettext 1421*946379e7Schristosimplementations that don't support the ISO C 99 <TT>‘<inttypes.h>’</TT> 1422*946379e7Schristosformatstring macros will be ignored. 1423*946379e7Schristos 1424*946379e7Schristos</P> 1425*946379e7Schristos<P> 1426*946379e7SchristosThe optional second argument of <CODE>AM_GNU_GETTEXT</CODE> is also taken into 1427*946379e7Schristosaccount. 1428*946379e7Schristos 1429*946379e7Schristos</P> 1430*946379e7Schristos<P> 1431*946379e7SchristosThe <CODE>AM_GNU_GETTEXT_NEED</CODE> invocations can occur before or after 1432*946379e7Schristosthe <CODE>AM_GNU_GETTEXT</CODE> invocation; the order doesn't matter. 1433*946379e7Schristos 1434*946379e7Schristos</P> 1435*946379e7Schristos 1436*946379e7Schristos 1437*946379e7Schristos<H3><A NAME="SEC218" HREF="gettext_toc.html#TOC218">13.5.4 AM_GNU_GETTEXT_INTL_SUBDIR in <TT>‘intldir.m4’</TT></A></H3> 1438*946379e7Schristos 1439*946379e7Schristos<P> 1440*946379e7Schristos<A NAME="IDX1092"></A> 1441*946379e7SchristosThe <CODE>AM_GNU_GETTEXT_INTL_SUBDIR</CODE> macro specifies that the 1442*946379e7Schristos<CODE>AM_GNU_GETTEXT</CODE> macro, although invoked with the first argument 1443*946379e7Schristos<SAMP>‘external’</SAMP>, should also prepare for building the <TT>‘intl/’</TT> 1444*946379e7Schristossubdirectory. 1445*946379e7Schristos 1446*946379e7Schristos</P> 1447*946379e7Schristos<P> 1448*946379e7SchristosThe <CODE>AM_GNU_GETTEXT_INTL_SUBDIR</CODE> invocation can occur before or after 1449*946379e7Schristosthe <CODE>AM_GNU_GETTEXT</CODE> invocation; the order doesn't matter. 1450*946379e7Schristos 1451*946379e7Schristos</P> 1452*946379e7Schristos<P> 1453*946379e7SchristosThe use of this macro requires GNU automake 1.10 or newer and 1454*946379e7SchristosGNU autoconf 2.61 or newer. 1455*946379e7Schristos 1456*946379e7Schristos</P> 1457*946379e7Schristos 1458*946379e7Schristos 1459*946379e7Schristos<H3><A NAME="SEC219" HREF="gettext_toc.html#TOC219">13.5.5 AM_PO_SUBDIRS in <TT>‘po.m4’</TT></A></H3> 1460*946379e7Schristos 1461*946379e7Schristos<P> 1462*946379e7Schristos<A NAME="IDX1093"></A> 1463*946379e7SchristosThe <CODE>AM_PO_SUBDIRS</CODE> macro prepares the <TT>‘po/’</TT> directories of the 1464*946379e7Schristospackage for building. This macro should be used in internationalized 1465*946379e7Schristosprograms written in other programming languages than C, C++, Objective C, 1466*946379e7Schristosfor example <CODE>sh</CODE>, <CODE>Python</CODE>, <CODE>Lisp</CODE>. See section <A HREF="gettext_15.html#SEC229">15 Other Programming Languages</A> for a list of programming languages that support localization 1467*946379e7Schristosthrough PO files. 1468*946379e7Schristos 1469*946379e7Schristos</P> 1470*946379e7Schristos<P> 1471*946379e7SchristosThe <CODE>AM_PO_SUBDIRS</CODE> macro determines whether internationalization 1472*946379e7Schristosshould be used. If so, it sets the <CODE>USE_NLS</CODE> variable to <SAMP>‘yes’</SAMP>, 1473*946379e7Schristosotherwise to <SAMP>‘no’</SAMP>. It also determines the right values for Makefile 1474*946379e7Schristosvariables in each <TT>‘po/’</TT> directory. 1475*946379e7Schristos 1476*946379e7Schristos</P> 1477*946379e7Schristos 1478*946379e7Schristos 1479*946379e7Schristos<H3><A NAME="SEC220" HREF="gettext_toc.html#TOC220">13.5.6 AM_ICONV in <TT>‘iconv.m4’</TT></A></H3> 1480*946379e7Schristos 1481*946379e7Schristos<P> 1482*946379e7Schristos<A NAME="IDX1094"></A> 1483*946379e7SchristosThe <CODE>AM_ICONV</CODE> macro tests for the presence of the POSIX/XSI 1484*946379e7Schristos<CODE>iconv</CODE> function family in either the C library or a separate 1485*946379e7Schristos<CODE>libiconv</CODE> library. If found, it sets the <CODE>am_cv_func_iconv</CODE> 1486*946379e7Schristosvariable to <SAMP>‘yes’</SAMP>; it defines <CODE>HAVE_ICONV</CODE> to 1 in the autoconf 1487*946379e7Schristosgenerated configuration file (usually called <TT>‘config.h’</TT>); it defines 1488*946379e7Schristos<CODE>ICONV_CONST</CODE> to <SAMP>‘const’</SAMP> or to empty, depending on whether the 1489*946379e7Schristossecond argument of <CODE>iconv()</CODE> is of type <SAMP>‘const char **’</SAMP> or 1490*946379e7Schristos<SAMP>‘char **’</SAMP>; it sets the variables <CODE>LIBICONV</CODE> and 1491*946379e7Schristos<CODE>LTLIBICONV</CODE> to the linker options for use in a Makefile 1492*946379e7Schristos(<CODE>LIBICONV</CODE> for use without libtool, <CODE>LTLIBICONV</CODE> for use with 1493*946379e7Schristoslibtool); it adds an <SAMP>‘-I’</SAMP> option to <CODE>CPPFLAGS</CODE> if 1494*946379e7Schristosnecessary. If not found, it sets <CODE>LIBICONV</CODE> and <CODE>LTLIBICONV</CODE> to 1495*946379e7Schristosempty and doesn't change <CODE>CPPFLAGS</CODE>. 1496*946379e7Schristos 1497*946379e7Schristos</P> 1498*946379e7Schristos<P> 1499*946379e7SchristosThe complexities that <CODE>AM_ICONV</CODE> deals with are the following: 1500*946379e7Schristos 1501*946379e7Schristos</P> 1502*946379e7Schristos 1503*946379e7Schristos<UL> 1504*946379e7Schristos<LI> 1505*946379e7Schristos 1506*946379e7Schristos<A NAME="IDX1095"></A> 1507*946379e7SchristosSome operating systems have <CODE>iconv</CODE> in the C library, for example 1508*946379e7Schristosglibc. Some have it in a separate library <CODE>libiconv</CODE>, for example 1509*946379e7SchristosOSF/1 or FreeBSD. Regardless of the operating system, GNU <CODE>libiconv</CODE> 1510*946379e7Schristosmight have been installed. In that case, it should be used instead of the 1511*946379e7Schristosoperating system's native <CODE>iconv</CODE>. 1512*946379e7Schristos 1513*946379e7Schristos<LI> 1514*946379e7Schristos 1515*946379e7SchristosGNU <CODE>libiconv</CODE>, if installed, is not necessarily already in the search 1516*946379e7Schristospath (<CODE>CPPFLAGS</CODE> for the include file search path, <CODE>LDFLAGS</CODE> for 1517*946379e7Schristosthe library search path). 1518*946379e7Schristos 1519*946379e7Schristos<LI> 1520*946379e7Schristos 1521*946379e7SchristosGNU <CODE>libiconv</CODE> is binary incompatible with some operating system's 1522*946379e7Schristosnative <CODE>iconv</CODE>, for example on FreeBSD. Use of an <TT>‘iconv.h’</TT> 1523*946379e7Schristosand <TT>‘libiconv.so’</TT> that don't fit together would produce program 1524*946379e7Schristoscrashes. 1525*946379e7Schristos 1526*946379e7Schristos<LI> 1527*946379e7Schristos 1528*946379e7SchristosGNU <CODE>libiconv</CODE>, if installed, is not necessarily already in the 1529*946379e7Schristosrun time library search path. To avoid the need for setting an environment 1530*946379e7Schristosvariable like <CODE>LD_LIBRARY_PATH</CODE>, the macro adds the appropriate 1531*946379e7Schristosrun time search path options to the <CODE>LIBICONV</CODE> variable. This works 1532*946379e7Schristoson most systems, but not on some operating systems with limited shared 1533*946379e7Schristoslibrary support, like SCO. 1534*946379e7Schristos</UL> 1535*946379e7Schristos 1536*946379e7Schristos<P> 1537*946379e7Schristos<TT>‘iconv.m4’</TT> is distributed with the GNU gettext package because 1538*946379e7Schristos<TT>‘gettext.m4’</TT> relies on it. 1539*946379e7Schristos 1540*946379e7Schristos</P> 1541*946379e7Schristos 1542*946379e7Schristos 1543*946379e7Schristos<H2><A NAME="SEC221" HREF="gettext_toc.html#TOC221">13.6 Integrating with CVS</A></H2> 1544*946379e7Schristos 1545*946379e7Schristos<P> 1546*946379e7SchristosMany projects use CVS for distributed development, version control and 1547*946379e7Schristossource backup. This section gives some advice how to manage the uses 1548*946379e7Schristosof <CODE>cvs</CODE>, <CODE>gettextize</CODE>, <CODE>autopoint</CODE> and <CODE>autoconf</CODE>. 1549*946379e7Schristos 1550*946379e7Schristos</P> 1551*946379e7Schristos 1552*946379e7Schristos 1553*946379e7Schristos 1554*946379e7Schristos<H3><A NAME="SEC222" HREF="gettext_toc.html#TOC222">13.6.1 Avoiding version mismatch in distributed development</A></H3> 1555*946379e7Schristos 1556*946379e7Schristos<P> 1557*946379e7SchristosIn a project development with multiple developers, using CVS, there 1558*946379e7Schristosshould be a single developer who occasionally - when there is desire to 1559*946379e7Schristosupgrade to a new <CODE>gettext</CODE> version - runs <CODE>gettextize</CODE> and 1560*946379e7Schristosperforms the changes listed in section <A HREF="gettext_13.html#SEC200">13.4 Files You Must Create or Alter</A>, and then commits 1561*946379e7Schristoshis changes to the CVS. 1562*946379e7Schristos 1563*946379e7Schristos</P> 1564*946379e7Schristos<P> 1565*946379e7SchristosIt is highly recommended that all developers on a project use the same 1566*946379e7Schristosversion of GNU <CODE>gettext</CODE> in the package. In other words, if a 1567*946379e7Schristosdeveloper runs <CODE>gettextize</CODE>, he should go the whole way, make the 1568*946379e7Schristosnecessary remaining changes and commit his changes to the CVS. 1569*946379e7SchristosOtherwise the following damages will likely occur: 1570*946379e7Schristos 1571*946379e7Schristos</P> 1572*946379e7Schristos 1573*946379e7Schristos<UL> 1574*946379e7Schristos<LI> 1575*946379e7Schristos 1576*946379e7SchristosApparent version mismatch between developers. Since some <CODE>gettext</CODE> 1577*946379e7Schristosspecific portions in <TT>‘configure.in’</TT>, <TT>‘configure.ac’</TT> and 1578*946379e7Schristos<CODE>Makefile.am</CODE>, <CODE>Makefile.in</CODE> files depend on the <CODE>gettext</CODE> 1579*946379e7Schristosversion, the use of infrastructure files belonging to different 1580*946379e7Schristos<CODE>gettext</CODE> versions can easily lead to build errors. 1581*946379e7Schristos 1582*946379e7Schristos<LI> 1583*946379e7Schristos 1584*946379e7SchristosHidden version mismatch. Such version mismatch can also lead to 1585*946379e7Schristosmalfunctioning of the package, that may be undiscovered by the developers. 1586*946379e7SchristosThe worst case of hidden version mismatch is that internationalization 1587*946379e7Schristosof the package doesn't work at all. 1588*946379e7Schristos 1589*946379e7Schristos<LI> 1590*946379e7Schristos 1591*946379e7SchristosRelease risks. All developers implicitly perform constant testing on 1592*946379e7Schristosa package. This is important in the days and weeks before a release. 1593*946379e7SchristosIf the guy who makes the release tar files uses a different version 1594*946379e7Schristosof GNU <CODE>gettext</CODE> than the other developers, the distribution will 1595*946379e7Schristosbe less well tested than if all had been using the same <CODE>gettext</CODE> 1596*946379e7Schristosversion. For example, it is possible that a platform specific bug goes 1597*946379e7Schristosundiscovered due to this constellation. 1598*946379e7Schristos</UL> 1599*946379e7Schristos 1600*946379e7Schristos 1601*946379e7Schristos 1602*946379e7Schristos<H3><A NAME="SEC223" HREF="gettext_toc.html#TOC223">13.6.2 Files to put under CVS version control</A></H3> 1603*946379e7Schristos 1604*946379e7Schristos<P> 1605*946379e7SchristosThere are basically three ways to deal with generated files in the 1606*946379e7Schristoscontext of a CVS repository, such as <TT>‘configure’</TT> generated from 1607*946379e7Schristos<TT>‘configure.in’</TT>, <CODE><VAR>parser</VAR>.c</CODE> generated from 1608*946379e7Schristos<CODE><VAR>parser</VAR>.y</CODE>, or <CODE>po/Makefile.in.in</CODE> autoinstalled by 1609*946379e7Schristos<CODE>gettextize</CODE> or <CODE>autopoint</CODE>. 1610*946379e7Schristos 1611*946379e7Schristos</P> 1612*946379e7Schristos 1613*946379e7Schristos<OL> 1614*946379e7Schristos<LI> 1615*946379e7Schristos 1616*946379e7SchristosAll generated files are always committed into the repository. 1617*946379e7Schristos 1618*946379e7Schristos<LI> 1619*946379e7Schristos 1620*946379e7SchristosAll generated files are committed into the repository occasionally, 1621*946379e7Schristosfor example each time a release is made. 1622*946379e7Schristos 1623*946379e7Schristos<LI> 1624*946379e7Schristos 1625*946379e7SchristosGenerated files are never committed into the repository. 1626*946379e7Schristos</OL> 1627*946379e7Schristos 1628*946379e7Schristos<P> 1629*946379e7SchristosEach of these three approaches has different advantages and drawbacks. 1630*946379e7Schristos 1631*946379e7Schristos</P> 1632*946379e7Schristos 1633*946379e7Schristos<OL> 1634*946379e7Schristos<LI> 1635*946379e7Schristos 1636*946379e7SchristosThe advantage is that anyone can check out the CVS at any moment and 1637*946379e7Schristosgets a working build. The drawbacks are: 1a. It requires some frequent 1638*946379e7Schristos"cvs commit" actions by the maintainers. 1b. The repository grows in size 1639*946379e7Schristosquite fast. 1640*946379e7Schristos 1641*946379e7Schristos<LI> 1642*946379e7Schristos 1643*946379e7SchristosThe advantage is that anyone can check out the CVS, and the usual 1644*946379e7Schristos"./configure; make" will work. The drawbacks are: 2a. The one who 1645*946379e7Schristoschecks out the repository needs tools like GNU <CODE>automake</CODE>, 1646*946379e7SchristosGNU <CODE>autoconf</CODE>, GNU <CODE>m4</CODE> installed in his PATH; sometimes 1647*946379e7Schristoshe even needs particular versions of them. 2b. When a release is made 1648*946379e7Schristosand a commit is made on the generated files, the other developers get 1649*946379e7Schristosconflicts on the generated files after doing "cvs update". Although 1650*946379e7Schristosthese conflicts are easy to resolve, they are annoying. 1651*946379e7Schristos 1652*946379e7Schristos<LI> 1653*946379e7Schristos 1654*946379e7SchristosThe advantage is less work for the maintainers. The drawback is that 1655*946379e7Schristosanyone who checks out the CVS not only needs tools like GNU <CODE>automake</CODE>, 1656*946379e7SchristosGNU <CODE>autoconf</CODE>, GNU <CODE>m4</CODE> installed in his PATH, but also that 1657*946379e7Schristoshe needs to perform a package specific pre-build step before being able 1658*946379e7Schristosto "./configure; make". 1659*946379e7Schristos</OL> 1660*946379e7Schristos 1661*946379e7Schristos<P> 1662*946379e7SchristosFor the first and second approach, all files modified or brought in 1663*946379e7Schristosby the occasional <CODE>gettextize</CODE> invocation and update should be 1664*946379e7Schristoscommitted into the CVS. 1665*946379e7Schristos 1666*946379e7Schristos</P> 1667*946379e7Schristos<P> 1668*946379e7SchristosFor the third approach, the maintainer can omit from the CVS repository 1669*946379e7Schristosall the files that <CODE>gettextize</CODE> mentions as "copy". Instead, he 1670*946379e7Schristosadds to the <TT>‘configure.in’</TT> or <TT>‘configure.ac’</TT> a line of the 1671*946379e7Schristosform 1672*946379e7Schristos 1673*946379e7Schristos</P> 1674*946379e7Schristos 1675*946379e7Schristos<PRE> 1676*946379e7SchristosAM_GNU_GETTEXT_VERSION(0.16.1) 1677*946379e7Schristos</PRE> 1678*946379e7Schristos 1679*946379e7Schristos<P> 1680*946379e7Schristosand adds to the package's pre-build script an invocation of 1681*946379e7Schristos<SAMP>‘autopoint’</SAMP>. For everyone who checks out the CVS, this 1682*946379e7Schristos<CODE>autopoint</CODE> invocation will copy into the right place the 1683*946379e7Schristos<CODE>gettext</CODE> infrastructure files that have been omitted from the CVS. 1684*946379e7Schristos 1685*946379e7Schristos</P> 1686*946379e7Schristos<P> 1687*946379e7SchristosThe version number used as argument to <CODE>AM_GNU_GETTEXT_VERSION</CODE> is 1688*946379e7Schristosthe version of the <CODE>gettext</CODE> infrastructure that the package wants 1689*946379e7Schristosto use. It is also the minimum version number of the <SAMP>‘autopoint’</SAMP> 1690*946379e7Schristosprogram. So, if you write <CODE>AM_GNU_GETTEXT_VERSION(0.11.5)</CODE> then the 1691*946379e7Schristosdevelopers can have any version >= 0.11.5 installed; the package will work 1692*946379e7Schristoswith the 0.11.5 infrastructure in all developers' builds. When the 1693*946379e7Schristosmaintainer then runs gettextize from, say, version 0.12.1 on the package, 1694*946379e7Schristosthe occurrence of <CODE>AM_GNU_GETTEXT_VERSION(0.11.5)</CODE> will be changed 1695*946379e7Schristosinto <CODE>AM_GNU_GETTEXT_VERSION(0.12.1)</CODE>, and all other developers that 1696*946379e7Schristosuse the CVS will henceforth need to have GNU <CODE>gettext</CODE> 0.12.1 or newer 1697*946379e7Schristosinstalled. 1698*946379e7Schristos 1699*946379e7Schristos</P> 1700*946379e7Schristos 1701*946379e7Schristos 1702*946379e7Schristos<H3><A NAME="SEC224" HREF="gettext_toc.html#TOC224">13.6.3 Invoking the <CODE>autopoint</CODE> Program</A></H3> 1703*946379e7Schristos 1704*946379e7Schristos<P> 1705*946379e7Schristos<A NAME="IDX1096"></A> 1706*946379e7Schristos<A NAME="IDX1097"></A> 1707*946379e7Schristos 1708*946379e7Schristos<PRE> 1709*946379e7Schristosautopoint [<VAR>option</VAR>]... 1710*946379e7Schristos</PRE> 1711*946379e7Schristos 1712*946379e7Schristos<P> 1713*946379e7SchristosThe <CODE>autopoint</CODE> program copies standard gettext infrastructure files 1714*946379e7Schristosinto a source package. It extracts from a macro call of the form 1715*946379e7Schristos<CODE>AM_GNU_GETTEXT_VERSION(<VAR>version</VAR>)</CODE>, found in the package's 1716*946379e7Schristos<TT>‘configure.in’</TT> or <TT>‘configure.ac’</TT> file, the gettext version 1717*946379e7Schristosused by the package, and copies the infrastructure files belonging to 1718*946379e7Schristosthis version into the package. 1719*946379e7Schristos 1720*946379e7Schristos</P> 1721*946379e7Schristos 1722*946379e7Schristos 1723*946379e7Schristos<H4><A NAME="SEC225" HREF="gettext_toc.html#TOC225">13.6.3.1 Options</A></H4> 1724*946379e7Schristos 1725*946379e7Schristos<DL COMPACT> 1726*946379e7Schristos 1727*946379e7Schristos<DT><SAMP>‘-f’</SAMP> 1728*946379e7Schristos<DD> 1729*946379e7Schristos<DT><SAMP>‘--force’</SAMP> 1730*946379e7Schristos<DD> 1731*946379e7Schristos<A NAME="IDX1098"></A> 1732*946379e7Schristos<A NAME="IDX1099"></A> 1733*946379e7SchristosForce overwriting of files that already exist. 1734*946379e7Schristos 1735*946379e7Schristos<DT><SAMP>‘-n’</SAMP> 1736*946379e7Schristos<DD> 1737*946379e7Schristos<DT><SAMP>‘--dry-run’</SAMP> 1738*946379e7Schristos<DD> 1739*946379e7Schristos<A NAME="IDX1100"></A> 1740*946379e7Schristos<A NAME="IDX1101"></A> 1741*946379e7SchristosPrint modifications but don't perform them. All file copying actions that 1742*946379e7Schristos<CODE>autopoint</CODE> would normally execute are inhibited and instead only 1743*946379e7Schristoslisted on standard output. 1744*946379e7Schristos 1745*946379e7Schristos</DL> 1746*946379e7Schristos 1747*946379e7Schristos 1748*946379e7Schristos 1749*946379e7Schristos<H4><A NAME="SEC226" HREF="gettext_toc.html#TOC226">13.6.3.2 Informative output</A></H4> 1750*946379e7Schristos 1751*946379e7Schristos<DL COMPACT> 1752*946379e7Schristos 1753*946379e7Schristos<DT><SAMP>‘--help’</SAMP> 1754*946379e7Schristos<DD> 1755*946379e7Schristos<A NAME="IDX1102"></A> 1756*946379e7SchristosDisplay this help and exit. 1757*946379e7Schristos 1758*946379e7Schristos<DT><SAMP>‘--version’</SAMP> 1759*946379e7Schristos<DD> 1760*946379e7Schristos<A NAME="IDX1103"></A> 1761*946379e7SchristosOutput version information and exit. 1762*946379e7Schristos 1763*946379e7Schristos</DL> 1764*946379e7Schristos 1765*946379e7Schristos<P> 1766*946379e7Schristos<CODE>autopoint</CODE> supports the GNU <CODE>gettext</CODE> versions from 0.10.35 to 1767*946379e7Schristosthe current one, 0.16.1. In order to apply <CODE>autopoint</CODE> to 1768*946379e7Schristosa package using a <CODE>gettext</CODE> version newer than 0.16.1, you 1769*946379e7Schristosneed to install this same version of GNU <CODE>gettext</CODE> at least. 1770*946379e7Schristos 1771*946379e7Schristos</P> 1772*946379e7Schristos<P> 1773*946379e7SchristosIn packages using GNU <CODE>automake</CODE>, an invocation of <CODE>autopoint</CODE> 1774*946379e7Schristosshould be followed by invocations of <CODE>aclocal</CODE> and then <CODE>autoconf</CODE> 1775*946379e7Schristosand <CODE>autoheader</CODE>. The reason is that <CODE>autopoint</CODE> installs some 1776*946379e7Schristosautoconf macro files, which are used by <CODE>aclocal</CODE> to create 1777*946379e7Schristos<TT>‘aclocal.m4’</TT>, and the latter is used by <CODE>autoconf</CODE> to create the 1778*946379e7Schristospackage's <TT>‘configure’</TT> script and by <CODE>autoheader</CODE> to create the 1779*946379e7Schristospackage's <TT>‘config.h.in’</TT> include file template. 1780*946379e7Schristos 1781*946379e7Schristos</P> 1782*946379e7Schristos<P> 1783*946379e7SchristosThe name <SAMP>‘autopoint’</SAMP> is an abbreviation of <SAMP>‘auto-po-intl-m4’</SAMP>; 1784*946379e7Schristosthe tool copies or updates mostly files in the <TT>‘po’</TT>, <TT>‘intl’</TT>, 1785*946379e7Schristos<TT>‘m4’</TT> directories. 1786*946379e7Schristos 1787*946379e7Schristos</P> 1788*946379e7Schristos 1789*946379e7Schristos 1790*946379e7Schristos<H2><A NAME="SEC227" HREF="gettext_toc.html#TOC227">13.7 Creating a Distribution Tarball</A></H2> 1791*946379e7Schristos 1792*946379e7Schristos<P> 1793*946379e7Schristos<A NAME="IDX1104"></A> 1794*946379e7Schristos<A NAME="IDX1105"></A> 1795*946379e7SchristosIn projects that use GNU <CODE>automake</CODE>, the usual commands for creating 1796*946379e7Schristosa distribution tarball, <SAMP>‘make dist’</SAMP> or <SAMP>‘make distcheck’</SAMP>, 1797*946379e7Schristosautomatically update the PO files as needed. 1798*946379e7Schristos 1799*946379e7Schristos</P> 1800*946379e7Schristos<P> 1801*946379e7SchristosIf GNU <CODE>automake</CODE> is not used, the maintainer needs to perform this 1802*946379e7Schristosupdate before making a release: 1803*946379e7Schristos 1804*946379e7Schristos</P> 1805*946379e7Schristos 1806*946379e7Schristos<PRE> 1807*946379e7Schristos$ ./configure 1808*946379e7Schristos$ (cd po; make update-po) 1809*946379e7Schristos$ make distclean 1810*946379e7Schristos</PRE> 1811*946379e7Schristos 1812*946379e7Schristos<P><HR><P> 1813*946379e7SchristosGo to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_12.html">previous</A>, <A HREF="gettext_14.html">next</A>, <A HREF="gettext_25.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. 1814*946379e7Schristos</BODY> 1815*946379e7Schristos</HTML> 1816