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