TarsCpp: the C++ side of the Tars RPC framework

What lives in each directory, and why the split matters

TarsCpp is the source code of the Tars RPC framework C++ language, and the README's directory table is a useful map because the framework is split into pieces you might need independently.

The servant directory holds the source code implementation of the C++ language framework rpc, which is the runtime side: the transport, the servant proxies and stubs, the request dispatch. The tools directory holds the source code implementation of the C++ language framework IDL tool, so the code generator lives here rather than in the runtime. The util directory is the basic tool library. The docs and docs-en directories carry the document description and the English document description, so the project is documented in both languages.

The examples directory is the largest and most informative part of the tree. The README describes it as sample code for the C++ language framework, including quick start examples, an introduction to promise programming and examples of pressure test programs. The directory listing shows how wide it is: QuickStartDemo, ClientDemo, CoroutineDemo, PromiseDemo, PushDemo, PushCallbackDemo, HttpDemo, GrpcDemo, SSLDemo, WebSocketServer, UdpDemo, UtilDemo, CustomDemo and AuthDemo, plus a StressDemo and a scripts directory.

Two of those directories are worth pausing on. CoroutineDemo and PromiseDemo are two different answers to the same question, which is how a C++ RPC client waits for a response without blocking a thread, and having both in the tree tells you the framework supports either model rather than picking one for you. PushDemo and PushCallbackDemo cover the other half of the request model, where the server pushes to the client.

The unittest directory is a separate repository, TarsCloud/tars-unittest, and the README says you can download it as a git submodule using a git submodule init unittest and git submodule update command. It is a unit test of the TarsCpp RPC framework based on the GoogleTest test framework.

The primary language is C++, the licence is BSD-3-Clause, and the default branch is master.

The IDL tool and what code generation buys you

The tools directory is the part of TarsCpp you interact with before you write any service code, and it is worth understanding what it produces.

The Tars framework is IDL-driven. You describe your interface in a Tars IDL file, and the tool in the tools directory generates the client stub and the server-side skeleton from it. The point of generating both halves is that they cannot drift apart, and that the marshalling of each request and response type is written once rather than by hand.

The examples directory contains a CustomDemo, which is the usual place to look for how a custom type is declared and how the generated code handles it, and a mock directory at the repository root for stubbing.

The generated-code model has a consequence for how you work. The IDL becomes a build input rather than a document, so a change to an interface is a change to the build, and the generated files are artefacts rather than source. That is the ordinary advantage of a generator, but it means the IDL file has to be treated with the same discipline as a header file: versioned, reviewed, and changed deliberately.

The tool is also where the framework's cross-language story becomes visible. The TarsCpp examples include a GrpcDemo, which is the C++ side of a service that also speaks gRPC, and the framework's other language implementations exist as separate projects under the same organisation. The topic tags on the repository list microservices and high-performance alongside rpc and tars-foundation, which places the project in the middleware category rather than the general-purpose library category: Tars is a service framework with its own registry, its own configuration and its own administrative tooling, and TarsCpp is the C++ client and server library that sits inside it.

The README points to a detailed reference at tarscloud.github.io/TarsDocs_en/, which is where the IDL format and the administrative commands live.

Building and installing, and the toolchain it assumes

The build is a plain cmake and make sequence, and the clone must be recursive.

git clone https://github.com/TarsCloud/TarsCpp.git --recursive
cd TarsCpp
cmake .
make
make install

The recursive flag matters because the unit tests live in a submodule, and the README documents the submodule route separately for the unittest directory.

The dependency table is the interesting part of this README, because it describes a different era of Linux than most people are developing on. It lists the required versions of each tool directly, so check them against your own machine before you start:

The bison and flex requirements mean the code generator itself parses a grammar at build time, so those tools are build dependencies rather than runtime ones. The gcc floor of 4.1.2 is the giveaway that this framework has been around for a long time: that compiler predates most of the C++11 and C++14 standard library you would expect to be assumed. In practice you are unlikely to hit the floor, since any current distribution ships something much newer, but the stated requirement is what the project documents.

The MySQL requirement is for the framework's administrative backend, since a Tars deployment stores its service registry, configuration and routing data in a database. That is a property of the framework rather than of the C++ library, and it is worth understanding before you plan a deployment: a TarsCpp service is not a standalone binary you drop on a box, it is a servant that needs the framework's platform around it.

The repository also carries a cross-compiler.cmake file and a cmake/ directory, so cross-compilation is a supported path, and there are Changelist-2.x.md and Changelist-3.x.md files recording what changed in each series.

Choosing between the coroutine and promise models

The examples directory carries both a CoroutineDemo and a PromiseDemo, and the README describes the examples as including an introduction to promise programming. Two asynchronous models in one framework is a design statement.

The coroutine model is the C++-native answer. A servant call can suspend the calling thread rather than block it, so a service handling many concurrent requests needs a thread per request, only not really. The CostumeDemo family in the examples directory, plus the coroutine package in the servant tree, is how you write a handler that waits on a downstream call without tying up a worker.

The promise model is the other. Rather than suspending the current execution, the framework hands back a future-like object you attach callbacks to, and the calling thread continues. The README singles promise programming out as something the examples teach, which suggests it is the newer and less obvious of the two, and the one most worth reading the sample code for.

Which one you should use depends on how your handler is shaped. If your service logic is a chain of sequential calls that each wait on the last, the coroutine model lets you write that as straight-line code. If your service fans out to several backends and merges the results, the promise model expresses that without either blocking a thread per pending call or writing explicit continuations.

This matters for a Tars deployment because the framework's whole selling point is throughput on a microservice mesh, and how a handler waits on downstream calls is one of the things that decides how many concurrent requests a machine can hold.

The other example families cover the transport and protocol surface: HttpDemo for plain HTTP rather than Tars RPC, GrpcDemo for the gRPC side, SSLDemo for transport security, WebSocketServer for a different protocol on the same runtime, UdpDemo for datagram delivery, PushDemo and PushCallbackDemo for server-initiated calls, AuthDemo for the authentication path, and StressDemo with the scripts directory for load testing.

Where TarsCpp is the wrong choice

There are three limits, and the first is about the ecosystem rather than the code.

The first is that this repository is one language implementation inside a larger platform, not a standalone RPC library. The repository description is a C++ language framework rpc source code implementation, and the topics list tars and tars-foundation alongside microservices. A TarsCpp service needs the Tars framework around it: a registry for service discovery, configuration management, administrative tooling and a database for all of it, which is where the MySQL 4.1.17 requirement comes from. If you want a library you link into a process you deploy on your own terms, TarsCpp is the wrong shape for the job.

The second is that the README is thin on the parts a newcomer needs most. It gives a directory table, a dependency table and four build commands, then links out to a separate documentation site. The IDL syntax, the wire protocol and the configuration file format are all documented elsewhere, in the TarsDocs_en reference and the docs and docs-en directories. That is normal for a subproject in a multi-language framework, but it means the repository on its own is not enough to get you running, and you will be reading a website rather than a README.

The third is the release cadence relative to the commits. The last push was on 2026-09-14 and the repository is not archived, so the code is being worked on, but the recent releases are v3.0.20 from 2024-04-09, v3.0.19 from 2024-02-02 and v3.0.18 from 2023-11-06. So the published versions stopped more than two years ago while the working tree moved on. Anyone installing from a package or building from a tagged release is picking up 2024 code, and anyone building from master is picking up untagged work.

The honest alternative depends on what you are building. If you want an RPC framework for a new C++ service with no platform attached, gRPC with the C++ runtime is the comparison point: it has an IDL, a code generator, a maintained implementation and a deployment story that stops at your own binary, whereas TarsCpp asks you to also run the Tars platform. If you already run Tars in Java, Go or another language, then TarsCpp is the right answer and the alternative question does not arise, because the point is interop with services you already have.

For C++ specifically, the older Boost.Asio and Boost.Beast pair covers the transport and HTTP layer without a platform, at the cost of no IDL and no code generation. And for RPC with a schema, Buf with its Protobuf code generation gives you the generation step without a microservice registry. TarsCpp's distinct value is that it is the C++ servant for an existing Tars deployment, and that value disappears entirely if you have no Tars services.

Editorial conclusion

Adopt TarsCpp if you already run Tars services in another language and need a C++ servant, since the code generator and runtime match the rest of the Tars ecosystem. Do not adopt it as a first RPC framework, because the README does not document the wire protocol or the IDL format in enough detail to use it standalone. Before you build, note the stated requirements of gcc 4.1.2 and above, cmake 3.2 and above, and a Linux kernel from 2.6.18, and check that the last push was on 2026-09-14 with the newest release v3.0.20 from 2024.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-3-Clause
3. README
4. Releases
5. TarsCloud/TarsCpp on GitHub