locale-utils.eclass

Name

locale-utils.eclass — Generate locales into a private directory

Description

Test suites frequently call setlocale(3) with specific locales and fail if they are not available. Which locales exist is system configuration (/etc/locale.gen), so an ebuild can neither depend on them nor expect them to be present. elocale_gen generates them instead.

Example:

inherit locale-utils

src_test() {
      local -x LOCPATH
      if elocale_gen cs_CZ.UTF-8 de_DE@euro; then
              meson_src_test
      else
              meson_src_test --no-suite locale
      fi
}

If the locale also has to be selected, pass --set instead of assigning the variable:

src_test() {
      local -x LOCPATH LC_ALL
      elocale_gen --set LC_ALL en_US.UTF-8
      cmake_src_test
}

Supported EAPIs

8 9

Functions

elocale_gen [--set <variable>] <locale>...

Generate the given locales into a directory under ${T} and export LOCPATH so that programs run afterwards can use them. Locales are named as in /usr/share/i18n/SUPPORTED, e.g. cs_CZ.UTF-8, en_US or de_DE@euro. Other spellings of the codeset, e.g. cs_CZ.utf8, are accepted.

Setting LOCPATH hides the system's locales, so the locales in use by the environment and C.UTF-8 are generated as well. Any other locale that is needed must be requested, even if it happens to be installed.

"locale -a" does not honor LOCPATH and never lists the generated locales.

Dies if a locale cannot be generated, unless called under nonfatal.

Only glibc can compile locales. With any other libc nothing is generated and LOCPATH is left alone. Returns 0 if "locale -a" lists all of the given locales, e.g. because sys-apps/musl-locales provides them, and otherwise 1 without dying, so that the caller can skip the affected tests.

With --set, the variable, which must be LANG or one of LC_*, is exported with the first locale as its value. Use this rather than assigning the variable. LOCPATH only takes effect in programs started afterwards, so bash itself cannot find the generated locales and warns that it cannot change locale whenever such a variable is assigned. For the same reason, bash keeps using its previous locale. If the libc is not glibc, the variable is exported whether or not the locale is available.

LOCPATH is saved with the rest of the environment, and the directory is gone by the time pkg_prerm and pkg_postrm run. Declare it local in the calling phase, as in the examples, along with the variable given to --set, which would otherwise cause the warning again whenever the environment is loaded. If the locales are needed in several phases, call elocale_gen in each of them. Locales that are already there are not generated again. pkg_setup is not suitable, since it runs as root and for binary packages.

May be called more than once. Locales accumulate.

Return value: 0 if the locales are available, 1 if they are not

Authors

Matt Turner <mattst88@gentoo.org>

Maintainers

Matt Turner <mattst88@gentoo.org>

Reporting Bugs

Please report bugs via https://bugs.gentoo.org/