Copyright (c) 2012 - present, Victor Zverovich

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

--- Optional exception to the license ---

As an exception, if, as a result of your compiling your source code, portions
of this Software are embedded into a machine-executable object form of such
source code, you may redistribute such embedded portions in such object form
without including the above copyright and permission notices.

Perforator is a cluster-wide continuous profiling tool designed for large data centers


{fmt}
=====

.. image:: https://github.com/fmtlib/fmt/workflows/linux/badge.svg
   :target: https://github.com/fmtlib/fmt/actions?query=workflow%3Alinux

.. image:: https://github.com/fmtlib/fmt/workflows/macos/badge.svg
   :target: https://github.com/fmtlib/fmt/actions?query=workflow%3Amacos

.. image:: https://github.com/fmtlib/fmt/workflows/windows/badge.svg
   :target: https://github.com/fmtlib/fmt/actions?query=workflow%3Awindows

.. image:: https://ci.appveyor.com/api/projects/status/ehjkiefde6gucy1v?svg=true
   :target: https://ci.appveyor.com/project/vitaut/fmt

.. image:: https://oss-fuzz-build-logs.storage.googleapis.com/badges/fmt.svg
   :alt: fmt is continuously fuzzed at oss-fuzz
   :target: https://bugs.chromium.org/p/oss-fuzz/issues/list?\
            colspec=ID%20Type%20Component%20Status%20Proj%20Reported%20Owner%20\
            Summary&q=proj%3Dfmt&can=1

.. image:: https://img.shields.io/badge/stackoverflow-fmt-blue.svg
   :alt: Ask questions at StackOverflow with the tag fmt
   :target: https://stackoverflow.com/questions/tagged/fmt

**{fmt}** is an open-source formatting library providing a fast and safe
alternative to C stdio and C++ iostreams.

If you like this project, please consider donating to the BYSOL
Foundation that helps victims of political repressions in Belarus:
https://bysol.org/en/bs/general/.

`Documentation <https://fmt.dev>`__

Q&A: ask questions on `StackOverflow with the tag fmt
<https://stackoverflow.com/questions/tagged/fmt>`_.

Try {fmt} in `Compiler Explorer <https://godbolt.org/z/Eq5763>`_.

Features
--------

* Simple `format API <https://fmt.dev/latest/api.html>`_ with positional arguments
  for localization
* Implementation of `C++20 std::format
  <https://en.cppreference.com/w/cpp/utility/format>`__
* `Format string syntax <https://fmt.dev/latest/syntax.html>`_ similar to Python's
  `format <https://docs.python.org/3/library/stdtypes.html#str.format>`_
* Fast IEEE 754 floating-point formatter with correct rounding, shortness and
  round-trip guarantees
* Safe `printf implementation
  <https://fmt.dev/latest/api.html#printf-formatting>`_ including the POSIX
  extension for positional arguments
* Extensibility: `support for user-defined types
  <https://fmt.dev/latest/api.html#formatting-user-defined-types>`_
* High performance: faster than common standard library implementations of
  ``(s)printf``, iostreams, ``to_string`` and ``to_chars``, see `Speed tests`_
  and `Converting a hundred million integers to strings per second
  <http://www.zverovich.net/2020/06/13/fast-int-to-string-revisited.html>`_
* Small code size both in terms of source code with the minimum configuration
  consisting of just three files, ``core.h``, ``format.h`` and ``format-inl.h``,
  and compiled code; see `Compile time and code bloat`_
* Reliability: the library has an extensive set of `tests
  <https://github.com/fmtlib/fmt/tree/master/test>`_ and is `continuously fuzzed
  <https://bugs.chromium.org/p/oss-fuzz/issues/list?colspec=ID%20Type%20
  Component%20Status%20Proj%20Reported%20Owner%20Summary&q=proj%3Dfmt&can=1>`_
* Safety: the library is fully type safe, errors in format strings can be
  reported at compile time, automatic memory management prevents buffer overflow
  errors
* Ease of use: small self-contained code base, no external dependencies,
  permissive MIT `license
  <https://github.com/fmtlib/fmt/blob/master/LICENSE.rst>`_
* `Portability <https://fmt.dev/latest/index.html#portability>`_ with
  consistent output across platforms and support for older compilers
* Clean warning-free codebase even on high warning levels such as
  ``-Wall -Wextra -pedantic``
* Locale-independence by default
* Optional header-only configuration enabled with the ``FMT_HEADER_ONLY`` macro

See the `documentation <https://fmt.dev>`_ for more details.

Examples
--------

**Print to stdout** (`run <https://godbolt.org/z/Tevcjh>`_)

.. code:: c++

    #include <fmt/core.h>

    int main() {
      fmt::print("Hello, world!\n");
    }

**Format a string** (`run <https://godbolt.org/z/oK8h33>`_)

.. code:: c++

    std::string s = fmt::format("The answer is {}.", 42);
    // s == "The answer is 42."

**Format a string using positional arguments** (`run <https://godbolt.org/z/Yn7Txe>`_)

.. code:: c++

    std::string s = fmt::format("I'd rather be {1} than {0}.", "right", "happy");
    // s == "I'd rather be happy than right."

**Print chrono durations** (`run <https://godbolt.org/z/K8s4Mc>`_)

.. code:: c++

    #include <fmt/chrono.h>

    int main() {
      using namespace std::literals::chrono_literals;
      fmt::print("Default format: {} {}\n", 42s, 100ms);
      fmt::print("strftime-like format: {:%H:%M:%S}\n", 3h + 15min + 30s);
    }

Output::

    Default format: 42s 100ms
    strftime-like format: 03:15:30

**Print a container** (`run <https://godbolt.org/z/MjsY7c>`_)

.. code:: c++

    #include <vector>
    #include <fmt/ranges.h>

    int main() {
      std::vector<int> v = {1, 2, 3};
      fmt::print("{}\n", v);
    }

Output::

    [1, 2, 3]

**Check a format string at compile time**

.. code:: c++

    std::string s = fmt::format("{:d}", "I am not a number");

This gives a compile-time error in C++20 because ``d`` is an invalid format
specifier for a string.

**Write a file from a single thread**

.. code:: c++

    #include <fmt/os.h>

    int main() {
      auto out = fmt::output_file("guide.txt");
      out.print("Don't {}", "Panic");
    }

This can be `5 to 9 times faster than fprintf
<http://www.zverovich.net/2020/08/04/optimal-file-buffer-size.html>`_.

**Print with colors and text styles**

.. code:: c++

    #include <fmt/color.h>

    int main() {
      fmt::print(fg(fmt::color::crimson) | fmt::emphasis::bold,
                 "Hello, {}!\n", "world");
      fmt::print(fg(fmt::color::floral_white) | bg(fmt::color::slate_gray) |
                 fmt::emphasis::underline, "Hello, {}!\n", "мир");
      fmt::print(fg(fmt::color::steel_blue) | fmt::emphasis::italic,
                 "Hello, {}!\n", "世界");
    }

Output on a modern terminal:

.. image:: https://user-images.githubusercontent.com/
           576385/88485597-d312f600-cf2b-11ea-9cbe-61f535a86e28.png

Benchmarks
----------

Speed tests
~~~~~~~~~~~

================= ============= ===========
Library           Method        Run Time, s
================= ============= ===========
libc              printf          1.04
libc++            std::ostream    3.05
{fmt} 6.1.1       fmt::print      0.75
Boost Format 1.67 boost::format   7.24
Folly Format      folly::format   2.23
================= ============= ===========

{fmt} is the fastest of the benchmarked methods, ~35% faster than ``printf``.

The above results were generated by building ``tinyformat_test.cpp`` on macOS
10.14.6 with ``clang++ -O3 -DNDEBUG -DSPEED_TEST -DHAVE_FORMAT``, and taking the
best of three runs. In the test, the format string ``"%0.10f:%04d:%+g:%s:%p:%c:%%\n"``
or equivalent is filled 2,000,000 times with output sent to ``/dev/null``; for
further details refer to the `source
<https://github.com/fmtlib/format-benchmark/blob/master/src/tinyformat-test.cc>`_.

{fmt} is up to 20-30x faster than ``std::ostringstream`` and ``sprintf`` on
floating-point formatting (`dtoa-benchmark <https://github.com/fmtlib/dtoa-benchmark>`_)
and faster than `double-conversion <https://github.com/google/double-conversion>`_ and
`ryu <https://github.com/ulfjack/ryu>`_:

.. image:: https://user-images.githubusercontent.com/576385/
           95684665-11719600-0ba8-11eb-8e5b-972ff4e49428.png
   :target: https://fmt.dev/unknown_mac64_clang12.0.html

Compile time and code bloat
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The script `bloat-test.py
<https://github.com/fmtlib/format-benchmark/blob/master/bloat-test.py>`_
from `format-benchmark <https://github.com/fmtlib/format-benchmark>`_
tests compile time and code bloat for nontrivial projects.
It generates 100 translation units and uses ``printf()`` or its alternative
five times in each to simulate a medium sized project.  The resulting
executable size and compile time (Apple LLVM version 8.1.0 (clang-802.0.42),
macOS Sierra, best of three) is shown in the following tables.

**Optimized build (-O3)**

============= =============== ==================== ==================
Method        Compile Time, s Executable size, KiB Stripped size, KiB
============= =============== ==================== ==================
printf                    2.6                   29                 26
printf+string            16.4                   29                 26
iostreams                31.1                   59                 55
{fmt}                    19.0                   37                 34
Boost Format             91.9                  226                203
Folly Format            115.7                  101                 88
============= =============== ==================== ==================

As you can see, {fmt} has 60% less overhead in terms of resulting binary code
size compared to iostreams and comes pretty close to ``printf``. Boost Format
and Folly Format have the largest overheads.

``printf+string`` is the same as ``printf`` but with extra ``<string>``
include to measure the overhead of the latter.

**Non-optimized build**

============= =============== ==================== ==================
Method        Compile Time, s Executable size, KiB Stripped size, KiB
============= =============== ==================== ==================
printf                    2.2                   33                 30
printf+string            16.0                   33                 30
iostreams                28.3                   56                 52
{fmt}                    18.2                   59                 50
Boost Format             54.1                  365                303
Folly Format             79.9                  445                430
============= =============== ==================== ==================

``libc``, ``lib(std)c++`` and ``libfmt`` are all linked as shared libraries to
compare formatting function overhead only. Boost Format is a
header-only library so it doesn't provide any linkage options.

Running the tests
~~~~~~~~~~~~~~~~~

Please refer to `Building the library`__ for the instructions on how to build
the library and run the unit tests.

__ https://fmt.dev/latest/usage.html#building-the-library

Benchmarks reside in a separate repository,
`format-benchmarks <https://github.com/fmtlib/format-benchmark>`_,
so to run the benchmarks you first need to clone this repository and
generate Makefiles with CMake::

    $ git clone --recursive https://github.com/fmtlib/format-benchmark.git
    $ cd format-benchmark
    $ cmake .

Then you can run the speed test::

    $ make speed-test

or the bloat test::

    $ make bloat-test

Migrating code
--------------

`clang-tidy-fmt <https://github.com/mikecrowe/clang-tidy-fmt>`_ provides clang
tidy checks for converting occurrences of ``printf`` and ``fprintf`` to
``fmt::print``.

Projects using this library
---------------------------

* `0 A.D. <https://play0ad.com/>`_: a free, open-source, cross-platform
  real-time strategy game

* `2GIS <https://2gis.ru/>`_: free business listings with a city map

* `AMPL/MP <https://github.com/ampl/mp>`_:
  an open-source library for mathematical programming

* `Aseprite <https://github.com/aseprite/aseprite>`_:
  animated sprite editor & pixel art tool

* `AvioBook <https://www.aviobook.aero/en>`_: a comprehensive aircraft
  operations suite

* `Blizzard Battle.net <https://battle.net/>`_: an online gaming platform

* `Celestia <https://celestia.space/>`_: real-time 3D visualization of space

* `Ceph <https://ceph.com/>`_: a scalable distributed storage system

* `ccache <https://ccache.dev/>`_: a compiler cache

* `ClickHouse <https://github.com/ClickHouse/ClickHouse>`_: analytical database
  management system

* `CUAUV <https://cuauv.org/>`_: Cornell University's autonomous underwater
  vehicle

* `Drake <https://drake.mit.edu/>`_: a planning, control, and analysis toolbox
  for nonlinear dynamical systems (MIT)

* `Envoy <https://lyft.github.io/envoy/>`_: C++ L7 proxy and communication bus
  (Lyft)

* `FiveM <https://fivem.net/>`_: a modification framework for GTA V

* `fmtlog <https://github.com/MengRao/fmtlog>`_: a performant fmtlib-style
  logging library with latency in nanoseconds

* `Folly <https://github.com/facebook/folly>`_: Facebook open-source library

* `Grand Mountain Adventure
  <https://store.steampowered.com/app/1247360/Grand_Mountain_Adventure/>`_:
  A beautiful open-world ski & snowboarding game

* `HarpyWar/pvpgn <https://github.com/pvpgn/pvpgn-server>`_:
  Player vs Player Gaming Network with tweaks

* `KBEngine <https://github.com/kbengine/kbengine>`_: an open-source MMOG server
  engine

* `Keypirinha <https://keypirinha.com/>`_: a semantic launcher for Windows

* `Kodi <https://kodi.tv/>`_ (formerly xbmc): home theater software

* `Knuth <https://kth.cash/>`_: high-performance Bitcoin full-node

* `Microsoft Verona <https://github.com/microsoft/verona>`_:
  research programming language for concurrent ownership

* `MongoDB <https://mongodb.com/>`_: distributed document database

* `MongoDB Smasher <https://github.com/duckie/mongo_smasher>`_: a small tool to
  generate randomized datasets

* `OpenSpace <https://openspaceproject.com/>`_: an open-source
  astrovisualization framework

* `PenUltima Online (POL) <https://www.polserver.com/>`_:
  an MMO server, compatible with most Ultima Online clients

* `PyTorch <https://github.com/pytorch/pytorch>`_: an open-source machine
  learning library

* `quasardb <https://www.quasardb.net/>`_: a distributed, high-performance,
  associative database

* `Quill <https://github.com/odygrd/quill>`_: asynchronous low-latency logging library

* `QKW <https://github.com/ravijanjam/qkw>`_: generalizing aliasing to simplify
  navigation, and executing complex multi-line terminal command sequences

* `redis-cerberus <https://github.com/HunanTV/redis-cerberus>`_: a Redis cluster
  proxy

* `redpanda <https://vectorized.io/redpanda>`_: a 10x faster Kafka® replacement
  for mission critical systems written in C++

* `rpclib <http://rpclib.net/>`_: a modern C++ msgpack-RPC server and client
  library

* `Salesforce Analytics Cloud
  <https://www.salesforce.com/analytics-cloud/overview/>`_:
  business intelligence software

* `Scylla <https://www.scylladb.com/>`_: a Cassandra-compatible NoSQL data store
  that can handle 1 million transactions per second on a single server

* `Seastar <http://www.seastar-project.org/>`_: an advanced, open-source C++
  framework for high-performance server applications on modern hardware

* `spdlog <https://github.com/gabime/spdlog>`_: super fast C++ logging library

* `Stellar <https://www.stellar.org/>`_: financial platform

* `Touch Surgery <https://www.touchsurgery.com/>`_: surgery simulator

* `TrinityCore <https://github.com/TrinityCore/TrinityCore>`_: open-source
  MMORPG framework

* `Windows Terminal <https://github.com/microsoft/terminal>`_: the new Windows
  terminal

`More... <https://github.com/search?q=fmtlib&type=Code>`_

If you are aware of other projects using this library, please let me know
by `email <mailto:victor.zverovich@gmail.com>`_ or by submitting an
`issue <https://github.com/fmtlib/fmt/issues>`_.

Motivation
----------

So why yet another formatting library?

There are plenty of methods for doing this task, from standard ones like
the printf family of function and iostreams to Boost Format and FastFormat
libraries. The reason for creating a new library is that every existing
solution that I found either had serious issues or didn't provide
all the features I needed.

printf
~~~~~~

The good thing about ``printf`` is that it is pretty fast and readily available
being a part of the C standard library. The main drawback is that it
doesn't support user-defined types. ``printf`` also has safety issues although
they are somewhat mitigated with `__attribute__ ((format (printf, ...))
<https://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ in GCC.
There is a POSIX extension that adds positional arguments required for
`i18n <https://en.wikipedia.org/wiki/Internationalization_and_localization>`_
to ``printf`` but it is not a part of C99 and may not be available on some
platforms.

iostreams
~~~~~~~~~

The main issue with iostreams is best illustrated with an example:

.. code:: c++

    std::cout << std::setprecision(2) << std::fixed << 1.23456 << "\n";

which is a lot of typing compared to printf:

.. code:: c++

    printf("%.2f\n", 1.23456);

Matthew Wilson, the author of FastFormat, called this "chevron hell". iostreams
don't support positional arguments by design.

The good part is that iostreams support user-defined types and are safe although
error handling is awkward.

Boost Format
~~~~~~~~~~~~

This is a very powerful library which supports both ``printf``-like format
strings and positional arguments. Its main drawback is performance. According to
various benchmarks, it is much slower than other methods considered here. Boost
Format also has excessive build times and severe code bloat issues (see
`Benchmarks`_).

FastFormat
~~~~~~~~~~

This is an interesting library which is fast, safe and has positional arguments.
However, it has significant limitations, citing its author:

    Three features that have no hope of being accommodated within the
    current design are:

    * Leading zeros (or any other non-space padding)
    * Octal/hexadecimal encoding
    * Runtime width/alignment specification

It is also quite big and has a heavy dependency, STLSoft, which might be too
restrictive for using it in some projects.

Boost Spirit.Karma
~~~~~~~~~~~~~~~~~~

This is not really a formatting library but I decided to include it here for
completeness. As iostreams, it suffers from the problem of mixing verbatim text
with arguments. The library is pretty fast, but slower on integer formatting
than ``fmt::format_to`` with format string compilation on Karma's own benchmark,
see `Converting a hundred million integers to strings per second
<http://www.zverovich.net/2020/06/13/fast-int-to-string-revisited.html>`_.

License
-------

{fmt} is distributed under the MIT `license
<https://github.com/fmtlib/fmt/blob/master/LICENSE.rst>`_.

Documentation License
---------------------

The `Format String Syntax <https://fmt.dev/latest/syntax.html>`_
section in the documentation is based on the one from Python `string module
documentation <https://docs.python.org/3/library/string.html#module-string>`_.
For this reason the documentation is distributed under the Python Software
Foundation license available in `doc/python-license.txt
<https://raw.github.com/fmtlib/fmt/master/doc/python-license.txt>`_.
It only applies if you distribute the documentation of {fmt}.

Maintainers
-----------

The {fmt} library is maintained by Victor Zverovich (`vitaut
<https://github.com/vitaut>`_) and Jonathan Müller (`foonathan
<https://github.com/foonathan>`_) with contributions from many other people.
See `Contributors <https://github.com/fmtlib/fmt/graphs/contributors>`_ and
`Releases <https://github.com/fmtlib/fmt/releases>`_ for some of the names.
Let us know if your contribution is not listed or mentioned incorrectly and
we'll make it right.


# Changelog

## [1.66.0](https://github.com/googleapis/python-api-common-protos/compare/v1.65.0...v1.66.0) (2024-11-12)

### Features

* Add `MISSING_ORIGIN` and `OVERLOADED_CREDENTIALS` to `ErrorReason` enum ([d0478d8](https://github.com/googleapis/python-api-common-protos/commit/d0478d8beacb6c53aa29aa0ac14b949421de8112))
* Add field `protobuf_pythonic_types_enabled` to `ExperimentalFeatures` message ([d0478d8](https://github.com/googleapis/python-api-common-protos/commit/d0478d8beacb6c53aa29aa0ac14b949421de8112))
* Add field `selective_gapic_generation` to `CommonLanguageSettings` message ([d0478d8](https://github.com/googleapis/python-api-common-protos/commit/d0478d8beacb6c53aa29aa0ac14b949421de8112))
* Add field `time_series_resource_hierarchy_level` to `MetricDescriptorMetadata` message ([d0478d8](https://github.com/googleapis/python-api-common-protos/commit/d0478d8beacb6c53aa29aa0ac14b949421de8112))
* Add message `SelectiveGapicGeneration` ([d0478d8](https://github.com/googleapis/python-api-common-protos/commit/d0478d8beacb6c53aa29aa0ac14b949421de8112))

## [1.65.0](https://github.com/googleapis/python-api-common-protos/compare/v1.64.0...v1.65.0) (2024-08-27)

### Features

* Add field `experimental_features` to message `PythonSettings` ([#249](https://github.com/googleapis/python-api-common-protos/issues/249)) ([139490f](https://github.com/googleapis/python-api-common-protos/commit/139490fedcebf1a6674d9cf058226e6814208619))

## [1.64.0](https://github.com/googleapis/python-api-common-protos/compare/v1.63.2...v1.64.0) (2024-08-26)

### Features

* Add FieldInfo.referenced_types for generics ([2ba3577](https://github.com/googleapis/python-api-common-protos/commit/2ba35774cb6ea31513b1985e3a391c5c3435e7be))

### Bug Fixes

* Un-deprecate Endpoint.aliases field ([2ba3577](https://github.com/googleapis/python-api-common-protos/commit/2ba35774cb6ea31513b1985e3a391c5c3435e7be))

### Documentation

* Fix formatting in http.proto comments ([2ba3577](https://github.com/googleapis/python-api-common-protos/commit/2ba35774cb6ea31513b1985e3a391c5c3435e7be))
* Improve MethodSettings selector examples ([2ba3577](https://github.com/googleapis/python-api-common-protos/commit/2ba35774cb6ea31513b1985e3a391c5c3435e7be))
* Reformat comments in context proto ([2ba3577](https://github.com/googleapis/python-api-common-protos/commit/2ba35774cb6ea31513b1985e3a391c5c3435e7be))
* Update ResourceDescriptor.plural docs with AIP-122 nested collections guidance ([2ba3577](https://github.com/googleapis/python-api-common-protos/commit/2ba35774cb6ea31513b1985e3a391c5c3435e7be))

## [1.63.2](https://github.com/googleapis/python-api-common-protos/compare/v1.63.1...v1.63.2) (2024-06-19)

### Bug Fixes

* **deps:** Require protobuf>=3.20.2 ([c77c0dc](https://github.com/googleapis/python-api-common-protos/commit/c77c0dc5d29ef780d781a3c5d757736a9ed09674))
* Regenerate pb2 files for compatibility with protobuf 5.x ([c77c0dc](https://github.com/googleapis/python-api-common-protos/commit/c77c0dc5d29ef780d781a3c5d757736a9ed09674))

## [1.63.1](https://github.com/googleapis/python-api-common-protos/compare/v1.63.0...v1.63.1) (2024-05-30)

### Bug Fixes

* Increase upper limit for protobuf 5.X versions ([#212](https://github.com/googleapis/python-api-common-protos/issues/212)) ([28fc17a](https://github.com/googleapis/python-api-common-protos/commit/28fc17a9208aa98782acc6bee6c40ec12b959706))

## [1.63.0](https://github.com/googleapis/python-api-common-protos/compare/v1.62.0...v1.63.0) (2024-03-08)

### Features

* Add `api_version` field to `ServiceOptions` in `google/api/client.proto` ([6f9c4d2](https://github.com/googleapis/python-api-common-protos/commit/6f9c4d2b4b787d9ed2b447d7b99281aa3dcf97b5))
* Add `LOCATION_POLICY_VIOLATED` enum to `ErrorReason` in `google/api/error_reason.proto` ([6f9c4d2](https://github.com/googleapis/python-api-common-protos/commit/6f9c4d2b4b787d9ed2b447d7b99281aa3dcf97b5))
* Add `rest_reference_documentation_uri` field to `ServiceOptions` in `google/api/client.proto` ([6f9c4d2](https://github.com/googleapis/python-api-common-protos/commit/6f9c4d2b4b787d9ed2b447d7b99281aa3dcf97b5))

## [1.62.0](https://github.com/googleapis/python-api-common-protos/compare/v1.61.0...v1.62.0) (2023-12-01)

### Features

* Add `auto_populated_fields` field of `MethodSettings` in `google/api/client_pb2` ([#194](https://github.com/googleapis/python-api-common-protos/issues/194)) ([4b0c73a](https://github.com/googleapis/python-api-common-protos/commit/4b0c73a40f9bf5337fe451c0210f73eadd196b99))
* Add support for Python 3.12 ([#192](https://github.com/googleapis/python-api-common-protos/issues/192)) ([336cdf3](https://github.com/googleapis/python-api-common-protos/commit/336cdf351d4e87891d735837817d2cfc4e5a9fc7))

### Bug Fixes

* Migrate to native namespace packages ([#187](https://github.com/googleapis/python-api-common-protos/issues/187)) ([713e388](https://github.com/googleapis/python-api-common-protos/commit/713e3887a3293aea314060e84bdcf8a12eda3d6c))

## [1.61.0](https://github.com/googleapis/python-api-common-protos/compare/v1.60.0...v1.61.0) (2023-10-09)

### Features

* Add `google/api/field_info.proto` ([2d39f37](https://github.com/googleapis/python-api-common-protos/commit/2d39f37212fe886b3029e1043ca28789e2d66876))
* Add `IDENTIFIER` to `FieldBehavior` enum ([2d39f37](https://github.com/googleapis/python-api-common-protos/commit/2d39f37212fe886b3029e1043ca28789e2d66876))

## [1.60.0](https://github.com/googleapis/python-api-common-protos/compare/v1.59.1...v1.60.0) (2023-07-27)

### Features

* Add `google/api/policy.proto` ([b2cb5c2](https://github.com/googleapis/python-api-common-protos/commit/b2cb5c257ae8d0869d33581b116995620ddae0b2))
* Add `method_policies` to `Control` ([b2cb5c2](https://github.com/googleapis/python-api-common-protos/commit/b2cb5c257ae8d0869d33581b116995620ddae0b2))

## [1.59.1](https://github.com/googleapis/python-api-common-protos/compare/v1.59.0...v1.59.1) (2023-06-06)

### Bug Fixes

* Invalid `dev` version identifiers in `setup.py` ([#166](https://github.com/googleapis/python-api-common-protos/issues/166)) ([c38e03a](https://github.com/googleapis/python-api-common-protos/commit/c38e03aa06eedf65373c283f16e7bbbd5622f37b)), closes [#165](https://github.com/googleapis/python-api-common-protos/issues/165)

## [1.59.0](https://github.com/googleapis/python-api-common-protos/compare/v1.58.0...v1.59.0) (2023-03-20)

### Features

* Add overrides_by_request_protocol to BackendRule in google/api/backend.proto ([77376dd](https://github.com/googleapis/python-api-common-protos/commit/77376dd02af0a1c9255a50516550d2474536fa9d))
* Add proto_reference_documentation_uri to Publishing in google/api/client.proto ([77376dd](https://github.com/googleapis/python-api-common-protos/commit/77376dd02af0a1c9255a50516550d2474536fa9d))
* Add SERVICE_NOT_VISIBLE and GCP_SUSPENDED to ErrorReason in google/api/error_reason.proto ([77376dd](https://github.com/googleapis/python-api-common-protos/commit/77376dd02af0a1c9255a50516550d2474536fa9d))

### Documentation

* Use rst syntax in readme  ([77376dd](https://github.com/googleapis/python-api-common-protos/commit/77376dd02af0a1c9255a50516550d2474536fa9d))

## [1.58.0](https://github.com/googleapis/python-api-common-protos/compare/v1.57.1...v1.58.0) (2023-01-06)

### Features

* Add google/rpc/context/audit_context.proto ([41f1529](https://github.com/googleapis/python-api-common-protos/commit/41f1529500e535ec83e2d72f8e97dfda5469cb72))
* Add google/rpc/http.proto ([41f1529](https://github.com/googleapis/python-api-common-protos/commit/41f1529500e535ec83e2d72f8e97dfda5469cb72))

## [1.57.1](https://github.com/googleapis/python-api-common-protos/compare/v1.57.0...v1.57.1) (2022-12-08)

### Bug Fixes

* Mark reference_docs_uri field in google/api/client.proto as deprecated ([#150](https://github.com/googleapis/python-api-common-protos/issues/150)) ([52b5018](https://github.com/googleapis/python-api-common-protos/commit/52b5018abf0902a1e582a406c993b51e0d2aa3cd))

## [1.57.0](https://github.com/googleapis/python-api-common-protos/compare/v1.56.4...v1.57.0) (2022-11-15)

### Features

* Add support for Python 3.10 ([#143](https://github.com/googleapis/python-api-common-protos/issues/143)) ([63ca888](https://github.com/googleapis/python-api-common-protos/commit/63ca888512be84508fcf95e4d5d40df036a85e18))
* Add support for Python 3.11 ([#145](https://github.com/googleapis/python-api-common-protos/issues/145)) ([b9dbb21](https://github.com/googleapis/python-api-common-protos/commit/b9dbb219ea46abd9851af1fc41ea37f9d5631c0b))
* added google.api.JwtLocation.cookie ([6af2132](https://github.com/googleapis/python-api-common-protos/commit/6af21322879cba158e0a5992c9799e68c1744fac))
* added google.api.Service.publishing and client libraries settings ([6af2132](https://github.com/googleapis/python-api-common-protos/commit/6af21322879cba158e0a5992c9799e68c1744fac))
* new fields in enum google.api.ErrorReason ([6af2132](https://github.com/googleapis/python-api-common-protos/commit/6af21322879cba158e0a5992c9799e68c1744fac))

### Bug Fixes

* deprecate google.api.BackendRule.min_deadline ([6af2132](https://github.com/googleapis/python-api-common-protos/commit/6af21322879cba158e0a5992c9799e68c1744fac))
* **deps:** Require protobuf >=3.19.5 ([#141](https://github.com/googleapis/python-api-common-protos/issues/141)) ([9ea3530](https://github.com/googleapis/python-api-common-protos/commit/9ea3530b459269e964fcc98db1c5025e05d6495f))

### Documentation

* minor updates to comments ([6af2132](https://github.com/googleapis/python-api-common-protos/commit/6af21322879cba158e0a5992c9799e68c1744fac))

## [1.56.4](https://github.com/googleapis/python-api-common-protos/compare/v1.56.3...v1.56.4) (2022-07-12)

### Bug Fixes

* require python 3.7+ ([#119](https://github.com/googleapis/python-api-common-protos/issues/119)) ([507b58d](https://github.com/googleapis/python-api-common-protos/commit/507b58dfa0516aedf57880b384e92cda97152398))

## [1.56.3](https://github.com/googleapis/python-api-common-protos/compare/v1.56.2...v1.56.3) (2022-06-21)

### Bug Fixes

* **deps:** allow protobuf < 5.0.0 ([#112](https://github.com/googleapis/python-api-common-protos/issues/112)) ([67b0231](https://github.com/googleapis/python-api-common-protos/commit/67b02313bf47d86ac84917756ff026e331665637))

### Documentation

* fix changelog header to consistent size ([#108](https://github.com/googleapis/python-api-common-protos/issues/108)) ([d315b9f](https://github.com/googleapis/python-api-common-protos/commit/d315b9f23f5dbbce27c965a2b692a8d1dcf03d60))

## [1.56.2](https://github.com/googleapis/python-api-common-protos/compare/v1.56.1...v1.56.2) (2022-05-26)

### Bug Fixes

* **deps:** require grpcio >= 1.0.0, <2.0.0dev ([4a402ce](https://github.com/googleapis/python-api-common-protos/commit/4a402ce798c8364679e69eefdaadcf61fc289308))
* **deps:** require protobuf>= 3.15.0, <4.0.0dev ([#105](https://github.com/googleapis/python-api-common-protos/issues/105)) ([4a402ce](https://github.com/googleapis/python-api-common-protos/commit/4a402ce798c8364679e69eefdaadcf61fc289308))

## [1.56.1](https://github.com/googleapis/python-api-common-protos/compare/v1.56.0...v1.56.1) (2022-05-05)

### Bug Fixes

* **deps:** require protobuf >=1.15.0 ([f04ed64](https://github.com/googleapis/python-api-common-protos/commit/f04ed64b233e1ff95370ef412ad5ecb92cb5780e))
* include tests directory ([#103](https://github.com/googleapis/python-api-common-protos/issues/103)) ([72e5df1](https://github.com/googleapis/python-api-common-protos/commit/72e5df15ce63012f7d5c7781a51687e85a2cf63c))
* regenerate pb2 files using the latest version of grpcio-tools ([f04ed64](https://github.com/googleapis/python-api-common-protos/commit/f04ed64b233e1ff95370ef412ad5ecb92cb5780e))

## [1.56.0](https://github.com/googleapis/python-api-common-protos/compare/v1.55.0...v1.56.0) (2022-03-17)

### Features

* add google/api/error_reason.proto ([62c04b8](https://github.com/googleapis/python-api-common-protos/commit/62c04b83ef9ce972760407d8e9e9e0d77bbb071c))
* add google/api/visibility.proto ([62c04b8](https://github.com/googleapis/python-api-common-protos/commit/62c04b83ef9ce972760407d8e9e9e0d77bbb071c))
* add google/type/decimal.proto ([62c04b8](https://github.com/googleapis/python-api-common-protos/commit/62c04b83ef9ce972760407d8e9e9e0d77bbb071c))
* add google/type/interval.proto ([62c04b8](https://github.com/googleapis/python-api-common-protos/commit/62c04b83ef9ce972760407d8e9e9e0d77bbb071c))
* add google/type/localized_text.proto ([62c04b8](https://github.com/googleapis/python-api-common-protos/commit/62c04b83ef9ce972760407d8e9e9e0d77bbb071c))
* add google/type/phone_number.proto ([62c04b8](https://github.com/googleapis/python-api-common-protos/commit/62c04b83ef9ce972760407d8e9e9e0d77bbb071c))
* update all protos and pb2 files ([62c04b8](https://github.com/googleapis/python-api-common-protos/commit/62c04b83ef9ce972760407d8e9e9e0d77bbb071c))

### Bug Fixes

* expose all names in longrunning _pb2's ([#90](https://github.com/googleapis/python-api-common-protos/issues/90)) ([09e9ccd](https://github.com/googleapis/python-api-common-protos/commit/09e9ccd86c21dceb3a5add66cc4bf5009cb255a9))
* re-generate pb2 files ([#87](https://github.com/googleapis/python-api-common-protos/issues/87)) ([6260547](https://github.com/googleapis/python-api-common-protos/commit/6260547506f122ca9ee833aca0669d1650304a11))
* re-generate pb2 files using grpcio-tools<1.44.0 ([#93](https://github.com/googleapis/python-api-common-protos/issues/93)) ([76bb9f6](https://github.com/googleapis/python-api-common-protos/commit/76bb9f66f9674ad4c3a7fdc8812dadfb25b170a6))
* remove deprecated fields `aliases` and `features` from google/api/endpoint.proto ([62c04b8](https://github.com/googleapis/python-api-common-protos/commit/62c04b83ef9ce972760407d8e9e9e0d77bbb071c))

## [1.55.0](https://github.com/googleapis/python-api-common-protos/compare/v1.54.0...v1.55.0) (2022-02-15)

### Features

* add location proto files. ([#84](https://github.com/googleapis/python-api-common-protos/issues/84)) ([9a33e56](https://github.com/googleapis/python-api-common-protos/commit/9a33e56ac6a07a2e717edc55a39fa7cf2f9eec15))

## [1.54.0](https://www.github.com/googleapis/python-api-common-protos/compare/v1.53.0...v1.54.0) (2021-12-07)

### Features

* add extended_operations.proto ([#77](https://www.github.com/googleapis/python-api-common-protos/issues/77)) ([bc85849](https://www.github.com/googleapis/python-api-common-protos/commit/bc85849e21494b267d87cd6dc5d0a0e23e012470))
* add google/api/routing.proto ([#75](https://www.github.com/googleapis/python-api-common-protos/issues/75)) ([1ae0bbc](https://www.github.com/googleapis/python-api-common-protos/commit/1ae0bbcc9747af4dd467e7a246c1a2a4cd5ef2ec))

## [1.53.0](https://www.github.com/googleapis/python-api-common-protos/compare/v1.52.0...v1.53.0) (2021-02-25)

### Features

* add `google.api.ResourceDescriptor.Style` ([4ce679c](https://www.github.com/googleapis/python-api-common-protos/commit/4ce679cd49771946bf781108e92e07cdf04a61eb))
* add API method signatures to longrunning operations ([8de7ae2](https://www.github.com/googleapis/python-api-common-protos/commit/8de7ae28dfe5dd4d0cb99dd3b89a8f1e614bbe6d))
* add gapic_metadata_pb2 ([#38](https://www.github.com/googleapis/python-api-common-protos/issues/38)) ([8de7ae2](https://www.github.com/googleapis/python-api-common-protos/commit/8de7ae28dfe5dd4d0cb99dd3b89a8f1e614bbe6d))
* add UNORDERED_LIST to field options ([8de7ae2](https://www.github.com/googleapis/python-api-common-protos/commit/8de7ae28dfe5dd4d0cb99dd3b89a8f1e614bbe6d))
* add WaitOperation method to longrunning operations ([8de7ae2](https://www.github.com/googleapis/python-api-common-protos/commit/8de7ae28dfe5dd4d0cb99dd3b89a8f1e614bbe6d))
* require python >=3.6 and   ([#31](https://www.github.com/googleapis/python-api-common-protos/issues/31)) ([4ce679c](https://www.github.com/googleapis/python-api-common-protos/commit/4ce679cd49771946bf781108e92e07cdf04a61eb))

### Bug Fixes

* add `create_key` to FieldDescriptors ([4ce679c](https://www.github.com/googleapis/python-api-common-protos/commit/4ce679cd49771946bf781108e92e07cdf04a61eb))
* Generate gRPC files for long-running operations ([#13](https://www.github.com/googleapis/python-api-common-protos/issues/13)) ([a9ce288](https://www.github.com/googleapis/python-api-common-protos/commit/a9ce28840ddfec712da5b296f43e6c3131840db4))

### Documentation

* add link to PyPI ([#10](https://www.github.com/googleapis/python-api-common-protos/issues/10)) ([3f79402](https://www.github.com/googleapis/python-api-common-protos/commit/3f7940226b0e22aef31b82c8dc2196aa25b48a3f))

## [1.53.0dev1](https://www.github.com/googleapis/python-api-common-protos/compare/v1.52.0...v1.53.0dev1) (2021-01-27)

### Features

* add `google.api.ResourceDescriptor.Style` ([4ce679c](https://www.github.com/googleapis/python-api-common-protos/commit/4ce679cd49771946bf781108e92e07cdf04a61eb))
* require python >=3.6 and   ([#31](https://www.github.com/googleapis/python-api-common-protos/issues/31)) ([4ce679c](https://www.github.com/googleapis/python-api-common-protos/commit/4ce679cd49771946bf781108e92e07cdf04a61eb))

### Bug Fixes

* add `create_key` to FieldDescriptors ([4ce679c](https://www.github.com/googleapis/python-api-common-protos/commit/4ce679cd49771946bf781108e92e07cdf04a61eb))
* Generate gRPC files for long-running operations ([#13](https://www.github.com/googleapis/python-api-common-protos/issues/13)) ([a9ce288](https://www.github.com/googleapis/python-api-common-protos/commit/a9ce28840ddfec712da5b296f43e6c3131840db4))

### Documentation

* add link to PyPI ([#10](https://www.github.com/googleapis/python-api-common-protos/issues/10)) ([3f79402](https://www.github.com/googleapis/python-api-common-protos/commit/3f7940226b0e22aef31b82c8dc2196aa25b48a3f))

## 1.52.0 (2020-06-04)

### Features

* create api-common-protos repo for python common protos ([4ef4b0d](https://www.github.com/googleapis/python-api-common-protos/commit/4ef4b0d177136bfbd19f4c00ccf2f6d7eaccb153))


# Contributor Code of Conduct

As contributors and maintainers of this project,
and in the interest of fostering an open and welcoming community,
we pledge to respect all people who contribute through reporting issues,
posting feature requests, updating documentation,
submitting pull requests or patches, and other activities.

We are committed to making participation in this project
a harassment-free experience for everyone,
regardless of level of experience, gender, gender identity and expression,
sexual orientation, disability, personal appearance,
body size, race, ethnicity, age, religion, or nationality.

Examples of unacceptable behavior by participants include:

* The use of sexualized language or imagery
* Personal attacks
* Trolling or insulting/derogatory comments
* Public or private harassment
* Publishing other's private information,
such as physical or electronic
addresses, without explicit permission
* Other unethical or unprofessional conduct.

Project maintainers have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct.
By adopting this Code of Conduct,
project maintainers commit themselves to fairly and consistently
applying these principles to every aspect of managing this project.
Project maintainers who do not follow or enforce the Code of Conduct
may be permanently removed from the project team.

This code of conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community.

Instances of abusive, harassing, or otherwise unacceptable behavior
may be reported by opening an issue
or contacting one or more of the project maintainers.

This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.2.0,
available at [http://contributor-covenant.org/version/1/2/0/](http://contributor-covenant.org/version/1/2/0/)


# How to Contribute

We'd love to accept your patches and contributions to this project. There are
just a few small guidelines you need to follow.

## Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License
Agreement (CLA). You (or your employer) retain the copyright to your
contribution; this simply gives us permission to use and redistribute your
contributions as part of the project. Head over to
<https://cla.developers.google.com/> to see your current agreements on file or
to sign a new one.

You generally only need to submit a CLA once, so if you've already submitted one
(even if it was for a different project), you probably don't need to do it
again.

## Code reviews

All submissions, including submissions by project members, require review. We
use GitHub pull requests for this purpose. Consult
[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
information on using pull requests.

## Community Guidelines

This project follows
[Google's Open Source Community Guidelines](https://opensource.google/conduct/).


Google APIs common protos
-------------------------

.. image:: https://img.shields.io/pypi/v/googleapis-common-protos.svg
    :target: https://pypi.org/project/googleapis-common-protos/

googleapis-common-protos contains the python classes generated from the common
protos in the `googleapis/googleapis <https://github.com/googleapis/googleapis>`_ repository.


# Security Policy

To report a security issue, please use [g.co/vulnz](https://g.co/vulnz).

The Google Security Team will respond within 5 working days of your report on g.co/vulnz.

We use g.co/vulnz for our intake, and do coordination and disclosure here using GitHub Security Advisory to privately discuss and fix the issue.


gRPC C++ - Building from source
===========================

This document has detailed instructions on how to build gRPC C++ from source. Note that it only covers the build of gRPC itself and is meant for gRPC C++ contributors and/or power users.
Other should follow the user instructions. See the [How to use](https://github.com/grpc/grpc/tree/master/src/cpp#to-start-using-grpc-c) instructions for guidance on how to add gRPC as a dependency to a C++ application (there are several ways and system-wide installation is often not the best choice).

# Pre-requisites

## Linux

```sh
 $ [sudo] apt-get install build-essential autoconf libtool pkg-config
```

If you plan to build using CMake
```sh
 $ [sudo] apt-get install cmake
```

If you are a contributor and plan to build and run tests, install the following as well:
```sh
 $ # clang and LLVM C++ lib is only required for sanitizer builds
 $ [sudo] apt-get install clang libc++-dev
```

## MacOS

On a Mac, you will first need to
install Xcode or
[Command Line Tools for Xcode](https://developer.apple.com/download/more/)
and then run the following command from a terminal:

```sh
 $ [sudo] xcode-select --install
```

To build gRPC from source, you may need to install the following
packages from [Homebrew](https://brew.sh):

```sh
 $ brew install autoconf automake libtool shtool
```

If you plan to build using CMake, follow the instructions from https://cmake.org/download/

*Tip*: when building,
you *may* want to explicitly set the `LIBTOOL` and `LIBTOOLIZE`
environment variables when running `make` to ensure the version
installed by `brew` is being used:

```sh
 $ LIBTOOL=glibtool LIBTOOLIZE=glibtoolize make
```

## Windows

To prepare for cmake + Microsoft Visual C++ compiler build
- Install Visual Studio 2019 or later (Visual C++ compiler will be used).
- Install [Git](https://git-scm.com/).
- Install [CMake](https://cmake.org/download/).
- Install [nasm](https://www.nasm.us/) and add it to `PATH` (`choco install nasm`) - *required by boringssl*
- (Optional) Install [Ninja](https://ninja-build.org/) (`choco install ninja`)

# Clone the repository (including submodules)

Before building, you need to clone the gRPC github repository and download submodules containing source code
for gRPC's dependencies (that's done by the `submodule` command or `--recursive` flag). Use following commands
to clone the gRPC repository at the [latest stable release tag](https://github.com/grpc/grpc/releases)

## Unix

```sh
 $ git clone -b RELEASE_TAG_HERE https://github.com/grpc/grpc
 $ cd grpc
 $ git submodule update --init
 ```

## Windows

```
> git clone -b RELEASE_TAG_HERE https://github.com/grpc/grpc
> cd grpc
> git submodule update --init
```

NOTE: The `bazel` build tool uses a different model for dependencies. You only need to worry about downloading submodules if you're building
with something else than `bazel` (e.g. `cmake`).

# Build from source

In the C++ world, there's no "standard" build system that would work for all supported use cases and on all supported platforms.
Therefore, gRPC supports several major build systems, which should satisfy most users. Depending on your needs
we recommend building using `bazel` or `cmake`.

## Building with bazel (recommended)

Bazel is the primary build system for gRPC C++. If you're comfortable using bazel, we can certainly recommend it.
Using bazel will give you the best developer experience in addition to faster and cleaner builds.

You'll need `bazel` version `1.0.0` or higher to build gRPC.
See [Installing Bazel](https://docs.bazel.build/versions/master/install.html) for instructions how to install bazel on your system.
We support building with `bazel` on Linux, MacOS and Windows.

From the grpc repository root
```
# Build gRPC C++
$ bazel build :all
```

```
# Run all the C/C++ tests
$ bazel test --config=dbg //test/...
```

NOTE: If you are a gRPC maintainer and you have access to our test cluster, you should use our [gRPC's Remote Execution environment](tools/remote_build/README.md)
to get significant improvement to the build and test speed (and a bunch of other very useful features).

## Building with CMake

### Linux/Unix, Using Make

Run from the grpc directory after cloning the repo with --recursive or updating submodules.
```
$ mkdir -p cmake/build
$ cd cmake/build
$ cmake ../..
$ make
```

If you want to build shared libraries (`.so` files), run `cmake` with `-DBUILD_SHARED_LIBS=ON`.

### Windows, Using Visual Studio 2019 or later

When using the "Visual Studio" generator,
cmake will generate a solution (`grpc.sln`) that contains a VS project for
every target defined in `CMakeLists.txt` (+ a few extra convenience projects
added automatically by cmake). After opening the solution with Visual Studio
you will be able to browse and build the code.
```
> @rem Run from grpc directory after cloning the repo with --recursive or updating submodules.
> md .build
> cd .build
> cmake .. -G "Visual Studio 16 2019"
> cmake --build . --config Release
```

Using gRPC C++ as a DLL is not recommended, but you can still enable it by running `cmake` with `-DBUILD_SHARED_LIBS=ON`.

### Windows, Using Ninja (faster build).

Please note that when using Ninja, you will still need Visual C++ (part of Visual Studio)
installed to be able to compile the C/C++ sources.
```
> @rem Run from grpc directory after cloning the repo with --recursive or updating submodules.
> cd cmake
> md build
> cd build
> call "%VS140COMNTOOLS%..\..\VC\vcvarsall.bat" x64
> cmake ..\.. -GNinja -DCMAKE_BUILD_TYPE=Release
> cmake --build .
```

Using gRPC C++ as a DLL is not recommended, but you can still enable it by running `cmake` with `-DBUILD_SHARED_LIBS=ON`.

### Windows: A note on building shared libs (DLLs)

Windows DLL build is supported at a "best effort" basis and we don't recommend using gRPC C++ as a DLL as there are some known drawbacks around how C++ DLLs work on Windows. For example, there is no stable C++ ABI and you can't safely allocate memory in one DLL, and free it in another etc.

That said, we don't actively prohibit building DLLs on windows (it can be enabled in cmake with `-DBUILD_SHARED_LIBS=ON`), and are free to use the DLL builds
at your own risk.
- you've been warned that there are some important drawbacks and some things might not work at all or will be broken in interesting ways.
- we don't have extensive testing for DLL builds in place (to avoid maintenance costs, increased test duration etc.) so regressions / build breakages might occur

### Dependency management

gRPC's CMake build system has two options for handling dependencies.
CMake can build the dependencies for you, or it can search for libraries
that are already installed on your system and use them to build gRPC.

This behavior is controlled by the `gRPC_<depname>_PROVIDER` CMake variables,
e.g. `gRPC_CARES_PROVIDER`. The options that these variables take are as follows:

* module - build dependencies alongside gRPC. The source code is obtained from
gRPC's git submodules.
* package - use external copies of dependencies that are already available
on your system. These could come from your system package manager, or perhaps
you pre-installed them using CMake with the `CMAKE_INSTALL_PREFIX` option.

For example, if you set `gRPC_CARES_PROVIDER=module`, then CMake will build
c-ares before building gRPC. On the other hand, if you set
`gRPC_CARES_PROVIDER=package`, then CMake will search for a copy of c-ares
that's already installed on your system and use it to build gRPC.

### Install after build

Perform the following steps to install gRPC using CMake.
* Set `-DgRPC_INSTALL=ON`
* Build the `install` target

The install destination is controlled by the
[`CMAKE_INSTALL_PREFIX`](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html) variable.

If you are running CMake v3.13 or newer you can build gRPC's dependencies
in "module" mode and install them alongside gRPC in a single step.
[Example](test/distrib/cpp/run_distrib_test_cmake_module_install.sh)

If you are building gRPC < 1.27 or if you are using CMake < 3.13 you will need
to select "package" mode (rather than "module" mode) for the dependencies.
This means you will need to have external copies of these libraries available
on your system. This [example](test/distrib/cpp/run_distrib_test_cmake.sh) shows
how to install dependencies with cmake before proceeding to installing gRPC itself.

```
# NOTE: all of gRPC's dependencies need to be already installed
$ cmake ../.. -DgRPC_INSTALL=ON                \
              -DCMAKE_BUILD_TYPE=Release       \
              -DgRPC_ABSL_PROVIDER=package     \
              -DgRPC_CARES_PROVIDER=package    \
              -DgRPC_PROTOBUF_PROVIDER=package \
              -DgRPC_RE2_PROVIDER=package      \
              -DgRPC_SSL_PROVIDER=package      \
              -DgRPC_ZLIB_PROVIDER=package
$ make
$ make install
```

### Cross-compiling

You can use CMake to cross-compile gRPC for another architecture. In order to
do so, you will first need to build `protoc` and `grpc_cpp_plugin`
for the host architecture. These tools are used during the build of gRPC, so
we need copies of executables that can be run natively.

You will likely need to install the toolchain for the platform you are
targeting for your cross-compile. Once you have done so, you can write a
toolchain file to tell CMake where to find the compilers and system tools
that will be used for this build.

This toolchain file is specified to CMake by setting the `CMAKE_TOOLCHAIN_FILE`
variable.
```
$ cmake ../.. -DCMAKE_TOOLCHAIN_FILE=path/to/file
$ make
```

[Cross-compile example](test/distrib/cpp/run_distrib_test_cmake_aarch64_cross.sh)

### A note on SONAME and its ABI compatibility implications in the cmake build

Best efforts are made to bump the SONAME revision during ABI breaches. While a
change in the SONAME clearly indicates an ABI incompatibility, no hard guarantees
can be made about any sort of ABI stability across the same SONAME version.

## Building with make on UNIX systems (deprecated)

NOTE: `make` used to be gRPC's default build system, but we're no longer recommending it. You should use `bazel` or `cmake` instead. The `Makefile` is only intended for internal usage and is not meant for public consumption.

From the grpc repository root
```sh
 $ make
```

NOTE: if you get an error on linux such as 'aclocal-1.15: command not found', which can happen if you ran 'make' before installing the pre-reqs, try the following:
```sh
$ git clean -f -d -x && git submodule foreach --recursive git clean -f -d -x
$ [sudo] apt-get install build-essential autoconf libtool pkg-config
$ make
```

### A note on `protoc`

By default gRPC uses [protocol buffers](https://github.com/protocolbuffers/protobuf),
you will need the `protoc` compiler to generate stub server and client code.

If you compile gRPC from source, as described above, the Makefile will
automatically try compiling the `protoc` in third_party if you cloned the
repository recursively and it detects that you do not already have 'protoc' compiler
installed.


## Community Code of Conduct

gRPC follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).


# gRPC Concepts Overview

Remote Procedure Calls (RPCs) provide a useful abstraction for building
distributed applications and services. The libraries in this repository
provide a concrete implementation of the gRPC protocol, layered over HTTP/2.
These libraries enable communication between clients and servers using any
combination of the supported languages.

## Interface

Developers using gRPC start with a language agnostic description of an RPC service (a collection
of methods). From this description, gRPC will generate client and server side interfaces
in any of the supported languages. The server implements
the service interface, which can be remotely invoked by the client interface.

By default, gRPC uses [Protocol Buffers](https://github.com/protocolbuffers/protobuf) as the
Interface Definition Language (IDL) for describing both the service interface
and the structure of the payload messages. It is possible to use other
alternatives if desired.

### Invoking & handling remote calls
Starting from an interface definition in a .proto file, gRPC provides
Protocol Compiler plugins that generate Client- and Server-side APIs.
gRPC users call into these APIs on the Client side and implement
the corresponding API on the server side.

#### Synchronous vs. asynchronous
Synchronous RPC calls, that block until a response arrives from the server, are
the closest approximation to the abstraction of a procedure call that RPC
aspires to.

On the other hand, networks are inherently asynchronous and in many scenarios,
it is desirable to have the ability to start RPCs without blocking the current
thread.

The gRPC programming surface in most languages comes in both synchronous and
asynchronous flavors.

## Streaming

gRPC supports streaming semantics, where either the client or the server (or both)
send a stream of messages on a single RPC call. The most general case is
Bidirectional Streaming where a single gRPC call establishes a stream in which both
the client and the server can send a stream of messages to each other. The streamed
messages are delivered in the order they were sent.

# Protocol

The [gRPC protocol](doc/PROTOCOL-HTTP2.md) specifies the abstract requirements for communication between
clients and servers. A concrete embedding over HTTP/2 completes the picture by
fleshing out the details of each of the required operations.

## Abstract gRPC protocol
A gRPC call comprises of a bidirectional stream of messages, initiated by the client. In the client-to-server direction, this stream begins with a mandatory `Call Header`, followed by optional `Initial-Metadata`, followed by zero or more `Payload Messages`. A client signals end of its message stream by means of an underlying lower level protocol. The server-to-client direction contains an optional `Initial-Metadata`, followed by zero or more `Payload Messages` terminated with a mandatory `Status` and optional `Status-Metadata` (a.k.a.,`Trailing-Metadata`).

## Implementation over HTTP/2
The abstract protocol defined above is implemented over [HTTP/2](https://http2.github.io/). gRPC bidirectional streams are mapped to HTTP/2 streams. The contents of `Call Header` and `Initial Metadata` are sent as HTTP/2 headers and subject to HPACK compression. `Payload Messages` are serialized into a byte stream of length prefixed gRPC frames which are then fragmented into HTTP/2 frames at the sender and reassembled at the receiver. `Status` and `Trailing-Metadata` are sent as HTTP/2 trailing headers (a.k.a., trailers). A client signals end of its message stream by setting `END_STREAM` flag on the last DATA frame.
For a detailed description see [doc/PROTOCOL-HTTP2.md](doc/PROTOCOL-HTTP2.md).

## Flow Control
gRPC uses the flow control mechanism in HTTP/2. This enables fine-grained control of memory used for buffering in-flight messages.


# How to contribute

We definitely welcome your patches and contributions to gRPC! Please read the gRPC
organization's [governance rules](https://github.com/grpc/grpc-community/blob/master/governance.md)
and [contribution guidelines](https://github.com/grpc/grpc-community/blob/master/CONTRIBUTING.md) before proceeding.

If you are new to github, please start by reading [Pull Request
howto](https://help.github.com/articles/about-pull-requests/)

If you are looking for features to work on, please filter the issues list with the label ["disposition/help wanted"](https://github.com/grpc/grpc/issues?q=label%3A%22disposition%2Fhelp+wanted%22).
Please note that some of these feature requests might have been closed in the past as a result of them being marked as stale due to there being no activity, but these are still valid feature requests.

## Legal requirements

In order to protect both you and ourselves, you will need to sign the
[Contributor License
Agreement](https://identity.linuxfoundation.org/projects/cncf).

## Cloning the repository

Before starting any development work you will need a local copy of the gRPC repository.
Please follow the instructions in [Building gRPC C++: Clone the repository](BUILDING.md#clone-the-repository-including-submodules).

## Building & Running tests

Different languages use different build systems. To hide the complexity
of needing to build with many different build systems, a portable python
script that unifies the experience of building and testing gRPC in different
languages and on different platforms is provided.

To build gRPC in the language of choice (e.g. `c++`, `csharp`, `php`, `python`, `ruby`, ...)
- Prepare your development environment based on language-specific instructions in `src/YOUR-LANGUAGE` directory.
- The language-specific instructions might involve installing C/C++ prerequisites listed in
  [Building gRPC C++: Prerequisites](BUILDING.md#pre-requisites). This is because gRPC implementations
  in this repository are using the native gRPC "core" library internally.
- Run
  ```
  python tools/run_tests/run_tests.py -l YOUR_LANGUAGE --build_only
  ```
- To also run all the unit tests after building
  ```
  python tools/run_tests/run_tests.py -l YOUR_LANGUAGE
  ```

You can also run `python tools/run_tests/run_tests.py --help` to discover useful command line flags supported. For more details,
see [tools/run_tests](tools/run_tests) where you will also find guidance on how to run various other test suites (e.g. interop tests, benchmarks).

## Generated project files

To ease maintenance of language- and platform- specific build systems, many
projects files are generated using templates and should not be edited by hand.
Run `tools/buildgen/generate_projects.sh` to regenerate.  See
[templates](templates) for details.

As a rule of thumb, if you see the "sanity tests" failing you've most likely
edited generated files or you didn't regenerate the projects properly (or your
code formatting doesn't match our code style).

## Guidelines for Pull Requests
How to get your contributions merged smoothly and quickly.

- Create **small PRs** that are narrowly focused on **addressing a single
  concern**.  We often times receive PRs that are trying to fix several things
  at a time, but only one fix is considered acceptable, nothing gets merged and
  both author's & review's time is wasted.  Create more PRs to address different
  concerns and everyone will be happy.

- For speculative changes, consider opening an issue and discussing it first.
  If you are suggesting a behavioral or API change, consider starting with a
  [gRFC proposal](https://github.com/grpc/proposal).

- Provide a good **PR description** as a record of **what** change is being made
  and **why** it was made.  Link to a GitHub issue if it exists.

- Don't fix code style and formatting unless you are already changing that line
  to address an issue.  PRs with irrelevant changes won't be merged.  If you do
  want to fix formatting or style, do that in a separate PR.

- If you are adding a new file, make sure it has the copyright message template
  at the top as a comment. You can copy over the message from an existing file
  and update the year.

- Unless your PR is trivial, you should expect there will be reviewer comments
  that you'll need to address before merging.  We expect you to be reasonably
  responsive to those comments, otherwise the PR will be closed after 2-3 weeks
  of inactivity.

- If you have non-trivial contributions, please consider adding an entry to [the
  AUTHORS file](https://github.com/grpc/grpc/blob/master/AUTHORS) listing the
  copyright holder for the contribution (yourself, if you are signing the
  individual CLA, or your company, for corporate CLAs) in the same PR as your
  contribution.  This needs to be done only once, for each company, or
  individual. Please keep this file in alphabetical order.

- Maintain **clean commit history** and use **meaningful commit messages**.
  PRs with messy commit history are difficult to review and won't be merged.
  Use `rebase -i upstream/master` to curate your commit history and/or to
  bring in latest changes from master (but avoid rebasing in the middle of
  a code review).

- Keep your PR up to date with upstream/master (if there are merge conflicts,
  we can't really merge your change).

- If you are regenerating the projects using
  `tools/buildgen/generate_projects.sh`, make changes to generated files a
  separate commit with commit message `regenerate projects`.  Mixing changes
  to generated and hand-written files make your PR difficult to review.
  Note that running this script requires the installation of Python packages
  `pyyaml` and `mako` (typically installed using `pip`) as well as a recent
  version of [`go`](https://golang.org/doc/install#install).

- **All tests need to be passing** before your change can be merged.
  We recommend you **run tests locally** before creating your PR to catch
  breakages early on (see [tools/run_tests](tools/run_tests).  Ultimately, the
  green signal will be provided by our testing infrastructure.  The reviewer
  will help you if there are test failures that seem not related to the change
  you are making.

- Exceptions to the rules can be made if there's a compelling reason for doing
  so.

## Obtaining Commit Access
We grant Commit Access to contributors based on the following criteria:
* Sustained contribution to the gRPC project.
* Deep understanding of the areas contributed to, and good consideration of various reliability, usability and performance tradeoffs.
* Contributions demonstrate that obtaining Commit Access will significantly reduce friction for the contributors or others.

In addition to submitting PRs, a Contributor with Commit Access can:
* Review PRs and merge once other checks and criteria pass.
* Triage bugs and PRs and assign appropriate labels and reviewers.

### Obtaining Commit Access without Code Contributions
The [gRPC organization](https://github.com/grpc) is comprised of multiple repositories and commit access is usually restricted to one or more of these repositories. Some repositories such as the [grpc.github.io](https://github.com/grpc/grpc.github.io/) do not have code, but the same principle of sustained, high quality contributions, with a good understanding of the fundamentals, apply.


This repository is governed by the gRPC organization's [governance rules](https://github.com/grpc/grpc-community/blob/master/governance.md).


This page lists all active maintainers of this repository. If you were a
maintainer and would like to add your name to the Emeritus list, please send us a
PR.

See [GOVERNANCE.md](https://github.com/grpc/grpc-community/blob/master/governance.md)
for governance guidelines and how to become a maintainer.
See [CONTRIBUTING.md](https://github.com/grpc/grpc-community/blob/master/CONTRIBUTING.md)
for general contribution guidelines.

## Maintainers (in alphabetical order)
- [a11r](https://github.com/a11r), Google LLC
- [apolcyn](https://github.com/apolcyn), Google LLC
- [arjunroy](https://github.com/arjunroy), Google LLC
- [ctiller](https://github.com/ctiller), Google LLC
- [daniel-j-born](https://github.com/daniel-j-born), Google LLC
- [dapengzhang0](https://github.com/dapengzhang0), Google LLC
- [dfawley](https://github.com/dfawley), Google LLC
- [dklempner](https://github.com/dklempner), Google LLC
- [drfloob](https://github.com/drfloob), Google LLC
- [ejona86](https://github.com/ejona86), Google LLC
- [gnossen](https://github.com/gnossen), Google LLC
- [guantaol](https://github.com/guantaol), Google LLC
- [hcaseyal](https://github.com/hcaseyal), Google LLC
- [jtattermusch](https://github.com/jtattermusch), Google LLC
- [LittleCVR](https://github.com/littlecvr), Google LLC
- [markdroth](https://github.com/markdroth), Google LLC
- [matthewstevenson88](https://github.com/matthewstevenson88), Google LLC
- [medinandres](https://github.com/medinandres), Google LLC
- [murgatroid99](https://github.com/murgatroid99), Google LLC
- [nanahpang](https://github.com/nanahpang), Google LLC
- [pfreixes](https://github.com/pfreixes), Skyscanner Ltd
- [ran-su](https://github.com/ran-su), Google LLC
- [sanjaypujare](https://github.com/sanjaypujare), Google LLC
- [sergiitk](https://github.com/sergiitk), Google LLC
- [soheilhy](https://github.com/soheilhy), Google LLC
- [stanley-cheung](https://github.com/stanley-cheung), Google LLC
- [veblush](https://github.com/veblush), Google LLC
- [vishalpowar](https://github.com/vishalpowar), Google LLC
- [Vizerai](https://github.com/Vizerai), Google LLC
- [wenbozhu](https://github.com/wenbozhu), Google LLC
- [yashykt](https://github.com/yashykt), Google LLC
- [yihuazhang](https://github.com/yihuazhang), Google LLC
- [ZhenLian](https://github.com/ZhenLian), Google LLC
- [ZhouyihaiDing](https://github.com/ZhouyihaiDing), Google LLC

## Emeritus Maintainers (in alphabetical order)
- [adelez](https://github.com/adelez), Google LLC
- [AspirinSJL](https://github.com/AspirinSJL), Google LLC
- [billfeng327](https://github.com/billfeng327), Google LLC
- [bogdandrutu](https://github.com/bogdandrutu), Google LLC
- [dgquintas](https://github.com/dgquintas), Google LLC
- [ericgribkoff](https://github.com/ericgribkoff), Google LLC
- [fengli79](https://github.com/fengli79), Google LLC
- [jboeuf](https://github.com/jboeuf), Google LLC
- [jcanizales](https://github.com/jcanizales), Google LLC
- [jiangtaoli2016](https://github.com/jiangtaoli2016), Google LLC
- [jkolhe](https://github.com/jkolhe), Google LLC
- [jpalmerLinuxFoundation](https://github.com/jpalmerLinuxFoundation), Linux Foundation
- [justinburke](https://github.com/justinburke), Google LLC
- [karthikravis](https://github.com/karthikravis), Google LLC
- [kpayson64](https://github.com/kpayson64), Google LLC
- [kumaralokgithub](https://github.com/kumaralokgithub), Google LLC
- [lidizheng](https://github.com/lidizheng), Google LLC
- [lyuxuan](https://github.com/lyuxuan), Google LLC
- [matt-kwong](https://github.com/matt-kwong), Google LLC
- [mehrdada](https://github.com/mehrdada), Dropbox, Inc.
- [mhaidrygoog](https://github.com/mhaidrygoog), Google LLC
- [mit-mit](https://github.com/mit-mit), Google LLC
- [mpwarres](https://github.com/mpwarres), Google LLC
- [muxi](https://github.com/muxi), Google LLC
- [nathanielmanistaatgoogle](https://github.com/nathanielmanistaatgoogle), Google LLC
- [ncteisen](https://github.com/ncteisen), Google LLC
- [nicolasnoble](https://github.com/nicolasnoble), Google LLC
- [pmarks-net](https://github.com/pmarks-net), Google LLC
- [qixuanl1](https://github.com/qixuanl1), Google LLC
- [rmstar](https://github.com/rmstar), Google LLC
- [sheenaqotj](https://github.com/sheenaqotj), Google LLC
- [slash-lib](https://github.com/slash-lib), Google LLC
- [soltanmm](https://github.com/soltanmm), Google LLC
- [sreecha](https://github.com/sreecha), LinkedIn
- [srini100](https://github.com/srini100), Google LLC
- [summerxyt](https://github.com/summerxyt), Google LLC
- [vjpai](https://github.com/vjpai), Google LLC
- [wcevans](https://github.com/wcevans), Google LLC
- [y-zeng](https://github.com/y-zeng), Google LLC
- [yang-g](https://github.com/yang-g), Google LLC
- [zpencer](https://github.com/zpencer), Google LLC


# Top-level Items by language

## Bazel
* [grpc.bzl](grpc.bzl)

## Objective-C
* [gRPC.podspec](gRPC.podspec)

## PHP
* [composer.json](composer.json)
* [config.m4](config.m4)
* [package.xml](package.xml)

## Python
* [requirements.txt](requirements.txt)
* [setup.cfg](setup.cfg)
* [setup.py](setup.py)
* [PYTHON-MANIFEST.in](PYTHON-MANIFEST.in)

## Ruby
* [Gemfile](Gemfile)
* [grpc.gemspec](grpc.gemspec)
* [Rakefile](Rakefile)


# gRPC – An RPC library and framework

gRPC is a modern, open source, high-performance remote procedure call (RPC)
framework that can run anywhere. gRPC enables client and server applications to
communicate transparently, and simplifies the building of connected systems.

    Homepage:
    grpc.io

    Mailing List:
    grpc-io@googlegroups.com

[![Join the chat at https://gitter.im/grpc/grpc](https://badges.gitter.im/grpc/grpc.svg)](https://gitter.im/grpc/grpc?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

## To start using gRPC

To maximize usability, gRPC supports the standard method for adding dependencies
to a user's chosen language (if there is one). In most languages, the gRPC
runtime comes as a package available in a user's language package manager.

For instructions on how to use the language-specific gRPC runtime for a project,
please refer to these documents

- [C++](src/cpp): follow the instructions under the `src/cpp` directory
- [C#/.NET](https://github.com/grpc/grpc-dotnet): NuGet packages `Grpc.Net.Client`, `Grpc.AspNetCore.Server`
- [Dart](https://github.com/grpc/grpc-dart): pub package `grpc`
- [Go](https://github.com/grpc/grpc-go): `go get google.golang.org/grpc`
- [Java](https://github.com/grpc/grpc-java): Use JARs from Maven Central
  Repository
- [Kotlin](https://github.com/grpc/grpc-kotlin): Use JARs from Maven Central
  Repository
- [Node](https://github.com/grpc/grpc-node): `npm install @grpc/grpc-js`
- [Objective-C](src/objective-c): Add `gRPC-ProtoRPC` dependency to podspec
- [PHP](src/php): `pecl install grpc`
- [Python](src/python/grpcio): `pip install grpcio`
- [Ruby](src/ruby): `gem install grpc`
- [WebJS](https://github.com/grpc/grpc-web): follow the grpc-web instructions

Per-language quickstart guides and tutorials can be found in the
[documentation section on the grpc.io website](https://grpc.io/docs/). Code
examples are available in the [examples](examples) directory.

Precompiled bleeding-edge package builds of gRPC `master` branch's `HEAD` are
uploaded daily to [packages.grpc.io](https://packages.grpc.io).

## To start developing gRPC

Contributions are welcome!

Please read [How to contribute](CONTRIBUTING.md) which will guide you through
the entire workflow of how to build the source code, how to run the tests, and
how to contribute changes to the gRPC codebase. The "How to contribute" document
also contains info on how the contribution process works and contains best
practices for creating contributions.

## Troubleshooting

Sometimes things go wrong. Please check out the
[Troubleshooting guide](TROUBLESHOOTING.md) if you are experiencing issues with
gRPC.

## Performance

See the
[Performance dashboard](https://grafana-dot-grpc-testing.appspot.com/)
for performance numbers of master branch daily builds.

## Concepts

See [gRPC Concepts](CONCEPTS.md)

## About This Repository

This repository contains source code for gRPC libraries implemented in multiple
languages written on top of a shared C core library [src/core](src/core).

Libraries in different languages may be in various states of development. We are
seeking contributions for all of these libraries:

| Language                | Source                             |
| ----------------------- | ---------------------------------- |
| Shared C [core library] | [src/core](src/core)               |
| C++                     | [src/cpp](src/cpp)                 |
| Ruby                    | [src/ruby](src/ruby)               |
| Python                  | [src/python](src/python)           |
| PHP                     | [src/php](src/php)                 |
| C# (core library based) | [src/csharp](src/csharp)           |
| Objective-C             | [src/objective-c](src/objective-c) |

| Language             | Source repo                                        |
| -------------------- | -------------------------------------------------- |
| Java                 | [grpc-java](https://github.com/grpc/grpc-java)     |
| Kotlin               | [grpc-kotlin](https://github.com/grpc/grpc-kotlin) |
| Go                   | [grpc-go](https://github.com/grpc/grpc-go)         |
| NodeJS               | [grpc-node](https://github.com/grpc/grpc-node)     |
| WebJS                | [grpc-web](https://github.com/grpc/grpc-web)       |
| Dart                 | [grpc-dart](https://github.com/grpc/grpc-dart)     |
| .NET (pure C# impl.) | [grpc-dotnet](https://github.com/grpc/grpc-dotnet) |
| Swift                | [grpc-swift](https://github.com/grpc/grpc-swift) |


# Security Policy

For information on gRPC Security Policy and reporting potentional security issues, please see [gRPC CVE Process](https://github.com/grpc/proposal/blob/master/P4-grpc-cve-process.md).


# Troubleshooting gRPC

This guide is for troubleshooting gRPC implementations based on C core library (sources for most of them are living in the `grpc/grpc` repository).

## Enabling extra logging and tracing

Extra logging can be very useful for diagnosing problems. All gRPC implementations based on C core library support
the `GRPC_VERBOSITY` and `GRPC_TRACE` environment variables that can be used to increase the amount of information
that gets printed to stderr.

## GRPC_VERBOSITY

`GRPC_VERBOSITY` is used to set the minimum level of log messages printed by gRPC (supported values are `DEBUG`, `INFO` and `ERROR`). If this environment variable is unset, only `ERROR` logs will be printed.

## GRPC_TRACE

`GRPC_TRACE` can be used to enable extra logging for some internal gRPC components. Enabling the right traces can be invaluable
for diagnosing for what is going wrong when things aren't working as intended. Possible values for `GRPC_TRACE` are listed in [Environment Variables Overview](doc/environment_variables.md).
Multiple traces can be enabled at once (use comma as separator).

```
# Enable debug logs for an application
GRPC_VERBOSITY=debug ./helloworld_application_using_grpc
```

```
# Print information about invocations of low-level C core API.
# Note that trace logs of log level DEBUG won't be displayed.
# Also note that most tracers user log level INFO, so without setting
# GPRC_VERBOSITY accordingly, no traces will be printed.
GRPC_VERBOSITY=info GRPC_TRACE=api ./helloworld_application_using_grpc
```

```
# Print info from 3 different tracers, including tracing logs with log level DEBUG
GRPC_VERBOSITY=debug GRPC_TRACE=tcp,http,api ./helloworld_application_using_grpc
```

Known limitations: `GPRC_TRACE=tcp` is currently not implemented for Windows (you won't see any tcp traces).

Please note that the `GRPC_TRACE` environment variable has nothing to do with gRPC's "tracing" feature (= tracing RPCs in
microservice environment to gain insight about how requests are processed by deployment), it is merely used to enable printing
of extra logs.


Building and installing a packaged release of jemalloc can be as simple as
typing the following while in the root directory of the source tree:

    ./configure
    make
    make install

If building from unpackaged developer sources, the simplest command sequence
that might work is:

    ./autogen.sh
    make
    make install

You can uninstall the installed build artifacts like this:

    make uninstall

Notes:
 - "autoconf" needs to be installed
 - Documentation is built by the default target only when xsltproc is
available.  Build will warn but not stop if the dependency is missing.

## Advanced configuration

The 'configure' script supports numerous options that allow control of which
functionality is enabled, where jemalloc is installed, etc.  Optionally, pass
any of the following arguments (not a definitive list) to 'configure':

* `--help`

    Print a definitive list of options.

* `--prefix=<install-root-dir>`

    Set the base directory in which to install.  For example:

        ./configure --prefix=/usr/local

    will cause files to be installed into /usr/local/include, /usr/local/lib,
    and /usr/local/man.

* `--with-version=(<major>.<minor>.<bugfix>-<nrev>-g<gid>|VERSION)`

    The VERSION file is mandatory for successful configuration, and the
    following steps are taken to assure its presence:
    1) If --with-version=<major>.<minor>.<bugfix>-<nrev>-g<gid> is specified,
       generate VERSION using the specified value.
    2) If --with-version is not specified in either form and the source
       directory is inside a git repository, try to generate VERSION via 'git
       describe' invocations that pattern-match release tags.
    3) If VERSION is missing, generate it with a bogus version:
       0.0.0-0-g0000000000000000000000000000000000000000

    Note that --with-version=VERSION bypasses (1) and (2), which simplifies
    VERSION configuration when embedding a jemalloc release into another
    project's git repository.

* `--with-rpath=<colon-separated-rpath>`

    Embed one or more library paths, so that libjemalloc can find the libraries
    it is linked to.  This works only on ELF-based systems.

* `--with-mangling=<map>`

    Mangle public symbols specified in <map> which is a comma-separated list of
    name:mangled pairs.

    For example, to use ld's --wrap option as an alternative method for
    overriding libc's malloc implementation, specify something like:

      --with-mangling=malloc:__wrap_malloc,free:__wrap_free[...]

    Note that mangling happens prior to application of the prefix specified by
    --with-jemalloc-prefix, and mangled symbols are then ignored when applying
    the prefix.

* `--with-jemalloc-prefix=<prefix>`

    Prefix all public APIs with <prefix>.  For example, if <prefix> is
    "prefix_", API changes like the following occur:

      malloc()         --> prefix_malloc()
      malloc_conf      --> prefix_malloc_conf
      /etc/malloc.conf --> /etc/prefix_malloc.conf
      MALLOC_CONF      --> PREFIX_MALLOC_CONF

    This makes it possible to use jemalloc at the same time as the system
    allocator, or even to use multiple copies of jemalloc simultaneously.

    By default, the prefix is "", except on OS X, where it is "je_".  On OS X,
    jemalloc overlays the default malloc zone, but makes no attempt to actually
    replace the "malloc", "calloc", etc. symbols.

* `--without-export`

    Don't export public APIs.  This can be useful when building jemalloc as a
    static library, or to avoid exporting public APIs when using the zone
    allocator on OSX.

* `--with-private-namespace=<prefix>`

    Prefix all library-private APIs with <prefix>je_.  For shared libraries,
    symbol visibility mechanisms prevent these symbols from being exported, but
    for static libraries, naming collisions are a real possibility.  By
    default, <prefix> is empty, which results in a symbol prefix of je_ .

* `--with-install-suffix=<suffix>`

    Append <suffix> to the base name of all installed files, such that multiple
    versions of jemalloc can coexist in the same installation directory.  For
    example, libjemalloc.so.0 becomes libjemalloc<suffix>.so.0.

* `--with-malloc-conf=<malloc_conf>`

    Embed `<malloc_conf>` as a run-time options string that is processed prior to
    the malloc_conf global variable, the /etc/malloc.conf symlink, and the
    MALLOC_CONF environment variable.  For example, to change the default decay
    time to 30 seconds:

      --with-malloc-conf=decay_ms:30000

* `--enable-debug`

    Enable assertions and validation code.  This incurs a substantial
    performance hit, but is very useful during application development.

* `--disable-stats`

    Disable statistics gathering functionality.  See the "opt.stats_print"
    option documentation for usage details.

* `--enable-prof`

    Enable heap profiling and leak detection functionality.  See the "opt.prof"
    option documentation for usage details.  When enabled, there are several
    approaches to backtracing, and the configure script chooses the first one
    in the following list that appears to function correctly:

    + libunwind      (requires --enable-prof-libunwind)
    + libgcc         (unless --disable-prof-libgcc)
    + gcc intrinsics (unless --disable-prof-gcc)

* `--enable-prof-libunwind`

    Use the libunwind library (http://www.nongnu.org/libunwind/) for stack
    backtracing.

* `--disable-prof-libgcc`

    Disable the use of libgcc's backtracing functionality.

* `--disable-prof-gcc`

    Disable the use of gcc intrinsics for backtracing.

* `--with-static-libunwind=<libunwind.a>`

    Statically link against the specified libunwind.a rather than dynamically
    linking with -lunwind.

* `--disable-fill`

    Disable support for junk/zero filling of memory.  See the "opt.junk" and
    "opt.zero" option documentation for usage details.

* `--disable-zone-allocator`

    Disable zone allocator for Darwin.  This means jemalloc won't be hooked as
    the default allocator on OSX/iOS.

* `--enable-utrace`

    Enable utrace(2)-based allocation tracing.  This feature is not broadly
    portable (FreeBSD has it, but Linux and OS X do not).

* `--enable-xmalloc`

    Enable support for optional immediate termination due to out-of-memory
    errors, as is commonly implemented by "xmalloc" wrapper function for malloc.
    See the "opt.xmalloc" option documentation for usage details.

* `--enable-lazy-lock`

    Enable code that wraps pthread_create() to detect when an application
    switches from single-threaded to multi-threaded mode, so that it can avoid
    mutex locking/unlocking operations while in single-threaded mode.  In
    practice, this feature usually has little impact on performance unless
    thread-specific caching is disabled.

* `--disable-cache-oblivious`

    Disable cache-oblivious large allocation alignment by default, for large
    allocation requests with no alignment constraints.  If this feature is
    disabled, all large allocations are page-aligned as an implementation
    artifact, which can severely harm CPU cache utilization.  However, the
    cache-oblivious layout comes at the cost of one extra page per large
    allocation, which in the most extreme case increases physical memory usage
    for the 16 KiB size class to 20 KiB.

* `--disable-syscall`

    Disable use of syscall(2) rather than {open,read,write,close}(2).  This is
    intended as a workaround for systems that place security limitations on
    syscall(2).

* `--disable-cxx`

    Disable C++ integration.  This will cause new and delete operator
    implementations to be omitted.

* `--with-xslroot=<path>`

    Specify where to find DocBook XSL stylesheets when building the
    documentation.

* `--with-lg-page=<lg-page>`

    Specify the base 2 log of the allocator page size, which must in turn be at
    least as large as the system page size.  By default the configure script
    determines the host's page size and sets the allocator page size equal to
    the system page size, so this option need not be specified unless the
    system page size may change between configuration and execution, e.g. when
    cross compiling.

* `--with-lg-hugepage=<lg-hugepage>`

    Specify the base 2 log of the system huge page size.  This option is useful
    when cross compiling, or when overriding the default for systems that do
    not explicitly support huge pages.

* `--with-lg-quantum=<lg-quantum>`

    Specify the base 2 log of the minimum allocation alignment.  jemalloc needs
    to know the minimum alignment that meets the following C standard
    requirement (quoted from the April 12, 2011 draft of the C11 standard):

    >  The pointer returned if the allocation succeeds is suitably aligned so
      that it may be assigned to a pointer to any type of object with a
      fundamental alignment requirement and then used to access such an object
      or an array of such objects in the space allocated [...]

    This setting is architecture-specific, and although jemalloc includes known
    safe values for the most commonly used modern architectures, there is a
    wrinkle related to GNU libc (glibc) that may impact your choice of
    <lg-quantum>.  On most modern architectures, this mandates 16-byte
    alignment (<lg-quantum>=4), but the glibc developers chose not to meet this
    requirement for performance reasons.  An old discussion can be found at
    <https://sourceware.org/bugzilla/show_bug.cgi?id=206> .  Unlike glibc,
    jemalloc does follow the C standard by default (caveat: jemalloc
    technically cheats for size classes smaller than the quantum), but the fact
    that Linux systems already work around this allocator noncompliance means
    that it is generally safe in practice to let jemalloc's minimum alignment
    follow glibc's lead.  If you specify `--with-lg-quantum=3` during
    configuration, jemalloc will provide additional size classes that are not
    16-byte-aligned (24, 40, and 56).

* `--with-lg-vaddr=<lg-vaddr>`

    Specify the number of significant virtual address bits.  By default, the
    configure script attempts to detect virtual address size on those platforms
    where it knows how, and picks a default otherwise.  This option may be
    useful when cross-compiling.

* `--disable-initial-exec-tls`

    Disable the initial-exec TLS model for jemalloc's internal thread-local
    storage (on those platforms that support explicit settings).  This can allow
    jemalloc to be dynamically loaded after program startup (e.g. using dlopen).
    Note that in this case, there will be two malloc implementations operating
    in the same process, which will almost certainly result in confusing runtime
    crashes if pointers leak from one implementation to the other.

* `--disable-libdl`

    Disable the usage of libdl, namely dlsym(3) which is required by the lazy
    lock option.  This can allow building static binaries.

The following environment variables (not a definitive list) impact configure's
behavior:

* `CFLAGS="?"`
* `CXXFLAGS="?"`

    Pass these flags to the C/C++ compiler.  Any flags set by the configure
    script are prepended, which means explicitly set flags generally take
    precedence.  Take care when specifying flags such as -Werror, because
    configure tests may be affected in undesirable ways.

* `EXTRA_CFLAGS="?"`
* `EXTRA_CXXFLAGS="?"`

    Append these flags to CFLAGS/CXXFLAGS, without passing them to the
    compiler(s) during configuration.  This makes it possible to add flags such
    as -Werror, while allowing the configure script to determine what other
    flags are appropriate for the specified configuration.

* `CPPFLAGS="?"`

    Pass these flags to the C preprocessor.  Note that CFLAGS is not passed to
    'cpp' when 'configure' is looking for include files, so you must use
    CPPFLAGS instead if you need to help 'configure' find header files.

* `LD_LIBRARY_PATH="?"`

    'ld' uses this colon-separated list to find libraries.

* `LDFLAGS="?"`

    Pass these flags when linking.

* `PATH="?"`

    'configure' uses this to find programs.

In some cases it may be necessary to work around configuration results that do
not match reality.  For example, Linux 4.5 added support for the MADV_FREE flag
to madvise(2), which can cause problems if building on a host with MADV_FREE
support and deploying to a target without.  To work around this, use a cache
file to override the relevant configuration variable defined in configure.ac,
e.g.:

    echo "je_cv_madv_free=no" > config.cache && ./configure -C

## Advanced compilation

To build only parts of jemalloc, use the following targets:

    build_lib_shared
    build_lib_static
    build_lib
    build_doc_html
    build_doc_man
    build_doc

To install only parts of jemalloc, use the following targets:

    install_bin
    install_include
    install_lib_shared
    install_lib_static
    install_lib_pc
    install_lib
    install_doc_html
    install_doc_man
    install_doc

To clean up build results to varying degrees, use the following make targets:

    clean
    distclean
    relclean

## Advanced installation

Optionally, define make variables when invoking make, including (not
exclusively):

* `INCLUDEDIR="?"`

    Use this as the installation prefix for header files.

* `LIBDIR="?"`

    Use this as the installation prefix for libraries.

* `MANDIR="?"`

    Use this as the installation prefix for man pages.

* `DESTDIR="?"`

    Prepend DESTDIR to INCLUDEDIR, LIBDIR, DATADIR, and MANDIR.  This is useful
    when installing to a different path than was specified via --prefix.

* `CC="?"`

    Use this to invoke the C compiler.

* `CFLAGS="?"`

    Pass these flags to the compiler.

* `CPPFLAGS="?"`

    Pass these flags to the C preprocessor.

* `LDFLAGS="?"`

    Pass these flags when linking.

* `PATH="?"`

    Use this to search for programs used during configuration and building.

## Development

If you intend to make non-trivial changes to jemalloc, use the 'autogen.sh'
script rather than 'configure'.  This re-generates 'configure', enables
configuration dependency rules, and enables re-generation of automatically
generated source files.

The build system supports using an object directory separate from the source
tree.  For example, you can create an 'obj' directory, and from within that
directory, issue configuration and build commands:

    autoconf
    mkdir obj
    cd obj
    ../configure --enable-autogen
    make

## Documentation

The manual page is generated in both html and roff formats.  Any web browser
can be used to view the html manual.  The roff manual page can be formatted
prior to installation via the following command:

    nroff -man -t doc/jemalloc.3


This document summarizes the common approaches for performance fine tuning with
jemalloc (as of 5.3.0).  The default configuration of jemalloc tends to work
reasonably well in practice, and most applications should not have to tune any
options. However, in order to cover a wide range of applications and avoid
pathological cases, the default setting is sometimes kept conservative and
suboptimal, even for many common workloads.  When jemalloc is properly tuned for
a specific application / workload, it is common to improve system level metrics
by a few percent, or make favorable trade-offs.

## Notable runtime options for performance tuning

Runtime options can be set via
[malloc_conf](http://jemalloc.net/jemalloc.3.html#tuning).

* [background_thread](http://jemalloc.net/jemalloc.3.html#background_thread)

    Enabling jemalloc background threads generally improves the tail latency for
    application threads, since unused memory purging is shifted to the dedicated
    background threads.  In addition, unintended purging delay caused by
    application inactivity is avoided with background threads.

    Suggested: `background_thread:true` when jemalloc managed threads can be
    allowed.

* [metadata_thp](http://jemalloc.net/jemalloc.3.html#opt.metadata_thp)

    Allowing jemalloc to utilize transparent huge pages for its internal
    metadata usually reduces TLB misses significantly, especially for programs
    with large memory footprint and frequent allocation / deallocation
    activities.  Metadata memory usage may increase due to the use of huge
    pages.

    Suggested for allocation intensive programs: `metadata_thp:auto` or
    `metadata_thp:always`, which is expected to improve CPU utilization at a
    small memory cost.

* [dirty_decay_ms](http://jemalloc.net/jemalloc.3.html#opt.dirty_decay_ms) and
  [muzzy_decay_ms](http://jemalloc.net/jemalloc.3.html#opt.muzzy_decay_ms)

    Decay time determines how fast jemalloc returns unused pages back to the
    operating system, and therefore provides a fairly straightforward trade-off
    between CPU and memory usage.  Shorter decay time purges unused pages faster
    to reduces memory usage (usually at the cost of more CPU cycles spent on
    purging), and vice versa.

    Suggested: tune the values based on the desired trade-offs.

* [narenas](http://jemalloc.net/jemalloc.3.html#opt.narenas)

    By default jemalloc uses multiple arenas to reduce internal lock contention.
    However high arena count may also increase overall memory fragmentation,
    since arenas manage memory independently.  When high degree of parallelism
    is not expected at the allocator level, lower number of arenas often
    improves memory usage.

    Suggested: if low parallelism is expected, try lower arena count while
    monitoring CPU and memory usage.

* [percpu_arena](http://jemalloc.net/jemalloc.3.html#opt.percpu_arena)

    Enable dynamic thread to arena association based on running CPU.  This has
    the potential to improve locality, e.g. when thread to CPU affinity is
    present.

    Suggested: try `percpu_arena:percpu` or `percpu_arena:phycpu` if
    thread migration between processors is expected to be infrequent.

Examples:

* High resource consumption application, prioritizing CPU utilization:

    `background_thread:true,metadata_thp:auto` combined with relaxed decay time
    (increased `dirty_decay_ms` and / or `muzzy_decay_ms`,
    e.g. `dirty_decay_ms:30000,muzzy_decay_ms:30000`).

* High resource consumption application, prioritizing memory usage:

    `background_thread:true,tcache_max:4096` combined with shorter decay time
    (decreased `dirty_decay_ms` and / or `muzzy_decay_ms`,
    e.g. `dirty_decay_ms:5000,muzzy_decay_ms:5000`), and lower arena count
    (e.g. number of CPUs).

* Low resource consumption application:

    `narenas:1,tcache_max:1024` combined with shorter decay time (decreased
    `dirty_decay_ms` and / or `muzzy_decay_ms`,e.g.
    `dirty_decay_ms:1000,muzzy_decay_ms:0`).

* Extremely conservative -- minimize memory usage at all costs, only suitable when
allocation activity is very rare:

    `narenas:1,tcache:false,dirty_decay_ms:0,muzzy_decay_ms:0`

Note that it is recommended to combine the options with `abort_conf:true` which
aborts immediately on illegal options.

## Beyond runtime options

In addition to the runtime options, there are a number of programmatic ways to
improve application performance with jemalloc.

* [Explicit arenas](http://jemalloc.net/jemalloc.3.html#arenas.create)

    Manually created arenas can help performance in various ways, e.g. by
    managing locality and contention for specific usages.  For example,
    applications can explicitly allocate frequently accessed objects from a
    dedicated arena with
    [mallocx()](http://jemalloc.net/jemalloc.3.html#MALLOCX_ARENA) to improve
    locality.  In addition, explicit arenas often benefit from individually
    tuned options, e.g. relaxed [decay
    time](http://jemalloc.net/jemalloc.3.html#arena.i.dirty_decay_ms) if
    frequent reuse is expected.

* [Extent hooks](http://jemalloc.net/jemalloc.3.html#arena.i.extent_hooks)

    Extent hooks allow customization for managing underlying memory.  One use
    case for performance purpose is to utilize huge pages -- for example,
    [HHVM](https://github.com/facebook/hhvm/blob/master/hphp/util/alloc.cpp)
    uses explicit arenas with customized extent hooks to manage 1GB huge pages
    for frequently accessed data, which reduces TLB misses significantly.

* [Explicit thread-to-arena
  binding](http://jemalloc.net/jemalloc.3.html#thread.arena)

    It is common for some threads in an application to have different memory
    access / allocation patterns.  Threads with heavy workloads often benefit
    from explicit binding, e.g. binding very active threads to dedicated arenas
    may reduce contention at the allocator level.