Add initial support for API versioning (see #3836)

- Generated files are now created when running cef_create_projects or
  the new version_manager.py tool. These files are still created in the
  cef/ source tree (same location as before) but Git ignores them due to
  the generated .gitignore file.
- API hashes are committed to Git as a new cef_api_versions.json file.
  This file is used for both code generation and CEF version calculation
  (replacing the previous usage of cef_api_hash.h for this purpose).
  It will be updated by the CEF admin before merging breaking API
  changes upstream.
- As an added benefit to the above, contributor PRs will no longer
  contain generated code that is susceptible to frequent merge conflicts.
- From a code generation perspective, the main difference is that we now
  use versioned structs (e.g. cef_browser_0_t instead of cef_browser_t)
  on the libcef (dll/framework) side. Most of the make_*.py tool changes
  are related to supporting this.
- From the client perspective, you can now define CEF_API_VERSION in the
  project configuration (or get CEF_EXPERIMENTAL by default). This
  define will change the API exposed in CEF’s include/ and include/capi
  header files. All client-side targets including libcef_dll_wrapper
  will need be recompiled when changing this define.
- Examples of the new API-related define usage are provided in
  cef_api_version_test.h, api_version_test_impl.cc and
  api_version_unittest.cc.

To test:
- Run `ceftests --gtest_filter=ApiVersionTest.*`
- Add `cef_api_version=13300` to GN_DEFINES. Re-run configure, build and
  ceftests steps.
- Repeat with 13301, 13302, 13303 (all supported test versions).

include/cef_api_hash.h

@@ -27,45 +27,124 @@
 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 //
-// ---------------------------------------------------------------------------
-//
-// This file was generated by the make_api_hash_header.py tool.
+// Versions are managed using the version_manager.py tool. For usage details
+// see https://bitbucket.org/chromiumembedded/cef/wiki/ApiVersioning.md
 //
 
-#ifndef CEF_INCLUDE_API_HASH_H_
-#define CEF_INCLUDE_API_HASH_H_
+#ifndef CEF_INCLUDE_CEF_API_HASH_H_
+#define CEF_INCLUDE_CEF_API_HASH_H_
 
 #include "include/internal/cef_export.h"
 
-// The API hash is created by analyzing CEF header files for C API type
-// definitions. The hash value will change when header files are modified in a
-// way that may cause binary incompatibility with other builds. The universal
-// hash value will change if any platform is affected whereas the platform hash
-// values will change only if that particular platform is affected.
-#define CEF_API_HASH_UNIVERSAL "e52a54bfb4cfc13366fe52766756180fc7d3d1b2"
-#if defined(OS_WIN)
-#define CEF_API_HASH_PLATFORM "ce7bfedc905e90407eb975eebf2f419a347b27cd"
-#elif defined(OS_MAC)
-#define CEF_API_HASH_PLATFORM "8bb21c09270905fe64b8c31f744e0cbf7bc39ff5"
-#elif defined(OS_LINUX)
-#define CEF_API_HASH_PLATFORM "a8198f66f731c8ac91bba1e45847807bffca7b01"
+#if !defined(GENERATING_CEF_API_HASH)
+#include "include/cef_api_versions.h"
 #endif
 
+// Experimental CEF API. Experimental API is unversioned, meaning that it is
+// excluded (compiled out) when clients explicitly set the CEF_API_VERSION
+// value in their project configuration. Experimental API is not back/forward
+// compatible with different CEF versions.
+#define CEF_API_VERSION_EXPERIMENTAL 999999
+
+// Placeholder for the next CEF version currently under development. This is a
+// temporary value that must be replaced with the actual next version number
+// (output of running `version_manager.py -n`) prior to upstream merge. As an
+// added reminder, use of this value will cause version_manager.py to fail when
+// computing hashes for explicit API versions. When adding new API consider
+// using CEF_API_VERSION_EXPERIMENTAL instead.
+#if !defined(CEF_API_VERSION_NEXT)
+#define CEF_API_VERSION_NEXT 999998
+#endif
+
+// Shorter versions of the above for convenience use in comparison macros.
+#define CEF_NEXT CEF_API_VERSION_NEXT
+#define CEF_EXPERIMENTAL CEF_API_VERSION_EXPERIMENTAL
+
+// API version that will be compiled client-side. The experimental (unversioned)
+// API is selected by default. Clients can set the CEF_API_VERSION value in
+// their project configuration to configure an explicit API version. Unlike
+// the experimental API, explicit API versions are back/forward compatible with
+// a specific range of CEF versions.
+#if !defined(CEF_API_VERSION)
+#define CEF_API_VERSION CEF_API_VERSION_EXPERIMENTAL
+#endif
+
+#if !defined(GENERATING_CEF_API_HASH)
+#if CEF_API_VERSION < CEF_API_VERSION_MIN ||                                  \
+    (CEF_API_VERSION > CEF_API_VERSION_LAST && CEF_API_VERSION != CEF_NEXT && \
+     CEF_API_VERSION != CEF_EXPERIMENTAL)
+#error Building with unsupported CEF_API_VERSION value
+#endif
+#endif
+
+#define _CEF_AH_PASTE(a, b, c) a##_##b##_##c
+#define _CEF_AH_EVAL(a, b, c) _CEF_AH_PASTE(a, b, c)
+#define _CEF_AH_DECLARE(version, suffix) \
+  _CEF_AH_EVAL(CEF_API_HASH, version, suffix)
+
+// API hashes for the selected CEF_API_VERSION. API hashes are created for
+// each version by analyzing CEF header files for C API type definitions. The
+// hash value will change when header files are modified in a way that may
+// cause binary incompatibility with other builds. The universal hash value
+// will change if any platform is affected whereas the platform hash values
+// will change only if that particular platform is affected.
+#define CEF_API_HASH_UNIVERSAL _CEF_AH_DECLARE(CEF_API_VERSION, UNIVERSAL)
+#define CEF_API_HASH_PLATFORM _CEF_AH_DECLARE(CEF_API_VERSION, PLATFORM)
+
+#if defined(BUILDING_CEF_SHARED)
+
+#define _CEF_AV_LT(v) 1
+#define _CEF_AV_GE(v) 1
+
+#else  // !defined(BUILDING_CEF_SHARED)
+
+#define _CEF_AV_CMP(v, op) (CEF_API_VERSION op v)
+
+#define _CEF_AV_LT(v) _CEF_AV_CMP(v, <)
+#define _CEF_AV_GE(v) _CEF_AV_CMP(v, >=)
+
+#endif  // !defined(BUILDING_CEF_SHARED)
+
+///
+/// API was added in the specified version.
+///
+#define CEF_API_ADDED(v) _CEF_AV_GE(v)
+
+///
+/// API was removed in the specified version.
+///
+#define CEF_API_REMOVED(v) _CEF_AV_LT(v)
+
+///
+/// API exists only in the specified version range.
+///
+#define CEF_API_RANGE(va, vr) (_CEF_AV_GE(va) && _CEF_AV_LT(vr))
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 ///
-// Returns CEF API hashes for the libcef library. The returned string is owned
-// by the library and should not be freed. The |entry| parameter describes which
-// hash value will be returned:
-// 0 - CEF_API_HASH_PLATFORM
-// 1 - CEF_API_HASH_UNIVERSAL
-// 2 - CEF_COMMIT_HASH (from cef_version.h)
+/// Configures the CEF API version and returns API hashes for the libcef
+/// library. The returned string is owned by the library and should not be
+/// freed. The |version| parameter should be CEF_API_VERSION and any changes to
+/// this value will be ignored after the first call to this method. The |entry|
+/// parameter describes which hash value will be returned:
 ///
-CEF_EXPORT const char* cef_api_hash(int entry);
+/// 0 - CEF_API_HASH_PLATFORM
+/// 1 - CEF_API_HASH_UNIVERSAL
+/// 2 - CEF_COMMIT_HASH (from cef_version.h)
+///
+CEF_EXPORT const char* cef_api_hash(int version, int entry);
+
+///
+/// Returns the CEF API version that was configured by the first call to
+/// cef_api_hash().
+///
+CEF_EXPORT int cef_api_version();
 
 #ifdef __cplusplus
 }
 #endif
-#endif  // CEF_INCLUDE_API_HASH_H_
+
+#endif  // CEF_INCLUDE_CEF_API_HASH_H_