INSTALL.adoc

   1 Installation instructions
   2 =========================
   3 :docext: adoc
   4
   5 Download a tarball from http://jonas.nitro.dk/tig/releases[] or clone the Tig
   6 repository http://github.com/jonas/tig[git://github.com/jonas/tig.git].
   7
   8 NB: Do not use tig-2.0.tar because it will fail to compile due to these issues https://github.com/jonas/tig/pull/283 and https://github.com/jonas/tig/issues/337
   9
  10 The quick and simple way to install Tig is:
  11
  12         $ make
  13         $ make install
  14
  15 By default, `tig` is installed in `$HOME/bin`. To install `tig` elsewhere set
  16 `prefix` to the desired path:
  17
  18         $ make prefix=/usr/local
  19         $ sudo make install prefix=/usr/local
  20
  21 Documentation files, such as manpages, are distributed in the release tarballs,
  22 and can be installed using:
  23
  24         $ make install-doc
  25
  26 When installing directly from the Tig repository, `make install-doc` will assume
  27 that the documentation tool chain is available and build the documentation
  28 locally. In case you do not wish to install the required tools, documentation
  29 can be installed from the 'release' branch using:
  30
  31         $ make install-release-doc
  32
  33 Before upgrading, you are advised to read link:NEWS.{docext}[the release notes].
  34
  35 Installation using `configure`
  36 ------------------------------
  37
  38 Optionally, you can use the `configure` script to detect dependencies:
  39
  40         $ ./configure
  41         $ make
  42         $ make install
  43
  44 If your `iconv` library is not in the default library and include path, you need
  45 to pass the `--with-libiconv` option to `configure` to tell it where to look.
  46
  47 Note, if you are building from the Tig repository, you need to generate
  48 `configure` yourself. First, ensure that `autoconf` is installed on your system,
  49 and then run the following command:
  50
  51         $ make configure
  52
  53 Installation using Homebrew
  54 ---------------------------
  55 You can use link:http://brew.sh[Homebrew] to install Tig on OS X:
  56
  57         $ brew install tig
  58
  59 Installation on Windows
  60 -----------------------
  61 To run on Windows, you will need link:https://www.cygwin.com/[cygwin].
  62 You must then install the packages `git`, `gcc-core`, `make`, `libiconv-devel`
  63 and `libncurses-devel`. Extract the tarball and install by using `configure`
  64 as explained above.
  65
  66 If you want to install from the sources, then you will also need the `automake`
  67 package (which will also install `autoconf`). Then run `make configure` and install
  68 by using `configure` as explained above.
  69
  70 Build configuration
  71 -------------------
  72
  73 Build settings are read from the file `config.make` and for certain systems also
  74 from `contrib/config.make-$kernel`. An example of the latter is Mac OS X, where
  75 `contrib/config.make-Darwin` provides out-of-the-box configuration for using the
  76 system ncurses library and linking with the iconv library. This makes it easy to
  77 configure the build without having to use the `configure` script. As a side
  78 note, `configure` itself generates a `config.make` file.
  79
  80 Apart from the different standard `make` build variables (`CC`, `CFLAGS`, etc.)
  81 and standard `configure` variables (`prefix`, `bindir`, etc.), build settings
  82 can be one of the following flags:
  83
  84  - `NO_SETENV`: Define this variable to enable work-around for missing
  85    `setenv()`.
  86  - `NO_MKSTEMPS`: Define this variable to enable work-around for missing
  87    `mkstemps()`.
  88  - `NO_BUILTIN_TIGRC`: Reduce the size of the binary by not including a
  89    built-in tigrc. The built-in tigrc is used as a fallback when no
  90    `tigrc` is found in the system configuration directory (e.g. `/etc`).
  91  - `TIG_USER_CONFIG`: Allow to customize the `tigrc` path (default `~/.tigrc`).
  92
  93 The following example `config.make` manually configures Tig to use the ncurses
  94 library with wide character support and include the proper ncurses header file
  95 (see tig.h for more information):
  96
  97         LDLIBS = -lncursesw
  98         CPPFLAGS = -DHAVE_NCURSESW_CURSES_H
  99
 100 For more examples of build settings, see `contrib/config.make` and
 101 `config.make.in`.
 102
 103 Tools and packages
 104 ------------------
 105
 106 The following tools and packages are needed:
 107
 108 [cols="2<,8<",options="header"]
 109 |=============================================================================
 110 |Tool                           |Description
 111 |git-core                       |Tig is just a frontend for Git.
 112 |ncurses or ncursesw            |Be sure to have the development files
 113                                  installed. Usually they are available in a
 114                                  separate package ending with `-dev`.
 115
 116                                  Ncurses with wide character support (ncursesw)
 117                                  is required to properly handle UTF-8 encoded
 118                                  strings.
 119
 120                                  Note for packagers: For Tig's `configure`
 121                                  script to work as expected you should avoid
 122                                  configuring and building ncurses using
 123                                  `--with-shared`.
 124 |iconv                          |If iconv is not provided by the c library
 125                                  you need to change the Makefile to link it
 126                                  into the binary.
 127 |=============================================================================
 128
 129 The following tools and packages are optional and mainly needed for creating the
 130 configure script and building documentation:
 131
 132 [cols="2<,8<",options="header"]
 133 |=============================================================================
 134 |Tool                           |Description
 135 |readline                       |Adds support for completion and history in
 136                                  search and command prompts.
 137 |gsed (i.e. GNU sed)            |Required for running the test suite.
 138                                  Can be installed with `brew install gnu-sed`
 139                                  on OS X.
 140 |autoconf                       |Contains autoreconf for generating configure
 141                                  from configure.ac.
 142 |asciidoc (>= 8.4)              |Generates HTML and (DocBook) XML from text.
 143 |xmlto                          |Generates manpages and chunked HTML from XML.
 144 |DocBook XSL (>= 1.72.0)        |Used by xmlto for building manpages.
 145 |DocBook (DSSL/Jade) tools      |Generates PDF from XML.
 146                                  Also known as docbook-utils.
 147 |=============================================================================