From 3483c891dcdaeb3205a6996811da789e7dbcc5fa Mon Sep 17 00:00:00 2001
From: Max Kellermann <max@duempel.org>
Date: Tue, 2 Jun 2009 21:09:45 +0200
Subject: [PATCH] doc: added Developer's Manual
Just a start...
---
.gitignore | 1 +
Makefile.am | 6 ++-
doc/developer.xml | 105 ++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 111 insertions(+), 1 deletion(-)
create mode 100644 doc/developer.xml
diff --git a/.gitignore b/.gitignore
index fa2a8ac7e..1a58409d8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -39,6 +39,7 @@ tags
doc/protocol.html
doc/protocol
doc/user
+doc/developer
doc/sticker
doc/api
test/software_volume
diff --git a/Makefile.am b/Makefile.am
index e9ca647ec..d02eeb12b 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -720,7 +720,7 @@ endif
man_MANS = doc/mpd.1 doc/mpd.conf.5
doc_DATA = AUTHORS COPYING NEWS README UPGRADING doc/mpdconf.example
-DOCBOOK_FILES = doc/protocol.xml doc/user.xml doc/sticker.xml
+DOCBOOK_FILES = doc/protocol.xml doc/user.xml doc/developer.xml doc/sticker.xml
if ENABLE_DOCUMENTATION
protocoldir = $(docdir)/protocol
@@ -729,6 +729,9 @@ protocol_DATA = $(wildcard doc/protocol/*.html)
userdir = $(docdir)/user
user_DATA = $(wildcard doc/user/*.html)
+developerdir = $(docdir)/developer
+developer_DATA = $(wildcard doc/developer/*.html)
+
if HAVE_XMLTO
DOCBOOK_HTML = $(patsubst %.xml,%/index.html,$(DOCBOOK_FILES))
@@ -762,6 +765,7 @@ upload: $(DOCBOOK_HTML) doc/api/html/index.html
--chmod=Dug+rwx,Do+rx,Fug+rw,Fo+r \
--include=protocol --include=protocol/** \
--include=user --include=user/** \
+ --include=developer --include=developer/** \
--include=api --include=api/** \
--exclude=*
diff --git a/doc/developer.xml b/doc/developer.xml
new file mode 100644
index 000000000..c63e2c265
--- /dev/null
+++ b/doc/developer.xml
@@ -0,0 +1,105 @@
+<?xml version='1.0' encoding="utf-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "docbook/dtd/xml/4.2/docbookx.dtd">
+<book>
+ <title>The Music Player Daemon - Developer's Manual</title>
+
+ <chapter>
+ <title>Introduction</title>
+
+ <para>
+ This is a guide for those who wish to hack on the MPD source
+ code. MPD is an open project, and we are always happy about
+ contributions. So far, more than 50 people have contributed
+ patches.
+ </para>
+
+ <para>
+ This document is work in progress. Most of it may be incomplete
+ yet. Please help!
+ </para>
+ </chapter>
+
+ <chapter>
+ <title>Code Style</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ indent with tabs (width 8)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ don't write CPP when you can write C: use inline functions
+ and enums instead of macros
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ the code should be C99 compliant, and must compile with
+ <application>GCC</application>;
+ <application>clang</application> support is highly desirable
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ C++ is ok (for integrating C++ only libraries), but it
+ should be avoided
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Some example code:
+ </para>
+
+ <programlisting lang="C">static inline bool
+foo(const char *abc, int xyz)
+{
+ if (abc == NULL) {
+ g_warning("Foo happened!\n");
+ return -1;
+ }
+
+ return xyz;
+}
+ </programlisting>
+ </listitem>
+ </itemizedlist>
+ </chapter>
+
+ <chapter>
+ <title>Hacking The Source</title>
+
+ <para>
+ Always write your code against the latest git:
+ </para>
+
+ <programlisting>git clone git://git.musicpd.org/master/mpd.git</programlisting>
+
+ <para>
+ Configure with the options <option>--enable-debug
+ --enable-werror</option>. Enable as many plugins as possible,
+ to be sure that you don't break any disabled code.
+ </para>
+
+ <para>
+ Don't mix several changes in one single patch. Create a
+ separate patch for every change. Tools like
+ <application>stgit</application> help you with that.
+ </para>
+ </chapter>
+
+ <chapter>
+ <title>Submitting Patches</title>
+
+ <para>
+ Send your patches to the mailing list:
+ musicpd-dev-team@lists.sourceforge.net
+ </para>
+ </chapter>
+</book>