From 26a029d407be480d791972afb5975cf62c9360a6 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 02:47:55 +0200 Subject: Adding upstream version 124.0.1. Signed-off-by: Daniel Baumann --- third_party/libwebrtc/g3doc/OWNERS | 5 + third_party/libwebrtc/g3doc/abseil-in-webrtc.md | 85 +++ third_party/libwebrtc/g3doc/add-new-test-binary.md | 33 + third_party/libwebrtc/g3doc/become_a_committer.md | 84 +++ third_party/libwebrtc/g3doc/field-trials.md | 70 +++ .../libwebrtc/g3doc/how_to_write_documentation.md | 68 +++ .../libwebrtc/g3doc/implementation_basics.md | 141 +++++ third_party/libwebrtc/g3doc/index.md | 6 + third_party/libwebrtc/g3doc/logo.svg | 675 +++++++++++++++++++++ third_party/libwebrtc/g3doc/sitemap.md | 55 ++ third_party/libwebrtc/g3doc/style-guide.md | 308 ++++++++++ third_party/libwebrtc/g3doc/style-guide/OWNERS | 1 + .../libwebrtc/g3doc/style-guide/h-cc-pairs.md | 32 + .../g3doc/supported-platforms-and-compilers.md | 34 ++ 14 files changed, 1597 insertions(+) create mode 100644 third_party/libwebrtc/g3doc/OWNERS create mode 100644 third_party/libwebrtc/g3doc/abseil-in-webrtc.md create mode 100644 third_party/libwebrtc/g3doc/add-new-test-binary.md create mode 100644 third_party/libwebrtc/g3doc/become_a_committer.md create mode 100644 third_party/libwebrtc/g3doc/field-trials.md create mode 100644 third_party/libwebrtc/g3doc/how_to_write_documentation.md create mode 100644 third_party/libwebrtc/g3doc/implementation_basics.md create mode 100644 third_party/libwebrtc/g3doc/index.md create mode 100644 third_party/libwebrtc/g3doc/logo.svg create mode 100644 third_party/libwebrtc/g3doc/sitemap.md create mode 100644 third_party/libwebrtc/g3doc/style-guide.md create mode 100644 third_party/libwebrtc/g3doc/style-guide/OWNERS create mode 100644 third_party/libwebrtc/g3doc/style-guide/h-cc-pairs.md create mode 100644 third_party/libwebrtc/g3doc/supported-platforms-and-compilers.md (limited to 'third_party/libwebrtc/g3doc') diff --git a/third_party/libwebrtc/g3doc/OWNERS b/third_party/libwebrtc/g3doc/OWNERS new file mode 100644 index 0000000000..9ece35c39b --- /dev/null +++ b/third_party/libwebrtc/g3doc/OWNERS @@ -0,0 +1,5 @@ +titovartem@webrtc.org + +per-file abseil-in-webrtc.md=danilchap@webrtc.org +per-file abseil-in-webrtc.md=mbonadei@webrtc.org +per-file style-guide.md=danilchap@webrtc.org diff --git a/third_party/libwebrtc/g3doc/abseil-in-webrtc.md b/third_party/libwebrtc/g3doc/abseil-in-webrtc.md new file mode 100644 index 0000000000..034f6c2fb4 --- /dev/null +++ b/third_party/libwebrtc/g3doc/abseil-in-webrtc.md @@ -0,0 +1,85 @@ + + + +# Using Abseil in WebRTC + +You may use a subset of the utilities provided by the [Abseil][abseil] +library when writing WebRTC C++ code. Below, we list the explicitly +*allowed* and the explicitly *disallowed* subsets of Abseil; if you +find yourself in need of something that isn’t in either subset, +please add it to the *allowed* subset in this doc in the same CL that +adds the first use. + +[abseil]: https://abseil.io/about/ + + +## How to depend on Abseil + +For build targets of type `rtc_library`, `rtc_source_set` and +`rtc_static_library`, dependencies on Abseil need to be listed in `absl_deps` +instead of `deps`. + +This is needed in order to support the Abseil component build in Chromium. In +that build mode, WebRTC will depend on a monolithic Abseil build target that +will generate a shared library. + +## **Allowed** + +* `absl::AnyInvocable` +* `absl::bind_front` +* `absl::Cleanup` +* `absl::InlinedVector` +* `absl::Nonnull` and `absl::Nullable` +* `absl::WrapUnique` +* `absl::optional` and related stuff from `absl/types/optional.h`. +* `absl::string_view` +* The functions in `absl/strings/ascii.h`, `absl/strings/match.h`, + and `absl/strings/str_replace.h`. +* The functions in `absl/strings/escaping.h`. +* `absl::is_trivially_copy_constructible`, + `absl::is_trivially_copy_assignable`, and + `absl::is_trivially_destructible` from `absl/meta/type_traits.h`. +* `absl::variant` and related stuff from `absl/types/variant.h`. +* The functions in `absl/algorithm/algorithm.h` and + `absl/algorithm/container.h`. +* `absl/base/const_init.h` for mutex initialization. +* The macros in `absl/base/attributes.h`, `absl/base/config.h` and + `absl/base/macros.h`. +* `absl/numeric/bits.h` + + +## **Disallowed** + +### `absl::make_unique` + +*Use `std::make_unique` instead.* + +### `absl::Mutex` + +*Use `webrtc::Mutex` instead.* + +Chromium has a ban on new static initializers, and `absl::Mutex` uses +one. To make `absl::Mutex` available, we would need to nicely ask the +Abseil team to remove that initializer (like they already did for a +spinlock initializer). Additionally, `absl::Mutex` handles time in a +way that may not be compatible with the rest of WebRTC. + +### `absl::Span` + +*Use `rtc::ArrayView` instead.* + +`absl::Span` differs from `rtc::ArrayView` on several points, and both +of them differ from the `std::span` that was voted into +C++20—and `std::span` is likely to undergo further changes +before C++20 is finalized. We should just keep using `rtc::ArrayView` +and avoid `absl::Span` until C++20 is finalized and the Abseil team +has decided if they will change `absl::Span` to match. +[Bug](https://bugs.webrtc.org/9214). + +### `absl::StrCat`, `absl::StrAppend`, `absl::StrJoin`, `absl::StrSplit` + +*Use `rtc::SimpleStringBuilder` to build strings.* + +These are optimized for speed, not binary size. Even `StrCat` calls +with a modest number of arguments can easily add several hundred bytes +to the binary. diff --git a/third_party/libwebrtc/g3doc/add-new-test-binary.md b/third_party/libwebrtc/g3doc/add-new-test-binary.md new file mode 100644 index 0000000000..177c212b89 --- /dev/null +++ b/third_party/libwebrtc/g3doc/add-new-test-binary.md @@ -0,0 +1,33 @@ +# Add a new test binary + +This page lists all the steps needed in order to add an `rtc_test` target to +WebRTC's BUILD.gn files and ensure the test binary will run on the presubmit and +postsubmit infrastructure. + +1. While working on your CL, add an `rtc_test` target, with `testonly = true`, + and `../test:test_main` among its dependencies (`rtc_test` targets require + a `main()` function). + +2. Add the newly created `rtc_test` target to the `group("default")` target in + the root [BUILD.gn](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/BUILD.gn). + The target needs to be added within the `rtc_include_tests` section. + +3. Add the name of the newly created `rtc_test` into + [infra/specs/gn_isolate_map.pyl](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/infra/specs/gn_isolate_map.pyl). + +4. Add the name of the newly created `rtc_test` into + [infra/specs/test_suites.pyl](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/infra/specs/test_suites.pyl). + By default, you should add it to the `android_tests`, `desktop_tests` and + `ios_simulator_tests` sections. + +5. Run the script + [infra/specs/generate_buildbot_json.py](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/infra/specs/generate_buildbot_json.py) + (no arguments) to generate the JSON scripts based on the previsouly modified .pyl scripts. + +6. Build, test, review and submit! + +The bots will execute the new configs as part of the CQ. Inspect some logs to +verify that your test is in fact executed by the bots where you expect them to be. + +The details of the (many) config files are described in +https://chromium.googlesource.com/chromium/src/testing/+/HEAD/buildbot/README.md. diff --git a/third_party/libwebrtc/g3doc/become_a_committer.md b/third_party/libwebrtc/g3doc/become_a_committer.md new file mode 100644 index 0000000000..b2f49721e1 --- /dev/null +++ b/third_party/libwebrtc/g3doc/become_a_committer.md @@ -0,0 +1,84 @@ + + + +# How to get tryjob access or become WebRTC committer + +## Overview + +There are two levels of WebRTC contributors access: + +1. Tryjob access - permits contributor to run tests for their changes using + WebRTC infrastructure +2. WebRTC committer rights - permits to submit changes to the WebRTC code base. + This includes tryjob access. + +## Getting tryjob access + +To get tryjob access applicant has to do a contribution around 10-20 CLs to the +WebRTC code base. After that, they should file a bug using +[Get tryjob access template][7], specifying the email which was used for the +contributions and to which access will be granted, and listing contributed CLs. + +The access will be granted when the ticket is resolved by one of the project +members. In case of rejection the explanation will be provided. + +## WebRTC committer duties + +WebRTC committers are responsible for keeping WebRTC codebase in a good shape +including, but not limited to the following aspects: + +* Code complexity and correctness +* C++ best practices +* Code formatting +* Test coverage +* Class/function level and conceptual documentation + +Whenever a committer sets `Code Review +1` label on the CL, they approve that +the CL fulfills WebRTC style guides, language mastery, testability and +documentation. Being a committer means being responsible for the WebRTC codebase +health and code quality. + +## Becoming a WebRTC committer + +To write code in WebRTC you don't need to be a committer (also see [FAQ][1]), +but to submit code to WebRTC you do. So if you don't plan to work on the WebRTC +codebase regularly, you can ask other committers through code review to submit +your patches, but if you are going to work in the WebRTC codebase, then it's +recommended to apply for WebRTC committer rights obtaining process. + +1. If you are going to write in C++ make yourself familiar with with C++ style + guides: + + * [Google style guide][5] + * [Chromium style guide][2] + * [WebRTC style guide][3] + +2. Create a ticket to obtain WebRTC committers rights in Monorail. Please use + [this template][6] of it. + +3. Pick a mentor among WebRTC committers, who will review your CLs. For C++ + authors, the mentor will also look for C++ readability skills. It's + recommended to ask someone who is familiar with the code base which you will + be working on (you can check OWNERS files to find such person). Otherwise + you can reach out to committers mailing list \. + +4. Send CLs to the mentor for review and attach them to the created ticket. + +5. When the mentor decides that you are ready (for C++ authors their C++ + readability skills are good enough), they will send a proposal for granting + WebRTC committer rights to the reviewing committee mailing list to review. + If the proposal will be approved, then committer rights will be granted. + Committee members will have up to 5 business days to answer. In case of + rejection detailed feedback on what aspects should be improved will be + provided. + +6. Also as any contributor you must sign and return the + [Contributor License Agreement][4] + +[1]: https://webrtc.googlesource.com/src/+/refs/heads/main/docs/faq.md#to-be-a-contributor_do-i-need-to-sign-any-agreements +[2]: https://chromium.googlesource.com/chromium/src/+/refs/heads/main/styleguide/c++/c++.md +[3]: https://webrtc.googlesource.com/src/+/refs/heads/main/g3doc/style-guide.md +[4]: https://developers.google.com/open-source/cla/individual?hl=en +[5]: https://google.github.io/styleguide/cppguide.html +[6]: https://bugs.chromium.org/p/webrtc/issues/entry?template=Become+WebRTC+committer +[7]: https://bugs.chromium.org/p/webrtc/issues/entry?template=Get+tryjob+access diff --git a/third_party/libwebrtc/g3doc/field-trials.md b/third_party/libwebrtc/g3doc/field-trials.md new file mode 100644 index 0000000000..724a302fe1 --- /dev/null +++ b/third_party/libwebrtc/g3doc/field-trials.md @@ -0,0 +1,70 @@ + + + +# Field trials + +WebRTC provides some means to alter its default behavior during run-time, +colloquially known as *field trials*. This is foremost used for A/B testing new +features and are related to +[Chromium field trials](https://chromium.googlesource.com/chromium/src/+/main/testing/variations/README.md) +to facilitate interoperability. + +A field trial consist of a key-value pair of strings. By convention, the field +trial key is prefixed with `WebRTC-` and each word is capitalized without +spaces. Sometimes the key is further subdivided into a category, for example, +`WebRTC-MyCategory-MyExperiment`. The field trial value is an opaque string and +it is up to the author to define what it represents. There are +[helper functions](https://webrtc.googlesource.com/src/+/refs/heads/main/api/field_trials_view.h) +to use a field trial as a boolean, with the string `Enabled` representing true +and `Disabled` representing false. You can also use +[field trial parameters](https://webrtc.googlesource.com/src/+/refs/heads/main/rtc_base/experiments/field_trial_parser.h) +if you wish to encode more elaborate data types. + +The set of field trials can be instantiated from a single string with the format +`////`. Note the final `/` at the end! In +Chromium you can launch with the `--force-fieldtrials` flag to instantiate field +trials this way, for example: + +``` +--force-fieldtrials="WebRTC-Foo/Enabled/WebRTC-Bar/Disabled/" +``` + +## Policy + +The policy for field trials is: + +- A field trial should only be used to test out new code or parameters for a + limited time period. It should not be used for configuring persistent + behavior. +- The field trial must have an end date. The end date may be pushed back if + necessary, but should not be pushed back indefinitely. +- A field trial must be associated with a bug that + - reserves the field trial key, and + - is assigned to an owner. + +## Creating a field trial + +Before creating a new field trial, make sure to read the [policy](#policy). + +Either create a new or reuse an existing bug and make sure it is assigned to the +correct owner. Take note of the bug ID. Next, decide how long you need the field +trial to last. It should be rare to have field trials lasting more than 12 +months. You can use the `NextAction` field in the bug to help you remember the +end date. + +Using this information, add a new entry to `ACTIVE_FIELD_TRIALS` in +`experiments/field_trials.py`. You may not add new items to +`POLICY_EXEMPT_FIELD_TRIALS` since it is reserved for field trials that were +created before the policy was in place. + +## Removing a field trial + +Any field trial that has expired or otherwise is not needed anymore may be +removed by following these steps: + +- Remove all references from the code base. You can find these by, e.g. + grepping for the field trial key. +- Clean up potential glue code that might have been added. +- Remove the field trial from `ACTIVE_FIELD_TRIALS` in + `experiments/field_trials.py`. +- If all work is finished, also close the associated bug. diff --git a/third_party/libwebrtc/g3doc/how_to_write_documentation.md b/third_party/libwebrtc/g3doc/how_to_write_documentation.md new file mode 100644 index 0000000000..6c6a4902ee --- /dev/null +++ b/third_party/libwebrtc/g3doc/how_to_write_documentation.md @@ -0,0 +1,68 @@ + + + +# How to write WebRTC documentation + +## Audience + +Engineers and tech writers who wants to contribute to WebRTC documentation + +## Conceptual documentation + +Conceptual documentation provides overview of APIs or systems. Examples can +be threading model of a particular module or data life cycle. Conceptual +documentation can skip some edge cases in favor of clarity. The main point +is to impart understanding. + +Conceptual documentation often cannot be embedded directly within the source +code because it usually describes multiple APIs and entities, so the only +logical place to document such complex behavior is through a separate +conceptual document. + +A concept document needs to be useful to both experts and novices. Moreover, +it needs to emphasize clarity, so it often needs to sacrifice completeness +and sometimes strict accuracy. That's not to say a conceptual document should +intentionally be inaccurate. It just means that is should focus more on common +usage and leave rare ones or side effects for class/function level comments. + +In the WebRTC repo, conceptual documentation is located in `g3doc` subfolders +of related components. To add a new document for the component `Foo` find a +`g3doc` subfolder for this component and create a `.md` file there with +desired documentation. If there is no `g3doc` subfolder, create a new one. + +Please put the following file header into any created documentation file as the +first line: + +```markdown + +``` + +When you want to specify a link from one page to another - use the absolute +path: + +``` +[My document](/module/g3doc/my_document.md) +``` + +If you are a Googler also please specify an owner, who will be responsible for +keeping this documentation updated, by adding the next lines at the beginning +of your `.md` file immediately after page title: + +```markdown + +``` + +After the document is ready you should add it into `/g3doc/sitemap.md`, so it +will be discoverable by others. + +### Documentation format + +The documentation is written in GitHub Markdown +([spec](https://github.github.com/gfm/#:~:text=GitHub%20Flavored%20Markdown%2C%20often%20shortened,a%20strict%20superset%20of%20CommonMark.)). + +## Class/function level comments + +Documentation of specific classes and function APIs and their usage, including +their purpose, is embedded in the .h files defining that API. See +[C++ style guide](https://chromium.googlesource.com/chromium/src/+/main/styleguide/c++/c++.md) +for pointers on how to write API documentatin in .h files. diff --git a/third_party/libwebrtc/g3doc/implementation_basics.md b/third_party/libwebrtc/g3doc/implementation_basics.md new file mode 100644 index 0000000000..ae1f199b68 --- /dev/null +++ b/third_party/libwebrtc/g3doc/implementation_basics.md @@ -0,0 +1,141 @@ + + + +# Basic concepts and primitives + +## Time + +Internally, time is represent using the [webrtc::Timestamp][1] class. This +represents +time with a resolution of one microsecond, using a 64-bit integer, and provides +converters to milliseconds or seconds as needed. + +All timestamps need to be measured from the system monotonic time. + +The epoch is not specified (because we can't always know if the system clock is +correct), but whenever an absolute epoch is needed, the Unix time +epoch (Jan 1, 1970 at 0:00 GMT) is used. + +Conversion from/to other formats (for example milliseconds, NTP times, +timestamp strings) should happen as close to the interface requiring that +format as possible. + +NOTE: There are parts of the codebase that don't use Timestamp, parts of the +codebase that use the NTP epoch, and parts of the codebase that don't use the +monotonic clock. They need to +be updated. + +## Threads + +All execution happens on a TaskQueue instance. How a TaskQueue is implemented +varies by platform, but they all have the [webrtc::TaskQueueBase][3] API. + +This API offers primitives for posting tasks, with or without delay. + +Some core parts use the [rtc::Thread][2], which is a subclass of TaskQueueBase. +This may contain a SocketServer for processing I/O, and is used for policing +certain calling pattern between a few core threads (the NetworkThread cannot +do Invoke on the Worker thread, for instance). + +## Reserved class suffixes + +C++ classes with names ending in the suffixes "Factory", "Builder" and "Manager" are supposed to behave +in certain well known ways. + +For a particular class name Foo, the following classes, if they exist, should +behave as follows: + +* FooFactory: Has a Create function that creates a Foo object and returns the + object or an owning reference to it (for instance std::unique_ptr or + rtc::scoped_refptr). The Create function should NOT alter the factory + state; ideally, it is marked const. Ownership of the returned object is only + with the caller. + +* FooBuilder: Has a Build function that returns ownership of a Foo object (as + above). The Builder can only be used once, and resources given to the Builder + before the Build function is called are either released or owned by the Foo + object. The Create function may be reference-qualified (declared as ```Foo + Build() &&```), which means it is invoked as ```std::move(builder).Build()```, + and C++ will ensure that it is not used again. + +* FooManager: Has a Create function that returns an rtc::scoped_refptr (if + shared ownership) or a Foo* (if the Manager retains sole ownership). If + Create() cannot fail, consider returning a Foo&. The Manager is responsible + for keeping track of the object; if the Create function returns a Foo*, the + Foo object is guaranteed to be destroyed when the FooManager is destroyed. + +If a Manager class manages multiple classes of objects, the Create functions +should be appropriately named (the FooAndBarManager would have CreateFoo() and +CreateBar() functions), and the class will have a suitable name for the group of +objects it is managing. + +FooFactory is mainly useful for the case where preparation for producing Foo +objects is complex. If Foo can be created with just an argument list, consider +exposing its constructor instead; if Foo creation can fail, consider having +a free function called CreateFoo instead of a factory. + +Note that classes with these names exist that do not follow these conventions. +When they are detected, they need to be marked with TODO statements and bugs +filed on them to get them into a conformant state. + +## Synchronization primitives + +### PostTask and thread-guarded variables + +The preferred method for synchronization is to post tasks between threads, +and to let each thread take care of its own variables (lock-free programming). +All variables in +classes intended to be used with multiple threads should therefore be +annotated with RTC_GUARDED_BY(thread). + +For classes used with only one thread, the recommended pattern is to let +them own a webrtc::SequenceChecker (conventionally named sequence_checker_) +and let all variables be RTC_GUARDED_BY(sequence_checker_). + +Member variables marked const do not need to be guarded, since they never +change. (But note that they may point to objects that can change!) + +When posting tasks with callbacks, it is the duty of the caller to check +that the object one is calling back into still exists when the callback +is made. A helper for this task is the [webrtc::ScopedTaskSafety][5] +flag, which can automatically drop callbacks in this situation, and +associated classes. + +### Synchronization primitives to be used when needed + +When it is absolutely necessary to let one thread wait for another thread +to do something, Thread::Invoke can be used. This function is DISCOURAGED, +since it leads to performance issues, but is currently still widespread. + +When it is absolutely necessary to access one variable from multiple threads, +the webrtc::Mutex can be used. Such variables MUST be marked up with +RTC_GUARDED_BY(mutex), to allow static analysis that lessens the chance of +deadlocks or unintended consequences. + +### Synchronization primitives that are being removed +The following non-exhaustive list of synchronization primitives are +in the (slow) process of being removed from the codebase. + +* sigslot. Use [webrtc::CallbackList][4] instead, or, when there's only one + signal consumer, a single std::function. + +* AsyncInvoker. + +* RecursiveCriticalSection. Try to use [webrtc::Mutex][6] instead, and don't recurse. + +## Enum-To-String functions +If there is a need to convert an enum to a string representation, such as for +enums exposed at the Javascript API interface, the recommended way is to write +a function named AsString, declared "static constexpr" and returning an +absl::string_view. The declaration should be right after the enum declaration, +in the same scope; the implementation (which must be marked "inline") should +be at the end of the same header file. + +If the enum is not defined within a class, the "static" keyword is not needed. + +[1]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/api/units/timestamp.h;drc=b95d90b78a3491ef8e8aa0640dd521515ec881ca;l=29 +[2]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/rtc_base/thread.h;drc=1107751b6f11c35259a1c5c8a0f716e227b7e3b4;l=194 +[3]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/api/task_queue/task_queue_base.h;drc=1107751b6f11c35259a1c5c8a0f716e227b7e3b4;l=25 +[4]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/rtc_base/callback_list.h;drc=54b91412de3f579a2d5ccdead6e04cc2cc5ca3a1;l=162 +[5]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/rtc_base/task_utils/pending_task_safety_flag.h;drc=86ee89f73e4f4799b3ebcc0b5c65837c9601fe6d;l=117 +[6]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/rtc_base/synchronization/mutex.h;drc=0d3c09a8fe5f12dfbc9f1bcd5790fda8830624ec;l=40 diff --git a/third_party/libwebrtc/g3doc/index.md b/third_party/libwebrtc/g3doc/index.md new file mode 100644 index 0000000000..8016054d3c --- /dev/null +++ b/third_party/libwebrtc/g3doc/index.md @@ -0,0 +1,6 @@ + + + +# WebRTC C++ library + +This is a home page for WebRTC C++ library documentation diff --git a/third_party/libwebrtc/g3doc/logo.svg b/third_party/libwebrtc/g3doc/logo.svg new file mode 100644 index 0000000000..634b8cb116 --- /dev/null +++ b/third_party/libwebrtc/g3doc/logo.svg @@ -0,0 +1,675 @@ + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/third_party/libwebrtc/g3doc/sitemap.md b/third_party/libwebrtc/g3doc/sitemap.md new file mode 100644 index 0000000000..c1221e5335 --- /dev/null +++ b/third_party/libwebrtc/g3doc/sitemap.md @@ -0,0 +1,55 @@ +* [Home](/g3doc/index.md) +* How to contribute + * Code + * [Style guide](/g3doc/style-guide.md) + * [`.h` and `.cc` files come in pairs](/g3doc/style-guide/h-cc-pairs.md) + * [How to write code in the `api/` directory](/api/README.md) + * [Using Abseil in WebRTC](/g3doc/abseil-in-webrtc.md) + * [Code of conduct](/CODE_OF_CONDUCT.md) + * [Documentation](/g3doc/how_to_write_documentation.md) + * [Become a committer](/g3doc/become_a_committer.md) +* [Public C++ API](/api/g3doc/index.md) + * [API header files](/native-api.md) + * [Threading](/api/g3doc/threading_design.md) +* Implementation + * [Basic concepts](/g3doc/implementation_basics.md) + * [Supported Platforms and Compilers](/g3doc/supported-platforms-and-compilers.md) + * Network + * [ICE](/p2p/g3doc/ice.md) + * STUN + * TURN + * [DTLS](/pc/g3doc/dtls_transport.md) + * [RTP](/pc/g3doc/rtp.md) + * [SRTP](/pc/g3doc/srtp.md) + * [SCTP](/pc/g3doc/sctp_transport.md) + * [Pacing buffer](/modules/pacing/g3doc/index.md) + * Congestion control and bandwidth estimation + * Audio + * [NetEq](/modules/audio_coding/neteq/g3doc/index.md) + * AudioEngine + * [ADM](/modules/audio_device/g3doc/audio_device_module.md) + * [Audio Coding](/modules/audio_coding/g3doc/index.md) + * [Audio Mixer](/modules/audio_mixer/g3doc/index.md) + * AudioProcessingModule + * [APM](/modules/audio_processing/g3doc/audio_processing_module.md) + * Video + * [Adaptation](/video/g3doc/adaptation.md) + * [Video coding](/modules/video_coding/g3doc/index.md) + * [Stats](/video/g3doc/stats.md) + * DataChannel + * [PeerConnection](/pc/g3doc/peer_connection.md) + * Desktop capture + * [Stats](/stats/g3doc/stats.md) + * [Logging](/logging/g3doc/rtc_event_log.md) +* Testing + * Media Quality and performance + * [PeerConnection Framework](/test/pc/e2e/g3doc/index.md) + * [Architecture](/test/pc/e2e/g3doc/architecture.md) + * [Video analyzer](/test/pc/e2e/g3doc/default_video_quality_analyzer.md) + * Call framework + * Video codecs test framework + * Network emulation + * [Implementation](/test/network/g3doc/index.md) + * Performance stats collection +* Experimentation + * [Field trials](/g3doc/field-trials.md) diff --git a/third_party/libwebrtc/g3doc/style-guide.md b/third_party/libwebrtc/g3doc/style-guide.md new file mode 100644 index 0000000000..b32163f906 --- /dev/null +++ b/third_party/libwebrtc/g3doc/style-guide.md @@ -0,0 +1,308 @@ + + + +# WebRTC coding style guide + +## General advice + +Some older parts of the code violate the style guide in various ways. +If making large changes to such code, consider first cleaning it up in a + separate CL. + +## C++ + +WebRTC follows the [Chromium C++ style guide][chr-style] and the +[Google C++ style guide][goog-style]. In cases where they conflict, the Chromium +style guide trumps the Google style guide, and the rules in this file trump them +both. + +[chr-style]: https://chromium.googlesource.com/chromium/src/+/main/styleguide/c++/c++.md +[goog-style]: https://google.github.io/styleguide/cppguide.html + +### C++ version + +WebRTC is written in C++17, but with some restrictions: + +* We only allow the subset of C++17 (language and library) that is not banned by + Chromium; see the [list of banned C++ features in Chromium][chr-style-cpp]. +* We only allow the subset of C++17 that is also valid C++20; otherwise, users + would not be able to compile WebRTC in C++20 mode. + +[chr-style-cpp]: https://chromium.googlesource.com/chromium/src/+/main/styleguide/c++/c++-features.md + +### Abseil + +You may use a subset of the utilities provided by the [Abseil][abseil] library +when writing WebRTC C++ code; see the +[instructions on how to use Abseil in WebRTC](abseil-in-webrtc.md). + +[abseil]: https://abseil.io/about/ + +### `.h` and `.cc` files come in pairs + +`.h` and `.cc` files should come in pairs, with the same name (except for the +file type suffix), in the same directory, in the same build target. + +* If a declaration in `path/to/foo.h` has a definition in some `.cc` file, it + should be in `path/to/foo.cc`. +* If a definition in `path/to/foo.cc` file has a declaration in some `.h` file, + it should be in `path/to/foo.h`. +* Omit the `.cc` file if it would have been empty, but still list the `.h` file + in a build target. +* Omit the `.h` file if it would have been empty. (This can happen with unit + test `.cc` files, and with `.cc` files that define `main`.) + +See also the +[examples and exceptions on how to treat `.h` and `.cpp` files](style-guide/h-cc-pairs.md). + +This makes the source code easier to navigate and organize, and precludes some +questionable build system practices such as having build targets that don't pull +in definitions for everything they declare. + +### `TODO` comments + +Follow the [Google styleguide for `TODO` comments][goog-style-todo]. When +referencing a WebRTC bug, prefer using the URL form (excluding the scheme part): + +```cpp +// TODO(bugs.webrtc.org/12345): Delete the hack when blocking bugs are resolved. +``` + +The short form used in commit messages, e.g. `webrtc:12345`, is discouraged. + +[goog-style-todo]: https://google.github.io/styleguide/cppguide.html#TODO_Comments + +### Deprecation + +Annotate the declarations of deprecated functions and classes with the +[`[[deprecated]]` attribute][DEPRECATED] to cause an error when they're used +inside WebRTC and a compiler warning when they're used by dependant projects. +Like so: + +```cpp +[[deprecated("bugs.webrtc.org/12345")]] +std::pony PonyPlz(const std::pony_spec& ps); +``` + +NOTE 1: The annotation goes on the declaration in the `.h` file, not the +definition in the `.cc` file! + +NOTE 2: In order to have unit tests that use the deprecated function without +getting errors, do something like this: + +```cpp +std::pony DEPRECATED_PonyPlz(const std::pony_spec& ps); +[[deprecated("bugs.webrtc.org/12345")]] +inline std::pony PonyPlz(const std::pony_spec& ps) { + return DEPRECATED_PonyPlz(ps); +} +``` + +In other words, rename the existing function, and provide an inline wrapper +using the original name that calls it. That way, callers who are willing to +call it using the `DEPRECATED_`-prefixed name don't get the warning. + +NOTE 3: Occasionally, with long descriptions, `git cl format` will do the wrong +thing with the attribute. In that case, you can use the +[`ABSL_DEPRECATED` macro][ABSL_DEPRECATED], which is formatted in a more +readable way. + +[DEPRECATED]: https://en.cppreference.com/w/cpp/language/attributes/deprecated +[ABSL_DEPRECATED]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/abseil-cpp/absl/base/attributes.h?q=ABSL_DEPRECATED + +### ArrayView + +When passing an array of values to a function, use `rtc::ArrayView` +whenever possible—that is, whenever you're not passing ownership of +the array, and don't allow the callee to change the array size. + +For example, + +| instead of | use | +|-------------------------------------|----------------------| +| `const std::vector&` | `ArrayView` | +| `const T* ptr, size_t num_elements` | `ArrayView` | +| `T* ptr, size_t num_elements` | `ArrayView` | + +See the [source code for `rtc::ArrayView`](api/array_view.h) for more detailed +docs. + +### Strings + +WebRTC uses std::string, with content assumed to be UTF-8. Note that this +has to be verified whenever accepting external input. + +For concatenation of strings, use rtc::SimpleStringBuilder. + +The following string building tools are NOT recommended: +* The + operator. See https://abseil.io/tips/3 for why not. +* absl::StrCat, absl::StrAppend, absl::StrJoin. These are optimized for + speed, not code size, and have significant code size overhead. +* strcat. It is too easy to create buffer overflows. + +### sigslot + +SIGSLOT IS DEPRECATED. + +Prefer `webrtc::CallbackList`, and manage thread safety yourself. + +### Smart pointers + +The following smart pointer types are recommended: + + * `std::unique_ptr` for all singly-owned objects + * `rtc::scoped_refptr` for all objects with shared ownership + +Use of `std::shared_ptr` is *not permitted*. It is banned in the Chromium style +guide (overriding the Google style guide). See the +[list of banned C++ library features in Chromium][chr-std-shared-ptr] for more +information. + +In most cases, one will want to explicitly control lifetimes, and therefore use +`std::unique_ptr`, but in some cases, for instance where references have to +exist both from the API users and internally, with no way to invalidate pointers +held by the API user, `rtc::scoped_refptr` can be appropriate. + +[chr-std-shared-ptr]: https://chromium.googlesource.com/chromium/src/+/main/styleguide/c++/c++-features.md#shared-pointers-banned + +### `std::bind` + +Don't use `std::bind`—there are pitfalls, and lambdas are almost as succinct and +already familiar to modern C++ programmers. + +### `std::function` + +`std::function` is allowed, but remember that it's not the right tool for every +occasion. Prefer to use interfaces when that makes sense, and consider +`rtc::FunctionView` for cases where the callee will not save the function +object. + +### Forward declarations + +WebRTC follows the +[Google C++ style guide on forward declarations][goog-forward-declarations]. +In summary: avoid using forward declarations where possible; just `#include` the +headers you need. + +[goog-forward-declarations]: https://google.github.io/styleguide/cppguide.html#Forward_Declarations + +### RTTI and dynamic_cast + +The Google style guide [permits the use of dynamic_cast](https://google.github.io/styleguide/cppguide.html#Run-Time_Type_Information__RTTI_). + +However, WebRTC does not permit it. WebRTC (and Chrome) is compiled with the +-fno-rtti flag, and the overhead of enabling RTTI it is on the order of 220 +Kbytes (for Android Arm64). + +Use static_cast and take your own steps to ensure type safety. + +## C + +There's a substantial chunk of legacy C code in WebRTC, and a lot of it is old +enough that it violates the parts of the C++ style guide that also applies to C +(naming etc.) for the simple reason that it pre-dates the use of the current C++ +style guide for this code base. If making large changes to C code, consider +converting the whole thing to C++ first. + +## Java + +WebRTC follows the [Google Java style guide][goog-java-style]. + +[goog-java-style]: https://google.github.io/styleguide/javaguide.html + +## Objective-C and Objective-C++ + +WebRTC follows the +[Chromium Objective-C and Objective-C++ style guide][chr-objc-style]. + +[chr-objc-style]: https://chromium.googlesource.com/chromium/src/+/main/styleguide/objective-c/objective-c.md + +## Python + +WebRTC follows [Chromium's Python style][chr-py-style]. + +[chr-py-style]: https://chromium.googlesource.com/chromium/src/+/main/styleguide/python/python.md + +## Build files + +The WebRTC build files are written in [GN][gn], and we follow the +[GN style guide][gn-style]. Additionally, there are some +WebRTC-specific rules below; in case of conflict, they trump the Chromium style +guide. + +[gn]: https://gn.googlesource.com/gn/ +[gn-style]: https://gn.googlesource.com/gn/+/HEAD/docs/style_guide.md + +### WebRTC-specific GN templates + +As shown in the table below, for library targets (`source_set` and +`static_library`), you should default on using `rtc_library` (which abstracts +away the complexity of using the correct target type for Chromium component +builds). + +The general rule is for library targets is: +1. Use `rtc_library`. +2. If the library is a header only target use `rtc_source_set`. +3. If you really need to generate a static library, use `rtc_static_library` + (same for shared libraries, in such case use `rtc_shared_library`). + +To ensure that all our [GN targets][gn-target] are built with the same +configuration, only use the following [GN templates][gn-templ]. + +| instead of | use | +|------------------|-----------------------------------------------------------------------------------------| +| `executable` | `rtc_executable` | +| `shared_library` | `rtc_shared_library` | +| `source_set` | `rtc_source_set` (only for header only libraries, for everything else use `rtc_library` | +| `static_library` | `rtc_static_library` (use `rtc_library` unless you really need `rtc_static_library` | +| `test` | `rtc_test` | + + +[gn-templ]: https://gn.googlesource.com/gn/+/HEAD/docs/language.md#Templates +[gn-target]: https://gn.googlesource.com/gn/+/HEAD/docs/language.md#Targets + +### Target visibility and the native API + +The [WebRTC-specific GN templates](#webrtc-gn-templates) declare build targets +whose default `visibility` allows all other targets in the WebRTC tree (and no +targets outside the tree) to depend on them. + +Prefer to restrict the `visibility` if possible: + +* If a target is used by only one or a tiny number of other targets, prefer to + list them explicitly: `visibility = [ ":foo", ":bar" ]` +* If a target is used only by targets in the same `BUILD.gn` file: + `visibility = [ ":*" ]`. + +Setting `visibility = [ "*" ]` means that targets outside the WebRTC tree can +depend on this target; use this only for build targets whose headers are part of +the [native WebRTC API](native-api.md). + +### Conditional compilation with the C preprocessor + +Avoid using the C preprocessor to conditionally enable or disable pieces of +code. But if you can't avoid it, introduce a GN variable, and then set a +preprocessor constant to either 0 or 1 in the build targets that need it: + +```gn +if (apm_debug_dump) { + defines = [ "WEBRTC_APM_DEBUG_DUMP=1" ] +} else { + defines = [ "WEBRTC_APM_DEBUG_DUMP=0" ] +} +``` + +In the C, C++, or Objective-C files, use `#if` when testing the flag, +not `#ifdef` or `#if defined()`: + +```c +#if WEBRTC_APM_DEBUG_DUMP +// One way. +#else +// Or another. +#endif +``` + +When combined with the `-Wundef` compiler option, this produces compile time +warnings if preprocessor symbols are misspelled, or used without corresponding +build rules to set them. diff --git a/third_party/libwebrtc/g3doc/style-guide/OWNERS b/third_party/libwebrtc/g3doc/style-guide/OWNERS new file mode 100644 index 0000000000..a3ecbc9948 --- /dev/null +++ b/third_party/libwebrtc/g3doc/style-guide/OWNERS @@ -0,0 +1 @@ +danilchap@webrtc.org diff --git a/third_party/libwebrtc/g3doc/style-guide/h-cc-pairs.md b/third_party/libwebrtc/g3doc/style-guide/h-cc-pairs.md new file mode 100644 index 0000000000..08eed85c23 --- /dev/null +++ b/third_party/libwebrtc/g3doc/style-guide/h-cc-pairs.md @@ -0,0 +1,32 @@ + + + +# `.h` and `.cc` files come in pairs + +This is an overflow page for [this](/g3doc/style-guide.md#h-cc-pairs) +style rule. + +## Example violations + +Example violations, which should be avoided in new code: + +* Declarations in `path/to/include/foo.h`, definitions in + `path/to/source/foo.cc`. **Fix:** The `.h` and `.cc` files should be + in the same directory. +* Declarations in `foo.h`, definitions in both `foo_bar.cc` and + `foo_baz.cc`. **Fix:** The `.h` and `.cc` files should come in + pairs, so either split `foo.h` into `foo_bar.h` and `foo_baz.h`, or + merge `foo_bar.cc` and `foo_baz.cc` into `foo.cc`. + +## Exception for platform-specific code + +If the functions in a header file need different implementations for +different platforms, we allow the following arrangement: + +* Declarations in `foo.h`. +* A complete set of matching definitions in `foo_win.cc`, another + complete set of matching definitions in `foo_mac.cc`, and so on. +* As per the main rule, these files should all be in the same + directory and in the same build target. The build target should use + platform conditionals to ensure that exactly one of the `.cc` files + are included. diff --git a/third_party/libwebrtc/g3doc/supported-platforms-and-compilers.md b/third_party/libwebrtc/g3doc/supported-platforms-and-compilers.md new file mode 100644 index 0000000000..4e65767499 --- /dev/null +++ b/third_party/libwebrtc/g3doc/supported-platforms-and-compilers.md @@ -0,0 +1,34 @@ + + + +# WebRTC supported plaftorms and compilers + +## Operating systems and CPUs + +The list of officially supported operating systems and CPUs is: + +* Android: armeabi-v7a, arm64-v8a, x86, x86_64. +* iOS: arm64, x86_64. +* Linux: armeabi-v7a, arm64-v8a, x86, x86_64. +* macOS: x86_64, arm64 (M1). +* Windows: x86_64. + +Other platforms are not officially supported (which means there is no CI +coverage for them) but patches to keep WebRTC working with them are welcomed by +the WebRTC Team. + +## Compilers + +WebRTC officially supports clang on all the supported platforms. The clang +version officially supported is the one used by Chromium (hence the version is +really close to Tip of Tree and can be checked +[here](https://source.chromium.org/chromium/chromium/src/+/main:tools/clang/scripts/update.py) +by looking at the value of `CLANG_REVISION`). + +See also +[here](https://source.chromium.org/chromium/chromium/src/+/main:docs/clang.md) +for some clang related documentation from Chromium. + +Other compilers are not officially supported (which means there is no CI +coverage for them) but patches to keep WebRTC working with them are welcomed by +the WebRTC Team. -- cgit v1.2.3