diff --git a/docs/assets/travis-instruction-0.png b/docs/assets/travis-instruction-0.png new file mode 100644 index 00000000..7daec7e1 Binary files /dev/null and b/docs/assets/travis-instruction-0.png differ diff --git a/docs/assets/travis-instruction-1.png b/docs/assets/travis-instruction-1.png new file mode 100644 index 00000000..f38146e2 Binary files /dev/null and b/docs/assets/travis-instruction-1.png differ diff --git a/docs/assets/travis-instruction-10.png b/docs/assets/travis-instruction-10.png new file mode 100644 index 00000000..a00a3491 Binary files /dev/null and b/docs/assets/travis-instruction-10.png differ diff --git a/docs/assets/travis-instruction-11.png b/docs/assets/travis-instruction-11.png new file mode 100644 index 00000000..0c55004c Binary files /dev/null and b/docs/assets/travis-instruction-11.png differ diff --git a/docs/assets/travis-instruction-12.png b/docs/assets/travis-instruction-12.png new file mode 100644 index 00000000..c14bff4f Binary files /dev/null and b/docs/assets/travis-instruction-12.png differ diff --git a/docs/assets/travis-instruction-2.png b/docs/assets/travis-instruction-2.png new file mode 100644 index 00000000..7dcf1444 Binary files /dev/null and b/docs/assets/travis-instruction-2.png differ diff --git a/docs/assets/travis-instruction-3.png b/docs/assets/travis-instruction-3.png new file mode 100644 index 00000000..8d448eaf Binary files /dev/null and b/docs/assets/travis-instruction-3.png differ diff --git a/docs/assets/travis-instruction-4.png b/docs/assets/travis-instruction-4.png new file mode 100644 index 00000000..2f331b6c Binary files /dev/null and b/docs/assets/travis-instruction-4.png differ diff --git a/docs/assets/travis-instruction-5.png b/docs/assets/travis-instruction-5.png new file mode 100644 index 00000000..50303b0f Binary files /dev/null and b/docs/assets/travis-instruction-5.png differ diff --git a/docs/assets/travis-instruction-6.png b/docs/assets/travis-instruction-6.png new file mode 100644 index 00000000..0d2cdad9 Binary files /dev/null and b/docs/assets/travis-instruction-6.png differ diff --git a/docs/assets/travis-instruction-7.png b/docs/assets/travis-instruction-7.png new file mode 100644 index 00000000..ae25af68 Binary files /dev/null and b/docs/assets/travis-instruction-7.png differ diff --git a/docs/assets/travis-instruction-8.png b/docs/assets/travis-instruction-8.png new file mode 100644 index 00000000..48937fe3 Binary files /dev/null and b/docs/assets/travis-instruction-8.png differ diff --git a/docs/assets/travis-instruction-9.png b/docs/assets/travis-instruction-9.png new file mode 100644 index 00000000..fdca417d Binary files /dev/null and b/docs/assets/travis-instruction-9.png differ diff --git a/docs/ru/SUMMARY.md b/docs/ru/SUMMARY.md index b0a1e243..3cac60c9 100644 --- a/docs/ru/SUMMARY.md +++ b/docs/ru/SUMMARY.md @@ -66,6 +66,7 @@ * Дополнительные материалы * [Олимпиада НТИ 2019](nti2019.md) * [Вклад в Клевер](contributing.md) + * [Сборка и модификация образа Клевера](image_building.md) * [Прошивка ESC контроллеров](esc_firmware.md) * [Протокол MAVLink](mavlink.md) * [Работа с логами PX4](flight_logs.md) diff --git a/docs/ru/image_building.md b/docs/ru/image_building.md new file mode 100644 index 00000000..afa454d6 --- /dev/null +++ b/docs/ru/image_building.md @@ -0,0 +1,85 @@ +# Автоматическая сборка и модификация образа Клевера + +Иногда возникает необходимость в сборке модифицированного образа системы, например для [своего проекта](https://github.com/artem30801/CleverSwarm) на базе [Клевера](https://github.com/copterexpress/clever). За основу можно взять, например, чистый образ Raspbian Stretch и модифицировать его с нуля, пройдя те же этапы, через который проходит сборка образа Клевера, добавив свои модификации. Однако на данный момент времени сборка образа Клевера занимает [чуть больше часа](https://travis-ci.org/CopterExpress/clever), что превышает ограничения бесплатной сборки в Travis \(50 минут\). Соответственно для проектов на базе Клевера имеет смысл брать за основу уже готовый образ и кастомизировать его. Концепция и основные этапы для автоматизированной сборки изложены ниже. + +## Концепция + +Имеется [docker](https://www.docker.com/) образ, который содержит инструментарий для выполнения скриптов, копирования файлов и увеличения/сжатия размера образа системы на требуемой платформе для сборки \(например сборка для Raspberry Pi 3 осуществляется через qemu-arm-static, пример docker образа для сборки находится [здесь](https://hub.docker.com/r/goldarte/img-tool)\). При запуске docker образа выполняется скрипт builder/image-build.sh, в котором описан процесс сборки \(например скачивание опорного образа - увеличение свободного места на образе - установка необходимого софта - сжатие образа\), в результате которого создаётся файл образа системы. Триггер сборки, запуск docker образа для сборки, выкладка образа осуществляется с помощью CI \(continuous integration\) системы [Travis](https://travis-ci.com/). + +## Добавление скриптов сборки + +1. Для осуществления сборки образа добавьте в свой проект build скрипты, модифицирующие исходный образ. За основу можно взять скрипты из репозитория Клевера \(папка [builder](https://github.com/CopterExpress/clever/tree/master/builder)\) или из репозитория шоу дронов на основе клеверов \(тоже папка [builder](https://github.com/artem30801/CleverSwarm/tree/master/builder)\). Опорный скрипт, который исполняется безусловно docker образом в этих проектах - builder/image-build.sh. +2. Для автоматического запуска сборки в облаке добавьте в свой проект .travis.yml файл, описывающий последовательность этапов выполнения сборки и правила для выкладки образов. [Пример](https://github.com/CopterExpress/clever/blob/master/.travis.yml) из репозитория Клевера, [пример](https://github.com/artem30801/CleverSwarm/blob/master/.travis.yml) из репозитория шоу дронов. Документация по составлению .travis.yml файла находится [здесь](https://docs.travis-ci.com/user/tutorial/). + +## Настройка инструмента сборки travis-ci.com + +1. Войдите в [Travis](/travis-ci.com) через свой GitHub аккаунт. +2. Проверьте, что файл .travis.yml добавлен правильно: выберите свой проект, нажмите Trigger build из выпадающего меню справа сверху. Сборка должна начаться и успешно завершиться через некоторое время, если всё правильно. +3. Настройте проект. Основные настройки можно оставить по умолчанию. Если необходимы ключи авторизации \(токены\) для доступа к репозиторию \(например для того, чтобы выложить образ прикреплённым файлом в релиз\), нужно сгенерировать их в своём аккаунте и добавить под названием переменной, которая используется для передачи токена. + +## Запуск сборки в облаке travis-ci.com + +По умолчанию скрипт сборки из .travis.yml файла выполняется автоматически при любом изменении GitHub репозитория. Есть возможность добавить скрипты, которые будут выполняться только при создании релиза \(публикации тега\), пример [здесь](https://github.com/CopterExpress/clever/blob/master/.travis.yml#L35). + +## Запуск сборки на локальной машине + +Если есть необходимость собрать образ быстрее, чем в облаке, или поэкспериментировать со сборкой локально, можно запустить docker образ на локальной машине. Для этого необходимо в консоли перейти в папку с репозиторием, где прописаны скрипты автоматической сборки, и запустить оттуда docker, например \(подробнее [здесь](https://github.com/goldarte/img-tool/blob/master/README.md)\): + +``` +cd repo-w-instructions + +docker run --privileged -it --rm -v /dev:/dev -v $(pwd):/mnt goldarte/img-tool:v0.5 +``` + +## Пример запуска автоматической сборки образа из форка репозитория шоу дронов + +* Сделайте форк [репозитория](https://github.com/artem30801/CleverSwarm): + + ![](../assets/travis-instruction-0.png) + +* Склонируйте репозиторий к себе на компьютер: + + ```bash + git clone <адрес репозитория> + ``` + +* Зайдите на travis-ci.org под своим аккаунтом GitHub. +* Выберите среди проектов форк репозитория шоу дронов и запустите тестовую сборку, нажав Trigger build из выпадающего меню: + + ![](../assets/travis-instruction-1.png) + ![](../assets/travis-instruction-2.png) + +* Проверьте, что сборка запустилась: + + ![](../assets/travis-instruction-3.png) + +* Добавьте ключ аутентификации к вашему репозиторию для прикрепления файла образа к релизу. Зайдите в [настройки токенов](https://github.com/settings/tokens) своего аккаунта и сгенерируйте новый токен для доступа к вашему репозиторию: + + ![](../assets/travis-instruction-4.png) + ![](../assets/travis-instruction-5.png) + ![](../assets/travis-instruction-6.png) + +* Скопируйте получившийся токен: + + ![](../assets/travis-instruction-7.png) + +* Перейдите в настройки сборки travis-ci.com и добавьте скопированный токен под именем `GITHUB_OAUTH_TOKEN`: + + ![](../assets/travis-instruction-9.png) + +* В терминале перейдите в папку со скопированным репозиторием, создайте и опубликуйте тег для создания пре-релиза, автоматической сборки и выкладки образа на GitHub: + + ``` + git tag <имя тега> + + git push --tags + ``` + +* Дождитесь окончания сборки образа и проверьте раздел Releases в вашем репозитории: + + ![](../assets/travis-instruction-10.png) + ![](../assets/travis-instruction-11.png) + +* Нажмите на кнопку Draft a new release и выпустите [pre-release](https://github.com/goldarte/CleverSwarm/releases/tag/v0.2-test.1) или release собранного образа и исходным кодом: + + ![](../assets/travis-instruction-12.png)