mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-06-26 10:54:28 +02:00
0c84dfd42e
Copy paste from Taskwarrior, not used in Timewarrior Signed-off-by: Thomas Lauf <thomas.lauf@tngtech.com>
133 lines
4.9 KiB
Text
133 lines
4.9 KiB
Text
# 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.
|
|
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> .
|
|
|
|
Five 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
|
|
TIMEW_BINDIR bin
|
|
TIMEW_DOCDIR share/doc/timew
|
|
TIMEW_MAN1DIR share/man/man1
|
|
TIMEW_MAN5DIR share/man/man5
|
|
TIMEW_MAN7DIR share/man/man7
|
|
|
|
The corresponding `TIMEW_*` variables will be combined with `CMAKE_INSTALL_PREFIX` to get absolute installation directories:
|
|
|
|
CMAKE_INSTALL_PREFIX/TIMEW_BINDIR /usr/local/bin
|
|
CMAKE_INSTALL_PREFIX/TIMEW_DOCDIR /usr/local/share/doc/timew
|
|
CMAKE_INSTALL_PREFIX/TIMEW_MAN1DIR /usr/local/share/man/man1
|
|
CMAKE_INSTALL_PREFIX/TIMEW_MAN5DIR /usr/local/share/man/man5
|
|
CMAKE_INSTALL_PREFIX/TIMEW_MAN7DIR /usr/local/share/man/man7
|
|
|
|
|
|
# Updating Timewarrior build
|
|
|
|
This section concerns itself with the description of the procedure needed to update the local Timewarrior build from the 'timew' Git repository.
|
|
|
|
To update the local Timewarrior build, you need to update the Git repository, including the `src/libshared` submodule.
|
|
To do that, 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.
|