-
Notifications
You must be signed in to change notification settings - Fork 97
/
INSTALL
127 lines (74 loc) · 4.57 KB
/
INSTALL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
# 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 `<name>` and a `<value>`:
$ cmake -D<name>=<value> .
To change the installation directory, use the `CMAKE_INSTALL_PREFIX` variable:
$ cmake -DCMAKE_INSTALL_PREFIX=<path-to-installation-dir> .
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 `[email protected]`.
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.