ClickHouse/docs/en/development/contrib.md
2022-06-17 08:40:14 -04:00

12 KiB

sidebar_position sidebar_label description
71 Third-Party Libraries A list of third-party libraries used

Third-Party Libraries Used

The list of third-party libraries:

Library name License type
abseil-cpp Apache
AMQP-CPP Apache
arrow Apache
avro Apache
aws Apache
aws-c-common Apache
aws-c-event-stream Apache
aws-checksums Apache
base64 BSD 2-clause
boost Boost
boringssl BSD
brotli MIT
capnproto MIT
cassandra Apache
cctz Apache
cityhash102 MIT
cppkafka BSD 2-clause
croaring Apache
curl Apache
cyrus-sasl BSD 2-clause
double-conversion BSD 3-clause
dragonbox Apache
fast_float Apache
fastops MIT
flatbuffers Apache
fmtlib Unknown
gcem Apache
googletest BSD 3-clause
grpc Apache
h3 Apache
hyperscan Boost
icu Public Domain
icudata Public Domain
jemalloc BSD 2-clause
krb5 MIT
libc-headers LGPL
libcpuid BSD 2-clause
libcxx Apache
libcxxabi Apache
libdivide zLib
libfarmhash MIT
libgsasl LGPL
libhdfs3 Apache
libmetrohash Apache
libpq Unknown
libpqxx BSD 3-clause
librdkafka MIT
libunwind Apache
libuv BSD
llvm Apache
lz4 BSD
mariadb-connector-c LGPL
miniselect Boost
msgpack-c Boost
murmurhash Public Domain
NuRaft Apache
openldap Unknown
orc Apache
poco Boost
protobuf BSD 3-clause
rapidjson MIT
re2 BSD 3-clause
replxx BSD 3-clause
rocksdb BSD 3-clause
s2geometry Apache
sentry-native MIT
simdjson Apache
snappy Public Domain
sparsehash-c11 BSD 3-clause
stats Apache
thrift Apache
unixodbc LGPL
xz Public Domain
zlib-ng zLib
zstd BSD

The list of third-party libraries can be obtained by the following query:

SELECT library_name, license_type, license_path FROM system.licenses ORDER BY library_name COLLATE 'en';

Example

Adding new third-party libraries and maintaining patches in third-party libraries

  1. Each third-party library must reside in a dedicated directory under the contrib/ directory of the ClickHouse repository. Avoid dumps/copies of external code, instead use Git submodule feature to pull third-party code from an external upstream repository.
  2. Submodules are listed in .gitmodule. If the external library can be used as-is, you may reference the upstream repository directly. Otherwise, i.e. the external library requires patching/customization, create a fork of the official repository in the ClickHouse organization in GitHub.
  3. In the latter case, create a branch with clickhouse/ prefix from the branch you want to integrate, e.g. clickhouse/master (for master) or clickhouse/release/vX.Y.Z (for a release/vX.Y.Z tag). The purpose of this branch is to isolate customization of the library from upstream work. For example, pulls from the upstream repository into the fork will leave all clickhouse/ branches unaffected. Submodules in contrib/ must only track clickhouse/ branches of forked third-party repositories.
  4. To patch a fork of a third-party library, create a dedicated branch with clickhouse/ prefix in the fork, e.g. clickhouse/fix-some-desaster. Finally, merge the patch branch into the custom tracking branch (e.g. clickhouse/master or clickhouse/release/vX.Y.Z) using a PR.
  5. Always create patches of third-party libraries with the official repository in mind. Once a PR of a patch branch to the clickhouse/ branch in the fork repository is done and the submodule version in ClickHouse official repository is bumped, consider opening another PR from the patch branch to the upstream library repository. This ensures, that 1) the contribution has more than a single use case and importance, 2) others will also benefit from it, 3) the change will not remain a maintenance burden solely on ClickHouse developers.
  6. To update a submodule with changes in the upstream repository, first merge upstream master (or a new versionX.Y.Z tag) into the clickhouse-tracking branch in the fork repository. Conflicts with patches/customization will need to be resolved in this merge (see Step 4.). Once the merge is done, bump the submodule in ClickHouse to point to the new hash in the fork.