From d4f01c1e870e43efb178e50b24fbe0685a523cf1 Mon Sep 17 00:00:00 2001 From: Karl Wiberg Date: Fri, 10 Nov 2017 10:55:45 +0100 Subject: [PATCH] Tell users where they can find the native API headers The listed directories are the same as in PRESUBMIT.py, which was previously the only way to look this stuff up... BUG=webrtc:8445 NOTRY=true Change-Id: I218c91e554f3163ae13fc75b9cbf76b42f70624e Reviewed-on: https://webrtc-review.googlesource.com/16432 Commit-Queue: Karl Wiberg Reviewed-by: Fredrik Solenberg Reviewed-by: Mirko Bonadei Reviewed-by: Niels Moller Cr-Commit-Position: refs/heads/master@{#20670} --- PRESUBMIT.py | 2 ++ README.md | 3 +++ native-api.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 72 insertions(+) create mode 100644 native-api.md diff --git a/PRESUBMIT.py b/PRESUBMIT.py index 69751a82df..5d9f459411 100755 --- a/PRESUBMIT.py +++ b/PRESUBMIT.py @@ -93,6 +93,8 @@ LEGACY_API_DIRS = ( 'voice_engine/include', ) +# NOTE: The set of directories in API_DIRS should be the same as those +# listed in the table in native-api.md. API_DIRS = NATIVE_API_DIRS[:] + LEGACY_API_DIRS[:] # TARGET_RE matches a GN target, and extracts the target name and the contents. diff --git a/README.md b/README.md index 70d7c5f3e5..2a24595476 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,9 @@ amongst others. See http://www.webrtc.org/native-code/development for instructions on how to get started developing with the native code. +[Authoritative list](native-api.md) of directories that contain the +native API header files. + ### More info * Official web site: http://www.webrtc.org diff --git a/native-api.md b/native-api.md new file mode 100644 index 0000000000..b0ebe2762f --- /dev/null +++ b/native-api.md @@ -0,0 +1,67 @@ +# API header files + +As a user of the WebRTC library, you may use headers and build files +in the following directories: + +API directory | Including subdirectories? +--------------|------------------------- +`api` | Yes + +For now, you may also use headers and build files in the following +legacy API directories—but see the +[disclaimer](#legacy-disclaimer) below. + +Legacy API directory | Including subdirectories? +-------------------------------------------|-------------------------- +`common_audio/include` | No +`media` | No +`modules/audio_coding/include` | No +`modules/audio_device/include` | No +`modules/audio_processing/include` | No +`modules/bitrate_controller/include` | No +`modules/congestion_controller/include` | No +`modules/include` | No +`modules/remote_bitrate_estimator/include` | No +`modules/rtp_rtcp/include` | No +`modules/rtp_rtcp/source` | No +`modules/utility/include` | No +`modules/video_coding/codecs/h264/include` | No +`modules/video_coding/codecs/i420/include` | No +`modules/video_coding/codecs/vp8/include` | No +`modules/video_coding/codecs/vp9/include` | No +`modules/video_coding/include` | No +`pc` | No +`rtc_base` | No +`system_wrappers/include` | No +`voice_engine/include` | No + +While the files, types, functions, macros, build targets, etc. in the +API and legacy API directories will sometimes undergo incompatible +changes, such changes will be announced in advance to +[discuss-webrtc@googlegroups.com][discuss-webrtc], and a migration +path will be provided. + +[discuss-webrtc]: https://groups.google.com/forum/#!forum/discuss-webrtc + +In the directories not listed in the tables above, incompatible +changes may happen at any time, and are not announced. + +## The legacy API directories contain some things you shouldn’t use + +The legacy API directories, in addition to things that genuinely +should be part of the API, also contain things that should *not* be +part of the API. We are in the process of moving the good stuff to the +`api` directory tree, and will remove directories from the legacy list +once they no longer contain anything that should be in the API. + +In other words, if you find things in the legacy API directories that +don’t seem like they belong in the WebRTC native API, +don’t grow too attached to them. + +## All these worlds are yours—except Europa + +In the API headers, or in files included by the API headers, there are +types, functions, namespaces, etc. that have `impl` or `internal` in +their names (in various styles, such as `CamelCaseImpl`, +`snake_case_impl`). They are not part of the API, and may change +incompatibly at any time; do not use them.