[PATCH v2 0/3] INSTALL updates

[PATCH v2 0/3] INSTALL updates

[Brian Gernhardt]

I'm now up to a three patch series for this minor documentation update.
:-/

The first one simply removes the references to code that no longer exists
in our tree.  This paragraph will be changed again in 3/3 so this patch
could be dropped, but I left it since the factual error is a different
issue than the later enhancements.

The second patch mostly reorders the text so that later changes are more
obvious.  It does contain the changes Junio suggested regarding shell and
perl, since the old wording is archaic and confusing to new users.

The third contains the additions concerning the Makefile switches.  It has
been updated based on Junio's commends.

Brian Gernhardt (3):
  INSTALL: Update description of our SHA-1 code
  INSTALL: Reorder dependencies, split shell and Perl
  INSTALL: Describe dependency knobs from Makefile

 INSTALL |   48 +++++++++++++++++++++++++++++++-----------------
 1 files changed, 31 insertions(+), 17 deletions(-)

[PATCH v2 1/3] 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>
---

 The only change from v1 here is "based on" -> "inspired by".

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

diff --git a/INSTALL b/INSTALL
index ae7f750..5267468 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 inspired by Mozilla's and a
+	  PowerPC optimized one too - 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

[PATCH v2 2/3] INSTALL: Reorder dependencies, split shell and Perl

[Brian Gernhardt]

The most important and non-optional dependencies should go first, so put
them there.  While we're moving them, the descriptions for shell and perl
were archaic, referring to "bare-bones Porcelainish scripts" that have
become powerful and essential.

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

 Split from v1's 2/2 so the changes don't get confused with the re-order.

 I kept the shell and perl re-wordings here since they're also somewhat of
 a factual error instead of 3/3's additions.

 INSTALL |   14 +++++++++-----
 1 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/INSTALL b/INSTALL
index 5267468..7ab2580 100644
--- a/INSTALL
+++ b/INSTALL
@@ -52,6 +52,15 @@ Issues of note:
 
 	- "zlib", the compression library. Git won't build without it.
 
+	- "ssh" is used to push and pull over the net.
+
+	- A POSIX-compliant shell is required to run many scripts needed
+	  for everyday use (e.g. "bisect", "pull").
+
+	- "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").
+
 	- "openssl".  Unless you specify otherwise, you'll get the SHA1
 	  library from here.
 
@@ -70,11 +79,6 @@ Issues of note:
         - "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
-
-	- "perl" and POSIX-compliant shells are needed to use most of
-	  the bare-bones Porcelainish scripts.
-
  - Some platform specific issues are dealt with Makefile rules,
    but depending on your specific installation, you may not
    have all the libraries/tools needed, or you may have
-- 
1.6.4.2.420.g30ecf

[PATCH v2 3/3] INSTALL: Describe dependency knobs from 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, standardize on both using quotes for the names of the dependencies
and tabs for indentation of the list.

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

 This has the most changes since v1, containing re-writes based on Junio's
 comments.  The paragraph changed in 1/1 gets changed again to include the
 Makefile switches and adapt to changes in the previous paragraph.

 I dropped the RFC since Junio seemed to appreciate the changes, but I kept
 the style changes here separate from the earlier factual changes both
 because I prefer to work that way and to allow the others to continue if
 discussion needs to continue on this one.

 INSTALL |   38 ++++++++++++++++++++++++--------------
 1 files changed, 24 insertions(+), 14 deletions(-)

diff --git a/INSTALL b/INSTALL
index 7ab2580..69c97b2 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,7 +52,9 @@ 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.
 
@@ -59,25 +65,29 @@ Issues of note:
 
 	- "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").
+	  repositories with "git svn").  If you can live without these, use
+	  NO_PERL.
 
-	- "openssl".  Unless you specify otherwise, you'll get the SHA1
-	  library from here.
+	- "openssl" library is used by git-imap-send to use IMAP over SSL.
+	  If you don't need it, use NO_OPENSSL.
 
-	  If you don't have openssl, you can use one of the SHA1 libraries
-	  that come with git (git includes one inspired by Mozilla's and a
-	  PowerPC optimized one too - see the Makefile).
+	  By default, git uses OpenSSL for SHA1 but it will use it's own
+	  library (inspired by Mozilla's) with either NO_OPENSSL or
+	  BLK_SHA1.  Also included is a version optimized for PowerPC
+	  (PPC_SHA1).
 
-	- libcurl library; git-http-fetch and git-fetch use them.  You
+	- "libcurl" library is used by git-http-fetch and git-fetch.  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.
+	  If you do not use http:// or https:// repositories, you do not
+	  have to 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.
+	- "expat" library; git-http-push uses it for remote lock
+	  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.
+	- "wish", the Tcl/Tk windowing shell is used in gitk to show the
+	  history graphically, and in git-gui.  If you don't want gitk or
+	  git-gui, you can use NO_TCLTK.
 
  - 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: [PATCH v2 2/3] INSTALL: Reorder dependencies, split shell and Perl

[Junio C Hamano]

Brian Gernhardt <brian@gernhardtsoftware.com> writes:

> The most important and non-optional dependencies should go first, so put
> them there.  While we're moving them, the descriptions for shell and perl
> were archaic, referring to "bare-bones Porcelainish scripts" that have
> become powerful and essential.
>
> Signed-off-by: Brian Gernhardt <brian@gernhardtsoftware.com>
> ---
>
>  Split from v1's 2/2 so the changes don't get confused with the re-order.
>
>  I kept the shell and perl re-wordings here since they're also somewhat of
>  a factual error instead of 3/3's additions.
>
>  INSTALL |   14 +++++++++-----
>  1 files changed, 9 insertions(+), 5 deletions(-)
>
> diff --git a/INSTALL b/INSTALL
> index 5267468..7ab2580 100644
> --- a/INSTALL
> +++ b/INSTALL
> @@ -52,6 +52,15 @@ Issues of note:
>  
>  	- "zlib", the compression library. Git won't build without it.
>  
> +	- "ssh" is used to push and pull over the net.
> +
> +	- A POSIX-compliant shell is required to run many scripts needed
> +	  for everyday use (e.g. "bisect", "pull").
>
> +	- "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").
> +

This is a very minor point, but should we even make a distinction between
"scripts" vs "features" here?  It is a minor detail that "bisect" and
"pull" are implemented as scripts after all.  I dunno.

Re: [PATCH v2 3/3] INSTALL: Describe dependency knobs from Makefile

[Junio C Hamano]

Brian Gernhardt <brian@gernhardtsoftware.com> writes:

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

I did not like calling "make variables" "options", and also it was unclear
what good these "options" are for.  How about...

    The beginning of the Makefile documents many variables that affect the way
    git is built.  You can override them either from the command line, or in a
    config.mak file.

[PATCH v3 3/3] INSTALL: Describe dependency knobs from 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, standardize on both using quotes for the names of the dependencies
and tabs for indentation of the list.

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

  Junio C Hamano <gitster@pobox.com> wrote:
  > I did not like calling "make variables" "options", and also it was unclear
  > what good these "options" are for.  How about...

 Sounds good.  Would have sent this out yesterday, but I ran out of tuits.

 INSTALL |   38 ++++++++++++++++++++++++--------------
 1 files changed, 24 insertions(+), 14 deletions(-)

diff --git a/INSTALL b/INSTALL
index 7ab2580..69c97b2 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,7 +52,9 @@ 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.
 
@@ -59,25 +65,29 @@ Issues of note:
 
 	- "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").
+	  repositories with "git svn").  If you can live without these, use
+	  NO_PERL.
 
-	- "openssl".  Unless you specify otherwise, you'll get the SHA1
-	  library from here.
+	- "openssl" library is used by git-imap-send to use IMAP over SSL.
+	  If you don't need it, use NO_OPENSSL.
 
-	  If you don't have openssl, you can use one of the SHA1 libraries
-	  that come with git (git includes one inspired by Mozilla's and a
-	  PowerPC optimized one too - see the Makefile).
+	  By default, git uses OpenSSL for SHA1 but it will use it's own
+	  library (inspired by Mozilla's) with either NO_OPENSSL or
+	  BLK_SHA1.  Also included is a version optimized for PowerPC
+	  (PPC_SHA1).
 
-	- libcurl library; git-http-fetch and git-fetch use them.  You
+	- "libcurl" library is used by git-http-fetch and git-fetch.  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.
+	  If you do not use http:// or https:// repositories, you do not
+	  have to 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.
+	- "expat" library; git-http-push uses it for remote lock
+	  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.
+	- "wish", the Tcl/Tk windowing shell is used in gitk to show the
+	  history graphically, and in git-gui.  If you don't want gitk or
+	  git-gui, you can use NO_TCLTK.
 
  - 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: [PATCH v3 3/3] INSTALL: Describe dependency knobs from 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, standardize on both using quotes for the names of the dependencies
> and tabs for indentation of the list.
>
> Signed-off-by: Brian Gernhardt <brian@gernhardtsoftware.com>
> ---
>
>   Junio C Hamano <gitster@pobox.com> wrote:
>   > I did not like calling "make variables" "options", and also it was unclear
>   > what good these "options" are for.  How about...
>
>  Sounds good.  Would have sent this out yesterday, but I ran out of tuits.
>
>  INSTALL |   38 ++++++++++++++++++++++++--------------
>  1 files changed, 24 insertions(+), 14 deletions(-)
>
> diff --git a/INSTALL b/INSTALL
> index 7ab2580..69c97b2 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.

Sorry, but the description still speaks of options and does not say what
good they are.  Sent a wrong patch?

[PATCH v3 3/3] INSTALL: Describe dependency knobs from 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, standardize on both using quotes for the names of the dependencies
and tabs for indentation of the list.

Signed-off-by: Brian Gernhardt <brian@gernhardtsoftware.com>
---
 INSTALL |   38 ++++++++++++++++++++++++--------------
 1 files changed, 24 insertions(+), 14 deletions(-)

 Junio C Hamano <gitster@pobox.com> wrote:

 > Sorry, but the description still speaks of options and does not say what
 > good they are.  Sent a wrong patch?

 Wrong patch?  Never.  A good git developer always makes sure he re-generated
 patch files before making a fool of himself on a public list.

 Ahem.

diff --git a/INSTALL b/INSTALL
index 7ab2580..be504c9 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.
 
+The beginning of the Makefile documents many variables that affect the way
+git is built.  You can override them either from the command line, or in a
+config.mak file.
+
 Alternatively you can use autoconf generated ./configure script to
 set up install paths (via config.mak.autogen), so you can write instead
 
@@ -48,7 +52,9 @@ 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.
 
@@ -59,25 +65,29 @@ Issues of note:
 
 	- "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").
+	  repositories with "git svn").  If you can live without these, use
+	  NO_PERL.
 
-	- "openssl".  Unless you specify otherwise, you'll get the SHA1
-	  library from here.
+	- "openssl" library is used by git-imap-send to use IMAP over SSL.
+	  If you don't need it, use NO_OPENSSL.
 
-	  If you don't have openssl, you can use one of the SHA1 libraries
-	  that come with git (git includes one inspired by Mozilla's and a
-	  PowerPC optimized one too - see the Makefile).
+	  By default, git uses OpenSSL for SHA1 but it will use it's own
+	  library (inspired by Mozilla's) with either NO_OPENSSL or
+	  BLK_SHA1.  Also included is a version optimized for PowerPC
+	  (PPC_SHA1).
 
-	- libcurl library; git-http-fetch and git-fetch use them.  You
+	- "libcurl" library is used by git-http-fetch and git-fetch.  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.
+	  If you do not use http:// or https:// repositories, you do not
+	  have to 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.
+	- "expat" library; git-http-push uses it for remote lock
+	  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.
+	- "wish", the Tcl/Tk windowing shell is used in gitk to show the
+	  history graphically, and in git-gui.  If you don't want gitk or
+	  git-gui, you can use NO_TCLTK.
 
  - Some platform specific issues are dealt with Makefile rules,
    but depending on your specific installation, you may not
-- 
1.6.4.2.420.g30ecf