Сборка OutWiker

Общие моменты, связанные со сборкой

Все задачи, связанные со сборкой, создают внутри папки build папку, имя которой соответствует номеру текущей версии OutWiker в формате x.x.x.xxx. Например, 2.0.0.820. Также внутри папки build создается временная папка tmp, предназначенная для хранения файлов во время сборки. Данная папка очищается перед каждой сборкой.

Также перед каждой задачей сборки создается папка tmp/src, которая содержит копию исходников в соответствии с настройками сборщика: собирается стабильная версия или нестабильная. Если собирается нестабильная версия, то после копирования из исходников удаляется файл versions_stable.xml, остается только файл versions.xml, описывающий изменения в текущей версии в формате для нестабильной версии.

Если собирается стабильная версия, то после копирования исходников в tmp/src/ исходный файл versions.xml удаляется, а файл versions_stable.xml переименовывается в versions.xml. Подробнее о формате файла versions.xml см. раздел Хранение номеров версий в OutWiker и плагинах (не написано).

Разные классы сборок могут добавлять дополнительные файлы в папку tmp.

Описанные возможности реализованы в классе buildtools.builders.base.BuilderBase.

Сборка осуществляется с помощью команд Fabric (см. раздел Выполнение команд Fabric).

Примечание

Многие команды сборки принимают булевы параметры. Чтобы в такую задачу передать значение True, в качестве параметра в командной строке нужно передать одно из следующих значений: 1 или true (независимо от регистра). Чтобы передать значение False, нужно передать какое-либо другое значение.

Сборка под Windows

Использование команды fab win

Для того, чтобы собрать все виды дистрибутивов под Windows как нестабильную версию, используется команда

fab win

Для того, чтобы собрать все виды дистрибутивов под Windows как стабильную версию, используется команда

fab win:1

Для нестабильной версии будут созданы следующие артефакты в папке build/{номер версии}/windows:

  • Папка outwiker_exe, содержащая все файлы, необходимые для запуска под Windows, включая все плагины в папке plugins.
  • outwiker_win_unstable.zip - zip-архив, содержащий содержимое папки outwiker_exe, но без плагинов во вложенной папке plugins.
  • outwiker_win_unstable.7z - 7z-архив, содержащий содержимое папки outwiker_exe, но без плагинов во вложенной папке plugins.
  • outwiker_win_unstable_all_plugins.zip - zip-архив, содержащий содержимое папки outwiker_exe, включая плагины во вложенной папке plugins.
  • outwiker_win_unstable_all_plugins.7z - 7z-архив, содержащий содержимое папки outwiker_exe, включая плагины во вложенной папке plugins.
  • outwiker_win_unstable.exe - инсталятор, созданный с помощью Inno Setup.
  • versions.xml - манифест с описанием текущей версии программы OutWiker (см. раздел Хранение номеров версий в OutWiker и плагинах (не написано)).

Для стабильной версии будут созданы следующие артефакты в папке build/{номер версии}/windows:

  • Папка outwiker_exe, содержащая все файлы, необходимые для запуска под Windows, включая все плагины в папке plugins.
  • outwiker_{x.x.x}_win.zip - zip-архив, содержащий содержимое папки outwiker_exe, но без плагинов во вложенной папке plugins.
  • outwiker_{x.x.x}_win.7z - 7z-архив, содержащий содержимое папки outwiker_exe, но без плагинов во вложенной папке plugins.
  • outwiker_{x.x.x}_win_all_plugins.zip - zip-архив, содержащий содержимое папки outwiker_exe, включая плагины во вложенной папке plugins.
  • outwiker_{x.x.x}_win_all_plugins.7z - 7z-архив, содержащий содержимое папки outwiker_exe, включая плагины во вложенной папке plugins.
  • outwiker_{x.x.x}_win.exe - инсталятор, созданный с помощью Inno Setup.
  • versions.xml - манифест с описанием текущей версии программы OutWiker. Этот файл является переименованным файлом src/versions_stable.xml (см. раздел Хранение номеров версий в OutWiker и плагинах (не написано)).

Команда fab win может принимать три булевых параметра.

win(is_stable=False, skipinstaller=False, skiparchives=False)

Сборка дистрибутивов под Windows

Параметры:
  • is_stable (bool) – Собрать дистрибутивы как стабильную версию (True) или как нестабильную (False).
  • skipinstaller (bool) – Пропустить шаг создания инсталятора outwiker_win_unstable.exe (если skipinstaller = True).
  • skiparchives (bool) – Пропустить шаг создания архивов с собранной версией OutWiker (если skiparchives = True).

Чтобы удалить все артефакты, созданные командой fab win, предназначена команда:

fab win_clear

Порядок сборки дистрибутивов под Windows

Все действия, связанные со сборкой под Windows сосредоточены в классе buildtools.builders.windows.BuilderWindows, который является производным от buildtools.builders.base.BuilderBase.

В процессе сборки выполняются следующие действия:

Действия, выполняемые классом buildtools.builders.windows.BuilderBase.

  1. Создание папки build.
  2. Выполняется команда очистки. Для сборки под Windows это равносильно выполнению команды fab win_clear.
  3. Удаляется временная папка build/tmp, если она существовала.
  4. Создается временная папка build/tmp.
  5. Создается папка build/{номер версии}/windows, если она не существовала.
  6. Исходники копируются в папку build/tmp/src.
  7. В папке build/tmp/src удаляется файл versions_stable.xml, если создается нестабильная версия OutWiker, или versions_stable.xml переименовывается в versions.xml, если создается стабильная версия OutWiker.

Действия, выполняемые классом buildtools.builders.windows.BuilderWindows.

  1. В папку tmp копируются файлы copyright.txt и LICENSE.txt.
  2. Создается пустая папка для плагинов tmp/src/plugins, если она не была создана.
  3. Создается бинарная сборка в tmp/outwiker_exe (см. раздел Создание бинарной сборки).
  4. Удаляется и создается заново папка tmp/outwiker_exe/plugins.
  5. Создаются архивы с бинарной сборкой в формате zip и 7z без плагинов. Созданные архивы помещаются в build/{номер версии}/windows.
  6. На основе файла шаблона need_for_build/windows/outwiker_setup.iss.tpl создается файл tmp/outwiker_setup.iss, используемый для создания инсталятора с помощью Inno Setup.
  7. Создается инсталятор в папке tmp.
  8. Созданный инсталятор перемещается в папку build/{номер версии}/windows.
  9. Все плагины копируются в папку tmp/outwiker_exe/plugins.
  10. Создаются архивы с бинарной сборкой в формате zip и 7z с плагинами. Созданные архивы помещаются в build/{номер версии}/windows.
  11. Папка tmp/outwiker_exe перемещается в build/{номер версии}/windows.

Создание бинарной сборки

Самое важное, что делает команда fab win - это создание запускаемого приложения под Windows, чтобы пользователям не требовалось устанавливать интерпретатор Python. Это осуществляется с помощью утилиты cx_Freeze. Для создания запускаемых файлов под Windows используется скрипт src/setup.py (см. раздел Классы для создания бинарных сборок с помощью cx_Freeze)

В результате выполнения данного скрипта будет создана папка build/outwiker_exe, содержащая запускаемый файл outwiker.exe, динамически загружаемую библиотеку с интерпретатором Python python27.dll, архив library.zip, содержащий необходимые Python-библиотеки, а также дополнительные файлы, необходимые для работы с библиотеками и папки, необходимые для работы OutWiker.

../../_images/cx_freeze_files.png

Содержимое library.zip может выглядеть следующим образом:

../../_images/cx_freeze_library.png

Предупреждение

В данный момент для сборки OutWiker под Windows используется cx_Freeze 4.3.3. В cx_Freeze 5.x возникла проблема с тем, что запускаемое приложение стало гарантированно виснуть при запуске. Пока проблема не решена, используется предыдущая версия cx_Freeze.

Примечание

В cx_Freeze 5.0 изменился способ сохранения необходимых Python-библиотек, и по умолчанию они не архивируются в library.zip. С помощью дополнительных параметров можно явно указать, какие библиотеки должны быть включены в library.zip. Это нужно будет сделать, если решится проблема с зависаниями, описанная выше. В данный момент эти параметры закомментированы в файле src/setup.py (см. раздел Классы для создания бинарных сборок с помощью cx_Freeze).

Подробное описание работы скрипта src/setup.py приводится в разделе Классы для создания бинарных сборок с помощью cx_Freeze.

Сборка под Linux

В данный момент для установки под Linux есть возможность создания только deb-пакетов, которые могут быть установлены с помощью команды sudo dpkg -i {имя пакета} или закачан на PPA (Personal Packages Archive). В данный момент существуют три PPA-репозитория:

Создание deb-пакетов осуществляется через команды Fabric (см. раздел Выполнение команд Fabric):

  • fab deb создает deb-пакеты для всех поддерживаемых версий Ubuntu.
  • fab deb_single создает единственный deb-пакет под ту версию Ubuntu, в которой запускается данная команда.
  • fab deb_install создает единственный deb-пакет под ту версию Ubuntu, в которой запускается данная команд, и устанавливает созданный пакет в систему с помощью команды sudo dpkg -i {имя пакета}.
  • fab deb_sources_included создает необходимые файлы для загрузки OutWiker на PPA.

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

Для удаления файлов, созданных с помощью команд fab deb..., предназначена команда fab deb_clear.

Список поддерживаемых версий Ubuntu содержится в модуле buildtools.defines в переменной UBUNTU_RELEASE_NAMES.

Порядок сборки deb-пакетов

Для выполнения задач Fabric deb, deb_single и deb_install предназначен класс buildtools.builders.linux.debsource.BuilderDebSource. Для выполнения задачи deb_sources_included предназначен класс buildtools.builders.linux.debsource.BuilderDebSourcesIncluded. Оба этих класса являются производными от класса buildtools.builders.linux.debsource.BuilderBaseDebSource, который в свою очередь, является производным от buildtools.builders.base.BuilderBase.

Классы BuilderDebSource и BuilderDebSourcesIncluded отличаются только параметрами, которые передаются в утилиту сборки deb-пакетов debuild.

В классе BuilderDebSource используется набор параметров для сборки deb-пакета, предназначенного для непосредственной установки:

debuild --source-option=--include-binaries --source-option=--auto-commit

В классе BuilderDebSourcesIncluded используется набор параметров для создания файлов, предназначенных для закачки пакета на сервер PPA, где будут создаваться необходимые для установки файлы.

debuild -S -sa --source-option=--include-binaries --source-option=--auto-commit

Основные действия по сборке пакетов под Linux выполняет базовый класс BuilderBaseDebSource.

Порядок сборки deb-пакета следующий.

Действия, выполняемые классом buildtools.builders.windows.BuilderBase (те же самые действия, что и при сборке под Windows).

  1. Создание папки build.
  2. Выполняется команда очистки. Для сборки под Windows это равносильно выполнению команды fab win_clear.
  3. Удаляется временная папка build/tmp, если она существовала.
  4. Создается временная папка build/tmp.
  5. Создается папка build/{номер версии}/linux/deb_source, если она не существовала.
  6. Исходники копируются в папку build/tmp/src.
  7. В папке build/tmp/src удаляется файл versions_stable.xml, если создается нестабильная версия OutWiker, или versions_stable.xml переименовывается в versions.xml, если создается стабильная версия OutWiker.

Действия, выполняемые классом buildtools.builders.linux.debsource.BuilderBaseDebSource (внутри метода buildtools.builders.linux.debsource.BuilderBaseDebSource._debuild()). Действия выполняются для каждой поддерживаемой версии Ubuntu.

  1. Создается папка вида build/{номер версии}/linux/deb_source/outwiker-x.x.x+xxx, где x.x.x+xxx соответствует номеру версии OutWiker.
  2. Внутрь созданной папки outwiker-x.x.x+xxx копируются минимальный набор исходников из build/tmp/src. Копирование осуществляется с помощью утилиты rsync, которая позволяет задать маски для файлов и папок, которые нужно пропустить при копировании. Также копируются дополнительные файлы, необходимые для сборки. В частности, папка need_for_build/debian_debsource/{ubuntu_name}/debian, содержащая инструкции для сборки deb-пакета под конкретную версию Ubuntu. Также копируются другие файлы и папки из need_for_build/debian_debsource/{ubuntu_name}. Также копируются файлы copyright.txt, README и папка images из корня исходных кодов.
  3. В папке build/{номер версии}/linux/deb_source создается архив с “оригинальными” (original) исходниками. Имя архива выглядит следующим образом: outwiker_2.0.0+817~{ubuntu_name}.orig.tar.gz, где {ubuntu_name} - кодовое имя дистрибутива Ubuntu, для которого создается сборка, число после знака “+” соответствует номеру сборки OutWiker.
  4. Создается файл :file:`build/{номер версии}/linux/deb_source/outwiker-x.x.x+xxx/changelog, содержащий список изменений для данной версии OutWiker.
  5. Выполняется команда debuild, соответствующая цели сборки (параметры команды debuild показаны выше).
  6. Удаляется папка build/{номер версии}/linux/deb_source/outwiker-x.x.x+xxx.

Создание архивов с исходниками

Для создания архивов с исходниками предназначена команда fab sources, которая может принимать один булев параметр (см. примечание), указывающий, будет создаваться архив исходников в виде стабильной или нестабильной версии.

Во время сборки архивов с исходниками создается папка build/{номер версии}/sources, в которую будут помещены архивы. Независимо от выбранного режима сборки создается архив outwiker-src-full-{номер версии}.zip с полной копией исходников (создается с помощью команды git archive).

Если создается архив исходников как нестабильной версии, то создается файл outwiker-src-min-{номер версии}-unstable.zip, который содержит минимально необходимый набор файлов, чтобы запустить OutWiker. Если создается архив стабильной версии, то этот файл будет называться outwiker-src-min-{номер версии}.zip. Содержимое архивов в двух режимах сборки отличается только текстом файла versions.xml.