docs/manual/adding-packages-gettext.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 === Gettext integration and interaction with packages
   5
   6 Many packages that support internationalization use the gettext
   7 library. Dependencies for this library are fairly complicated and
   8 therefore, deserve some explanation.
   9
  10 The 'uClibc' C library doesn't implement gettext functionality;
  11 therefore with this C library, a separate gettext must be compiled,
  12 which is provided by the additional +libintl+ library, part of the
  13 +gettext+ package.
  14
  15 On the other hand, the 'glibc' C library does integrate its own
  16 gettext library functions, so it is not necessary to build a separate
  17 +libintl+ library.
  18
  19 However, certain packages need some gettext utilities on the target,
  20 such as the +gettext+ program itself, which allows to retrieve
  21 translated strings, from the command line.
  22
  23 Additionally, some packages (such as +libglib2+) do require gettext
  24 functions unconditionally, while other packages (in general, those who
  25 support +--disable-nls+) only require gettext functions when locale
  26 support is enabled.
  27
  28 Therefore, Buildroot defines two configuration options:
  29
  30 * +BR2_NEEDS_GETTEXT+, which is true as soon as the toolchain doesn't
  31   provide its own gettext implementation
  32
  33 * +BR2_NEEDS_GETTEXT_IF_LOCALE+, which is true if the toolchain
  34   doesn't provide its own gettext implementation and if locale support
  35   is enabled
  36
  37 Packages that need gettext only when locale support is enabled should:
  38
  39 * use +select BR2_PACKAGE_GETTEXT if BR2_NEEDS_GETTEXT_IF_LOCALE+ in the
  40   +Config.in+ file;
  41
  42 * use +$(if $(BR2_NEEDS_GETTEXT_IF_LOCALE),gettext)+ in the package
  43   +DEPENDENCIES+ variable in the +.mk+ file.
  44
  45 Packages that unconditionally need gettext (which should be very rare)
  46 should:
  47
  48 * use +select BR2_PACKAGE_GETTEXT if BR2_NEEDS_GETTEXT+ in the +Config.in+
  49   file;
  50
  51 * use +$(if $(BR2_NEEDS_GETTEXT),gettext)+ in the package
  52   +DEPENDENCIES+ variable in the +.mk+ file.
  53
  54 Packages that need the +gettext+ utilities on the target (should be
  55 rare) should:
  56
  57 * use +select BR2_PACKAGE_GETTEXT+ in their +Config.in+ file,
  58   indicating in a comment above that it's a runtime dependency only.
  59
  60 * not add any +gettext+ dependency in the +DEPENDENCIES+ variable of
  61   their +.mk+ file.