INSTALL

   1 Installation Instructions
   2 -------------------------
   3
   4 Please follow the instructions below to build and install tasksh from source.
   5
   6
   7 Dependencies
   8 ------------
   9
  10 You will need the CMake build system installed in order to build tasksh from
  11 source.  Information on cmake can be obtained at http://cmake.org
  12
  13 Additionally, you will need:
  14
  15   libreadline
  16
  17
  18 Basic Installation
  19 ------------------
  20
  21 Briefly, these shell commands will unpack, build and install Tasksh:
  22
  23   $ tar xzf tasksh-X.Y.Z.tar.gz                   [1]
  24   $ cd tasksh-X.Y.Z                               [2]
  25   $ cmake -DCMAKE_BUILD_TYPE=release .            [3]
  26   $ make                                          [4]
  27   $ sudo make install                             [5]
  28   $ cd .. ; rm -r tasksh-X.Y.Z                    [6]
  29
  30 These commands are explained below:
  31
  32   1. Unpacks the source tarball.  This creates the directory tasksh-X.Y.Z,
  33      containing all the code.
  34
  35   2. Change directory to the root of the distribution.
  36
  37   3. Invokes CMake to scan for dependencies and machine-specific details, then
  38      generate the makefiles.  Requests an optimized build, which will run faster
  39      and be more compact.  This may take a minute.
  40
  41   4. Builds tasksh.  This may take a minute.
  42
  43   5. Installs the program, documentation and other data files.
  44
  45   6. Removes the temporary directory.
  46
  47
  48 Build and configurations options
  49 --------------------------------
  50
  51 You can customize the configuration run with cmake variables. This will modify
  52 the installation process:
  53
  54 To change the installation directory you use the following configuration
  55 variable:
  56
  57   $ cmake -DCMAKE_INSTALL_PREFIX=<path-to-installation-dir> .
  58
  59 cmake configuration variables are applied with the -D option and consist of a
  60 <name> and a <value>:
  61
  62   $ cmake -D<name>=<value> .
  63
  64 Four more variables can customize the installation process. The following table
  65 lists them and their defaults plus the CMAKE_INSTALL_PREFIX:
  66
  67   CMAKE_INSTALL_PREFIX  /usr/local
  68   TASKSH_BINDIR         bin
  69   TASKSH_DOCDIR         share/doc/tasksh
  70   TASKSH_MAN1DIR        share/man/man1
  71
  72 The corresponding TASKSH_* variables will be combined with CMAKE_INSTALL_PREFIX to
  73 get absolute installation directories:
  74
  75   CMAKE_INSTALL_PREFIX/TASKSH_BINDIR   /usr/local/bin
  76   CMAKE_INSTALL_PREFIX/TASKSH_DOCDIR   /usr/local/share/doc/tasksh
  77   CMAKE_INSTALL_PREFIX/TASKSH_MAN1DIR  /usr/local/share/man/man1
  78
  79
  80 Uninstallation
  81 --------------
  82
  83 There is no uninstall option in CMake makefiles. This is a manual process.
  84
  85 To uninstall Tasksh, remove the files listed in the install_manifest.txt file
  86 that was generated when you built Tasksh.
  87
  88
  89 Tasksh Build Notes
  90 -----------------------
  91
  92 Tasksh has dependencies that are detected by CMake in almost all cases, but
  93 there are situations and operating systems that mean you will need to offer a
  94 little help.
  95
  96 If Tasksh will not build on your system, first take a look at the Operating
  97 System notes below.  If this doesn't help, then go to the Troubleshooting
  98 section, which includes instructions on how to contact us for help.
  99
 100
 101 Operating System Notes
 102 ----------------------
 103
 104 Cygwin
 105   If 'make install' fails when writing to the /usr/local/share/ directory,
 106   this may be because your current login doesn't have permission to write
 107   to the Windows directory containing your Cygwin installation. Either
 108   login to Windows as an Administrator and try the 'make install' process
 109   again, or reinstall Cygwin under your normal Windows login.
 110
 111
 112 Troubleshooting
 113 ---------------
 114
 115 If you've recently made changes to dependencies (by reinstalling them, for
 116 example) be sure to rerun 'cmake .' before trying to execute 'make' again.
 117
 118 CMake will run and locate all the necessary pieces for the build, and create
 119 a Makefile.  There may be errors and warnings when running CMake, or there
 120 may be compiler errors and warnings when running 'make'.  Sometimes you will run
 121 CMake with no reported problems, and the build will fail later.  This is
 122 almost always because CMake is mistaken about some assumption.
 123
 124 If a build does not succeed, please send the contents of the 'CMakeCache.txt'
 125 and 'CMakeFiles/CMakeOutput.log' files to support@taskwarrior.org.
 126
 127 If CMake runs but tasksh does not build, please send the contents of the above
 128 files as well as a transcript from the build, which is not written to a file
 129 and must be captured from the terminal.
 130
 131 ---