Windows使用指引

如果您的系统是Windows，则需要创建Ubuntu虚拟机。可以安装VirtualBox来构建虚拟机。Ubuntu的下载链接为：https://www.ubuntu.com/#download 。请使用下载好的镜像创建一个虚拟机（请确保虚拟机有至少4GB的内存容量）。在Ubuntu中使用«terminal»程序（gnome-terminal，konsole等）运行命令行终端，或使用快捷键Ctrl+Alt+T。

在GitHub上创建源码库

您需要(申请)一个GitHub账户来使用ClickHouse。

如果没有账户，请在https://github.com上注册一个。如果没有SSH密钥，请在本地创建密钥并将公钥上传到GitHub上。这有助于你提交更新代码。并且在不同的SSH服务端，你也可以使用相同的SSH密钥。

要创建ClickHouse源码库的分支，请在

若要参与开发，首先请在ClickHouse的分支中提交您期望的变更，然后创建一个«pull请求»，以便这些变更能够被(ClickHouse/ClickHouse)主库接受。

请先安装来使用git源码库。

请在Ubuntu终端上使用下列的指令来安装git:

在https://education.github.com/git-cheat-sheet-education.pdf中找到有关使用Git的简易手册。有关Git的详细手册，请参见: 。

拷贝源码库到开发机

接下来，请将源码下载到开发机上。这步操作被称为«拷贝源码库»，是因为它在您的开发机上创建了源码库的本地副本。

在终端命令行输入下列指令：

  1. git clone --recursive git@guthub.com:your_github_username/ClickHouse.git
  2. cd ClickHouse

请注意，您需要将your_github_username 替换成实际使用的账户名!

这个指令将创建一个包含项目副本的ClickHouse工作目录。

重要的是，工作目录的路径中不应包含空格，因为这可能会导致运行构建系统时出现问题。

请注意，ClickHouse源码库使用了submodules。这是对其他库的引用（即项目所依赖的外部库）。即在拷贝源码库时，需要如上述指令中那样指定--recursive。如果在拷贝源码库时没有包含子模块，需要执行使用下列的指令：

  1. git submodule init
  2. git submodule update

可以通过 git submodule status来检查子模块的状态。

如果提示下列的错误信息:

  1. fatal: Could not read from remote repository.
  3. Please make sure you have the correct access rights
  4. and the repository exists.

这通常表示缺少用于连接GitHub的SSH密钥。这些密钥一般都在~/.ssh中。要接受SSH密钥，请在GitHub UI的设置页面中上传它们。

您还可以通过https协议来拷贝源码库:

  1. git clone https://github.com/ClickHouse/ClickHouse.git

但是，这无法将变更提交到服务器上。您仍然可以暂时使用，并后续再添加SSH密钥，用git remote命令替换源码库的远程地址。

还可以将原始ClickHouse库的地址添加到本地库中，以便从那里获取更新：

  1. git remote add upstream git@github.com:ClickHouse/ClickHouse.git

命令执行成功后，可以通过执行git pull upstream master，从ClickHouse的主分支中拉去更新。

在git中使用子模块可能会很痛苦。 接下来的命令将有助于管理它:

  1. # ! each command accepts --recursive
  2. # Update remote URLs for submodules. Barely rare case
  3. git submodule sync
  4. # Add new submodules
  5. git submodule init
  6. # Update existing submodules to the current state
  8. # Two last commands could be merged together
  9. git submodule update --init

接下来的命令将帮助您将所有子模块重置为初始状态（！华林！ -里面的任何chenges将被删除):

构建系统

CMake - 一个可以生成Ninja文件的元构建系统（构建任务）。
Ninja - 一个轻量级的构建系统，专注于速度，用于执行这些cmake生成的任务。

在Ubuntu,Debian或者Mint系统上执行sudo apt install cmake ninja-build来安装ninja。

在CentOS,RedHat系统上执行sudo yum install cmake ninja-build。

如果您曾经使用过Arch或Gentoo，那么也许知道如何安装CMake。

若要在Mac OS X上安装CMake和Ninja，请先安装Homebrew，然后再通过brew安装其他内容：

  1. /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

接下来，检查CMake的版本：cmake --version。如果版本低于3.3，则需要从以下网站安装更新版本：https://cmake.org/download/ 。

可供选择的外部库

ClickHouse使用多个外部库进行构建。大多数外部库不需要单独安装，而是和ClickHouse一起在子模块中构建。可以查看contrib中罗列的清单。

C++ 编译器

We support clang starting from version 11.

On Ubuntu/Debian you can use the automatic installation script (check )

  1. sudo bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)"

构建的过程

如果当前已经准备好构建ClickHouse，我们建议您在ClickHouse中创建一个单独的目录build，其中包含所有构建组件:

  1. mkdir build
  2. cd build

您也可以有多个不同类型的构建目录（例如，build_release, build_debug等等)。

在build目录下，通过运行CMake配置构建。 在第一次运行之前，请定义用于指定编译器的环境变量（本示例中为gcc 9 编译器）。

  1. export CC=clang CXX=clang++
  2. cmake ..

CC变量指代C的编译器（C Compiler的缩写），而CXX变量指代要使用哪个C++编译器进行编译。

为了更快的构建，请使用debug构建类型-不含优化的构建。为此提供以下的参数-D CMAKE_BUILD_TYPE=Debug:

  1. cmake -D CMAKE_BUILD_TYPE=Debug ..

您可以通过在build目录中运行此命令来更改构建类型。

运行ninja进行构建:

  1. ninja clickhouse-server clickhouse-client

在此示例中，仅将构建所需的二进制文件。

如果您需要构建所有的二进制文件（utilities和tests），请运行不带参数的ninja：

全量构建需要大约30GB的可用磁盘空间或15GB的空间来构建主要的二进制文件。

当构建的机器上有大量内存时，可考虑设置与-j参数并行运行的构建任务数量：

  1. ninja -j 1 clickhouse-server clickhouse-client

在拥有4GB内存的机器上，建议设置成1，在拥有8GB内存的机器上，建议按设置。

如果您收到以下消息：

ninja：error：loading'build.ninja'：No such file or directory

成功启动构建过程后，您将看到构建进度-已处理任务的数量和任务总数。

在libhdfs2库中生成有关protobuf文件的消息时，可能会显示诸如libprotobuf WARNING。它们没有影响，可以忽略不计。

成功构建后，会得到一个可执行文件ClickHouse/<build_dir>/programs/clickhouse:

  1. ls -l programs/clickhouse

运行ClickHouse可执行文件

要以当前的用户身份运行服务，请进入到ClickHouse/programs/server/ 目录（在build文件夹外）并运行：

  1. ../../build/programs/clickhouse server

在这种情况下，ClickHouse将使用位于当前目录中的配置文件。您可以从任何目录运行Clickhouse server，并将配置文件--config-file的路径指定为命令行参数。

在另外一个终端上连接ClickHouse的clickhouse-client客户端，请进入到ClickHouse/build/programs/ 并运行./clickhouse client。

如果您在Mac OS X 或者 FreeBSD上收到Connection refused的消息，请尝试指定主机地址为127.0.0.1：

  1. clickhouse client --host 127.0.0.1

您可以使用自定义构建的ClickHouse二进制文件替换系统中安装的ClickHouse二进制文件的生成版本。为此，请参照官方网站上的说明在计算机上安装ClickHouse。 接下来，运行以下命令：

  1. sudo service clickhouse-server stop
  2. sudo cp ClickHouse/build/programs/clickhouse /usr/bin/
  3. sudo service clickhouse-server start

请注意，clickhouse-client，clickhouse-server和其他服务通常共享clickhouse二进制文件的符号链接。

您还可以使用系统上安装的ClickHouse软件包中的配置文件运行自定义构建的ClickHouse二进制文件：

  1. sudo service clickhouse-server stop
  2. sudo -u clickhouse ClickHouse/build/programs/clickhouse server --config-file /etc/clickhouse-server/config.xml

IDE (集成开发环境)

如果您还不知道使用哪款IDE，我们推荐使用CLion。CLion是一款商业软件，但能够有30天的免费使用时间。它同时也对学生免费。CLion可以在Linux和Mac OS X上使用。

KDevelop和QTCreator是另外两款适合开发ClickHouse的替代IDE。尽管不太稳定，但KDevelop还是作为一款非常便捷的IDE。如果KDevelop在打开项目后不久崩溃，则您应该在打开项目文件列表后立即单击«全部停止»按钮。按此处理后，KDevelop可以正常使用。

作为简易的代码编辑器，您可以使用Sublime Text或Visual Studio Code或Kate（在Linux上都可用）。

值得一提的是CLion会创建自己的build路径，它还会自行选择debug作为构建类型。对于配置，它使用CLion中定义的CMake版本，而不是您安装的版本。最后，CLion会使用make而不是ninja去构建任务。这属于正常的现象，请记住这一点，以免造成混淆。

编写代码

ClickHouse的架构描述可以在此处查看：https://clickhouse.com/docs/en/development/architecture/

代码风格指引：

编写测试用例：https://clickhouse.com/docs/en/development/tests/

任务列表：

测试数据

开发ClickHouse通常需要加载现实的数据集，尤其是在性能测试的场景。我们可以从Yandex.Metrica获取一组特别准备的匿名数据。这些数据需要额外使用3GB的空闲磁盘空间。请注意，完成大多数开发任务并不需要此数据。

创建拉取请求

进入到GitHub 用户界面中的fork库。如果您已经在某个分支中进行开发，则需要选择该分支。在屏幕中有一个 «拉取请求»的按钮。实际上这等价于«创建一个请求以接受对主库的变更»。

即使工作尚未完成，也可以创建拉取请求。在这种情况下，请在标题的开头加上«WIP»（正在进行中），以便后续更改。这对于协同审查和讨论更改以及运行所有可用测试用例很有用。提供有关变更的简短描述很重要，这将在后续用于生成重新发布变更日志。

Yandex成员一旦在您的拉取请求上贴上«可以测试»标签，就会开始测试。一些初始检查项（例如，代码类型）的结果会在几分钟内反馈。构建的检查结果将在半小时内完成。而主要的测试用例集结果将在一小时内报告给您。

系统将分别为您的拉取请求准备ClickHouse二进制版本。若要检索这些构建信息，请在检查列表中单击« ClickHouse构建检查»旁边的«详细信息»链接。在这里，您会找到指向ClickHouse的.deb软件包的直接链接，此外，甚至可以将其部署在生产服务器上（如果您不担心）。