intl custom dependency

Checking how to aquire the *gettext family of symbols portably is
annoyingly complex, and may come from the libc, or standalone.

builtin dependency:

    This detects if libintl is unneeded, because the *gettext family of
    symbols is available in the libc.

system dependency:

    This detects if libintl is installed as separate software, linkable via
    -lintl; unfortunately, GNU gettext does not ship pkg-config files for
    it.

Fixes #3929

2 files changed, 55 insertions, 1 deletions

diff --git a/docs/markdown/Dependencies.md b/docs/markdown/Dependencies.md
index 41f3bc2..caf7af7 100644
--- a/docs/markdown/Dependencies.md
+++ b/docs/markdown/Dependencies.md
@@ -141,7 +141,7 @@ of all the work behind the scenes to make this work.
 You can use the keyword `method` to let Meson know what method to use
 when searching for the dependency. The default value is `auto`.
 Additional dependencies methods are `pkg-config`, `config-tool`, `cmake`,
-`system`, `sysconfig`, `qmake`, `extraframework` and `dub`.
+`builtin`, `system`, `sysconfig`, `qmake`, `extraframework` and `dub`.
 
 ```meson
 cups_dep = dependency('cups', method : 'pkg-config')
@@ -282,6 +282,15 @@ in the build system DSL or with a script, likely calling
 putting these in meson upstream the barrier of using them is lowered, as
 projects using meson don't have to re-implement the logic.
 
+## Builtin
+
+Some dependencies provide no valid methods for discovery on some systems,
+because they are provided internally by the language. One example of this is
+intl, which is built into GNU or musl libc but otherwise comes as a `system`
+dependency.
+
+In these cases meson provides convenience wrappers for the `system` dependency,
+but first checks if the functionality is usable by default.
 
 ## Blocks
 
@@ -400,6 +409,16 @@ language.
 *New in 0.56.0* the dependencies now return proper dependency types
  and `get_variable` and similar methods should work as expected.
 
+## intl
+
+*(added 0.59.0)*
+
+Provides access to the `*gettext` family of C functions. On systems where this
+is not built into libc, tries to find an external library providing them
+instead.
+
+`method` may be `auto`, `builtin` or `system`.
+
 ## libwmf
 
 *(added 0.44.0)*
diff --git a/docs/markdown/snippets/intl-dependency.md b/docs/markdown/snippets/intl-dependency.md
new file mode 100644
index 0000000..8e0cd40
--- /dev/null
+++ b/docs/markdown/snippets/intl-dependency.md
@@ -0,0 +1,35 @@
+## New custom dependency for libintl
+
+Meson can now find the library needed for translating messages via gettext.
+This works both on systems where libc provides gettext, such as GNU or musl,
+and on systems where the gettext project's standalone intl support library is
+required, such as macOS.
+
+Rather than doing something such as:
+
+```
+intl_dep = dependency('', required: false)
+
+if cc.has_function('ngettext')
+  intl_found = true
+else
+  intl_dep = cc.find_library('intl', required: false)
+  intl_found = intl_dep.found()
+endif
+
+if intl_found
+  # build options that need gettext
+  conf.set('ENABLE_NLS', 1)
+endif
+```
+  
+one may simply use:
+
+```
+intl_dep = dependency('intl')
+
+if intl_dep.found()
+  # build options that need gettext
+  conf.set('ENABLE_NLS', 1)
+endif
+```