Cmake package configuration script tests ------ How to run tests ================ Tests are located in the `testing/find_package` folder of the source tree. First they need to be configured using `cmake`. If testing OS-wide connector installation (from RPM, DEB or MSI package) it is enough to run `cmake` in a build location pointing at the folder with tests: > cmake ${SRC_DIR}/testing/find_package If connector was installed from TGZ or ZIP package to a custom location then this location needs to be given as `WITH_CONCPP` parameter (otherwise configuration fails with error): > cmake -D WITH_CONCPP=${INSTALL_DIR} ... This should configure various tests which can be run using `ctest` command (`ctest -N` will list configured tests). Note: No build step is required before running tests. Note: When invoking `ctest` on Windows (using the default generator) one needs to invoke it as `ctest -C Release` -- this is a technical limitation of cmake/ ctest. Some packages distribute only shared connector libraries (generic Linux for example). When testing such package the static library tests should be disabled using `BUILD_STATIC` option: > cmake -D BUILD_STATIC=0 ... If `WITH_SSL` configuration option is passed that points to location where OpenSSL is installed additional test scenarios are configured which check use of the connector with the external OpenSSL installation (*): > cmake -D WITH_SSL=${OPENSSL_DIR} ... Note (*): Without this option either bundled or OS-wide OpenSSL is used in tests depending on the type of the connector installation being tested. Package version test scenarios must know which version of connector package is being tested. They get this information from `INFO_SRC` file which is included in the package. If the file is not found for some reason the version test scenarios are not configured (with warning). They can be still generated by providing package version as `VERSION` parameter: > cmake -D VERSION=8.2.0 ... By default both XDevAPI and JDBC variants of the connector are tested. The JDBC tests can be excluded by disabling `WITH_JDBC` option when configuring tests: > cmake -D WITH_JDBC=OFF ... On Windows debug packages contain debug builds of connector libraries. To test them enable `WITH_DEBUG` option: > cmake -D WITH_DEBUG=ON ... This should be done only if debug packages are installed. Test scenarios ============== Main test scenarios are checked by tests with names: ``` ${ACTION}_A${A}_B${B}_C${C} ``` where ${ACTION} is one of: - config -- configure project that builds test applications (*) - build -- build test application - check -- check resulting executable for unresolved dependencies Note (*): The project lives at testapp/ folder in the source directory and defines simple test applications that uses different variants of the connector (XDevAPI, XAPI, JDBC). In the project connector package is loaded using find_package() command. Parameters ${A}, ${B} and ${C} describe the exact scenario being checked as follows: - A -- type of connector library used: "dynamic" or "static" - B -- build configuration: "Release" or "Debug" - C -- how OpenSSL dependency is resolved: "default" or "custom" In case of C="custom" scenarios the OpenSSL installed at location given by `WITH_SSL` parameter is used. Otherwise the default behavior of using either bundled or system-wide OpenSSL installation is tested. Additional version tests verify correct behavior of the script that reports available package version. They have names ``` version_A${A}_B${B} ``` where ${A} and ${B} determine test scenario as follows: - A -- what version of the package is requested in find_package() invocation; one of: "exect", "older", "newer", "different" - B -- whether exact version is requested: "yes", "no". The "older" and "newer" versions are versions that difer by mnior number. The "different" version is a version with different major version number. These tests also check that expected variables are set after successful loading of the package. The `debug_require` test checks situation when the "debug" component is requested when loading package, as in: ``` find_package(mysql-concpp REQUIRE debug) ``` This is expected to fail unless testing on Windows with debug package installed and WITH_DEBUG option enabled during test configuration. Copyright notice ---------------- Copyright (c) 2023, Oracle and/or its affiliates. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, version 2.0, as published by the Free Software Foundation. This program is also distributed with certain software (including but not limited to OpenSSL) that is licensed under separate terms, as designated in a particular file or component or in included license documentation. The authors of MySQL hereby grant you an additional permission to link the program and your derivative works with the separately licensed software that they have included with MySQL. Without limiting anything contained in the foregoing, this file, which is part of MySQL Connector/C++, is also subject to the Universal FOSS Exception, version 1.0, a copy of which can be found at http://oss.oracle.com/licenses/universal-foss-exception. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License, version 2.0, for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA