[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.5.2          2.4 won't work

   * 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 vorbis-tools wget libsamplerate0-dev

     On lenny use libdb4.5-deb.  libdb4.6 does not work (and configure will
     refuse to use it).

   * On FreeBSD you'll need at least these packages:
	 autotools
	 bash
	 flac
	 mad
         boehm-gc
         db43
         gmake
         gsed
         libao
         libgcrypt
         wget
         vorbis-tools

   * On OS X with Fink:

     fink install gtk+2-dev gc libgrypt pcre flac vorbis-tools libmad wget sed

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

Building:

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

        bash ./prepare
        ./configure -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) Create lib/uaudio-<name>.c; see uaudio.h for the interface.
     3) Update the list in lib/uaudio-apis.c
     4) Add a new option to clients/playrtp.c and document it in
        doc/disorder-playrtp.1.in (if appropriate).
     5) Update doc/disorder_config.5.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 for extended periods on long-lasting
     transactions or external resources is not acceptable; it will wedge the
     server for all other users.

     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; Javascript might be acceptable but it must degrade
     gracefuly if disabled.  Clever use of CSS is OK provided it works well on
     the mainstream browsers.

   * Update templates/help.tmpl 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.

New Platforms:

   * It is not mandatory to have an entry in configure's 'case $host' section,
     but may well be convenient.

   * Complete support for a new platform implies updating scripts/setup.in and
     scripts/teardown.in as well as getting the software to build and work (but
     this doesn't mean that patches that don't achieve this will be rejected).

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 (see http://www.stack.nl/~dimitri/doxygen/) but
     really the point is to have good inline code documentation, not the
     Doxygen output as such.

   * 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.)

   * GCCisms such as typeof and C99isms such as mixed declarations and named
     structure initializers are used; the configure script asks for -std=gnu99
     by default.  Some supported platforms are still on GCC 4.0.

   * 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 v3 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
9918a94b	8	Python 2.5.2 2.4 won't work
91d9a42d	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 \
c3feb35b	15	libflac-dev vorbis-tools wget libsamplerate0-dev
91d9a42d	16
db8ab224 RK	17	On lenny use libdb4.5-deb. libdb4.6 does not work (and configure will
	18	refuse to use it).
	19
42f43a11 RK	20	* On FreeBSD you'll need at least these packages:
	21	autotools
	22	bash
	23	flac
	24	mad
	25	boehm-gc
	26	db43
	27	gmake
	28	gsed
	29	libao
	30	libgcrypt
	31	wget
	32	vorbis-tools
	33
495f9857 RK	34	* On OS X with Fink:
	35
	36	fink install gtk+2-dev gc libgrypt pcre flac vorbis-tools libmad wget sed
	37
91d9a42d	38	* Please report unstated dependencies (here, README or debian/control).
91d9a42d	39
b30155e3 RK	40	Building:
b30155e3 RK	41
db8ab224 RK	42	* Compiled versions of configure and the makefiles are not included in bzr,
db8ab224 RK	43	so if you didn't use a source tarball, you must start as follows:
b30155e3	44
d558cce2 RK	45	bash ./prepare
d558cce2 RK	46	./configure -C
b30155e3 RK	47	make
	48
	49	* On FreeBSD you must use gmake.
	50
91d9a42d	51	Testing:
	52
	53	* There is an extensive test suite in lib/test.c and tests/*.py. You can
	54	run the tests with 'make check'. If possible please add tests for new
	55	code to at least one of these. At the very least the existing tests
	56	should continue to pass.
	57
	58	* The tests will not currently pass in an ASCII locale. This is essentially
	59	unavoidable given the need to test Unicode support. ISO 8859-1 or UTF-8
	60	locales should be OK for the time being.
	61
	62	APIs And Formats:
	63
	64	* To support a new sound API:
	65	1) Teach configure.ac how to detect any libraries required.
b116feb0 RK	66	2) Create lib/uaudio-<name>.c; see uaudio.h for the interface.
	67	3) Update the list in lib/uaudio-apis.c
	68	4) Add a new option to clients/playrtp.c and document it in
	69	doc/disorder-playrtp.1.in (if appropriate).
91d9a42d	70	5) Update doc/disorder_config.5.in.
91d9a42d	71
	72	* To support a new file format:
	73	1) Teach configure.ac how to detect any libraries required.
	74	2) Add a new section to server/decode.c. NB this file may be split into
	75	several bits one day.
	76	3) Add a new section to plugins/tracklength.c. Again this file may be
	77	split up in a future version.
	78	4) Update default_players[] in lib/configuration.c.
	79	5) Update doc/disorder_config.5.in.
	80
	81	The Server:
	82
	83	* The server's command implementations must not block. Waiting for a little
0590cedc RK	84	disk IO is OK but blocking for extended periods on long-lasting
	85	transactions or external resources is not acceptable; it will wedge the
	86	server for all other users.
	87
	88	Long-running subprocesses should use subprograms (rather than forking but
	89	not execing) if reasonably possible; see c_stats() for an example.
	90	c_reminder() is probably in the grey area.
91d9a42d	91
	92	* The server process does not use threads and I would like to keep it that
	93	way.
	94
	95	* The server uses the Boehm garbage collector. This eliminates the need to
	96	call free() and similar functions in many cases, though teardown calls to
	97	that do more than free GC-allocated memory (such as fclose()) are still
	98	required.
	99
	100	* DisOrder's *printf calls, such as byte_xasprintf(), are mostly preferred
	101	within the server to the ones built into libc. An important distinction
	102	is that they will always accept UTF-8 strings whereas the built-in ones
	103	may reject them in non-UTF-8 locales (for instance Glibc does this) with
	104	EILSEQ. Only where the data is guaranteed to be ASCII may the libc
	105	functions be used.
	106
	107	* To add a new configuration directive:
	108	1) Add a new entry to the struct in lib/configuration.h
	109	2) Add a new table entry to conf[] in lib/configuration.c
	110	3) If the directive is entirely unlike existing ones add a new type_
	111	to lib/configuration.c
	112	4) Set the default if non-0 in config_default(). In some cases
	113	config_postdefaults() may be more appropriate.
	114	5) Document the new directive in doc/disorder_config.5.in
	115
	116	* To add a new command:
	117	1) Add a new c_ function and table entry in server/server.c
	118	2) Document the new command in doc/disorder_protocol.5.in
	119	3) Add a new function to lib/client.c
	120	4) Add a new function to lib/eclient.c
	121	5) Add a new function to python/disorder.py.in
	122	6) Add a new command to clients/disorder.c and update doc/disorder.1.in
	123	7) Add a new test somewhere in tests/*.py
	124	Depending on the purpose of the command it may be acceptable to leave out
	125	some of the client side work - for instance commands only ever used by the
	126	web interface are not implemented in lib/eclient.c.
	127
	128	* See disorder_protocol(5) for details of how the status code is
	129	constructed, and the existing commands for examples.
	130
	131	* If the command needs a new right to be defined then update lib/rights.[ch]
	132	and doc/disorder_config.5.in. New rights should definitely be mentioned
	133	in README.upgrades as existing users will not automatically get new rights
	134	even if they are in default_rights. If the new right should not be in
	135	default_rights by default then you must update config_postdefaults().
	136
	137	Web Interface:
	138
	139	* The web interface does not use Javascript or Flash and I would like to
b116feb0 RK	140	keep it that way; Javascript might be acceptable but it must degrade
	141	gracefuly if disabled. Clever use of CSS is OK provided it works well on
	142	the mainstream browsers.
91d9a42d	143
50450a00	144	* Update templates/help.tmpl for any changes you make.
91d9a42d	145
	146	Disobedience:
	147
	148	* Disobedience does not currently use threads and I'd prefer to keep it that
	149	way.
	150
	151	* Disobedience uses the Boehm garbage collector but not for GTK+/GLIB's
	152	memory allocation, as they are incompatible with it. So you still have to
	153	do somewhat manual memory management for GTK+ objects. Fortunately it has
	154	its own refcounting system which does most of the work for you.
	155
	156	* Lengthy operations must not block. In practice this seems to be a less of
	157	a problem for Disobedience than the server. Use the GLIB event loop to
	158	deal with long-running operations if you do need any.
	159
	160	* Update doc/disobedience.1.in for any changes you make.
	161
0590cedc RK	162	New Platforms:
	163
	164	* It is not mandatory to have an entry in configure's 'case $host' section,
	165	but may well be convenient.
	166
	167	* Complete support for a new platform implies updating scripts/setup.in and
	168	scripts/teardown.in as well as getting the software to build and work (but
	169	this doesn't mean that patches that don't achieve this will be rejected).
	170
91d9a42d	171	Code And Patches:
	172
	173	* Please follow the existing layout conventions.
	174
	175	* Please try to write doc comments for new functions, types, etc using the
	176	same syntax as the existing ones. Doxygen can be used to turn this into
0590cedc RK	177	reference documentation (see http://www.stack.nl/~dimitri/doxygen/) but
	178	really the point is to have good inline code documentation, not the
	179	Doxygen output as such.
91d9a42d	180
	181	* More importantly, new configuration directives, protocol commands,
	182	interface features etc should be documented in the relevant places.
	183
	184	* If you add new dependencies please update README, README.developers and
	185	debian/control.
	186
	187	* New dependencies that are not in Debian stable are likely to be rejected.
	188	(But if your new feature only makes sense on a given platform then
	189	obviously its new dependencies don't need to be available elsewhere.)
	190
1b8ed51f RK	191	* GCCisms such as typeof and C99isms such as mixed declarations and named
	192	structure initializers are used; the configure script asks for -std=gnu99
	193	by default. Some supported platforms are still on GCC 4.0.
f0a76a4a	194
91d9a42d	195	* Please submit patches either using 'diff -u', or by publishing a bzr
	196	branch somewhere I can get at it.
	197
	198	* Please make it clear that your changes can be distributed under DisOrder's
7751df38	199	licence (which is "GPL v3 or later").
91d9a42d	200
	201	Local Variables:
	202	mode:text
	203	fill-column:79
	204	End: