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