[disorder] / README.developers

Dependencies:

   * You'll need, in addition to the packages mentioned in README:
     Automake         1.10           1.7 is no good; 1.8/9 might work
     Autoconf         2.61           Slightly older might work too
     Libtool          1.5.22         1.4 is no good
     Bazaar (bzr)                    You might be able to manage without
     Python           2.4

   * On Debian and derivatives this should work:

     apt-get install gcc libc-dev automake autoconf libtool libgtk2.0-dev \
		     libgc-dev libgcrypt-dev libpcre3-dev libvorbis-dev \
		     libao-dev libmad0-dev libasound2-dev libdb4.3-dev \
		     libflac-dev

   * Please report unstated dependencies (here, README or debian/control).

Building:

   * Compiled versions of configure and the makefiles are including in bzr, so
     if you didn't use a source tarball, you must start as follows:

        bash ./prepare -C
        make

   * On FreeBSD you must use gmake.

Testing:

   * There is an extensive test suite in lib/test.c and tests/*.py.  You can
     run the tests with 'make check'.  If possible please add tests for new
     code to at least one of these.  At the very least the existing tests
     should continue to pass.

   * The tests will not currently pass in an ASCII locale.  This is essentially
     unavoidable given the need to test Unicode support.  ISO 8859-1 or UTF-8
     locales should be OK for the time being.

APIs And Formats:

   * To support a new sound API:
     1) Teach configure.ac how to detect any libraries required.
     2) Define a new BACKEND_ value and update configuration.[ch] for it.
     3) Create a suitable server/speaker-*.c along the pattern of the existing
        ones.
     4) If possible create a suitable lib/mixer-*.c.  This doesn't make sense
        for all APIs (e.g. network), but even for those it does, playback
        support without volume control support is likely to be acceptable (even
        if inferior to full support).
     5) Update doc/disorder_config.5.in.
     6) If relevant, create a suitable clients/playrtp-*.c and update
        doc/disorder-playrtp.1.in.

   * To support a new file format:
     1) Teach configure.ac how to detect any libraries required.
     2) Add a new section to server/decode.c.  NB this file may be split into
        several bits one day.
     3) Add a new section to plugins/tracklength.c.  Again this file may be
        split up in a future version.
     4) Update default_players[] in lib/configuration.c.
     5) Update doc/disorder_config.5.in.

The Server:

   * The server's command implementations must not block.  Waiting for a little
     disk IO is OK but blocking on long-lasting transactions or external
     resources is not acceptable.  Long-running subprocesses should use
     subprograms (rather than forking but not execing) if reasonably possible;
     see c_stats() for an example.  c_reminder() is probably in the grey area.

   * The server process does not use threads and I would like to keep it that
     way.

   * The server uses the Boehm garbage collector.  This eliminates the need to
     call free() and similar functions in many cases, though teardown calls to
     that do more than free GC-allocated memory (such as fclose()) are still
     required.

   * DisOrder's *printf calls, such as byte_xasprintf(), are mostly preferred
     within the server to the ones built into libc.  An important distinction
     is that they will always accept UTF-8 strings whereas the built-in ones
     may reject them in non-UTF-8 locales (for instance Glibc does this) with
     EILSEQ.  Only where the data is guaranteed to be ASCII may the libc
     functions be used.

   * To add a new configuration directive:
     1) Add a new entry to the struct in lib/configuration.h
     2) Add a new table entry to conf[] in lib/configuration.c
     3) If the directive is entirely unlike existing ones add a new type_
        to lib/configuration.c
     4) Set the default if non-0 in config_default().  In some cases
        config_postdefaults() may be more appropriate.
     5) Document the new directive in doc/disorder_config.5.in

   * To add a new command:
     1) Add a new c_ function and table entry in server/server.c
     2) Document the new command in doc/disorder_protocol.5.in
     3) Add a new function to lib/client.c
     4) Add a new function to lib/eclient.c
     5) Add a new function to python/disorder.py.in
     6) Add a new command to clients/disorder.c and update doc/disorder.1.in
     7) Add a new test somewhere in tests/*.py
     Depending on the purpose of the command it may be acceptable to leave out
     some of the client side work - for instance commands only ever used by the
     web interface are not implemented in lib/eclient.c.

   * See disorder_protocol(5) for details of how the status code is
     constructed, and the existing commands for examples.

   * If the command needs a new right to be defined then update lib/rights.[ch]
     and doc/disorder_config.5.in.  New rights should definitely be mentioned
     in README.upgrades as existing users will not automatically get new rights
     even if they are in default_rights.  If the new right should not be in
     default_rights by default then you must update config_postdefaults().

Web Interface:

   * The web interface does not use Javascript or Flash and I would like to
     keep it that way.

   * I know that the web template syntax is rather nasty.  Perhaps it will be
     improved in a future version.

   * Update templates/help.html for any changes you make.

Disobedience:

   * Disobedience does not currently use threads and I'd prefer to keep it that
     way.

   * Disobedience uses the Boehm garbage collector but not for GTK+/GLIB's
     memory allocation, as they are incompatible with it.  So you still have to
     do somewhat manual memory management for GTK+ objects.  Fortunately it has
     its own refcounting system which does most of the work for you.

   * Lengthy operations must not block.  In practice this seems to be a less of
     a problem for Disobedience than the server.  Use the GLIB event loop to
     deal with long-running operations if you do need any.

   * Update doc/disobedience.1.in for any changes you make.

Code And Patches:

   * Please follow the existing layout conventions.

   * Please try to write doc comments for new functions, types, etc using the
     same syntax as the existing ones.  Doxygen can be used to turn this into
     reference documentation.

   * More importantly, new configuration directives, protocol commands,
     interface features etc should be documented in the relevant places.

   * If you add new dependencies please update README, README.developers and
     debian/control.

   * New dependencies that are not in Debian stable are likely to be rejected.
     (But if your new feature only makes sense on a given platform then
     obviously its new dependencies don't need to be available elsewhere.)

   * Please submit patches either using 'diff -u', or by publishing a bzr
     branch somewhere I can get at it.

   * Please make it clear that your changes can be distributed under DisOrder's
     licence (which is "GPL v2 or later").

Local Variables:
mode:text
fill-column:79
End:
Commit	Line	Data
91d9a42d	1	Dependencies:
	2
	3	* You'll need, in addition to the packages mentioned in README:
	4	Automake 1.10 1.7 is no good; 1.8/9 might work
	5	Autoconf 2.61 Slightly older might work too
	6	Libtool 1.5.22 1.4 is no good
	7	Bazaar (bzr) You might be able to manage without
	8	Python 2.4
	9
	10	* On Debian and derivatives this should work:
	11
	12	apt-get install gcc libc-dev automake autoconf libtool libgtk2.0-dev \
	13	libgc-dev libgcrypt-dev libpcre3-dev libvorbis-dev \
	14	libao-dev libmad0-dev libasound2-dev libdb4.3-dev \
	15	libflac-dev
	16
	17	* Please report unstated dependencies (here, README or debian/control).
	18
b30155e3 RK	19	Building:
	20
	21	* Compiled versions of configure and the makefiles are including in bzr, so
	22	if you didn't use a source tarball, you must start as follows:
	23
	24	bash ./prepare -C
	25	make
	26
	27	* On FreeBSD you must use gmake.
	28
91d9a42d	29	Testing:
	30
	31	* There is an extensive test suite in lib/test.c and tests/*.py. You can
	32	run the tests with 'make check'. If possible please add tests for new
	33	code to at least one of these. At the very least the existing tests
	34	should continue to pass.
	35
	36	* The tests will not currently pass in an ASCII locale. This is essentially
	37	unavoidable given the need to test Unicode support. ISO 8859-1 or UTF-8
	38	locales should be OK for the time being.
	39
	40	APIs And Formats:
	41
	42	* To support a new sound API:
	43	1) Teach configure.ac how to detect any libraries required.
	44	2) Define a new BACKEND_ value and update configuration.[ch] for it.
	45	3) Create a suitable server/speaker-*.c along the pattern of the existing
	46	ones.
	47	4) If possible create a suitable lib/mixer-*.c. This doesn't make sense
	48	for all APIs (e.g. network), but even for those it does, playback
	49	support without volume control support is likely to be acceptable (even
	50	if inferior to full support).
	51	5) Update doc/disorder_config.5.in.
	52	6) If relevant, create a suitable clients/playrtp-*.c and update
	53	doc/disorder-playrtp.1.in.
	54
	55	* To support a new file format:
	56	1) Teach configure.ac how to detect any libraries required.
	57	2) Add a new section to server/decode.c. NB this file may be split into
	58	several bits one day.
	59	3) Add a new section to plugins/tracklength.c. Again this file may be
	60	split up in a future version.
	61	4) Update default_players[] in lib/configuration.c.
	62	5) Update doc/disorder_config.5.in.
	63
	64	The Server:
	65
	66	* The server's command implementations must not block. Waiting for a little
	67	disk IO is OK but blocking on long-lasting transactions or external
	68	resources is not acceptable. Long-running subprocesses should use
	69	subprograms (rather than forking but not execing) if reasonably possible;
	70	see c_stats() for an example. c_reminder() is probably in the grey area.
	71
	72	* The server process does not use threads and I would like to keep it that
	73	way.
	74
	75	* The server uses the Boehm garbage collector. This eliminates the need to
	76	call free() and similar functions in many cases, though teardown calls to
	77	that do more than free GC-allocated memory (such as fclose()) are still
	78	required.
	79
	80	* DisOrder's *printf calls, such as byte_xasprintf(), are mostly preferred
	81	within the server to the ones built into libc. An important distinction
	82	is that they will always accept UTF-8 strings whereas the built-in ones
	83	may reject them in non-UTF-8 locales (for instance Glibc does this) with
	84	EILSEQ. Only where the data is guaranteed to be ASCII may the libc
	85	functions be used.
	86
	87	* To add a new configuration directive:
	88	1) Add a new entry to the struct in lib/configuration.h
	89	2) Add a new table entry to conf[] in lib/configuration.c
	90	3) If the directive is entirely unlike existing ones add a new type_
	91	to lib/configuration.c
	92	4) Set the default if non-0 in config_default(). In some cases
93	config_postdefaults() may be more appropriate.
94	5) Document the new directive in doc/disorder_config.5.in
95
96	* To add a new command:
97	1) Add a new c_ function and table entry in server/server.c
98	2) Document the new command in doc/disorder_protocol.5.in
99	3) Add a new function to lib/client.c
100	4) Add a new function to lib/eclient.c
101	5) Add a new function to python/disorder.py.in
102	6) Add a new command to clients/disorder.c and update doc/disorder.1.in
103	7) Add a new test somewhere in tests/*.py
104	Depending on the purpose of the command it may be acceptable to leave out
105	some of the client side work - for instance commands only ever used by the
106	web interface are not implemented in lib/eclient.c.
107
108	* See disorder_protocol(5) for details of how the status code is
109	constructed, and the existing commands for examples.
110
111	* If the command needs a new right to be defined then update lib/rights.[ch]
112	and doc/disorder_config.5.in. New rights should definitely be mentioned
113	in README.upgrades as existing users will not automatically get new rights
114	even if they are in default_rights. If the new right should not be in
115	default_rights by default then you must update config_postdefaults().
116
117	Web Interface:
118
119	* The web interface does not use Javascript or Flash and I would like to
120	keep it that way.
121
122	* I know that the web template syntax is rather nasty. Perhaps it will be
123	improved in a future version.
124
125	* Update templates/help.html for any changes you make.
126
127	Disobedience:
128
129	* Disobedience does not currently use threads and I'd prefer to keep it that
130	way.
131
132	* Disobedience uses the Boehm garbage collector but not for GTK+/GLIB's
133	memory allocation, as they are incompatible with it. So you still have to
134	do somewhat manual memory management for GTK+ objects. Fortunately it has
135	its own refcounting system which does most of the work for you.
136
137	* Lengthy operations must not block. In practice this seems to be a less of
138	a problem for Disobedience than the server. Use the GLIB event loop to
139	deal with long-running operations if you do need any.
140
141	* Update doc/disobedience.1.in for any changes you make.
142
143	Code And Patches:
144
145	* Please follow the existing layout conventions.
146
147	* Please try to write doc comments for new functions, types, etc using the
148	same syntax as the existing ones. Doxygen can be used to turn this into
149	reference documentation.
150
151	* More importantly, new configuration directives, protocol commands,
152	interface features etc should be documented in the relevant places.
153
154	* If you add new dependencies please update README, README.developers and
155	debian/control.
156
157	* New dependencies that are not in Debian stable are likely to be rejected.
158	(But if your new feature only makes sense on a given platform then
159	obviously its new dependencies don't need to be available elsewhere.)
160
161	* Please submit patches either using 'diff -u', or by publishing a bzr
162	branch somewhere I can get at it.
163
164	* Please make it clear that your changes can be distributed under DisOrder's
165	licence (which is "GPL v2 or later").
166
167	Local Variables:
168	mode:text
169	fill-column:79
170	End: