GoogleCloudPlatform · coryan · Feb 1, 2021 · Feb 1, 2021 · Feb 1, 2021 · Feb 1, 2021
@@ -2,6 +2,9 @@
 
 ## v0.3.0 - TBD
 
+* Renamed package and targets to use `functions-framework-cpp` as
+  the project's prefix.
+
 ## v0.2.0 - 2021-01
 
 * Moved `Run()` to the public API.

@@ -1,10 +1,168 @@
-# :construction: Functions Framework for C++
+# Functions Framework for C++
+
+[abseil-gh]: https://github.com/abseil/abseil-cpp
+[boost-org]: https://boost.org/
+[nlohmann-json-gh]: https://github.com/nlohmann/json
+[google-cloud-cpp-gh]: https://github.com/googleapis/google-cloud-cpp
+[fmt-gh]: https://github.com/fmtlib/fmt
+[github-releases]: https://github.com/GoogleCloudPlatform/functions-framework-cpp/releases
+[github-issue]: https://github.com/GoogleCloudPlatform/functions-framework-cpp/issues/new
 
 An open source FaaS (Functions as a Service) framework for writing portable C++
 functions -- brought to you by Google.
 
-This is work in progress. Code will appear here "soon".
+## Versions and Status
+
+This library is considered *experimental* its API and other interfaces
+are subject to change without notice. This library does **not** follow the
+[Semantic Versioning](https://semver.org) conventions.
+
+## Requirements
+
+This is a C++17-based framework. It requires a compiler supporting C++17, we
+routinely test with GCC (>= 8.), and with Clang (>= 10), let us know if you
+have problems with other compilers. The framework also depends on a number
+of other libraries, note that these libraries may have their own dependencies:
+
+| Library | Minimum version | Description |
+| ------- | --------------: | ----------- |
+| [Abseil][abseil-gh] | 20200923 | C++ components to augment the standard library |
+| [Boost][boost-org] | 1.73 | Peer-reviewed portable C++ libraries |
+| [nlohmann/json][nlohmann-json-gh] | 3.9.1 | JSON for Modern C++ |
+
+The examples use additional libraries, note that these libraries may have their
+own dependencies:
+
+| Library | Minimum version | Description |
+| ------- | --------------: | ----------- |
+| [google-cloud-cpp][google-cloud-cpp-gh] | 1.23.0 | Google Cloud C++ Client Libraries |
+| [{fmt}][fmt-gh] | 7.1.3 | A formatting library |
+
+## Public API and API Breaking Changes
+
+In general, we avoid making backwards incompatible changes to our C++ APIs (see
+below for the definition of "API"). Sometimes such changes yield benefits to
+our customers, in the form of better performance, easier-to-understand APIs,
+and/or more consistent APIs across services. When these benefits warrant it, we
+will announce these changes prominently in our `CHANGELOG.md` file and in the
+affected release's notes. Nevertheless, though we take commercially reasonable
+efforts to prevent this, it is possible that backwards incompatible changes go
+undetected and, therefore, undocumented. We apologize if this is the case and
+welcome feedback or bug reports to rectify the problem.
+
+By "API" we mean the C++ API exposed by public header files in this repo. We
+are not talking about the gRPC or REST APIs exposed by Google Cloud servers. We
+are also talking only about A**P**I stability -- the ABI is subject to change
+without notice. You should not assume that binary artifacts (e.g. static
+libraries, shared objects, dynamically loaded libraries, object files) created
+with one version of the library are usable with newer/older versions of the
+library. The ABI may, and does, change on "minor revisions", and even patch
+releases.
+
+We request that our customers adhere to the following guidelines to avoid
+accidentally depending on parts of the library we do not consider to be part of
+the public API and therefore may change (including removal) without notice:
+
+* You should only include headers matching the `google/cloud/framework/*.h`,
+  or `google/cloud/framework/mock/*.h` patterns.
+* You should **NOT** directly include headers in any subdirectories, such as
+  `google/cloud/framework/internal`.
+* The files *included from* our public headers are **not part of our public
+  API**. Depending on indirect includes may break your build in the future, as
+  we may change a header "foo.h" to stop including "bar.h" if "foo.h" no longer
+  needs the symbols in "bar.h". To avoid having your code broken, you should
+  directly include the public headers that define all the symbols you use (this
+  is sometimes known as
+  [include-what-you-use](https://include-what-you-use.org/)).
+* Any file or symbol that lives within a directory or namespace containing
+  "internal", "impl", "test", "detail", "benchmark", "sample", or "example", is
+  explicitly **not part of our public API**.
+* Any file or symbol with "Impl" or "impl" in its name is **not part of our
+  public API**.
+
+Previous versions of the library will remain available on the
+[GitHub Releases page][github-releases].
+
+## Beyond the C++ API
+
+Applications developers interact with a C++ library through more than just
+the C++ symbols and headers. They also need to reference the name of the
+library in their build scripts. Depending of the build system they use
+this may be a CMake target, a Bazel rule, a pkg-config module, or just the
+name of some object in the file system.
+
+As with the C++ API, we try to avoid breaking changes to these interface
+points. Sometimes such changes yield benefits to our customers, in the form of
+easier-to-understand what names go with with services, or more consistency
+across services. When these benefits warrant it, we will announce these changes
+prominently in our `CHANGELOG.md` file and in the affected release's notes.
+Nevertheless, though we take commercially reasonable efforts to prevent this,
+it is possible that backwards incompatible changes go undetected and,
+therefore, undocumented. We apologize if this is the case and welcome feedback
+or bug reports to rectify the problem.
+
+### Experimental Libraries
+
+From time to time we add libraries to `functions-framework-cpp` to validate
+new  designs, expose experimental (or otherwise not generally available)
+features, or simply because a library is not yet complete. Such libraries
+will have `experimental` in their CMake target and Bazel rule. The README
+file for these libraries will also document that they are experimental.
+Such libraries are subject to change, including removal, without notice.
+This includes, but it is not limited to, all their symbols, pre-processor
+macros, files, targets, rules, and installed artifacts.
+
+### CMake targets and packages
+
+Only CMake packages starting with the `functions_framework_cpp_` prefix are
+intended for customer use. Only targets starting with
+`functions-framework-cpp::` are intended for customer use. Experimental targets
+have `experimental` in their name (e.g.
+`functions-framework-cpp::experimental-foo`), as previously stated,
+experimental targets are subject to change or removal without notice.
+
+### pkg-config modules
+
+Only modules starting with `functions_framework_cpp_` are intended for customer
+use.
+
+### Unsupported use cases
+
+We try to provide stable names for the previously described mechanisms:
+
+* CMake targets loaded via `find_package()`,
+* pkg-config modules
+
+It is certainly possible to use the the library through other mechanisms,
+and while these may work, we may accidentally break these from time to time.
+Examples of such, and the recommended alternatives, include:
+
+* CMake's `FetchContent` and/or git submodules: in these approaches the
+  `functions-framework-cpp` library becomes a sub-directory of a larger CMake
+  build. We do not test `functions-framework-cpp` in this configuration, and we
+  find it brittle as **all** CMake targets become visible to the larger
+  project. This is both prone to conflicts, and makes it impossible to enforce
+  that some targets are only for testing or implementation. Applications may
+  want to consider source package managers, such as `vcpkg`, or CMake super
+  builds via `ExternalProject_Add()` as alternatives.
+
+* Using library names directly: applications should not use the
+  library names, e.g., by using `-lfunctions_framework_cpp` in build scripts. We
+  may need to split or merge libraries over time, making such names unstable.
+  Applications should use CMake targets, e.g.,
+  `functions-framework-cpp::framework`, or pkg-config modules, e.g.,
+  `$(pkg-config functions_framework_cpp --libs)`.
+
+### Documentation and Comments
+
+The documentation (and its links) is intended for human consumption and not
+third party websites, or automation (such as scripts scrapping the contents).
+The contents and links of our documentation may change without notice.
+
+### Other Interface Points
 
+We think this covers all interface points, if we missed something please
+file a [GitHub issue][github-issue].
 
 ## Contributing changes
 

@@ -17,14 +17,14 @@ project(functions-framework-application CXX)
 set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
-find_package(googleapis_functions_framework)
+find_package(functions_framework_cpp REQUIRED)
 
 function (functions_framework_cpp_define_target_with_glob directory)
     file(GLOB_RECURSE application_sources "${directory}/*.cc"
          "${directory}/*.cpp" "${directory}/*.cxx")
     add_library(functions_framework_cpp_function ${application_sources})
     target_link_libraries(functions_framework_cpp_function
-                          PUBLIC googleapis-c++::functions_framework)
+                          PUBLIC functions-framework-cpp::framework)
 endfunction ()
 
 if (EXISTS "${CNB_APP_DIR}/CMakeLists.txt")

@@ -52,22 +52,22 @@ add_library(
     site/tips_scopes/tips_scopes.cc)
 target_link_libraries(
     functions_framework_examples storage_client fmt::fmt
-    googleapis-c++::functions_framework googleapis-c++::pubsub_client)
+    functions-framework-cpp::framework googleapis-c++::pubsub_client)
 
 if (BUILD_TESTING)
     find_package(GTest CONFIG REQUIRED)
-    set(googleapis_functions_framework_examples_unit_tests
+    set(functions_framework_cpp_examples_unit_tests
         # cmake-format: sort
         cloud_event_examples_test.cc http_examples_test.cc site_test.cc)
 
-    foreach (fname ${googleapis_functions_framework_examples_unit_tests})
+    foreach (fname ${functions_framework_cpp_examples_unit_tests})
         string(REPLACE "/" "_" target "${fname}")
         string(REPLACE ".cc" "" target "${target}")
         add_executable("${target}" ${fname})
         target_link_libraries(
             ${target}
             PRIVATE functions_framework_examples
-                    googleapis_functions_framework
+                    functions-framework-cpp::framework
                     Boost::filesystem
                     Boost::log
                     GTest::gmock_main

@@ -15,8 +15,8 @@
 # ~~~
 
 find_package(storage_client REQUIRED)
-find_package(googleapis_functions_framework)
+find_package(functions_framework_cpp REQUIRED)
 
 add_library(functions_framework_cpp_function hello_gcs.cc)
 target_link_libraries(functions_framework_cpp_function storage_client
-                      googleapis-c++::functions_framework)
+                      functions-framework-cpp::framework)
@@ -15,8 +15,8 @@
 # ~~~
 
 find_package(fmt REQUIRED)
-find_package(googleapis_functions_framework)
+find_package(functions_framework_cpp REQUIRED)
 
 add_library(functions_framework_cpp_function hello_with_third_party.cc)
 target_link_libraries(functions_framework_cpp_function fmt::fmt
-                      googleapis-c++::functions_framework)
+                      functions-framework-cpp::framework)
@@ -14,8 +14,8 @@
 # limitations under the License.
 # ~~~
 
-find_package(googleapis_functions_framework)
+find_package(functions_framework_cpp REQUIRED)
 
 add_library(functions_framework_cpp_function concepts_filesystem.cc)
 target_link_libraries(functions_framework_cpp_function
-                      googleapis-c++::functions_framework stdc++fs)
+                      functions-framework-cpp::framework stdc++fs)
@@ -14,9 +14,9 @@
 # limitations under the License.
 # ~~~
 
-find_package(googleapis_functions_framework)
+find_package(functions_framework_cpp REQUIRED)
 find_package(Boost REQUIRED COMPONENTS log)
 
 add_library(functions_framework_cpp_function hello_world_pubsub.cc)
 target_link_libraries(functions_framework_cpp_function
-                      googleapis-c++::functions_framework Boost::log)
+                      functions-framework-cpp::framework Boost::log)
@@ -14,9 +14,9 @@
 # limitations under the License.
 # ~~~
 
-find_package(googleapis_functions_framework)
+find_package(functions_framework_cpp REQUIRED)
 find_package(Boost REQUIRED COMPONENTS log)
 
 add_library(functions_framework_cpp_function hello_world_storage.cc)
 target_link_libraries(functions_framework_cpp_function
-                      googleapis-c++::functions_framework Boost::log)
+                      functions-framework-cpp::framework Boost::log)
@@ -19,31 +19,30 @@ find_package(Boost REQUIRED COMPONENTS filesystem)
 
 if (BUILD_TESTING)
     find_package(GTest CONFIG REQUIRED)
-    set(googleapis_functions_framework_examples_unit_tests
+    set(functions_framework_cpp_examples_unit_tests
         # cmake-format: sort
         http_integration_test.cc http_unit_test.cc)
 
-    set(googleapis_functions_framework_examples_programs
-        # cmake-format: sort
-        http_integration_server.cc)
+    set(functions_framework_cpp_examples_programs # cmake-format: sort
+                                                  http_integration_server.cc)
 
-    foreach (fname ${googleapis_functions_framework_examples_unit_tests}
-                   ${googleapis_functions_framework_examples_programs})
+    foreach (fname ${functions_framework_cpp_examples_unit_tests}
+                   ${functions_framework_cpp_examples_programs})
         string(REPLACE "/" "_" target "${fname}")
         string(REPLACE ".cc" "" target "${target}")
         add_executable("${target}" ${fname})
         target_link_libraries(
             ${target}
             PRIVATE functions_framework_examples
-                    googleapis_functions_framework
+                    functions-framework-cpp::framework
                     CURL::libcurl
                     Boost::filesystem
                     GTest::gmock_main
                     GTest::gmock
                     GTest::gtest)
     endforeach ()
 
-    foreach (fname ${googleapis_functions_framework_examples_unit_tests})
+    foreach (fname ${functions_framework_cpp_examples_unit_tests})
         string(REPLACE "/" "_" target "${fname}")
         string(REPLACE ".cc" "" target "${target}")
         add_test(NAME ${target} COMMAND ${target})

@@ -16,22 +16,21 @@
 
 if (BUILD_TESTING)
     find_package(GTest CONFIG REQUIRED)
-    set(googleapis_functions_framework_examples_unit_tests
+    set(functions_framework_cpp_examples_unit_tests
         # cmake-format: sort
         pubsub_integration_test.cc pubsub_unit_test.cc)
 
-    set(googleapis_functions_framework_examples_programs
-        # cmake-format: sort
-        pubsub_integration_server.cc)
+    set(functions_framework_cpp_examples_programs # cmake-format: sort
+                                                  pubsub_integration_server.cc)
 
-    foreach (fname ${googleapis_functions_framework_examples_unit_tests})
+    foreach (fname ${functions_framework_cpp_examples_unit_tests})
         string(REPLACE "/" "_" target "${fname}")
         string(REPLACE ".cc" "" target "${target}")
         add_executable("${target}" ${fname})
         target_link_libraries(
             ${target}
             PRIVATE functions_framework_examples
-                    googleapis_functions_framework
+                    functions-framework-cpp::framework
                     Boost::filesystem
                     Boost::log
                     GTest::gmock_main
@@ -40,13 +39,14 @@ if (BUILD_TESTING)
         add_test(NAME ${target} COMMAND ${target})
     endforeach ()
 
-    foreach (fname ${googleapis_functions_framework_examples_programs})
+    foreach (fname ${functions_framework_cpp_examples_programs})
         string(REPLACE "/" "_" target "${fname}")
         string(REPLACE ".cc" "" target "${target}")
         add_executable("${target}" ${fname})
         target_link_libraries(
             ${target}
-            PRIVATE functions_framework_examples googleapis_functions_framework
-                    Boost::filesystem Boost::log)
+            PRIVATE functions_framework_examples
+                    functions-framework-cpp::framework Boost::filesystem
+                    Boost::log)
     endforeach ()
 endif ()