mirror of
https://github.com/GothenburgBitFactory/taskwarrior.git
synced 2025-06-26 10:54:26 +02:00
106 lines
3.9 KiB
Markdown
106 lines
3.9 KiB
Markdown
# Developing Taskwarrior
|
|
|
|
## Satisfy the Requirements:
|
|
|
|
* CMake 3.22 or later
|
|
* gcc 7.0 or later, clang 6.0 or later, or a compiler with full C++17 support
|
|
* libuuid (if not on macOS)
|
|
* Rust 1.64.0 or higher (hint: use https://rustup.rs/ instead of using your system's package manager)
|
|
|
|
## Install Optional Dependencies:
|
|
* python 3 (for running the test suite)
|
|
* pre-commit (for applying formatting changes locally)
|
|
* clangd or ccls (for C++ integration in many editors)
|
|
* rust-analyzer (for Rust integration in many editors)
|
|
|
|
## Obtain and Build Code:
|
|
The following documentation works with CMake 3.14 and later.
|
|
Here are the minimal steps to get started, using an out of source build directory and calling the underlying build tool over the CMake interface.
|
|
See the general CMake man pages or the [cmake-documentation](https://cmake.org/cmake/help/latest/manual/cmake.1.html) for more,
|
|
|
|
## Basic Building
|
|
```sh
|
|
git clone https://github.com/GothenburgBitFactory/taskwarrior
|
|
cd taskwarrior
|
|
cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
|
|
cmake --build build
|
|
```
|
|
Other possible build types can be `Release` and `Debug`.
|
|
This will build several executables, but the one you want is probably `src/task`, located in the `build` directory.
|
|
When you make changes, just run the last line again.
|
|
|
|
### Building a specific target
|
|
For **only** building the `task` executable, use
|
|
```sh
|
|
cmake --build build --target task_executable
|
|
```
|
|
|
|
### Building in parallel
|
|
If a parallel build is wanted use
|
|
```sh
|
|
cmake --build build -j <number-of-jobs>
|
|
```
|
|
|
|
### Building with clang as compiler
|
|
```sh
|
|
cmake -S . -B build-clang\
|
|
-DCMAKE_C_COMPILER=clang\
|
|
-DCMAKE_CXX_COMPILER=clang++
|
|
cmake --build build-clang
|
|
```
|
|
|
|
## Run the Test Suite:
|
|
For running the test suite [ctest](https://cmake.org/cmake/help/latest/manual/ctest.1.html) is used.
|
|
Before one can run the test suite the `task_executable` must be built.
|
|
After that also the `test_runner` target must be build, which can be done over:
|
|
```sh
|
|
cmake --build build --target test_runner
|
|
```
|
|
Again you may also use the `-j <number-of-jobs>` option for parallel builds.
|
|
|
|
Now one can invoke `ctest` to run the tests.
|
|
```sh
|
|
ctest --test-dir build
|
|
```
|
|
This would run all the test in serial and might take some time.
|
|
|
|
### Running tests in parallel
|
|
```sh
|
|
ctest --test-dir build -j <number-of-jobs>
|
|
```
|
|
|
|
Further it is adviced to add the `--output-on-failure` option to `ctest`, to recieve a verbose output if a test is failing as well as the `--rerun-failed` flag, to invoke in subsequent runs only the failed ones.
|
|
|
|
### Running specific tests
|
|
For this case one can use the `-R <regex>` or `--tests-regex <regex>` option to run only the tests matching the regular expression.
|
|
Running only the `cpp` tests can then be achieved over
|
|
```sh
|
|
ctest --test-dir build -R cpp
|
|
```
|
|
or running the `variant_*` tests
|
|
```sh
|
|
ctest --test-dir build -R variant
|
|
```
|
|
|
|
### Repeating a test case
|
|
In order to find sporadic test failures the `--repeat` flag can be used.
|
|
```sh
|
|
ctest --test-dir build -R cpp --repeat-until-fail 10
|
|
```
|
|
|
|
There are more options to `ctest` such as `--progress`, allowing to have a less verbose output.
|
|
They can be found in the [ctest](https://cmake.org/cmake/help/latest/manual/ctest.1.html) man page.
|
|
|
|
Note that any development should be performed using a git clone, and the current development branch.
|
|
The source tarballs do not reflect HEAD, and do not contain the test suite.
|
|
Follow the [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow) for creating a pull request.
|
|
|
|
## Using a Custom Version of TaskChampion
|
|
|
|
To build against a different version of Taskchampion, modify the requirement in `src/taskchampion-cpp/Cargo.toml`.
|
|
|
|
To build from a local checkout, replace the version with a [path dependency](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-path-dependencies), giving the path to the directory containing TaskChampion's `Cargo.toml`:
|
|
|
|
```toml
|
|
taskchampion = { path = "path/to/taskchampion" }
|
|
```
|