[PATCH 1/2] INSTALL: Update description of our SHA-1 code

[PATCH 1/2] INSTALL: Update description of our SHA-1 code

[Brian Gernhardt]

We haven't had Mozilla's code or an ARM optimized algorithm since
30ae47b.  Reword the paragraph to give credit but not authorship to
Mozilla.

Signed-off-by: Brian Gernhardt <brian@gernhardtsoftware.com>
---

 Minor nit I noticed while in the INSTALL file.

 INSTALL |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/INSTALL b/INSTALL
index ae7f750..4a57e47 100644
--- a/INSTALL
+++ b/INSTALL
@@ -56,8 +56,8 @@ Issues of note:
 	  library from here.
 
 	  If you don't have openssl, you can use one of the SHA1 libraries
-	  that come with git (git includes the one from Mozilla, and has
-	  its own PowerPC and ARM optimized ones too - see the Makefile).
+	  that come with git (git includes one based on Mozilla's as well
+	  as a PowerPC optimized one - see the Makefile).
 
 	- libcurl library; git-http-fetch and git-fetch use them.  You
 	  might also want the "curl" executable for debugging purposes.
-- 
1.6.4.2.420.g30ecf

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

[Brian Gernhardt]

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.

 INSTALL |   33 +++++++++++++++++++++++----------
 1 files changed, 23 insertions(+), 10 deletions(-)

diff --git a/INSTALL b/INSTALL
index 4a57e47..e08b990 100644
--- a/INSTALL
+++ b/INSTALL
@@ -13,6 +13,10 @@ that uses $prefix, the built results have some paths encoded,
 which are derived from $prefix, so "make all; make prefix=/usr
 install" would not work.
 
+There are many options that can be configured in the makefile using either
+command line defines or a config.mak file.  These options are documented at
+the beginning of the Makefile.
+
 Alternatively you can use autoconf generated ./configure script to
 set up install paths (via config.mak.autogen), so you can write instead
 
@@ -48,12 +52,19 @@ Issues of note:
 	export GIT_EXEC_PATH PATH GITPERLLIB
 
  - Git is reasonably self-sufficient, but does depend on a few external
-   programs and libraries:
+   programs and libraries.  Git can be used without most of them by adding
+   the approriate "NO_<LIBRARY>=YesPlease" to the make command line or
+   config.mak file.
 
 	- "zlib", the compression library. Git won't build without it.
 
-	- "openssl".  Unless you specify otherwise, you'll get the SHA1
-	  library from here.
+	- "ssh" is used to push and pull over the net
+
+	- A POSIX-compliant shell is needed to use most of the bare-bones
+	  Porcelainish scripts.
+
+	- "openssl".  Unless you specify otherwise (with NO_OPENSSL),
+	  you'll get the SHA1 library from here.
 
 	  If you don't have openssl, you can use one of the SHA1 libraries
 	  that come with git (git includes one based on Mozilla's as well
@@ -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.
+	  do not have them (use NO_CURL).
 
 	- expat library; git-http-push uses it for remote lock
-	  management over DAV.  Similar to "curl" above, this is optional.
+	  management over DAV.  Similar to "curl" above, this is optional
+	  (with NO_EXPAT).
 
         - "wish", the Tcl/Tk windowing shell is used in gitk to show the
-          history graphically, and in git-gui.
-
-	- "ssh" is used to push and pull over the net
+          history graphically, and in git-gui.  If you don't want gitk or
+          git-gui, you can use NO_TCLTK.
 
-	- "perl" and POSIX-compliant shells are needed to use most of
-	  the bare-bones Porcelainish scripts.
+	- "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.
 
  - Some platform specific issues are dealt with Makefile rules,
    but depending on your specific installation, you may not
-- 
1.6.4.2.420.g30ecf

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

[Junio C Hamano]

Brian Gernhardt <brian@gernhardtsoftware.com> writes:

> 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.

> @@ -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.

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

[Brian Gernhardt]

On Sep 8, 2009, at 4:26 PM, Junio C Hamano wrote:

> [rewrite suggestions snipped]

I'll re-roll this and the other INSTALL patch as per your suggested re- 
wordings.  I tried to add the minimum needed instead of changing  
things, but many of your suggestions make sense.  And since I'm in  
here anyway, might as well change them.

> Brian Gernhardt <brian@gernhardtsoftware.com> writes:
>> +	- "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.

Glancing at http*.[ch], it looks like we depend on curl's ability to  
speak https instead of using OpenSSL ourselves.

>> +	- "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.

I didn't move it this low so much as not move it when I moved the  
POSIX shell requirement that we can't live without.  Although I use  
git-svn on a regular basis, I don't think of it as core, but you're  
right that it's one of the main tools for many users.  Will move.

~~ Brian

Re: [PATCH 1/2] INSTALL: Update description of our SHA-1 code

[Junio C Hamano]

Brian Gernhardt <brian@gernhardtsoftware.com> writes:

> We haven't had Mozilla's code or an ARM optimized algorithm since
> 30ae47b.  Reword the paragraph to give credit but not authorship to
> Mozilla.

Thanks.

> Signed-off-by: Brian Gernhardt <brian@gernhardtsoftware.com>
> ---
>
>  Minor nit I noticed while in the INSTALL file.
>
>  INSTALL |    4 ++--
>  1 files changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/INSTALL b/INSTALL
> index ae7f750..4a57e47 100644
> --- a/INSTALL
> +++ b/INSTALL
> @@ -56,8 +56,8 @@ Issues of note:
>  	  library from here.
>  
>  	  If you don't have openssl, you can use one of the SHA1 libraries
> -	  that come with git (git includes the one from Mozilla, and has
> -	  its own PowerPC and ARM optimized ones too - see the Makefile).
> +	  that come with git (git includes one based on Mozilla's as well
> +	  as a PowerPC optimized one - see the Makefile).

The leading comment in block/sha1.c says "initially based on ... although
none of the original remains."  "one loosely based on" or "one inspired
by" might be a more fair statement, although I do not feel too strongly
about it.

>  
>  	- libcurl library; git-http-fetch and git-fetch use them.  You
>  	  might also want the "curl" executable for debugging purposes.
> -- 
> 1.6.4.2.420.g30ecf