chiark - git - mdw - disorder/blob - README.developers

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