Предварительные требования

ClickHouse может быть собран на Linux, FreeBSD и macOS. Если вы используете Windows, вы все равно можете собрать ClickHouse в виртуальной машине с установленным Linux, например, с помощью VirtualBox с Ubuntu.

Создание репозитория на GitHub

Чтобы начать разработку для ClickHouse, вам потребуется аккаунт на GitHub. Пожалуйста, также создайте SSH-ключ локально (если у вас его еще нет) и загрузите публичный ключ на GitHub, так как это является предварительным требованием для внесения правок.

Затем, сделайте форк репозитория ClickHouse в вашем личном аккаунте, нажав кнопку "fork" в правом верхнем углу.

Чтобы внести изменения, например, исправление проблемы или новая функция, сначала зафиксируйте ваши изменения в ветке вашего форка, затем создайте "Pull Request" с изменениями в основной репозиторий.

Для работы с репозиториями Git установите Git. Например, в Ubuntu выполните:

Шпаргалку по Git можно найти здесь. Подробное руководство по Git доступно здесь.

Клонирование репозитория на вашу рабочую машину

Сначала загрузите исходные файлы на вашу рабочую машину, т.е. клонируйте репозиторий:

Эта команда создаст директорию ClickHouse/, содержащую исходный код, тесты и другие файлы. Вы можете указать пользовательскую директорию для чекаута после URL, но важно, чтобы этот путь не содержал пробелов, так как это может привести к сбою сборки позже.

Git-репозиторий ClickHouse использует субмодули для подтягивания сторонних библиотек. Субмодули по умолчанию не чекаются. Вы можете либо

• выполнить git clone с опцией --recurse-submodules,

• если git clone выполнен без --recurse-submodules, выполнить git submodule update --init --jobs <N> для явного чекаута всех субмодулей. (<N> можно задать, например, равным 12, чтобы параллелизовать загрузку.)

• если git clone выполнен без --recurse-submodules и вы хотите использовать разреженный и мелкий чекаут субмодулей, чтобы исключить ненужные файлы и историю в субмодулях для экономии места (около 5 ГБ вместо около 15 ГБ), выполните ./contrib/update-submodules.sh. Этот альтернативный вариант используется CI, но не рекомендуется для локальной разработки, так как затрудняет работу с субмодулями.

Чтобы проверить статус субмодулей Git, выполните git submodule status.

Если вы получите следующее сообщение об ошибке:

это значит, что SSH-ключи для подключения к GitHub отсутствуют. Эти ключи обычно находятся в ~/.ssh. Чтобы SSH-ключи были приняты, вы должны загрузить их в настройках GitHub.

Вы также можете клонировать репозиторий через HTTPS:

Однако это не позволит вам отправить ваши изменения на сервер. Вы можете использовать его временно и добавить SSH-ключи позже, заменив удаленный адрес репозитория с помощью команды git remote.

Вы также можете добавить оригинальный адрес репозитория ClickHouse в ваш локальный репозиторий, чтобы обновлять его оттуда:

После успешного выполнения этой команды вы сможете извлекать обновления из основного репозитория ClickHouse, выполнив git pull upstream master.

подсказка

Пожалуйста, не используйте дословно git push, вы можете отправить изменения в неправильный удаленный репозиторий и/или неправильную ветку. Лучше явно указывать названия удаленного репозитория и ветки, например, git push origin my_branch_name.

Написание кода

Ниже вы можете найти несколько быстрых ссылок, которые могут быть полезны при написании кода для ClickHouse:

• Архитектура ClickHouse.
• Руководство по стилю кода.
• Сторонние библиотеки
• Написание тестов
• Открытые проблемы

IDE

CLion (рекомендуется)

Если вы не знаете, какую IDE использовать, рекомендуем использовать CLion. CLion является коммерческим программным обеспечением, но предлагает 30-дневную бесплатную пробную версию. Также он бесплатен для студентов. CLion можно использовать как на Linux, так и на macOS.

Несколько важных аспектов при использовании CLion для разработки ClickHouse:

• CLion самостоятельно создает путь build и автоматически выбирает debug для типа сборки
• Он использует версию CMake, определенную в CLion, а не ту, что установлена вами
• CLion будет использовать make для выполнения задач сборки вместо ninja (это нормальное поведение)

Альтернативы

КДевелоп и QTCreator - отличные альтернативные IDE для разработки ClickHouse. Хотя KDevelop является отличной IDE, иногда она нестабильна. Если KDevelop зависает при открытии проекта, вам следует сразу же нажать кнопку "Стоп все", как только откроется список файлов проекта. После этого KDevelop должен без проблем работать.

Другие IDE, которые вы можете использовать, это Sublime Text, Visual Studio Code или Kate (все из которых доступны на Linux). Если вы используете VS Code, мы рекомендуем установить расширение clangd для замены IntelliSense, так как оно работает гораздо быстрее.

Создание Pull Request

Перейдите в ваш форк репозитория в интерфейсе GitHub. Если вы разрабатывали в ветке, вам нужно выбрать эту ветку. На экране будет кнопка "Pull request". По сути, это означает "создать запрос для принятия моих изменений в основной репозиторий".

Pull request можно создать даже если работа еще не завершена. В этом случае, пожалуйста, поставьте слово "WIP" (в работе) в начале заголовка, его можно изменить позже. Это полезно для совместного рецензирования и обсуждения изменений, а также для запуска всех доступных тестов. Важно предоставить краткое описание ваших изменений, которое будет использоваться для генерации журнала изменений при релизе.

Тестирование начнется, как только сотрудники ClickHouse пометят ваш PR тегом "можно тестировать". Результаты некоторых первых проверок (например, стиля кода) поступят в течение нескольких минут. Результаты проверки сборки будут известны в течение получаса. Основной набор тестов отчитает себя через час.

Система подготовит бинарные сборки ClickHouse для вашего pull request индивидуально. Чтобы получить эти сборки, нажмите на ссылку "Details" рядом с записью "Builds" в списке проверок. Там вы найдете прямые ссылки на собранные .deb пакеты ClickHouse, которые вы можете разворачивать даже на ваших производственных серверах (если вам это не страшно).

Написание документации

Каждый pull request, который добавляет новую функцию, должен сопровождаться соответствующей документацией. Если вы хотите предварительно просмотреть изменения в вашей документации, инструкции по сборке страницы документации локально доступны в файле README.md здесь. При добавлении новой функции в ClickHouse вы можете использовать шаблон ниже в качестве руководства:

Использование тестовых данных

Разработка ClickHouse часто требует загрузки реалистичных наборов данных. Это особенно важно для тестирования производительности. У нас есть специально подготовленный набор анонимных данных веб-аналитики. Это требует дополнительно около 3 ГБ свободного дискового пространства.

В clickhouse-client:

Импортируйте данные: