Re: [RFC] Splitting gitweb and build-time configuration variables

On Wed, 18 Aug 2010, Jonathan Nieder wrote:

Jakub Narebski wrote:

quoted

1. Description of build-time configuration variable is in the module
   that defines it, and each block of variables coming from the same
   module would have notice where one can find description of those
   variables

[...]

quoted

2. Description of build-time configuration variables is in gitweb.perl,
   and in each module there is comment that full description of those
   variables can be found there, e.g. (proposal):

     # Values of those variables are set during build time in 
     # gitweb/gitweb.perl (main script).  You can find their description
     # there.

[...]

quoted

3. Duplicate description of those variables

With #2, a person reading the Makefile can grep for some particular
substitution (++GITWEB_PROJECTROOT++) and quickly find the name and
description of the variable it is used for.  If there were a 1:1
correspondence between the variables in gitweb.perl and the Makefile,
I would even suggest moving the description to the Makefile.

There is a bit of difference between Perl variables in gitweb.perl and
make build-time variables in gitweb/Makefile, namely:

  our $GIT = "++GIT_BINDIR++/git";

  our $site_name = "++GITWEB_SITENAME++"
                 || ($ENV{'SERVER_NAME'} || "Untitled") . " Git";

  our @stylesheets = ("++GITWEB_CSS++");

  our @git_base_url_list = grep { $_ ne '' } ("++GITWEB_BASE_URL++");

  our $GITWEB_CONFIG = $ENV{'GITWEB_CONFIG'} || "++GITWEB_CONFIG++";
  our $GITWEB_CONFIG_SYSTEM = $ENV{'GITWEB_CONFIG_SYSTEM'}
                            || "++GITWEB_CONFIG_SYSTEM++";

Perl variables can be overriden in run-time configuration (testsuite
uses this to test _source_ version i.e. gitweb.perl rather than 
generated gitweb.cgi), so they have to be described anyway.

I think that adding description of make variables to gitweb/Makefile,
similar to what main Makefile does, would be a good idea, though I don't
like that it leads to some duplication.

In practice, I suspect the run-time configuration is more important to
people.  That is already fairly well documented in gitweb/README.

Build-time configuration is also described in gitweb/README, in more
detail.

-- 
Jakub Narebski
Poland