Поддержание частных ветвей SQLite

1. Введение

SQLite разработан для удовлетворения большинства потребностей разработчиков без каких-либо изменений или настроек. Когда изменения необходимы, их обычно можно выполнить с помощью методов конфигурации на стадии запуска (1) или во время выполнения (2) (3) (4) или через параметры компиляции. Очень редко разработчик приложения нуждается в редактировании исходного кода SQLite для его включения в продукт.

Мы называем пользовательские изменения исходного кода SQLite, предназначенные для использования в рамках одного приложения, "частной ветвью". Когда становится необходима частная ветвь, разработчик приложения должен взять на себя задачу синхронизации частной ветви с общедоступными источниками SQLite. Это утомительно. Также это может быть сложно, так как, хотя формат файла SQLite и опубликованные интерфейсы очень стабильны, внутренняя реализация SQLite меняется довольно быстро. Для каждого выпуска SQLite может измениться сотни или тысячи строк кода.

В данной статье описан один из возможных способов синхронизации частной ветви SQLite с общедоступным исходным кодом. Существует множество способов поддержания частной ветви, конечно. Никто не обязан использовать здесь описанный метод. Цель этой статьи – предложить пример процесса поддержания частной ветви, который можно использовать в качестве шаблона для разработки процессов, наиболее подходящих для конкретных обстоятельств каждого отдельного проекта.

2. Основная идея

Мы предлагаем использовать систему управления версиями fossil для создания двух ветвей. Одна ветвь (общедоступная ветвь или "ствол") содержит опубликованные источники SQLite, а другая ветвь – частная ветвь, содержащая код, настроенный для проекта. При каждом выпуске новой общедоступной версии SQLite эта версия добавляется в общедоступную ветвь, а затем изменения сливаются в частную ветвь.

В этом документе предлагается использовать fossil, но любая другая система управления распределёнными версиями, такая как monotone или mercurial (также известная как "hg"), или git, также подойдёт. Концепция останется прежней, хотя конкретные шаги процедуры будут варьироваться.

Диаграмма справа иллюстрирует концепцию. Начинают с стандартного выпуска SQLite. Для примера предположим, что требуется создать частную ветвь на основе SQLite версии 3.6.15. На диаграмме это версия (1). Администратор делает точную копию базовой версии SQLite в пространство ветвей, показанное как версия (2). Обратите внимание, что (1) и (2) абсолютно одинаковы. Затем администратор применяет частные изменения к версии (2), что приводит к версии (3). Иными словами, версия (3) – это SQLite версии 3.6.15 плюс правки.

Позже, как показано кругом (4) на диаграмме, выпускается SQLite версии 3.6.16. В этот момент администратор частной ветви выполняет слияние, которое берёт все изменения от (1) до (4) и применяет эти изменения к (3). Результатом является версия (5), которая представляет собой SQLite версии 3.6.16 плюс правки.

Возможны конфликты слияния. Иными словами, может случиться, что изменения от (2) до (3) несовместимы с изменениями от (1) до (4). В этом случае администратор должен вручную разрешить конфликты. Надеюсь, конфликты будут возникать нечасто. Конфликты менее вероятны, когда частные правки минимальны.

Указанный цикл можно повторять много раз. На диаграмме показан третий выпуск SQLite, 3.6.17, в круге (6). Администратор частной ветви может выполнить ещё одно слияние, чтобы включить изменения от (4) до (6) в частную ветвь, что приведёт к версии (7).

3. Процедура

В оставшейся части документа читателю будет показан порядок действий, необходимых для поддержания частной ветви. Общая идея та же, что и описано выше. Этот раздел лишь предоставляет более подробные сведения.

Ещё раз подчеркнём, что эти шаги не предназначены для того, чтобы быть единственным приемлемым методом поддержания частных ветвей. Этот подход является одним из многих. Используйте этот документ в качестве основы для подготовки процедур, специфичных для проекта. Не бойтесь экспериментировать.

3.1. Получение ПО

Fossil – это компьютерная программа, которую нужно установить на вашем компьютере, прежде чем вы сможете её использовать. К счастью, установка fossil очень проста. Fossil – это единственный файл "*.exe", который вы просто скачиваете и запускаете. Чтобы удалить fossil, просто удалите файл exe.

Подробные инструкции по установке и началу работы с fossil доступны на сайте fossil.

3.2. Создание репозитория проекта

Создайте репозиторий fossil для размещения частной ветви, используя следующую команду:

fossil new private-project.fossil

Вы можете назвать свой проект как угодно. Приставка ".fossil" необязательна. В этом документе мы по-прежнему будем называть проект "private-project.fossil". Обратите внимание, что private-project.fossil – это обычный файл на диске (на самом деле база данных SQLite), который будет содержать всю историю вашего проекта. Вы можете сделать резервную копию проекта, просто скопировав этот файл.

Если вы хотите настроить новый проект, введите:

fossil ui private-project.fossil

Команда "ui" заставит fossil запустить встроенный мини-веб-сервер и открыть ваш веб-браузер, указав на этот веб-сервер. Вы можете использовать свой веб-браузер для настройки вашего проекта различными способами. Смотрите инструкции на сайте fossil для получения дополнительной информации.

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

fossil open private-project.fossil

Вы можете иметь несколько копий одного и того же проекта, если хотите. И вы можете "клонировать" репозиторий на разные машины, чтобы несколько разработчиков могли его использовать. Смотрите на сайте fossil для получения дополнительной информации.

3.3. Установка базовой версии SQLite в Fossil

Репозиторий, созданный на предыдущем шаге, изначально пуст. Следующим шагом является загрузка базовой версии SQLite – круг (1) на диаграмме выше.

Начните с получения копии SQLite в любом удобном для вас формате. Полученная общедоступная версия SQLite должна быть максимально близка к вашей частной отредактированной копии. Если ваш проект использует объединённый исходный код SQLite, получите копию объединённого исходного кода. Если вы используете предварительно обработанные отдельные исходные файлы, получите их вместо этого. Поместите все исходные файлы в созданный на предыдущем шаге каталог копий.

Исходный код в общедоступных выпусках SQLite использует окончания строк unix (ASCII-код 10: только "новая строка", NL) и пробелы вместо табуляции. Если вы будете изменять окончания строк на стиль Windows (ASCII-коды 13, 10: "возврат каретки" и "новая строка"; CR-NL) или если вы будете изменять отступы пробелами на отступы табуляцией, сделайте это изменение сейчас, прежде чем вы внесёте базу в систему управления версиями. Процесс слияния будет работать только хорошо, если различия между общедоступной и частной ветвями минимальны. Если каждая строка исходного файла изменена в частной ветви из-за изменения с NL на CR-NL окончания строк, шаги слияния не будут работать корректно.

Предположим, что вы используете объединённый исходный код. Добавьте базу в ваш проект следующим образом:

fossil add sqlite3.c sqlite3.h

Если вы используете отдельные исходные файлы, укажите все исходные файлы вместо двух объединённых исходных файлов. После этого зафиксируйте изменения следующим образом:

fossil commit

Вам будет предложено ввести комментарий к фиксации. Напишите что угодно. После завершения коммита ваша база будет частью репозитория. Следующая команда, если хотите, чтобы увидеть это в "временной шкале":

fossil ui

Последняя команда – та же команда "ui", которую мы использовали ранее. Она запускает мини-веб-сервер и направляет ваш веб-браузер на него. Но на этот раз нам не нужно было указывать имя файла репозитория, потому что мы находимся внутри копии, и поэтому fossil может определить репозиторий автоматически. Если вы хотите ввести имя файла репозитория в качестве второго аргумента, вы можете. Но это необязательно.

Если вы не хотите использовать веб-браузер для просмотра нового коммита, вы можете получить информацию из командной строки, используя команды типа:

fossil timeline
fossil info
fossil status

3.4. Создание частной ветви

На предыдущем шаге был создан круг (1) на диаграмме выше. Этот шаг создаст круг (2). Выполните следующую команду:

 
fossil branch new private trunk -bgcolor "#add8e8"

Эта команда создаст новую ветвь с именем "private" (вы можете использовать другое имя, если хотите) и назначит ей цвет фона светло-голубой ("#add8e8"). Вы можете опустить цвет фона, если хотите, но наличие отличительного фона упрощает различие ветви от "ствола" (общедоступной ветви) на графиках временной шкалы. Вы можете изменить цвет фона частной ветви или общедоступной ветви (ствола) с помощью веб-интерфейса, если хотите.

Команда выше создала новую ветвь. Но ваша копия всё ещё на стволе – это факт, который вы можете увидеть, выполнив команду:

fossil info

Чтобы переключиться на частную ветвь, введите:

fossil update private

Вы можете снова выполнить команду "info", чтобы проверить, что вы находитесь в частной ветви. Чтобы вернуться в общедоступную ветвь, введите:

fossil update trunk

Обычно fossil изменяет все файлы в вашей копии при переключении между частной и общедоступной ветвями. Но на данный момент файлы идентичны в обеих ветвях, поэтому никаких изменений вносить не нужно.

3.5. Добавление пользовательских настроек в код в частной ветви

Сейчас настало время внести частные, пользовательские изменения в SQLite, которые являются целью этого упражнения. Переключитесь на частную ветвь (если вы еще этого не сделали) с помощью команды "fossil update private", затем откройте исходные файлы в вашем текстовом редакторе и внесите любые необходимые изменения. После завершения изменений зафиксируйте их с помощью этой команды:

fossil commit

Вам снова будет предложено ввести описание изменений для коммита. Затем коммит будет создан. Коммит создает новую фиксацию в репозитории, соответствующую кругу (3) на диаграмме выше.

Теперь, когда публичная и частная ветви отличаются, вы можете выполнить команды "fossil update trunk" и "fossil update private" и убедиться, что fossil действительно изменяет файлы в рабочей копии при переключении между ветвями.

Обратите внимание, что на диаграмме выше частные правки показаны как один коммит. Это сделано только для наглядности. Ничто не мешает вам выполнять десятки или сотни отдельных мелких изменений и фиксировать каждое из них по отдельности. На самом деле, выполнение многих небольших изменений является предпочтительным способом работы. Единственная причина для внесения всех изменений в один коммит — упрощение построения диаграммы.

3.6. Включение новых публичных релизов SQLite

Предположим, что через некоторое время (обычно около месяца) выходит новая версия SQLite: 3.6.16. Вам необходимо будет включить эту новую публичную версию SQLite в свой репозиторий в публичной ветви (стволе). Для этого сначала измените свой репозиторий на ствол:

fossil update trunk

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

Если вы вносили изменения в окончания строк (NL на CR-NL) или отступы (пробелы на табуляции) в оригинальном исходном коде, внесите те же изменения в новый исходный файл.

После того, как все будет готово, выполните команду "fossil commit", чтобы зафиксировать изменения. Это создаст круг (4) на диаграмме выше.

3.7. Слияние обновлений публичного SQLite в частную ветвь

Следующим шагом является перенесение изменений из публичной ветви в частную. Другими словами, мы хотим создать круг (5) на диаграмме выше. Начните с перехода в частную ветвь с помощью команды "fossil update private". Затем введите эту команду:

fossil merge trunk

Команда «слияние» пытается применить все изменения между кругами (1) и (4) к файлам в локальной рабочей копии. Обратите внимание, что круг (5) еще не создан. Вам необходимо запустить команду «commit» для создания круга (5).

Возможны конфликты при слиянии. Конфликты возникают, когда одна и та же строка кода была изменена по-разному между кругами (1) и (4) по сравнению с кругами (2) и (3). Команда слияния сообщит о любых конфликтах и включит обе версии конфликтующих строк в вывод. Вам необходимо открыть файлы, содержащие конфликты, и вручную разрешить конфликты.

После разрешения конфликтов многие пользователи предпочитают скомпилировать и протестировать новую версию перед внесением ее в репозиторий. Или вы можете сначала зафиксировать, а затем протестировать. В любом случае, выполните команду "fossil commit", чтобы зафиксировать версию круга (5).

3.8. Дальнейшие обновления

По мере выхода новых версий SQLite повторяйте шаги 3.6 и 3.7, чтобы добавить изменения в новом релизе в частную ветвь. Дополнительные частные изменения могут быть внесены в частную ветвь между выпусками при необходимости.

4. Варианты

С момента написания этого документа исходный код SQLite был перенесен из системы CVS в репозиторий Fossil по адресу https://www.sqlite.org/src. Это означает, что если вы работаете с исходным кодом канонического SQLite (в отличие от файлов исходного кода консолидации sqlite3.c и sqlite3.h), вы можете создать частный репозиторий, просто клонировав официальный репозиторий:

fossil clone https://www.sqlite.org/src private-project.fossil

Эта команда создает новый репозиторий и заполняет его всем последним кодом SQLite. Затем вы можете создать частную ветвь, как описано в разделе 3.4.

При создании частного репозитория путем клонирования включение новых публичных релизов SQLite также становится намного проще. Чтобы получить все последние изменения из публичного репозитория SQLite, просто перейдите в открытую рабочую копию и выполните:

fossil update

Затем продолжайте сливать изменения из «trunk» с вашими изменениями в «private», как описано в разделе 3.7.

Эта страница была последним обновлена 10 октября 2023 г. 17:29:48 по Гринвичу