compilers/c_function_attributes: add retain

retain is a relatively young attribute which has proven itself useful
for working with --gc-sections -z start-stop-gc.

docs/markdown/Reference-tables.md

@@ -240,6 +240,7 @@ which are supported by GCC, Clang, and other compilers.
 | optimize                 |
 | packed                   |
 | pure                     |
+| retain⁴                  |
 | returns_nonnull          |
 | unused                   |
 | used                     |
@@ -261,6 +262,8 @@ which are supported by GCC, Clang, and other compilers.
 
 ³ *New in 0.55.0*
 
+⁴ *New in 0.62.0*
+
 ### MSVC __declspec
 
 These values are supported using the MSVC style `__declspec` annotation,

mesonbuild/compilers/c_function_attributes.py

@@ -113,6 +113,7 @@ C_FUNC_ATTRIBUTES = {
     'weakref': '''
         static int foo(void) { return 0; }
         static int var(void) __attribute__((weakref("foo")));''',
+    'retain': '__attribute__((retain)) int x;',
 }
 
 CXX_FUNC_ATTRIBUTES = {

test cases/common/197 function attributes/meson.build

@@ -80,6 +80,12 @@ if ['gcc', 'intel'].contains(c.get_id())
   if c.get_id() == 'gcc' and c.version().version_compare('>= 7.0.0')
     attributes += 'fallthrough'
   endif
+
+  # XXX(arsen): limited to clang 13+ even though gcc 11 has it, since gcc
+  # detects support for it at compile time based on binutils version
+  if c.get_id() == 'clang' and c.version().version_compare('>= 13.0.0')
+    attributes += 'retain'
+  endif
 endif
 
 if get_option('mode') == 'single'