Improve versioning (#362)

* Set version number in CMakeLists.txt

Version number gets sent to C code through preprocessor symbols
and to doxygen through environmental variables.

Also cleaned up printing of doxygen documentation to show only
major.minor at top of page but major.minor.patch in a note on
the main page.

Also did a bit more cleaning up of doxygen docs.

Users don't have access to version numbers now, because we are
basing them on CMake variables at our compile time, rather than
hard coding them in the header. What I think will make more sense
is to templatize the version.h file to actually paste those
numbers in there based on the values CMake is holding.

* Go back to hard coded version numbers in version.h

- Removed add_compile_definitions which needs a minimum of CMake 3.12
- Users have access to version numbers again, but we need to store
  them in two places

* Auto generate version.h with the correct version numbers

This does almost everything we need with version numbers in both
C and Doxygen code, except for one thing:

version.h is not yet being properly installed on make install

* Make newly generated version.h file get installed properly

Also cleaned up some cruft in CMakeLists.txt

* bugfix: public version.h cannot depend on private/config.h

Reversed the order of the dependency and kept user agent
string stuff entirely in private header file. Public
version string no longer contains git repo info, but
user agent string still does.

* clang formatting

* Move user agent string stuff to separate private header file

Also remove version unit test that wasn't really a unit test

* style check fix

Author: david-koenig

CMakeLists.txt

@@ -48,6 +48,11 @@ include(FindOpenSSL)
 
 set(PROJECT_NAME aws-encryption-sdk)
 
+# Version number of the SDK to be consumed by C code and Doxygen
+set(MAJOR 0)
+set(MINOR 2)
+set(PATCH 0)
+
 # Compiler feature tests and feature flags
 set(USE_ASM TRUE
     CACHE BOOL "Enable use of inline assembler, if supported by the compiler and platform")
@@ -72,14 +77,19 @@ CHECK_C_SOURCE_COMPILES("
     int main() { return __builtin_expect(0, 0); }
     " HAVE_BUILTIN_EXPECT)
 
+# Generate includable header files exposing build-time configuration
+set(GENERATED_INCLUDE "${CMAKE_CURRENT_BINARY_DIR}/generated/include")
+set(GENERATED_CONFIG_HEADER "${GENERATED_INCLUDE}/aws/cryptosdk/private/config.h")
+set(GENERATED_VERSION_HEADER "${GENERATED_INCLUDE}/aws/cryptosdk/version.h")
+
+configure_file("include/aws/cryptosdk/version.h.in"
+               ${GENERATED_VERSION_HEADER}
+               ESCAPE_QUOTES)
+
 file(GLOB AWS_CRYPTOSDK_HEADERS
 # Headers subject to API/ABI stability guarantees
      "include/aws/cryptosdk/*.h"
-)
-
-file(GLOB AWS_CRYPTOSDK_PRIV_HEADERS
-# Headers not installed with the library
-     "include/aws/cryptosdk/private/*.h"
+     ${GENERATED_VERSION_HEADER}
 )
 
 file(GLOB AWS_CRYPTOSDK_SRC
@@ -91,10 +101,6 @@ if (PERFORM_HEADER_CHECK)
     add_subdirectory(cmake/header-tester)
 endif()
 
-# Generate includable header files exposing build-time configuration
-set(GENERATED_INCLUDE "${CMAKE_CURRENT_BINARY_DIR}/generated/include")
-set(GENERATED_CONFIG_HEADER "${GENERATED_INCLUDE}/aws/cryptosdk/private/config.h")
-
 # Also expose git revision information in user-agent
 include(GitRevision)
 FindGitRevision(git_revision)
@@ -115,22 +121,13 @@ if(HAVE_LIBRT)
    set(PLATFORM_LIBS ${PLATFORM_LIBS} "pthread")
 endif()
 
-file(GLOB CORE_HEADERS
-    ${AWS_CRYPTOSDK_HEADERS}
-    ${GENERATED_CONFIG_HEADER}
-)
-
-file(GLOB CORE_SRC
-    ${AWS_CRYPTOSDK_SRC}
-)
-
 if(BUILD_SHARED_LIBS)
     set(LIBTYPE SHARED)
 else()
     set(LIBTYPE STATIC)
 endif()
 
-add_library(${PROJECT_NAME} ${LIBTYPE} ${CORE_HEADERS} ${CORE_SRC})
+add_library(${PROJECT_NAME} ${LIBTYPE} ${AWS_CRYPTOSDK_HEADERS} ${AWS_CRYPTOSDK_SRC})
 set_target_properties(${PROJECT_NAME} PROPERTIES LINKER_LANGUAGE C C_STANDARD 99)
 aws_cryptosdk_set_common_properties(${PROJECT_NAME})
 
@@ -147,7 +144,7 @@ target_link_libraries(${PROJECT_NAME} PUBLIC AWS::aws-c-common)
 
 # Some of our unit tests need to access private symbols. Build a static library for their use.
 # We'll use the shared lib for integration tests.
-add_library(aws-encryption-sdk-test EXCLUDE_FROM_ALL STATIC ${CORE_HEADERS} ${CORE_SRC})
+add_library(aws-encryption-sdk-test EXCLUDE_FROM_ALL STATIC ${AWS_CRYPTOSDK_HEADERS} ${AWS_CRYPTOSDK_SRC})
 set_target_properties(aws-encryption-sdk-test PROPERTIES LINKER_LANGUAGE C C_STANDARD 99)
 aws_cryptosdk_set_common_properties(aws-encryption-sdk-test)
 
@@ -168,7 +165,7 @@ include(CodeCoverageTargets)
 # Installation logic
 aws_install_target(
     TARGET ${CMAKE_PROJECT_NAME}
-    HEADERS ${CORE_HEADERS}
+    HEADERS ${AWS_CRYPTOSDK_HEADERS}
     HEADER_ROOTS ${GENERATED_INCLUDE} ${CMAKE_CURRENT_SOURCE_DIR}/include
 )
 
@@ -226,7 +223,7 @@ if (BUILD_DOC)
         set(DOXYGEN_CONFIG_FILE_GENERATED ${CMAKE_CURRENT_BINARY_DIR}/doxygen/doxygen.config)
         configure_file(${DOXYGEN_CONFIG_FILE_IN} ${DOXYGEN_CONFIG_FILE_GENERATED} @ONLY)
         add_custom_target(doc_doxygen ALL
-                COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_CONFIG_FILE_GENERATED}
+                COMMAND ${CMAKE_COMMAND} -E env MAJOR=${MAJOR} MINOR=${MINOR} PATCH=${PATCH} ${DOXYGEN_EXECUTABLE} ${DOXYGEN_CONFIG_FILE_GENERATED}
                 WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
                 COMMENT "Generating Doxygen documentation"
                 VERBATIM)

aws-encryption-sdk-cpp/source/kms_keyring.cpp

@@ -13,14 +13,14 @@
  * limitations under the License.
  */
 #include <aws/cryptosdk/private/kms_keyring.h>
-#include <aws/cryptosdk/version.h>
 
 #include <aws/core/utils/Outcome.h>
 #include <aws/core/utils/logging/LogMacros.h>
 #include <aws/core/utils/memory/MemorySystemInterface.h>
 #include <aws/core/utils/memory/stl/AWSAllocator.h>
 #include <aws/cryptosdk/list_utils.h>
 #include <aws/cryptosdk/private/cpputils.h>
+#include <aws/cryptosdk/private/user_agent.h>
 #include <aws/kms/model/DecryptRequest.h>
 #include <aws/kms/model/DecryptResult.h>
 #include <aws/kms/model/EncryptRequest.h>
@@ -328,7 +328,7 @@ Aws::Cryptosdk::Private::KmsKeyringImpl::KmsKeyringImpl(
 static std::shared_ptr<KMS::KMSClient> CreateDefaultKmsClient(const Aws::String &region) {
     Aws::Client::ClientConfiguration client_configuration;
     client_configuration.region = region;
-    client_configuration.userAgent += " " AWS_CRYPTOSDK_VERSION_UA "/kms-keyring-cpp";
+    client_configuration.userAgent += " " AWS_CRYPTOSDK_PRIVATE_VERSION_UA "/kms-keyring-cpp";
 #ifdef VALGRIND_TESTS
     // When running under valgrind, the default timeouts are too slow
     client_configuration.requestTimeoutMs = 10000;

doxygen/doxygen.config.in

@@ -5,8 +5,8 @@
 #---------------------------------------------------------------------------
 DOXYFILE_ENCODING      = UTF-8
 PROJECT_NAME           = "AWS Encryption SDK for C"
-PROJECT_NUMBER         = 0.2.x
-PROJECT_BRIEF          = "AWS Encryption SDK for C"
+PROJECT_NUMBER         = v$(MAJOR).$(MINOR)
+PROJECT_BRIEF          =
 PROJECT_LOGO           = 
 OUTPUT_DIRECTORY       = doxygen
 CREATE_SUBDIRS         = NO
@@ -112,7 +112,8 @@ WARN_LOGFILE           =
 # Configuration options related to the input files
 #---------------------------------------------------------------------------
 INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/include \
-                         @CMAKE_CURRENT_SOURCE_DIR@/aws-encryption-sdk-cpp/include
+                         @CMAKE_CURRENT_SOURCE_DIR@/aws-encryption-sdk-cpp/include \
+                         @GENERATED_INCLUDE@
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          = *.h \
                          *.md

include/aws/cryptosdk/private/config.h.in

@@ -12,7 +12,6 @@
  * implied. See the License for the specific language governing permissions and
  * limitations under the License.
  */ 
-
 #ifndef AWS_CRYPTOSDK_PRIVATE_CONFIG_H
 #define AWS_CRYPTOSDK_PRIVATE_CONFIG_H 1
 
@@ -24,6 +23,10 @@
 // not on a tag, we'll add the git revision to the version strings
 #cmakedefine AWS_CRYPTOSDK_PRIVATE_GITVERSION "@AWS_CRYPTOSDK_PRIVATE_GITVERSION@"
 
+#ifndef AWS_CRYPTOSDK_PRIVATE_GITVERSION
+#    define AWS_CRYPTOSDK_PRIVATE_GITVERSION ""
+#endif
+
 #ifdef __CPROVER__
 
 // Disable all compiler, and go to bare C

include/aws/cryptosdk/private/user_agent.h

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"). You may not use
+ * this file except in compliance with the License. A copy of the License is
+ * located at
+ *
+ *     http://aws.amazon.com/apache2.0/
+ *
+ * or in the "license" file accompanying this file. This file is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ * implied. See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+#ifndef AWS_CRYPTOSDK_PRIVATE_USER_AGENT_H
+#define AWS_CRYPTOSDK_PRIVATE_USER_AGENT_H
+
+#include <aws/cryptosdk/private/config.h>
+#include <aws/cryptosdk/version.h>
+
+// A string constant containing version information in a human-readable form, with git repo info.
+#define AWS_CRYPTOSDK_PRIVATE_VERSION_STR                                                                     \
+    AWS_CRYPTOSDK_PRIVATE_EXPANDQUOTE(AWS_CRYPTOSDK_VERSION_MAJOR)                                            \
+    "." AWS_CRYPTOSDK_PRIVATE_EXPANDQUOTE(AWS_CRYPTOSDK_VERSION_MINOR) "." AWS_CRYPTOSDK_PRIVATE_EXPANDQUOTE( \
+        AWS_CRYPTOSDK_VERSION_PATCH) AWS_CRYPTOSDK_PRIVATE_GITVERSION
+
+// A string constant containing version information in a form suitable for a user-agent string.
+#define AWS_CRYPTOSDK_PRIVATE_VERSION_UA "aws-encryption-sdk-c/" AWS_CRYPTOSDK_PRIVATE_VERSION_STR
+
+#endif  // AWS_CRYPTOSDK_PRIVATE_USER_AGENT_H

include/aws/cryptosdk/version.h renamed to include/aws/cryptosdk/version.h.in

@@ -16,8 +16,6 @@
 #ifndef AWS_CRYPTOSDK_VERSION_H
 #define AWS_CRYPTOSDK_VERSION_H
 
-#include <aws/cryptosdk/private/config.h>
-
 /*! \mainpage The AWS Encryption SDK for C
  *
  * The AWS Encryption SDK for C is a client-side encryption library designed to make it easy for
@@ -26,13 +24,10 @@
  * the AWS Encryption SDKs in all languages, see the
  * <a href="https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/introduction.html">Developer Guide</a>.
  *
- * <b>This library is currently in public preview.</b>
- * Feel free to check out the code and give it a spin, but be aware that the APIs are still in flux.
- * We'd love to hear your feedback on the APIs before they're fully nailed down.
- *
  * Source code and installation instructions are available in
  * <a href="https://github.com/awslabs/aws-encryption-sdk-c">the GitHub repository</a>.
  *
+ * This API documentation was generated from the v@MAJOR@.@MINOR@.@PATCH@ source code.
  *
  * <b>License</b>
  *
@@ -44,37 +39,38 @@
  *
  * This section defines version macros that can be used to query the current version of the Encryption SDK.
  * For prerelease builds, the version constants will generally contain the anticipated version of the upcoming
- * release; if a git working copy is detected at build time, we will include that revision in the version
- * strings, but not in the numeric version constants.
+ * release.
  *
  * @{
  */
 
-#ifndef AWS_CRYPTOSDK_PRIVATE_GITVERSION
-#    define AWS_CRYPTOSDK_PRIVATE_GITVERSION ""
-#endif
-
-#define AWS_CRYPTOSDK_VERSION_MAJOR 0
-#define AWS_CRYPTOSDK_VERSION_MINOR 2
-#define AWS_CRYPTOSDK_VERSION_PATCH 0
-
 #ifndef AWS_CRYPTOSDK_DOXYGEN  // undocumented private helpers
 #    define AWS_CRYPTOSDK_PRIVATE_QUOTEARG(a) #    a
 #    define AWS_CRYPTOSDK_PRIVATE_EXPANDQUOTE(a) AWS_CRYPTOSDK_PRIVATE_QUOTEARG(a)
 #endif
 
+/**
+ * The major version number. See VERSIONING.rst for details on versioning policy.
+ */
+#define AWS_CRYPTOSDK_VERSION_MAJOR @MAJOR@
+
+/**
+ * The minor version number. See VERSIONING.rst for details on versioning policy.
+ */
+#define AWS_CRYPTOSDK_VERSION_MINOR @MINOR@
+
+/**
+ * The patch version number. See VERSIONING.rst for details on versioning policy.
+ */
+#define AWS_CRYPTOSDK_VERSION_PATCH @PATCH@
+
 /**
  * A string constant containing version information in a human-readable form.
  */
 #define AWS_CRYPTOSDK_VERSION_STR                                                                             \
     AWS_CRYPTOSDK_PRIVATE_EXPANDQUOTE(AWS_CRYPTOSDK_VERSION_MAJOR)                                            \
     "." AWS_CRYPTOSDK_PRIVATE_EXPANDQUOTE(AWS_CRYPTOSDK_VERSION_MINOR) "." AWS_CRYPTOSDK_PRIVATE_EXPANDQUOTE( \
-        AWS_CRYPTOSDK_VERSION_PATCH) AWS_CRYPTOSDK_PRIVATE_GITVERSION
-
-/**
- * A string constant containing version information in a form suitable for a user-agent string.
- */
-#define AWS_CRYPTOSDK_VERSION_UA "aws-encryption-sdk-c/" AWS_CRYPTOSDK_VERSION_STR
+        AWS_CRYPTOSDK_VERSION_PATCH)
 
 /** @} */  // doxygen group versioning
 

tests/unit/testing.h

@@ -38,6 +38,7 @@ extern struct test_case raw_rsa_keyring_encrypt_test_cases[];
 extern struct test_case local_cache_test_cases[];
 extern struct test_case caching_cmm_test_cases[];
 extern struct test_case keyring_trace_test_cases[];
+extern struct test_case version_test_cases[];
 
 #define TEST_ASSERT(cond)                                                                        \
     do {                                                                                         \