Installation Instructions
-------------------------

# Building task with autotools is deprecated and will be phased out.
#
# Please follow the instructions below to build task with cmake.
#
# In case you still want or need to build task with autotools:
#
#    $ ./configure
#    $ make
#    $ sudo make install
#
# For more details on using autotools and options to ./configure please refer
# to the autoconf manual.

Pre-requisites
--------------

You will need the CMake build system installed in order to build taskwarrior
from source.

Optionally, you might want to have Lua installed, if you wish to write plugins
and modify taskwarrior.

More information on cmake can be obtained at http://cmake.org

Basic Installation
------------------

Briefly, these shell commands will unpack, build and install taskwarrior:

  $ tar xzf task-X.Y.Z.tar.gz                     [1]
  $ cd task-X.Y.Z                                 [2]
  $ cmake .                                       [3]
  $ make                                          [4]
  $ sudo make install                             [5]
  $ cd .. ; rm -r task-X.Y.Z                      [6]

These commands are explained below:

  1. Unpacks the source tarball.  This creates the directory task-X.Y.Z,
     containing all the code.

  2. Change directory to the root of the distribution.

  3. Invokes CMake to scan for dependencies and machine-specific details, then
     generate the makefiles.  This may take a minute.

  4. Builds taskwarrior.  This may take a minute.

  5. Installs the program, documentation and other data files.

  6. Removes the temporary directory.


Build and configurations options
--------------------------------

You can customize the configuration run with cmake variables. This will modify the
installation process:

To change the installation directory you use the following configuration variable:

  $ cmake -DCMAKE_INSTALL_PREFIX=<path-to-installation-dir> .

cmake configuration variables are applied with the -D option and consist of a <name>
and a <value>:

  $ cmake -D<name>=<value> .

Four more variables can customize the installation process. The following table lists
them and their defaults plus the CMAKE_INSTALL_PREFIX:

  CMAKE_INSTALL_PREFIX  /usr/local
  TASK_BINDIR           bin
  TASK_DOCDIR           share/doc/task
  TASK_MAN1DIR          share/man/man1
  TASK_MAN5DIR          share/man/man5

The correpsonding TASK_* variables will be combined with CMAKE_INSTALL_PREFIX to get
absolute installation directoris:

  CMAKE_INSTALL_PREFIZ/TASK_BINDIR   /usr/local/bin
  CMAKE_INSTALL_PREFIZ/TASK_DOCDIR   /usr/local/share/doc/task
  CMAKE_INSTALL_PREFIZ/TASK_MAN1DIR  /usr/local/share/man/man1
  CMAKE_INSTALL_PREFIZ/TASK_MAN5DIR  /usr/local/share/man/man5


Uninstallation
--------------

To uninstall taskwarrior, you need the Makefiles, so if you deleted them in
step 7 above, they must first be regenerated by following steps [1], [2] and
[3].  Then simply run:

    $ sudo make uninstall TODO TODO TODO -- cmake doesn't include uninstall


Taskwarrior Build Notes
-----------------------

Taskwarrior 1.9.4 has dependencies that are detected by cmake in almost all cases,
but there are situations and operating systems that mean you will need to offer
a little help.

If taskwarrior will not build on your system, first take a look at the Operating
System notes below.  If this doesn't help, then go to the Troubleshooting
section, which includes instructions on how to contact us for help.


Operating System Notes
----------------------

Cygwin
  If 'make install' fails when writing to the /usr/local/share/ directory,
  this may be because your current login doesn't have permission to write
  to the Windows directory containing your Cygwin installation. Either
  login to Windows as an Administrator and try the 'make install' process
  again, or reinstall Cygwin under your normal Windows login.


Darwin
  If you're having trouble with Lua, check to see if the include files were
  installed. If you're using fink, this will require the lua51-dev package in
  addition to lua51.


Troubleshooting
---------------

If you've recently made changes to dependencies (by reinstalling Lua, for
example) be sure to rerun 'cmake .' before trying to execute 'make' again.

CMake will run and locate all the necessary pieces for the build, and create
a Makefile.  There may be errors and warnings when running CMake, or there
may be compiler errors and warnings when running 'make'.  Sometimes you will run
CMake with no reported problems, and the build will fail later.  This is
almost always because CMake is mistaken about some assumption.

If a build does not succeed, please send the contents of the 'CMakeCache.txt' 
and 'CMakeFiles/CMakeOutput.log' files to support@taskwarrior.org, or post a
message in the support forums at taskwarrior.org along with the information.

If CMake runs but taskwarrior does not build, please send the contents of the
above files as well as a transcript from the build, which is not written to a
file and must be captured from the terminal.

---