Skip to main content

Добро пожаловать в раздел разработки

В процессе работы

Этот сайт ещё новый и находится в процессе разработки. Страницы будут добавляться, обновляться и улучшаться практически каждый день в ближайшие недели. Так что, если вы что-то пропустили, наберитесь терпения. Всё обязательно появится! Вы также можете нам помочь. Подробнее читайте на канале #documentation на сервере Discord.

Участие​

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

  • Реализация новой функции в прошивке или конфигураторе (см. ниже);
  • Обновления и исправления документации
  • Руководства — получили ли вы помощь? Помогите другим!
  • Сообщения об ошибках и их исправления;
  • Идеи для новых функций и их исправления. Предложения;
  • Предоставьте новый перевод для конфигуратора или помогите нам поддерживать существующие (см. ниже).

Помимо сервера Discord, следующим лучшим местом для поиска является система отслеживания ошибок GitHub:

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

Если вы хотите поддержать нас финансово, пожалуйста, сделайте пожертвование через PayPal.

Если вы хотите поддерживать нас финансово на постоянной основе, рассмотрите возможность стать нашим спонсором на Patreon.

Разработка​

Этот документ предназначен в первую очередь для разработчиков.

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

Действия GitHub используются для запуска автоматических сборок

Переводчики​

Мы хотим сделать AlphaFly доступным для пилотов, не владеющих английским языком, и поэтому в настоящее время поддерживаемвыполнение переводов для приложения AlphaFly на 21 язык: Català, Dansk, Deutsch, Español, Euskera, Français, Galego, Hrvatski, Bahasa Indonesia, Italiano, 日本語, 한국어, Latviešu, Português, Português Brasileiro, Polski, русский язык, Svenska,简体中文, 繁體中文. У нас есть команда переводчиков-добровольцев, которые выполняют эту работу, но всегда рады дополнительным переводчикам, которые разделят рабочую нагрузку, и мы стремимся добавить дополнительные языки. Если вы хотите помочь нам с переводами, у вас есть следующие возможности:

  • Если вы хотите помочь, предложив обновления или улучшения для переводов на знакомом вам языке, перейдите на сайт crowdin и добавьте там свои предложения.
  • Если вы хотите начать работу над переводом на новый язык или взять на себя ответственность за корректуру перевода на хорошо знакомый вам язык, перейдите на Discord-сервер AlphaFly и присоединитесь к каналу перевода в Раздел «Разработка» — специалисты этого раздела помогут вам добавить новый язык или назначить вас корректором.

Общие принципы​

  1. Дайте всему чёткие названия.
  2. Соблюсти баланс между простотой и отсутствием повторений. code.
  3. Методы, начинающиеся со слова «find», могут возвращать значение null, а методы, начинающиеся со слова «get», — нет.
  4. Пусть методы будут короткими — это упростит тестирование.
  5. Не бойтесь переносить код в новый файл — это поможет уменьшить зависимости при тестировании.
  6. Избегайте лишних слов в именах переменных, таких как «data» или «info». Продумайте, что вы называете, и дайте этому имя грамотно. Не бойтесь что-либо переименовывать.
  7. Избегайте комментариев, описывающих, что делает код: код должен сам себя описывать. Однако комментарии полезны для понимания общей картины и документирования содержимого переменных.
  8. Если вам нужно задокументировать переменную, сделайте это в объявлении. Не копируйте комментарий в тег extern, так как это приведёт к потере комментариев.
  9. Обратитесь за советом к другим разработчикам — знайте, что вы всегда можете узнать больше.
  10. Будьте профессионалом — попытки шутить или критиковать существующий код в самой кодовой базе бесполезны, когда вам нужно его изменить/исправить.
  11. Помните, что всегда есть несколько способов сделать что-то, и что код никогда не будет окончательным, но он должен работать.

Также рекомендуется почитать о чистом коде. Вот несколько полезных ссылок:

Модульное тестирование​

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

Если вы хотите внести изменения и убедиться, что они протестированы, сосредоточьтесь на минимальном наборе изменений, необходимых для добавления теста.

Тесты в настоящее время находятся в папке test и используют фреймворк Google Test. Тесты компилируются и запускаются нативно на вашем компьютере разработки, а не на целевой платформе. Это позволяет разрабатывать тесты и код, а также выполнять их, чтобы убедиться в их работоспособности, без использования платы разработки или симулятора.

Этому проекту очень не помешали бы функциональные тесты, проверяющие поведение приложения.

Мы будем рады любым запросам на добавление/улучшение тестируемости кода или методов тестирования!

Примечание: тесты написаны на C++ и связаны с C-кодом прошивки. Весь код также инструментируется с помощью gcov для анализа тестового покрытия.

Запуск тестов​

Тесты и система сборки тестов очень просты и основаны на файлах примеров Googletest. Со временем они будут дорабатываться. В корневой папке проекта просто выполните:






make тест

Вы также можете сделать:






make junittest

Это создаст набор исполняемых файлов в папке obj/test, по одному на каждый файл *_unittest.cc. Работа прервётся после первой ошибки компиляции/сборки. Если вы хотите продолжить работу со следующим тестовым модулем, используйте команду make -k test.

После выполнения тестов с помощью команды make вы можете запустить их в командной строке, чтобы выполнить тесты и просмотреть отчёт. Отчёты о тестировании также будут создаваться в виде XML-файлов Junit, если тесты собираются и запускаются с целью «junittest». Файлы отчётов Junit сохраняются в каталоге obj/test и имеют следующий шаблон именования: test_name_results.xml, например: obj/test/battery_unittest_results.xml

Вы также можете выполнить пошаговую отладку тестов в Eclipse, а также использовать инструмент для запуска тестов GoogleTest для упрощения сборки и повторного запуска тестов.

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

Тесты проверены и работают с GCC 4.9.3

Использование Git и Github​

Убедитесь, что вы понимаете рабочий процесс Git: https://guides.github.com/introduction/flow/index.html

Пожалуйста, делайте пул-реквесты, направленные только на что-то одно, так как это упрощает слияние и своевременное тестирование.

Если вам нужна помощь с пул-реквестами, руководства на Git есть здесь:

https://help.github.com/articles/creating-a-pull-request/

Основной процесс добавления выглядит следующим образом:

  1. Входна github, перейдите в репозиторий alfafly и нажмите fork;
  2. Затем, используя командную строку/терминал на вашем компьютере: git clone ;
  3. cd alfafly;
  4. git checkout master;
  5. git checkout -b my-new-code;
  6. Внесите изменения;
  7. git add ;
  8. git commit;
  9. git push origin my-new-code;
  10. Создайте запрос на извлечение, используя интерфейс GitHub, для слияния изменений из новой ветки с веткой alfafly/master;
  11. Повторите шаги с 4 для других изменений.

Главное, что следует помнить, — это то, что отдельные запросы на извлечение следует создавать для отдельных веток. Никогда не создавайте запрос на извлечение из ветки master.

После создания запроса на извлечение каждый новый коммит/пуш в вашей ветке будет распространяться из вашего форка в запрос на извлечение в основном репозитории GitHub/alfafly. Если вам нужно что-то ещё, сначала проверьте другую ветку.

Пусть изменения часто завершаются неудачей, если вы редактируете или сжимаете коммиты в уже отправленной ветке. Никогда не делайте этого после создания PR.

Позже вы можете перенести изменения из репозитория alfafly в свою ветку master, добавив alfafly как удалённый git-сервер и выполнив слияние следующим образом:

  1. git remote add alfafly https://github.com/alfafly/alfafly.git
  2. git checkout master
  3. git fetch alfafly
  4. git merge alfafly/master
  5. git push origin master — необязательный шаг, который обновит ваш форк на GitHub.

Вы также можете выполнять команды Git с помощью клиента Git в Eclipse. См. руководство по git для Eclipse.

Предоставление тестовых целей для запросов на извлечение​

Если вы открываете запрос на извлечение для репозитория alfafly, содержащий изменение, которое могут протестировать другие пользователи, пожалуйста, создайте набор тестовых файлов прошивки для всех унифицированных целей и прикрепите их к запросу на извлечение. Необходимые файлы прошивки можно собрать в архиве, готовом к загрузке на GitHub, с помощью команды make unified_zip. Прикрепляя файлы тестовой прошивки, вы можете указать пользователям на это видео с инструкциями по установке тестовой прошивки: https://youtu.be/I1uN9CN30gw

Пример запроса на извлечение с прикреплённой тестовой прошивкой:

Запрос на извлечение с тестовыми целями

IDE и .gitignore​

Файл проекта .gitignore уже игнорирует определённые артефакты из некоторых IDE, но если вы хотите использовать что-то другое, вы можете настроить git так, чтобы он игнорировал необходимые файлы на глобальном уровне (все проекты git на компьютере).

Всегда полезно проверить, не сделали ли вы это ранее: git config --global --get core.excludesfile

Для Linux/BSD/OSX: git config --global core.excludesfile '~/.gitignore'

Для Windows: git config --global core.excludesfile '%USERPROFILE%\.gitignore'

При повторном выполнении git config --global --get core.excludesfile вы должны получить доступ к файлу.

Локальная сборка Hex-файла​

Учитывая развёртывание платформы CLOUD BUILD, тем из вас, кто хочет собирать локально, необходимо добавить опции для выбора нужных функций. Удивительно, но эта возможность всегда присутствовала в виде параметра командной строки EXTRA_FLAGS для make. Платформа облачной сборки просто использует этот параметр — и весьма активно.

Лучший способ продемонстрировать это —Вот пример:






make TARGET=STM32F411 EXTRA_FLAGS="-DUSE_GPS -DUSE_LED_STRIP"

Вышеуказанный код создаст шестнадцатеричный целевой модуль F411 с GPS и LED_STRIP. Удачной компиляции! :). В большинстве случаев простая команда make с целевым модулем микроконтроллера включит почти всё. Исключение составляют микроконтроллеры с меньшим объёмом флэш-памяти, например, F411 и F722. В них не хватает места во Flash-памяти для всего, поэтому даже при локальной сборке вам потребуется указать, что именно вы хотите включить.

примечание

Обратите внимание на использование -D и USE_. Это отличается от способа отображения этих параметров в конфигураторе.

Эти определения, которые мы добавляем либо в командной строке, либо в пользовательских определениях (в экспертном режиме) в конфигураторе, называются gates и включают или исключают целые разделы кода.

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






make CONFIG=ALPHAFLYF7

This will build you a target hex file that has everything baked in for that manufacturers configuration, including any default features as specified by the manufacturer.