[thirdparty/git.git] / INSTALL


		Git installation

Normally you can just do "make" followed by "make install", and that
will install the git programs in your own ~/bin/ directory.  If you want
to do a global install, you can do

	$ make prefix=/usr all doc info ;# as yourself
	# make prefix=/usr install install-doc install-html install-info ;# as root

(or prefix=/usr/local, of course).  Just like any program suite
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

	$ make configure ;# as yourself
	$ ./configure --prefix=/usr ;# as yourself
	$ make all doc ;# as yourself
	# make install install-doc install-html;# as root

If you're willing to trade off (much) longer build time for a later
faster git you can also do a profile feedback build with

	$ make profile-all
	# make prefix=... install

This will run the complete test suite as training workload and then
rebuild git with the generated profile feedback. This results in a git
which is a few percent faster on CPU intensive workloads.  This
may be a good tradeoff for distribution packagers.

Note that the profile feedback build stage currently generates
a lot of additional compiler warnings.

Issues of note:

 - Ancient versions of GNU Interactive Tools (pre-4.9.2) installed a
   program "git", whose name conflicts with this program.  But with
   version 4.9.2, after long hiatus without active maintenance (since
   around 1997), it changed its name to gnuit and the name conflict is no
   longer a problem.

   NOTE: When compiled with backward compatibility option, the GNU
   Interactive Tools package still can install "git", but you can build it
   with --disable-transition option to avoid this.

 - You can use git after building but without installing if you want
   to test drive it.  Simply run git found in bin-wrappers directory
   in the build directory, or prepend that directory to your $PATH.
   This however is less efficient than running an installed git, as
   you always need an extra fork+exec to run any git subcommand.

   It is still possible to use git without installing by setting a few
   environment variables, which was the way this was done
   traditionally.  But using git found in bin-wrappers directory in
   the build directory is far simpler.  As a historical reference, the
   old way went like this:

	GIT_EXEC_PATH=`pwd`
	PATH=`pwd`:$PATH
	GITPERLLIB=`pwd`/perl/blib/lib
	export GIT_EXEC_PATH PATH GITPERLLIB

 - Git is reasonably self-sufficient, but does depend on a few external
   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.

	- "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" version 5.8 or later 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, use NO_PERL.

	- "openssl" library is used by git-imap-send to use IMAP over SSL.
	  If you don't need it, use NO_OPENSSL.

	  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 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:// 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
	  (with NO_EXPAT).

	- "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
   have all the libraries/tools needed, or you may have
   necessary libraries at unusual locations.  Please look at the
   top of the Makefile to see what can be adjusted for your needs.
   You can place local settings in config.mak and the Makefile
   will include them.  Note that config.mak is not distributed;
   the name is reserved for local settings.

 - To build and install documentation suite, you need to have
   the asciidoc/xmlto toolchain.  Because not many people are
   inclined to install the tools, the default build target
   ("make all") does _not_ build them.

   "make doc" builds documentation in man and html formats; there are
   also "make man", "make html" and "make info". Note that "make html"
   requires asciidoc, but not xmlto. "make man" (and thus make doc)
   requires both.

   "make install-doc" installs documentation in man format only; there
   are also "make install-man", "make install-html" and "make
   install-info".

   Building and installing the info file additionally requires
   makeinfo and docbook2X.  Version 0.8.3 is known to work.

   Building and installing the pdf file additionally requires
   dblatex.  Version 0.2.7 with asciidoc >= 8.2.7 is known to work.

   The documentation is written for AsciiDoc 7, but by default
   uses some compatibility wrappers to work on AsciiDoc 8. If you have
   AsciiDoc 7, try "make ASCIIDOC7=YesPlease".

   There are also "make quick-install-doc", "make quick-install-man"
   and "make quick-install-html" which install preformatted man pages
   and html documentation. To use these build targets, you need to
   clone two separate git-htmldocs and git-manpages repositories next
   to the clone of git itself.

   It has been reported that docbook-xsl version 1.72 and 1.73 are
   buggy; 1.72 misformats manual pages for callouts, and 1.73 needs
   the patch in contrib/patches/docbook-xsl-manpages-charmap.patch

   Users attempting to build the documentation on Cygwin may need to ensure
   that the /etc/xml/catalog file looks something like this:

   <?xml version="1.0"?>
   <!DOCTYPE catalog PUBLIC
      "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
      "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"
   >
   <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
     <rewriteURI
       uriStartString = "http://docbook.sourceforge.net/release/xsl/current"
       rewritePrefix = "/usr/share/sgml/docbook/xsl-stylesheets"
     />
     <rewriteURI
       uriStartString="http://www.oasis-open.org/docbook/xml/4.5"
       rewritePrefix="/usr/share/sgml/docbook/xml-dtd-4.5"
     />
  </catalog>

  This can be achieved with the following two xmlcatalog commands:

  xmlcatalog --noout \
     --add rewriteURI \
        http://docbook.sourceforge.net/release/xsl/current \
        /usr/share/sgml/docbook/xsl-stylesheets \
     /etc/xml/catalog

  xmlcatalog --noout \
     --add rewriteURI \
         http://www.oasis-open.org/docbook/xml/4.5/xsl/current \
         /usr/share/sgml/docbook/xml-dtd-4.5 \
     /etc/xml/catalog
Commit	Line	Data
c538d2d3 LT	1
	2	Git installation
	3
	4	Normally you can just do "make" followed by "make install", and that
	5	will install the git programs in your own ~/bin/ directory. If you want
	6	to do a global install, you can do
	7
98e79f63	8	$ make prefix=/usr all doc info ;# as yourself
414851a4	9	# make prefix=/usr install install-doc install-html install-info ;# as root
c538d2d3	10
c44922a7 JH	11	(or prefix=/usr/local, of course). Just like any program suite
	12	that uses $prefix, the built results have some paths encoded,
	13	which are derived from $prefix, so "make all; make prefix=/usr
	14	install" would not work.
c538d2d3	15
5beb577d BG	16	The beginning of the Makefile documents many variables that affect the way
	17	git is built. You can override them either from the command line, or in a
	18	config.mak file.
	19
55667714 JN	20	Alternatively you can use autoconf generated ./configure script to
	21	set up install paths (via config.mak.autogen), so you can write instead
	22
3900145e	23	$ make configure ;# as yourself
55667714 JN	24	$ ./configure --prefix=/usr ;# as yourself
55667714 JN	25	$ make all doc ;# as yourself
414851a4	26	# make install install-doc install-html;# as root
55667714	27
39001007 AK	28	If you're willing to trade off (much) longer build time for a later
	29	faster git you can also do a profile feedback build with
	30
	31	$ make profile-all
	32	# make prefix=... install
	33
	34	This will run the complete test suite as training workload and then
	35	rebuild git with the generated profile feedback. This results in a git
	36	which is a few percent faster on CPU intensive workloads. This
	37	may be a good tradeoff for distribution packagers.
	38
	39	Note that the profile feedback build stage currently generates
	40	a lot of additional compiler warnings.
55667714	41
c538d2d3 LT	42	Issues of note:
c538d2d3 LT	43
a958d8ed JH	44	- Ancient versions of GNU Interactive Tools (pre-4.9.2) installed a
	45	program "git", whose name conflicts with this program. But with
	46	version 4.9.2, after long hiatus without active maintenance (since
	47	around 1997), it changed its name to gnuit and the name conflict is no
	48	longer a problem.
	49
25032ccd	50	NOTE: When compiled with backward compatibility option, the GNU
a958d8ed JH	51	Interactive Tools package still can install "git", but you can build it
a958d8ed JH	52	with --disable-transition option to avoid this.
62a64d1a	53
90458012 MO	54	- You can use git after building but without installing if you want
	55	to test drive it. Simply run git found in bin-wrappers directory
	56	in the build directory, or prepend that directory to your $PATH.
	57	This however is less efficient than running an installed git, as
	58	you always need an extra fork+exec to run any git subcommand.
	59
	60	It is still possible to use git without installing by setting a few
	61	environment variables, which was the way this was done
	62	traditionally. But using git found in bin-wrappers directory in
	63	the build directory is far simpler. As a historical reference, the
	64	old way went like this:
3c767a08 JH	65
	66	GIT_EXEC_PATH=`pwd`
	67	PATH=`pwd`:$PATH
f7661ce0	68	GITPERLLIB=`pwd`/perl/blib/lib
6fcca938	69	export GIT_EXEC_PATH PATH GITPERLLIB
3c767a08	70
c538d2d3	71	- Git is reasonably self-sufficient, but does depend on a few external
5beb577d BG	72	programs and libraries. Git can be used without most of them by adding
	73	the approriate "NO_<LIBRARY>=YesPlease" to the make command line or
	74	config.mak file.
c538d2d3 LT	75
	76	- "zlib", the compression library. Git won't build without it.
	77
26d94439 BG	78	- "ssh" is used to push and pull over the net.
	79
	80	- A POSIX-compliant shell is required to run many scripts needed
	81	for everyday use (e.g. "bisect", "pull").
	82
d48b2841 ÆAB	83	- "Perl" version 5.8 or later is needed to use some of the
	84	features (e.g. preparing a partial commit using "git add -i/-p",
	85	interacting with svn repositories with "git svn"). If you can
	86	live without these, use NO_PERL.
26d94439	87
5beb577d BG	88	- "openssl" library is used by git-imap-send to use IMAP over SSL.
5beb577d BG	89	If you don't need it, use NO_OPENSSL.
c538d2d3	90
5beb577d BG	91	By default, git uses OpenSSL for SHA1 but it will use it's own
	92	library (inspired by Mozilla's) with either NO_OPENSSL or
	93	BLK_SHA1. Also included is a version optimized for PowerPC
	94	(PPC_SHA1).
c538d2d3	95
5beb577d	96	- "libcurl" library is used by git-http-fetch and git-fetch. You
1d53f90e	97	might also want the "curl" executable for debugging purposes.
5beb577d BG	98	If you do not use http:// or https:// repositories, you do not
5beb577d BG	99	have to have them (use NO_CURL).
c538d2d3	100
5beb577d BG	101	- "expat" library; git-http-push uses it for remote lock
	102	management over DAV. Similar to "curl" above, this is optional
	103	(with NO_EXPAT).
3402f1d6	104
5beb577d BG	105	- "wish", the Tcl/Tk windowing shell is used in gitk to show the
	106	history graphically, and in git-gui. If you don't want gitk or
	107	git-gui, you can use NO_TCLTK.
663a5ed5	108
3cab3594 JH	109	- Some platform specific issues are dealt with Makefile rules,
	110	but depending on your specific installation, you may not
	111	have all the libraries/tools needed, or you may have
	112	necessary libraries at unusual locations. Please look at the
	113	top of the Makefile to see what can be adjusted for your needs.
cd8c4589 JR	114	You can place local settings in config.mak and the Makefile
	115	will include them. Note that config.mak is not distributed;
	116	the name is reserved for local settings.
eff351c9	117
a90918e8 JH	118	- To build and install documentation suite, you need to have
	119	the asciidoc/xmlto toolchain. Because not many people are
	120	inclined to install the tools, the default build target
98e79f63 DK	121	("make all") does _not_ build them.
98e79f63 DK	122
414851a4 MG	123	"make doc" builds documentation in man and html formats; there are
	124	also "make man", "make html" and "make info". Note that "make html"
	125	requires asciidoc, but not xmlto. "make man" (and thus make doc)
	126	requires both.
	127
	128	"make install-doc" installs documentation in man format only; there
	129	are also "make install-man", "make install-html" and "make
	130	install-info".
	131
98e79f63 DK	132	Building and installing the info file additionally requires
	133	makeinfo and docbook2X. Version 0.8.3 is known to work.
	134
a325a1a7 MV	135	Building and installing the pdf file additionally requires
	136	dblatex. Version 0.2.7 with asciidoc >= 8.2.7 is known to work.
	137
79c461d5 JK	138	The documentation is written for AsciiDoc 7, but by default
	139	uses some compatibility wrappers to work on AsciiDoc 8. If you have
	140	AsciiDoc 7, try "make ASCIIDOC7=YesPlease".
a90918e8	141
b1a46b70 MH	142	There are also "make quick-install-doc", "make quick-install-man"
b1a46b70 MH	143	and "make quick-install-html" which install preformatted man pages
fcbebfdd JH	144	and html documentation. To use these build targets, you need to
	145	clone two separate git-htmldocs and git-manpages repositories next
	146	to the clone of git itself.
6fe570de	147
2ec39eda JH	148	It has been reported that docbook-xsl version 1.72 and 1.73 are
	149	buggy; 1.72 misformats manual pages for callouts, and 1.73 needs
	150	the patch in contrib/patches/docbook-xsl-manpages-charmap.patch
0edf06dc JS	151
	152	Users attempting to build the documentation on Cygwin may need to ensure
	153	that the /etc/xml/catalog file looks something like this:
	154
	155	<?xml version="1.0"?>
	156	<!DOCTYPE catalog PUBLIC
	157	"-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
	158	"http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"
	159	>
	160	<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
	161	<rewriteURI
	162	uriStartString = "http://docbook.sourceforge.net/release/xsl/current"
	163	rewritePrefix = "/usr/share/sgml/docbook/xsl-stylesheets"
	164	/>
	165	<rewriteURI
	166	uriStartString="http://www.oasis-open.org/docbook/xml/4.5"
	167	rewritePrefix="/usr/share/sgml/docbook/xml-dtd-4.5"
	168	/>
	169	</catalog>
	170
	171	This can be achieved with the following two xmlcatalog commands:
	172
	173	xmlcatalog --noout \
	174	--add rewriteURI \
	175	http://docbook.sourceforge.net/release/xsl/current \
	176	/usr/share/sgml/docbook/xsl-stylesheets \
	177	/etc/xml/catalog
	178
	179	xmlcatalog --noout \
	180	--add rewriteURI \
	181	http://www.oasis-open.org/docbook/xml/4.5/xsl/current \
	182	/usr/share/sgml/docbook/xml-dtd-4.5 \
	183	/etc/xml/catalog