server: deprecate in favor of the file-api

Document the server mode as deprecated.  Add a deprecation message
to the configure step output when invoked through server mode.

Closes: #19101

Help/manual/cmake-server.7.rst

@@ -7,6 +7,11 @@ cmake-server(7)
 
    .. contents::
 
+.. deprecated:: 3.15
+
+  This will be removed from a future version of CMake.
+  Clients should use the :manual:`cmake-file-api(7)` instead.
+
 Introduction
 ============
 

Help/release/dev/server-deprecate.rst

@@ -0,0 +1,6 @@
+server-deprecate
+----------------
+
+* The :manual:`cmake-server(7)` mode has been deprecated and will be
+  removed from a future version of CMake.  Please port clients to use
+  the :manual:`cmake-file-api(7)` instead.

Source/cmServerProtocol.cxx

@@ -8,6 +8,7 @@
 #include "cmGlobalGenerator.h"
 #include "cmJsonObjectDictionary.h"
 #include "cmJsonObjects.h"
+#include "cmMessageType.h"
 #include "cmServer.h"
 #include "cmServerDictionary.h"
 #include "cmState.h"
@@ -600,6 +601,10 @@ cmServerResponse cmServerProtocol1::ProcessConfigure(
   }
 
   int ret = cm->Configure();
+  cm->IssueMessage(
+    MessageType::DEPRECATION_WARNING,
+    "The 'cmake-server(7)' is deprecated.  "
+    "Please port clients to use the 'cmake-file-api(7)' instead.");
   if (ret < 0) {
     return request.ReportError("Configuration failed.");
   }