1. Введение

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

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

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

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

Мы предлагаем использовать систему fossil software configuration management , чтобы создать два отделения. Одно отделение ("public branch" или "trunk") содержит изданные источники SQLite, а другая это частное отделение, которое содержит код, который настраивается для проекта. Каждый раз, когда новый общественный выпуск SQLite сделан, тот выпуск добавляется к общественному отделению, и затем изменения слиты в частное отделение.

Этот документ предлагает использовать fossil, но любая другая система управления конфигурацией распределенных программных средств, такая как monotone, mercurial (a.k.a. "hg") или git, могла бы служить точно также. Понятие будет тем же самым, хотя специфические особенности процедуры изменятся.

Диаграмма справа иллюстрирует понятие. Каждый начинает со стандартного выпуска SQLite. Ради примера предположите, что вы намереваетесь создать частное отделение от SQLite version 3.6.15. В диаграмме это версия (1). Майнтейнер делает точную копию основания SQLite в пространство отделения, показанное как версия (2). Обратите внимание на то, что (1) и (2) точно то же самое. Тогда майнтейнер применяет частные изменения версии (2), приводящие к версии (3). Другими словами, версия (3) это версия SQLite version 3.6.15 плюс правки.

Далее выпускается SQLite version 3.6.16, как показано кругом (4) на диаграмме. Вот тут частный майнтейнер отделения делает слияние, которое вносит все изменения, идущие от (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 это единственный файл "*.exe", который вы просто загружаете и запускаете. Чтобы деинсталлировать fossil, просто удалите EXE-файл. Детальные инструкции для установки и начала работы с fossil доступны на fossil website.

3.2. Создайте хранилище проекта

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

fossil new private-project.fossil

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

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

fossil ui private-project.fossil

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

Как только хранилище проекта создается, создайте открытый контроль проекта, перейдя в каталог, где вы хотите держать весь исходный код проекта, и введите:

fossil open private-project.fossil

У вас может быть многократный контроль того же самого проекта, если вы хотите. И можно клонировать хранилище к различным машинам так, чтобы многие разработчики могли использовать его. Посмотрите веб-сайт fossil для дополнительной информации.

3.3. Установка основания SQLite в Fossil

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

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

Исходный код SQLite выпускает окончания строк unix с применением только ASCII code 10: "newline", он же NL и пробелов вместо табуляций. Если вы будете изменять строку, заканчивающуюся на окончания стиля windows (ASCII codes 13, 10: "carriage-return" и "newline"; 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"). Можно опустить цвет фона, если вы хотите, хотя наличие отличного фона действительно облегчает отличие отделения от "trunk" (public branch) на временной шкале. Можно изменить цвет фона частного или общественного отделения ("trunk") с использованием веб-интерфейса, если вам нравится.

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

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 в ваше хранилище в общественном отделении (trunk). Чтобы сделать это, сначала меняйте свое хранилище к trunk:

fossil update trunk

Тогда загрузите новую версию SQLite и перепишите файлы, которые находятся в контроле.

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

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

3.7. Слияние общественных обновлений SQLite в частное отделение

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

fossil merge trunk

Команда "merge" пытается применить все изменения между кругами (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.