Version the library at 0.1.0

project() now carries VERSION 0.1.0, and is the single place a version number
is spelled. It flows into generated version macros, the shared library's
VERSION/SOVERSION, the Version: field in akstdlib.pc, and a new
akstdlibConfigVersion.cmake. Before this @PROJECT_VERSION@ expanded to
nothing, so akstdlib.pc shipped an empty Version: and libakstdlib.so carried
no soname at all.

0.x on purpose: TODO.md section 2.1 still records four confirmed defects whose
fixes change documented behaviour, so the API is not being promised yet. While
the major version is 0 the soname carries MAJOR.MINOR -- 0.1 and 0.2 are
different ABIs -- and becomes MAJOR alone at 1.0. The if() in CMakeLists.txt
and the #if in tests/test_version.c encode that rule and are tested against
each other.

include/akstdlib_version.h.in is configured into the build tree as
akstdlib_version.h and installed beside akstdlib.h. It defines
AKSL_VERSION_MAJOR/MINOR/PATCH/STRING/NUMBER and AKSL_VERSION_SONAME.
AKSL_VERSION_NUMBER is computed rather than written as a literal, because a
literal 000100 is octal in C and would make 0.1.0 compare as 64;
test_version.c asserts it against the runtime components, so a rewrite to a
literal fails.

Those macros record what a caller was compiled against. aksl_version(),
aksl_version_string() and aksl_version_soname() report what actually loaded,
and AKSL_VERSION_CHECK() compares the two, raising AKERR_VALUE naming both.
It is a macro so that it expands at the caller's site and captures the
caller's numbers; the function compares them against the ones baked into the
library. Compatibility is "same soname", so patch is ignored -- a caller built
against 0.1.0 keeps working against 0.1.7.

Normally the soname catches a mismatch at load time and the check never fires.
It earns its keep when the soname is bypassed: a 0.2.0 build dropped in under
the 0.1 filename loads happily, and only the check notices.

write_basic_package_version_file() uses SameMinorVersion to mirror the soname,
falling back to ExactVersion below CMake 3.11 where that mode does not exist.
The fallback is stricter than the soname rule -- it pins the patch level too --
but never laxer, and wrongly refusing a good pairing beats wrongly accepting a
bad one.

Coverage of src/stdlib.c rose to 99.1% of lines (217/219), 45.1% of branches
and 25/25 functions. That puts branch coverage back over the old 45 gate, but
the gate stays at 40: 0.1 points of headroom is not a ratchet.

ctest 14/14, ASan+UBSan 14/14, coverage 16/16 at 90/40. Also verified out of
tree: SONAME libakstdlib.so.0.1 recorded in consumers, pkg-config
--modversion reporting 0.1.0, find_package(akstdlib 0.1) accepted with 0.2 and
1.0 refused, a patch-bumped 0.1.1 loading and passing the check, a 0.2.0
dropped in under the 0.1 filename caught by it, and an embedded
add_subdirectory build keeping its own version rather than the parent's.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

CMakeLists.txt

@@ -1,5 +1,32 @@
 cmake_minimum_required(VERSION 3.10)
-project(akstdlib LANGUAGES C)
+# The single source of truth for the version. It flows from here into
+# include/akstdlib_version.h (generated from the .in template next to it), the
+# shared library's VERSION/SOVERSION, the Version: field in akstdlib.pc, and
+# akstdlibConfigVersion.cmake. Nothing else should spell a version number.
+#
+# 0.x on purpose: TODO.md section 2.1 still records four confirmed defects whose
+# fixes change documented behaviour (aksl_atoi's contract, aksl_realpath's
+# signature), so this library is not promising a stable API yet.
+project(akstdlib VERSION 0.1.0 LANGUAGES C)
+
+# The granularity at which the ABI is allowed to break, and therefore the
+# soname: libakstdlib.so.0.1. Pre-1.0 that is MAJOR.MINOR, because a 0.x library
+# makes no compatibility promise across a minor bump. At 1.0 this becomes
+# ${PROJECT_VERSION_MAJOR} alone -- change it here, and AKSL_VERSION_SONAME in
+# the header template follows automatically because it is configured from this.
+if(PROJECT_VERSION_MAJOR EQUAL 0)
+  set(AKSL_SOVERSION "${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}")
+else()
+  set(AKSL_SOVERSION "${PROJECT_VERSION_MAJOR}")
+endif()
+
+set(AKSL_GENERATED_INCLUDE_DIR "${CMAKE_CURRENT_BINARY_DIR}/generated/include")
+set(AKSL_VERSION_HEADER "${AKSL_GENERATED_INCLUDE_DIR}/akstdlib_version.h")
+configure_file(
+  "${CMAKE_CURRENT_SOURCE_DIR}/include/akstdlib_version.h.in"
+  "${AKSL_VERSION_HEADER}"
+  @ONLY
+)
 
 set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -g -ggdb -pg")
 set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -g -ggdb -pg")
@@ -135,12 +162,25 @@ add_library(akstdlib SHARED
 
 add_library(akstdlib::akstdlib ALIAS akstdlib)
 
-# Specify include directories for the library's headers (if applicable)
+# Specify include directories for the library's headers (if applicable).
+# The generated directory carries akstdlib_version.h, which akstdlib.h includes;
+# it is PUBLIC because consumers building against the build tree need it too. On
+# install both headers land side by side in ${CMAKE_INSTALL_INCLUDEDIR}, so the
+# install interface needs no second entry.
 target_include_directories(akstdlib PUBLIC
   $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+  $<BUILD_INTERFACE:${AKSL_GENERATED_INCLUDE_DIR}>
   $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}/>
 )
 
+# VERSION gives the real file (libakstdlib.so.0.1.0); SOVERSION gives the symlink
+# and the ELF soname recorded in every consumer (libakstdlib.so.0.1), so a
+# consumer built against 0.1 will not silently load an ABI-incompatible 0.2.
+set_target_properties(akstdlib PROPERTIES
+  VERSION   ${PROJECT_VERSION}
+  SOVERSION ${AKSL_SOVERSION}
+)
+
 target_link_libraries(akstdlib PUBLIC akerror::akerror)
 
 aksl_target_coverage(akstdlib)
@@ -155,6 +195,7 @@ install(TARGETS akstdlib
 )
 
 install(FILES "include/akstdlib.h" DESTINATION "include/")
+install(FILES "${AKSL_VERSION_HEADER}" DESTINATION "include/")
 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/akstdlib.pc DESTINATION "lib/pkgconfig/")
 
 
@@ -170,8 +211,31 @@ configure_package_config_file(
     INSTALL_DESTINATION ${akstdlib_install_cmakedir}
 )
 
+# Without this, find_package(akstdlib 0.1 REQUIRED) is refused for want of a
+# version file no matter what is installed -- which is exactly the gap that
+# stops cmake/akstdlib.cmake.in from requesting a version of akerror.
+#
+# SameMinorVersion mirrors the soname: pre-1.0, 0.1 and 0.2 are different ABIs.
+# It arrived in CMake 3.11 and this project declares 3.10, so fall back to
+# ExactVersion on older CMake. That is stricter than the soname rule -- it pins
+# the patch level too, so a 0.1.0 request refuses a compatible 0.1.1 -- but it is
+# never laxer, and wrongly refusing a good pairing beats wrongly accepting a bad
+# one. Drop the branch when the minimum moves past 3.11.
+if(CMAKE_VERSION VERSION_LESS 3.11)
+    set(AKSL_VERSION_COMPATIBILITY ExactVersion)
+else()
+    set(AKSL_VERSION_COMPATIBILITY SameMinorVersion)
+endif()
+
+write_basic_package_version_file(
+    "${CMAKE_CURRENT_BINARY_DIR}/akstdlibConfigVersion.cmake"
+    VERSION ${PROJECT_VERSION}
+    COMPATIBILITY ${AKSL_VERSION_COMPATIBILITY}
+)
+
 install(FILES
     "${CMAKE_CURRENT_BINARY_DIR}/akstdlibConfig.cmake"
+    "${CMAKE_CURRENT_BINARY_DIR}/akstdlibConfigVersion.cmake"
     DESTINATION ${akstdlib_install_cmakedir}
 )
 
@@ -200,6 +264,7 @@ set(AKSL_TESTS
     stream
     strhash
     tree
+    version
 )
 
 set(AKSL_WILL_FAIL_TESTS