Re: [RFC PATCH 2/2] INSTALL: Describe a few knobs from the Makefile

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 8, 2009, 20:26 UTC
Message-ID: <7vy6opxjx8.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1252425313-69793-2-git-send-email-brian@gernhardtsoftware.com>

Brian Gernhardt <brian@gernhardtsoftware.com> writes:

Show 12 quoted lines

> We said that some of our dependencies were optional, but didn't say
> how to turn them off.  Add information for that and mention where to
> save the options close to the top of the file.
>
> Also, reorder the list so the absolutely required ones are at the top.
>
> Signed-off-by: Brian Gernhardt <brian@gernhardtsoftware.com>
> ---
>
>  I don't know if anyone wants this level of detail in the INSTALL file, or
>  if we'd prefer people actually RTFMakefile.  It didn't take long to write
>  though, so I thought I'd throw it out and see if people liked it.

Thanks.

Sprinkling these Makefile variable names in this document does not add too much detail. If anything, they serve as good keyphrases to jump to when you have Makefile in your pager and editing your own config.mak.

I like your patch especially because it makes it clear what the reader will be missing if s/he chooses to omit some dependencies.

> +	- "ssh" is used to push and pull over the net
> +

Please add a full-stop at the end (original was missing one, too).

> +	- A POSIX-compliant shell is needed to use most of the bare-bones
> +	  Porcelainish scripts.

Let's stop talking about Porcelain/plumbing in this document.

It is very likely that the reader of this file has not read the main documentation that talks about the two-tier structure.

The self pejorative reference "bare-bones" dates back to the days when git Porcelains were supposed to be merely simpler reference implementations, as opposed to something more end-user friendly like what Cogito aimed to be. But that is an old history, and there is nothing "bare-bones" about them anymore.

So please reword it along this line:

	- A POSIX-compilant shell is needed to use many of the features
          (e.g. "bisect", "pull") in everyday use.

> +	- "openssl".  Unless you specify otherwise (with NO_OPENSSL),
> +	  you'll get the SHA1 library from here.

It is not very clear what will be affected by disabling this.

 - SHA-1 is not used from OpenSSL, as stated;
 - imap-send won't be able to talk over SSL;

Do we still able to walk https:// URLs? If your cURL library is linked with gnutls I think we can, but I never tried the combination.

Show 5 quoted lines

> @@ -62,18 +73,20 @@ Issues of note:
>  	- libcurl library; git-http-fetch and git-fetch use them.  You
>  	  might also want the "curl" executable for debugging purposes.
>  	  If you do not use http transfer, you are probably OK if you
> +	  do not have them (use NO_CURL).

Probably reads more easily if it were:

	If you do not interact with http:// repositories, you do not have
	to have them (say NO_CURL).

> +	- "perl" is used for several scripts that are useful, but not
> +	  required for git (e.g. "git add -i" and "git difftool").  If you
> +	  don't need the *.perl scripts or the library contained in perl/,
> +	  then use NO_PERL.

I do not think moving "Perl" this low in the requirement level is such a good idea, at least for now. I'd suggest movign it back immediately after POSIX-compliant shell, and would say something like this:

	- "Perl" is needed to use some of the features (e.g. preparing a
          partial commit using "git add -i/-p", interacting with svn
          repositories with "git svn").  If you can live without these,
          say NO_PERL.

Maybe they are Ruby, github, and general acceptance by many open source projects these days, but it used to be that the initial entry points to git were "git cvsimport" and "git svn" for a surprisingly large number of people.