Generalized cmake sqlite & key api to allow easier use of SQLite Multiple Ciphers

[jagerman]

I have recently been working on a project that is looking to use SQLite Multiple Ciphers rather than sqlite (or sqlcipher), and stumbled into some CMake inflexibility in SQLiteCpp that makes this difficult to achieve:

1. SQLiteCpp's cmake only supports "build internal sqlite" or "use find_package". This has been a bit of a nuissance for me before, requiring this workaround before add_directory(SQLiteCpp):

   ... custom code to set up a build of sqlite and make an SQLite3::SQLite target ...
   
   # Hack around SQLiteCpp's attempts to locate sqlite3 because we *don't* want to link against the
   # system one, but don't download and build the embedded one until build time.  Thankfully it
   # actually links against the SQLite::SQLite3 cmake target if it already exists, so all we have to do
   # is set that up and circumvent some of the non-target bits of its FindSQLite3.cmake.
   set(SQLite3_FOUND TRUE CACHE BOOL "" FORCE)
   file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/ignored")
   file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/ignored/sqlite3.h" "#define SQLITE_VERSION \"${SQLite3_VERSION}\"")
   set(SQLite3_INCLUDE_DIR "${CMAKE_CURRENT_BINARY_DIR}/ignored" CACHE STRING "" FORCE)
   set(SQLite3_LIBRARY "ignored" CACHE STRING "" FORCE)
   set(SQLITECPP_INTERNAL_SQLITE OFF CACHE BOOL "don't build SQLiteCpp's internal sqlite3" FORCE)

   Basically: setting a bunch of cache variables to make the find_package(SQLite) inside SQLiteCpp short-circuit itself and return immediately, so that the target_link_libraries(SQLiteCpp PUBLIC SQLite3::SQLite) links to what I already set up.

   This was a bit gross, but it worked, with plain SQLite3.

2. The SQLITE_HAS_CODEC option forces a pkg-config search for sqlcipher. I am not using sqlcipher, and so this is obviously not what I want. I could go make a fake package config file to short circuit that search, but that feels like yet another layer of hacks.

   An alternative hack to make this work was to set cmake's SQLITE_HAS_CODEC=OFF but then, after the add_directory, modifying the SQLiteCpp target to add -DSQLITE_HAS_CODEC to bypass the sqlcipher search but still actually enable the key API. I.e. adding these to the above hacks:

   set(SQLITE_HAS_CODEC OFF CACHE BOOL "" FORCE)
   add_subdirectory(SQLiteCpp)
   target_compile_definitions(SQLiteCpp PRIVATE SQLITE_HAS_CODEC)

   This works, but again feels quite dirty.

This PR

Hence this PR: this adds an "escape hatch" to the cmake code so that I can tell SQLiteCpp to let me worry about SQLite3 via a SQLite3::SQLite pre-existing target, and then lets the SQLITE_USE_CIPHER cmake option be usable for this case.

With this:

• Existing builds shouldn't be affected as all the defaults remain the same, including support for finding sqlcipher when using the (default) non-internal-find-sqlite path.
• More complex builds (such as my case) can drop a bunch of hacks to circumvent cmake implementation and internal compile definitions, and instead just becomes:

  ... go build sqlite-multiple-ciphers ..
  ... add a SQLite3::SQLite target that sets up sqlite-mc linkage and includes ...
  
  set(SQLITE_HAS_CODEC ON CACHE BOOL "" FORCE)
  set(SQLITECPP_INTERNAL_SQLITE OFF CACHE BOOL "" FORCE)
  set(SQLITECPP_FIND_SQLITE OFF CACHE BOOL "" FORCE)
  add_subdirectory(SQLiteCpp)

The PR also makes some closely related changes to this part of the cmake code:

• fatal error when SQLITE_HAS_CODEC and SQLITECPP_INTERNAL_SQLITE are both enabled (because the internal build will certainly fail as it doesn't provide the key API).
• update comments to remove unused sqlite3_key_v2 function and add sqlite3_rekey function
• improve option descriptions around these options to reflect what happens
• update cmake options descriptions
• make the SQLITE_HAS_CODEC definition PRIVATE instead of PUBLIC. This only affects the internal Database.cpp code and does not need to be carried by things linking to SQLiteCpp.

[jagerman]

(I did see PR #392, but the approach here seems considerably simpler by just letting the caller worry about it.)