From 98a9f81d617fb8fe4653b368dfb1f5e05cbb3c82 Mon Sep 17 00:00:00 2001
From: Max Kellermann <max@musicpd.org>
Date: Mon, 15 Feb 2021 13:19:17 +0100
Subject: [PATCH] doc/client.rst: new chapter about client development

---
 doc/client.rst  | 65 +++++++++++++++++++++++++++++++++++++++++++++++++
 doc/index.rst   |  1 +
 doc/meson.build |  1 +
 3 files changed, 67 insertions(+)
 create mode 100644 doc/client.rst

diff --git a/doc/client.rst b/doc/client.rst
new file mode 100644
index 000000000..51a631e57
--- /dev/null
+++ b/doc/client.rst
@@ -0,0 +1,65 @@
+Client Developer's Manual
+#########################
+
+Introduction
+************
+
+MPD is a music player without a user interface.  The user interface
+will be provided by independent clients, which connect to MPD over
+socket connections (TCP or local sockets).
+
+This chapter describes how to develop a client.
+
+Before you develop a new client, consider joining an existing client
+project.  There are many clients, but few are mature; we need fewer,
+but better clients.
+
+Client Libraries
+****************
+
+There are many libraries which help with connecting to MPD.  If you
+develop a MPD client, use a library instead of reinventing the wheel.
+The MPD website has a list of libraries: https://www.musicpd.org/libs/
+
+
+Connecting to MPD
+*****************
+
+Do not hard-code your client to connect to ``localhost:6600``.
+Instead, use the defaults of the client library.  For example, with
+:program:`libmpdclient`, don't do::
+
+ c = mpd_connection_new("localhost", 6600, 30000);
+
+Instead, do::
+
+ c = mpd_connection_new(NULL, 0, 0);
+
+This way, the library can choose the best defaults, maybe derived from
+environment variables, so all MPD clients use the same settings.
+
+If you need to reimmeplemt those defaults (or if you are developing a
+client library), this is a good set of addresses to attempt to connect
+to:
+
+- if the environment variable :envvar:`MPD_HOST` is set:
+  ``$MPD_HOST:$MPD_PORT`` (:envvar:`MPD_PORT` defaulting to 6600)
+- if the environment variable :envvar:`XDG_RUNTIME_DIR` is set:
+  ``$XDG_RUNTIME_DIR/mpd/socket``
+- :file:`/run/mpd/socket`
+- ``localhost:$MPD_PORT`` (:envvar:`MPD_PORT` defaulting to 6600)
+
+Environment Variables
+*********************
+
+The following environment variables should be obeyed by all clients
+(preferably by the client library):
+
+- :envvar:`MPD_HOST`: the host (or local socket path) to connect to;
+  on Linux, this may start with a ``@`` to connect to an abstract
+  socket.
+- :envvar:`MPD_PORT`: the port number; defaults to 6600.
+- :envvar:`MPD_TIMEOUT`: timeout for connecting to MPD and for waiting
+  for MPD's response in milliseconds.  A good default is 30 seconds
+  (i.e. 30.000 ms).
+
diff --git a/doc/index.rst b/doc/index.rst
index 8ab49bb54..c9555de48 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -8,6 +8,7 @@ Music Player Daemon
    user
    plugins
    developer
+   client
    protocol
 
 
diff --git a/doc/meson.build b/doc/meson.build
index a67686483..82fd3b0cf 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -14,6 +14,7 @@ if get_option('html_manual')
     input: [
       'index.rst', 'user.rst', 'developer.rst',
       'plugins.rst',
+      'client.rst',
       'protocol.rst',
       'conf.py',
     ],