-*- text -*-

Notes to developers:

- Note that the README file is automatically generated from the main
  page of the doxygen documentation by running "make doc" (or "make
  readme").

- To check that all the code is working:

  make check
  make distcheck
  make check with --enable-debug

  Do this both from inside and outside sources.

- The following tools are necessary to generate all documentation (any
  flavor of "make dist" will fail if these tools are not available):

  - doxygen with man, pdf and html support
  - a latex distribution with pdflatex, and the usually recommended
    package files (such as float.sty) and fonts (such as ptmr8t)
  - fig2dev (transfig package)
  - gs (ghostscript package)
  - epstopdf
  - w3m or lynx (to generate the README)

  On Debian systems, the following packages should be enough:
    doxygen ghostscript texlive-latex-base texlive-latex-recommended 
    texlive-fonts-recommended texlive-font-utils transfig w3m
  On RedHat systems:
    ghostscript doxygen transfig tetex tetex-latex w3m

- *** BEFORE MAKING AN OFFICIAL RELEASE TARBALL: the release manager
  MUST update the VERSION file:

  - ensure that the major, minor, and release version numbers are
    correct.  The greek/svn numbers will automatically be stripped by
    make_dist_tarball (see below).
  - ensure that increment the so_version number as appropriate (see
    the GNU Libtool documentation for a description of what to do).

- Create a distribution tarball by running the following from the
  top-level source directory:

  shell$ ./contrib/dist/make_dist_tarball

  It will take a few minutes because it runs "make distcheck" and it
  builds two tarballs (an official release and a greek release).  For
  example, after "make_dist_tarball" completes, you'll have two
  tarballs, like this:

  hwloc-0.9.1.tar.gz
  hwloc-0.9.1rc1.tar.gz

  The "rc1" tarball (or whatever the greek version is) can be
  distributed for testing and validation.  If it passes, then the
  non-rc1 tarball can be released (it's identical to the rc1 tarball
  except for its version).

- Check tarballs by configuring and building them and then running
  "make check".

- For the windows zipball, make sure you have Microsoft's lib tool in
  PATH, to pass --enable-static to ./configure, and remember to copy README and
  NEWS at the root of the zip into README.txt and NEWS.txt files with CRLF:

  sed -e 's/$/'$'\015'/ < README > $prefix/README.txt
  sed -e 's/$/'$'\015'/ < NEWS > $prefix/NEWS.txt
  sed -e 's/$/'$'\015'/ < COPYING > $prefix/COPYING.txt

- For the 64bit version on windows, pass --host=x86_64-w64-mingw32 to
  ./configure to use mingw-64

- make maintainer-clean can be used to properly remove the generated
  documentations.

- Silent rules are used by default to reduce the build verbosity:

  shell$ make
  CC	src/topology.lo

  To revert to the old verbose rules, pass V=1 to make:

  shell$ make V=1
  /bin/sh ../libtool  --tag=CC   --mode=compile gcc [...] -c -o topology.lo topology.c

