From d7acccd36dcf1b62f144eb7389a5e221fe824be4 Mon Sep 17 00:00:00 2001
From: Dylan Baker <dylan@pnwbakers.com>
Date: Wed, 19 Jul 2023 13:22:20 -0700
Subject: [PATCH] interpreter: deprecate 'jar' value of
 build_target(target_type)

Jar has a very low set of overlap with other target types, including
that jar sources *must* be .java, and no other target allows .java
sources. As such, the difficulty in crafting a useful `build_target`
invocation that allows both `jar` and anything else is high, and the
usefulness is dubious. Just use `jar()` directly instead.

This depends on the changes to make all of the jar() specific keyword
arguments be handled by typed_kwargs so that the deprecation messages
are correct and consistent.
---
 docs/markdown/snippets/deprecate_build_target_jar.md | 8 ++++++++
 docs/yaml/functions/build_target.yaml                | 7 +++++--
 mesonbuild/interpreter/type_checking.py              | 6 +++++-
 3 files changed, 18 insertions(+), 3 deletions(-)
 create mode 100644 docs/markdown/snippets/deprecate_build_target_jar.md

diff --git a/docs/markdown/snippets/deprecate_build_target_jar.md b/docs/markdown/snippets/deprecate_build_target_jar.md
new file mode 100644
index 000000000..992903e53
--- /dev/null
+++ b/docs/markdown/snippets/deprecate_build_target_jar.md
@@ -0,0 +1,8 @@
+## Deprecate 'jar' as a build_target type
+
+The point of `build_target()` is that what is produced can be conditionally
+changed. However, `jar()` has a significant number of non-overlapping arguments
+from other build_targets, including the kinds of sources it can include. Because
+of this crafting a `build_target` that can be used as a Jar and as something
+else is incredibly hard to do. As such, it has been deprecated, and using
+`jar()` directly is recomended.
diff --git a/docs/yaml/functions/build_target.yaml b/docs/yaml/functions/build_target.yaml
index 48385f252..74d45f007 100644
--- a/docs/yaml/functions/build_target.yaml
+++ b/docs/yaml/functions/build_target.yaml
@@ -12,7 +12,7 @@ description: |
   - `static_library` (see [[static_library]])
   - `both_libraries` (see [[both_libraries]])
   - `library` (see [[library]])
-  - `jar` (see [[jar]])
+  - `jar` (see [[jar]])*
 
   This declaration:
 
@@ -32,6 +32,9 @@ description: |
 
   The returned object also has methods that are documented in [[@build_tgt]].
 
+  *"jar" is deprecated because it is fundementally a different thing than the
+  other build_target types.
+
 posargs_inherit: _build_target_base
 varargs_inherit: _build_target_base
 kwargs_inherit:
@@ -42,4 +45,4 @@ kwargs_inherit:
 kwargs:
   target_type:
     type: str
-    description: The actual target to build
+    description: The actual target type to build
diff --git a/mesonbuild/interpreter/type_checking.py b/mesonbuild/interpreter/type_checking.py
index 7c615c2c8..206a2e6f5 100644
--- a/mesonbuild/interpreter/type_checking.py
+++ b/mesonbuild/interpreter/type_checking.py
@@ -555,7 +555,8 @@ LIBRARY_KWS = [
 BUILD_TARGET_KWS = [
     *LIBRARY_KWS,
     *_EXCLUSIVE_EXECUTABLE_KWS,
-    *_EXCLUSIVE_JAR_KWS,
+    *[a.evolve(deprecated='1.3.0', deprecated_message='The use of "jar" in "build_target()" is deprecated, and this argument is only used by jar()')
+      for a in _EXCLUSIVE_JAR_KWS],
     KwargInfo(
         'target_type',
         str,
@@ -566,6 +567,9 @@ BUILD_TARGET_KWS = [
         }),
         since_values={
             'shared_module': '0.51.0',
+        },
+        deprecated_values={
+            'jar': ('1.3.0', 'use the "jar()" function directly'),
         }
     )
 ]