# Installation Instructions Please follow the instructions below to build and install Timewarrior from source. # Dependencies In order to build Timewarrior, you will need: - CMake (See https://cmake.org) - Make - Asciidoctor (for building documentation) You will need a C++ compiler that supports full C++17, which includes: - GCC 8 - Clang 5 # Basic Installation Briefly, these shell commands will unpack, build and install Timewarrior: $ tar xzf timew-X.Y.Z.tar.gz [1] $ cd timew-X.Y.Z [2] $ cmake . [3] $ make [4] $ sudo make install [5] $ cd .. ; rm -r timew-X.Y.Z [6] These commands are explained below: 1. Unpacks the source tarball. This creates the directory timew-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 Timewarrior. 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. CMake configuration variables are applied with the `-D` option and consist of a `` and a ``: $ cmake -D= . To change the installation directory, use the `CMAKE_INSTALL_PREFIX` variable: $ cmake -DCMAKE_INSTALL_PREFIX= . This variable defaults to `/usr/local` on UNIX/Linux systems. Five more variables can customize the installation process. The following table lists them and their default values: | Variable | Default Value | |-----------------|-------------------| | `TIMEW_BINDIR` | `bin` | | `TIMEW_DOCDIR` | `share/doc/timew` | | `TIMEW_MANDIR` | `share/man` | | `TIMEW_MAN1DIR` | `share/man/man1` | | `TIMEW_MAN7DIR` | `share/man/man7` | On FreeBSD or DragonFly BSD systems, the `share/` directory is omitted for the `TIMEW_MAN*DIR` variables. The `TIMEW_*` variables are combined with the value of `CMAKE_INSTALL_PREFIX` to get the absolute paths. # Updating Timewarrior build To update the local Timewarrior build, you need to update the Git repository, including the `src/libshared` submodule, run: $ git pull --recurse-submodules $ git submodule update At this point you have the fully updated sources at your disposal, and you can update your local build following the regular build instructions: $ cmake . $ make $ sudo make install # Uninstallation There is no uninstall option in CMake makefiles. This is a manual process. To uninstall Timewarrior, remove the files listed in the `install_manifest.txt` file that was generated when you built Timewarrior. # Timewarrior Build Notes Timewarrior 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 Timewarrior does 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. # Troubleshooting If you've recently made changes to dependencies (by reinstalling them, 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@gothenburgbitfactory.org`. If CMake runs but Timewarrior 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.