Poject bootstraping script in Developer Guide

[Behdad Esfahbod <behdad at cs dot toronto dot edu>]

Hi,

Since Elzubeir updated the developer guide to allow developers
*choose between* Makefile.cvs and autogen.sh, I feel like arguing
again about that:

First of all, for the record or consideration, I note that I
really like the idea of having the developer's guide, but want to
note that they should be there to remind important things, not to
force developers.  Many of what you say in developer's guide is
mostly personal preferences, that should not be forced to other
developers.  And moreover, many larger projects simply have their
own rules that when you are contributing to them, you should
follow.  Fortunately "The Source Code" section is marked as
optional, but I still go over that too:

4. The Source Code:

  * Naming Conventions:  The proposed schema is completely C++
oriented.  Any laguage has it's owen shcema, for example in C,
variables are all in lower-case.  Some projects keep type names
on title-case (FriBidi, GNOME), but others append a "_t" suffix
(Linux kernel, glibc).

  * Indentation:  I must confess Arabeyes is the first place I
see it says "The use of spaces should be avoided at all costs.
Instead, TABS should be used."  At least in Python, TABS should
be avoided.  In Linux kernel, all tabs are welcome, in almost any
other large project I know, they use 8-space tabs AND spaces to
feel the indented space.  That is, you put tabs until you can't,
and put space for the rest.  And they usually use a 2, 3, or 4
space indentation.  What I persoanlly use (in FriBidi, BiCon) is
the GNU style.  That make code decoration really easy, simply use
"indent(1)".

  * The Use of Autotools:  Now comes my first intention to write
this note.  While you recommend having "Makefile.cvs", or as an
alternative, the "autogen.sh", I believe that:

  - Makefile.cvs MUST be used with KDE projects, at least those
that rely on kdeadmin.

  - autogen.sh MUST be used with GNOME projects, at least those
generated by Glade.

  - bootstrap IS the prefered way.  I'm not sure anyone has ever
read the related part of the Autotools book, it's here:

http://sources.redhat.com/autobook/autobook/autobook_43.html

And it says "bootstrap" is the preferred way.  And here are my
reasons in short:

    o It has a pretty straight name.  "autogen.sh" and
"Makefile.cvs" are both completely non-sense to Joe user.

    o It's usage is pretty straight too.  You call "./bootstrap".
With Makefile.cvs you should say "make -f Makefile.cvs", and with
autogen.sh you probably should say "autogen.sh --prefix=$HOME".

    o As the page from the book says, you have to pass configure
options to autogen.sh, but you still don't know what options!

    o With bootstrap, any end user can find out that if there is
no "configure", he better run "bootstrap", and then he finds
configure and follows the configure; make; make install; way.
But with autogen.sh, building from CVS is almost completely
different from building from tarball.

    o Not enough? ;)



And now the documentation:

5. Project Documentation:

  * Well, many people like RCS headers, that doesn't look bad,
but I don't think it should be a mandatory thing either.

  * Doxygen style source code doc:  Many projects simply do not
accept Doxygen.  GNOME people have their own system which is very
similar to Doxygen.  Donno about KDE.  But again, Java and Python
have their own systems.  And I myself am lasier than doing
Doxygen.

  * Manpages:  They are old and being kinda deprecated.  The
format is evil and other stuff.  Many (GNU) recommends info
pages, but they are not necessarily easier to write.  For
example, GNU FriBidi is asked to have info pages instead of man.

Well, that's it for now.  I don't know if you have or not, but I
recommend give a link to GNU Coding Standard too.  That's a
really valuable document that I adore.

--behdad
  behdad.org