
Hacking the jigdo source code
=============================

This file is not very organized... if in doubt, use the source, Luke!

Mailing list, CVS
~~~~~~~~~~~~~~~~~
There is currently no CVS access to my current development version.

There is no mailing list dedicated to jigdo alone. So far, there
doesn't seem to be a demand for it, and the debian-cd@lists.debian.org
subscribers do not seem to mind the occasional jigdo-related message
which is *not* related to Debian...

Patches
~~~~~~~
Small bugfixes are very welcome, just send them e.g. to
<jigdo@atterer.net>.

Before starting anything bigger, better check with me whether it
coincides with my ideas - just to avoid frustration later on. I'm
pretty open to all ideas, though, especially if they save me some
work. :)

Sub-projects
~~~~~~~~~~~~
There are some things I'd *love* to see done by somebody else:

Windows/Solaris/BSD/MacOS porting:

  ATM, I test and build jigdo on Windows, and occasionally on
  Solaris/BSD. Especially maintaining the Windows port is a bit of
  work...

  It'd also be nice if someone ensured that it builds on Redhat, and
  maintained the jigdo.spec file.

CGI-like program for on-the-fly creation from .jigdo/.template files:

  With Debian, we have lots of mirror admins who have the bandwidth to
  host CD images, but not the disc space. They'd like a CGI-like
  program which generates a pseudo dirlisting with .iso links in it,
  and, when such an .iso link is downloaded, it creates the .iso
  data from the .jigdo/.template files and a local Debian mirror
  _on_the_fly_ as it is being sent over the net.

  NB however: This *cannot* be a CGI for performance reasons and
  because it must support HTTP/1.1 ranges (i.e. resuming of
  downloads). Also, it will be necessary to "pre-process" the
  .template file because repeatedly ungzipping it would be too slow.

  If not a CGI, what form should it have? I don't know - I'd go for an
  Apache module, but Attila Nagy tells me Apache needs too much memory
  if you have many thousand concurrent downloads. Maybe one could
  hack support into an existing small httpd?

".rawtemplate" support:

  It is possible to make .jigdo creation for Debian CDs much faster
  by hacking mkisofs to support more direct output of .jigdo/.template
  files:

  First, change mkisofs to output not .iso format, but a special
  ".rawtemplate" (or whatever) format. That format is similar to the
  normal .template format, except that files are not referenced by
  their md5sum, but by their filename, and that none of the data is
  compressed. This should be quite simple, and thus the modifications
  to mkisofs should be few and small, making it more likely that such
  a patch is accepted by mkisofs upstream.

  Next, the .rawtemplate is piped into jigdo-file, which creates
  .jigdo and .template files as usual. However, due to its cache, it
  won't need to read the files' contents to know their md5sum, so the
  overall process is much faster.

jigdo GUI app
~~~~~~~~~~~~~
This is very much work in progress.

I'm not entirely happy with libwww and have vague plans to switch away
from it once something better is available, so all code accessing
libwww should be in download.cc *only*, to make it easier to rip out.

The "something better", BTW, would ideally be the Mozilla HTTP code,
but ATM this isn't available as a separate library; you'd have to hack
Mozilla to extract it.

Required features for any replacement for libwww are HTTP/1.1 support
(both pipelining and ranges), multiple simultaneous connections
(either multi-threaded or single-threaded with select()) and
portability to Windows.

Translations
~~~~~~~~~~~~
Both jigdo-file and jigdo use gettext, translations are welcome. 
Please contact me before you start, to avoid duplication of effort.

Code style
~~~~~~~~~~
I use K&R-style indentation, indenting by 2 spaces for each level of
indentation. I dislike using tabs in the source because it seems
people can never agree on a value for the tab indentation. Emacs can
be told never to generate tabs when indenting code; see below.

Functions/methods should not be much longer than one screen. Source
files should never be larger than 1000 lines, and probably not even
larger than 500 files. I'm perfectly aware that the code violates
these rules all the time. ;-/

All code must, *MUST* be commented.

If possible, larger components should be accompanied by a *-test.cc
file which tests the code.

Lines must not be longer than 77 characters. To format comments to
exactly that width, and also never to use tabs for indentation, use
this in your ~/.emacs:

(add-hook 'c++-mode-hook (lambda () (interactive) (setq fill-column 77) (setq indent-tabs-mode nil)))

Header files (.fh, .hh, .ih)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To avoid excessive recompilation, I use three levels of headers.

.fh contain just forward declarations of classes and global functions,
and must not include .hh or .ih headers.

.hh are the main headers, and .ih files contain functions which are
compiled inline for --disable-debug and not inline for --enable-debug. 
This is done by checking for the definedness of NOINLINE.

"make depend" updates the dependencies in src/Makedeps. See also the
comments in scripts/depend.awk.
