CDRIVER-4763 reapply BUILD_VERSION CMake option

[kevinAlbs]

Summary

Document removal of BUILD_VERSION CMake option.

Apply BUILD_VERSION CMake option

Background & Motivation

#1382 removes the ability to specify a custom BUILD_VERSION.

This may result in an error when if attempting to build a source archive with steps that previously worked on 1.24.4:

wget "https://github.com/mongodb/mongo-c-driver/archive/refs/tags/1.25.0.tar.gz"
tar xf 1.25.0.tar.gz
cd mongo-c-driver-1.25.0
cmake -DBUILD_VERSION=1.25.0 -S. -Bcmake-build

Results in this error due to BUILD_VERSION being ignored:

Traceback (most recent call last):
  File "/Users/kevin.albertson/Desktop/mongo-c-driver-1.25.0/build/cmake/../calc_release_version.py", line 400, in <module>
    RELEASE_VER = previous(main()) if PREVIOUS else main()
                                                    ^^^^^^
  File "/Users/kevin.albertson/Desktop/mongo-c-driver-1.25.0/build/cmake/../calc_release_version.py", line 320, in main
    head_commit_short = check_output(['git', 'rev-parse', '--revs-only',
                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/kevin.albertson/Desktop/mongo-c-driver-1.25.0/build/cmake/../calc_release_version.py", line 136, in check_output
    raise subprocess.CalledProcessError(ret, args[0])
subprocess.CalledProcessError: Command 'git' returned non-zero exit status 128.
CMake Error at build/cmake/BuildVersion.cmake:43 (message):
  Computing the build version failed! [1]:

Call Stack (most recent call first):
  build/cmake/BuildVersion.cmake:50 (compute_build_version)
  CMakeLists.txt:5 (include)


-- Configuring incomplete, errors occurred!

Creating a VERSION_CURRENT file resolves the error. This was done in Homebrew/homebrew-core#153065.

---

If git history is available, the BUILD_VERSION is quietly ignored. The git history is used to compute the version:

git checkout a09129be6a3e1c875d4f923111e47b9a6ed4702c
if [ -f VERSION_CURRENT ]; then rm VERSION_CURRENT; fi
cmake -Bcmake-build -S. -DBUILD_VERSION=1.25.0-custom > /dev/null 2>&1
cat VERSION_CURRENT

Results in computing the version from the git history:

1.11.1-20231101+gita09129be6a

With changes in this PR:

git checkout document-removal-of-BUILD_VERSION
if [ -f VERSION_CURRENT ]; then rm VERSION_CURRENT; fi
cmake -Bcmake-build -S. -DBUILD_VERSION=1.25.0-custom > /dev/null 2>&1
cat VERSION_CURRENT

Results in applying the BUILD_VERSION from the CMake options:

1.25.0-custom

---

This PR proposes documenting this change in NEWS to inform use of the alternative.

Specifying BUILD_VERSION is documented: https://mongoc.org/libmongoc/1.25.0/learn/get/from-source.html#configuring-for-libbson

This PR proposes adding back support for the BUILD_VERSION option. This is intended to avoid quietly ignoring the applied BUILD_VERSION on existing builds specifying a custom BUILD_VERSION CMake option.

[rcsanchez97]

I am OK with documenting it this way if we want to discourage users from using it. However, it isn't exactly true that it has been removed. At least, in debian/rules we still specify it

        -DBUILD_VERSION=$(DEB_VERSION_UPSTREAM) \

I am not aware of this breaking.

[kevinAlbs]

However, it isn't exactly true that it has been removed. At least, in debian/rules we still specify it

        -DBUILD_VERSION=$(DEB_VERSION_UPSTREAM) \

I am not aware of this breaking.

I expect the BUILD_VERSION option is quietly ignored, and instead is computed from the git history.

This PR has been updated to apply the BUILD_VERSION CMake option. This is intended to avoid quietly changing builds specifying a custom BUILD_VERSION which also have git history available.

[rcsanchez97]

OK. I agree that this is a better approach. The removal caused a minor issue for Kyle and me in the packaging of 1.25.0. It was easy to work around it, and while it wasn't a silent change in the packaging scenario (since the packaging build runs without Git history available) I can see how the silent change in behavior could catch someone by surprise.