update build instructions

[felixschurk]

Description

In #3236 a problem regarding linkage is mentioned however the occured problem is mainly due to unclear usage of the metabuild system. Therefore, this changes update the develop guidelines minimally.

Usage of "modern" CMake syntax and using specific out of source build. Further add example on how to build in parallel, build a specific target and how to change the compiler.

This closes #3236.

Open Questions

• Should the commands have a $ prefixed to symbolize that they are run in the shell? Or better without to allow people to simply copy them?

• In order to use the provided documentation, CMake would need to be be newer than 3.12, I think this differs a bit from the code requirements (3.0). However, I think that people will have this version minimally, as it was released in 2018.

[felixschurk]

Should docker/task.dockerfile be updated accordingly?

I guess it would make sense to also have it consistent over the whole repository. It should have Ubuntu 22.04 as a base image, right?

[ryneeverett]

I guess it would make sense to also have it consistent over the whole repository. It should have Ubuntu 22.04 as a base image, right?

I don't understand what you're asking but I would note that all the image definitions in taskwarrior/test/docker should probably also be updated.

[felixschurk]

I guess it would make sense to also have it consistent over the whole repository. It should have Ubuntu 22.04 as a base image, right?

I don't understand what you're asking but I would note that all the image definitions in taskwarrior/test/docker should probably also be updated.

I mainly was asking like how recent the docker images are, not that it would fail due to old versions of CMake. We can update also there the commands and also in general the images, however I think that should come in a separate PR. One could also remove obsolete images such as Fedora 32, which is EOL since 2021. I can prepare another PR for this one.

[djmitche]

I think I already did that in #3248?

[felixschurk]

I think I already did that in #3248?

Ah yes there is the change to the newer distro versions in the CI.

I was mainly confused as the "old" version docker files are still in the folder namely

• fedora32
• fedora33
• fedora34
• fedora35
• ubuntu1604
• ubuntu1804

At least these are the distros I know are EOL. It was for me not obvious that they are no longer in use.

[felixschurk]

Just now saw that #3272 would update the CMake version. That's good, as then also the build instructions would make use of the newer CMake.

[djmitche]

Oh, good point - please feel free to submit a PR to delete those docker files and corresponding bits of docker-compose.yml.

[felixschurk]

Idk why it did not add all suggestions in the first commit... I hope now they are all covered.

[djmitche]

@ryneeverett are you happy with this?

[ryneeverett]

@ryneeverett are you happy with this?

I don't have an opinion on cmake usage but am happy to defer to the author's expertise. It would be nice if the docker images all used the same invocation we recommend to users though. Divergence of documentation and CI is best avoided unless there is a good reason for it.

[ryneeverett]

Also, I tried to follow the directions and cmake doesn't actually build the executables (e.g. ./src/task) like the previous instructions did.

[felixschurk]

Also, I tried to follow the directions and cmake doesn't actually build the executables (e.g. ./src/task) like the previous instructions did.

Hm this is strange. So you did run

cmake -S . -B cmake-build  -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build cmake-build

but can not find the task executable in cmake-build/src?

If yes, did it fail at some point or so?

[ryneeverett]

Hm this is strange. So you did run

cmake -S . -B cmake-build  -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build cmake-build

but can not find the task executable in cmake-build/src?

Ah, the executable was indeed built at cmake-build/src/task, whereas it used to be built at src/task. If you grep the repository for "src/task" you'll see that that path is hard-coded in several place so that needs to be resolved by either changing the build location, adding a symlink, or adjusting all the hard-coded paths.

Edit: I'd note that had CI been updated at the same time as documentation, we would have run into this discrepancy. :)

[felixschurk]

Oh, that is quite interesting.

So this means taskwarrior was usually build using in-source builds, more Information on CMake documentation (Directory Structure).

In order to have the in-source build one can run

cmake -S . -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build 

However, as it is not recommended by CMake I would not encourage doing so.

If you grep the repository for "src/task" you'll see that that path is hard-coded in several place so that needs to be resolved by either changing the build location, adding a symlink, or adjusting all the hard-coded paths.

I grepped it and I found it in following locations

• test/bash_tap_tw.sh
• docker/task.dockerfile
• performance/load
• performance/run_perf
• CMakeLists.txt

So I see two ways how one could proceed here.

1. Keep it as it is, and use an in-source build to not change anything.
2. Use an out-of source build directory (let's name it build) and update the paths.

I personally think way two should be the one to go, and I could try to take care of it.

@ryneeverett are you happy with this?

I don't have an opinion on cmake usage but am happy to defer to the author's expertise. It would be nice if the docker images all used the same invocation we recommend to users though. Divergence of documentation and CI is best avoided unless there is a good reason for it.

I also think that it would make sense to go with the CMake approach in the Dockerfiles/CI, as it in the end calls the corresponding underlying build tool. Hence, if one would try it on Windows one could use the same command however then not the GNU Make would be called, instead the Windows tool for it (I don't know which one that is), giving users a unified interface without needing to worry which build tool is used. The changes in the Dockerfiles would be quite minimal, I guess

cmake -S . -B cmake-build  -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build cmake-build
cmake --install cmake-build

would basically summarize the changes.

[djmitche]

I just switched to out of tree builds while working on changes to the rust build stuff. I think it's best to just make that change everywhere now.

[ryneeverett]

$ git grep -E "src/task"
.gitignore:src/task
.gitignore:src/taskd
CMakeLists.txt:                                "test" "package-config" "misc/*" "src/task$" "src/calc$" "performance"
doc/devel/contrib/development.md:This will build several executables, but the one you want is probably `src/task`.
docker/task.dockerfile:COPY --from=builder /root/code/src/task /usr/local/bin
performance/load:    qx{../src/task rc:perf.rc rc.gc=off $anno_id annotate $line};
performance/load:    qx{../src/task rc:perf.rc rc.gc=off add $line};
performance/load:    qx{../src/task rc:perf.rc rc.gc=off log $line};
performance/run_perf:  TASK=../src/task
test/CMakeLists.txt:                     ${CMAKE_SOURCE_DIR}/src/taskchampion/lib
test/bash_tap_tw.sh:    for t in "${bashtap_org_pwd}/task" "${bashtap_org_pwd}/src/task" "${bashtap_org_pwd}/../task" "${bashtap_org_pwd}/../src/task" "${bashtap_org_pwd}/../build/src/task"; do

[felixschurk]

I just switched to out of tree builds while working on changes to the rust build stuff. I think it's best to just make that change everywhere now.

Which 'default' directory name should be used? Simple build or cmake-build? I think e.g. Clion uses cmake-build-buildtype as a directory pattern.

[djmitche]

Let's just use build. Keep it simple :)

[felixschurk]

The removal of the unused docker files is now included in this PR as I was already working in the directory also updating the other scripts.

As far as I can tell now, it should use an out-of source build and corresponding calls with the CMake program at the relevant places.

In the force push, I had the path to the test folder wrong, which then of course lead to failing runs.

[felixschurk]

Indeed, but was also fun. Thanks for the guidance and the feedback.