GitHub — различия между версиями

Версия 10:18, 27 ноября 2018

Данная страница посвящена текущим проектам НОЦ «Газпромнефть-Политех» и методологии разработки программного обеспечения.

Централизованный репозиторий

На сайте GitHub создан общий аккаунт для размещения ПО, разрабатываемого в НОЦ «Газпромнефть-Политех». Каждому проекту может быть создан свой приватный git-репозиторий для сохранения исходных кодов, библиотек, документации и прочих файлов.

Такое решение преследует несколько целей. Во-первых, обеспечить сохранность ключевых версий ПО (как минимум, передаваемых заказчикам). Во-вторых, упростить взаимодействие и передачу программ между сотрудниками НОЦ. Нередко получается, что при передаче исходных кодов забывают удалить ненужные файлы (экспериментальные), указать файлы с входных данных, описать необходимые библиотеки и зависимости или ключи сборки. В-третьих, сформировать внутри НОЦ понимание того, какие проекты сейчас разрабатываются и на какой стадии они находятся. Также репозитории можно использовать в демонстративных целях.

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

Как подключиться

Общий пользователь НОЦ: @gpn-polytech

Подключение к приватным репозиториям требует аккаунт на GitHub. Регистрация полностью бесплатна (помимо этого существуют платные тарифы). По адресу почты в домене @spbstu.ru легко оформить студенческий аккаунт, предоставляющий больше возможностей для личного использования.

Для работы можно использовать любую программу, поддерживающую git, в том числе консольную или встроенную в текстовый редактор. Бесплатное приложение GitHub Desktop предоставляет простой в использовании графический интерфейс с достаточно широким функционалом.

За настройкой репозиториев обращайтесь к Егору Старобинскому.

Ограничения

Рекомендуется хранить в каждом репозитории не более 1 Гб данных. Вес отдельного файла не может превышать 100 Мб.

Подробнее:

• Conditions for large files
• What is my disk quota?

Участники

• Антонов Илья – @antoidco
• Калюжнюк Александр – @iomguy
• Краева Светлана – @svetlanakraeva
• Лапин Руслан – @FanOfRammstein
• Марков Николай – @mksfmksf
• Мурачёв Андрей – @anewmur
• Мущак Никита – @NikitaMushchak
• Осокина Алена – @ElaineEddington
• Старобинский Егор – @starobinskii
• Хлопин Сергей – @hlserg
• Цветков Денис – @AHuxley
• Шварёв Николай – @megameowmeow

Проекты

FractureGUI

Графический интерфейс для программных средств моделирования гидроразрыва пласта.

Ответственный: Шварёв Николай

Planar3D-LL

Программа расчета геометрии трещины ГРП с использованием функции Грина для слоистой среды и универсальных асимптотик для отслеживания фронта трещины ГРП для плоской трехмерной трещины ГРП с учетом контраста упругих модулей.

Ответственный: Старобинский Егор

Системы контроля версий

Использование систем контроля версий позволяет упростить процесс разработки ПО, с одной стороны раздельно сохраняя модификации файлов, а с другой — обеспечивая разработчика инструментом объединения различных модификаций в единую версию. Примерами таких систем являются Git, Subversion (svn), Mercurial.

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

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

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

Использование git-систем особенно удобно при разработке открытого ПО, так как существует большой набор бесплатных (для открытых лицензий) инструментов для непрерывной интеграции (Continuous Integration).

Сборка программ

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

Автоматическая сборка

Как на Unix-системах, так и на Windows возможно использование Make-файлов (Makefile) — мощного инструмента автоматизации и настройки сборки. На Linux и macOS сборка с Makefile может быть осуществлена программой make или gmake, на Windows — программой nmake, идущей в комплекте с Visual C++ Build Tools и Visual Studio.

C/C++

При сборке лучше явно задавать требуемый уровень оптимизации. Для отладочных сборок это обычно O0 (без оптимизаций), для релизных — O3 или Ox (максимальная оптимизация скорости). Директивы препроцессора позволяют разграничить функционал для разных типов сборки (например, добавлять вывод тестовой информации), а также автоматически дополнять программу информацией об условиях сборки (время, компилятор, сборочная платформа, целевая платформа и пр.).

Python

Программа PyInstaller позволяет собирать python-проекты в исполнительные файлы на разных платформах (включая Windows, Linux, macOS), автоматически подгружая необходимые библиотеки. Модификация исходного кода не требуется. Доступна сборка графических интерфейсов (Qt4, Qt5, wxWidgets, GTK) без консольного окна. Собранный проект не будет зависеть от того, установлен ли python нужной версии и требуемые библиотеки на компьютер пользователя.

Создание установщика

С помощью NSIS можно создавать программы-установщики для Windows (installer и uninstaller). Если платформа сборки установщика не Windows, потребуется компиляция NSIS из исходников. Существуют аналогичные решения для сборки установщиков под другие системы.

Тестирование

Современные методы тестирования направлены на проверку всех элементов программы, включая пользовательские интерфейсы. На практике проверка корректности работы включает перебор слишком большого количества параметров, чтобы проводить регулярное тестирование в ручном режиме. Если какая-то функция перестала работать корректно несколько сборок тому назад, поиск ошибки даже при использовании систем контроля версий может потребовать много времени. Библиотеки для автоматического тестирования (к примеру, для C++ можно использовать Catch2) позволяют существенно упростить эту процедуру.

Автоматическое тестирование позволяет перебирать любые комбинации входных параметров в указанных диапазонах (что может пригодиться также для проведения компьютерных экспериментов) и выдавать качественную оценку результатов. При этом тестировать можно не только всю программу целиком, но и каждую функцию (метод) в отдельности. Если какие-то данные должны приводить к ошибке программы или функции (к примеру, вызывать исключение), это можно проверить специальными инструкциями. Также автотесты удобны для отслеживания багов, например, в используемых сторонних библиотеках.

Виртуальные машины

Релизную сборку и её тестирование надёжнее осуществлять на «чистых операционных системах». Использование чистой ОС для сборки (ОС в минимальной комплектации + необходимое для сборки программное обеспечение) позволяет в полном объёме отследить зависимости пограммы от стороннего ПО и библиотек. Использование чистой ОС для тестирования (ОС в минимальной комплектации + тестируемая программа + необходимое для тестирования ПО) обеспечит более строгие условия проверки.

Использование виртуальных систем упрощяет проведение качественного тестирования. Программы для виртуализации (к примеру, VirtualBox) позволяют запускать одновременно несколько виртуальных ОС, не препятствующих работе основной ОС компьютера (если достаточно ресурсов). Вы можете установить несколько ОС (в том числе с разными архитектурами), по желанию менять их конфигурации (выставлять разное количество доступных ядер, объёмы оперативной памяти и видеопамяти и пр.), подключаться к ним удалённо и т. д. Настроенную виртуальную ОС можно клонировать или передавать в виде специального архива.

Очень полезной функцией систем виртуализации является возможность сохранения состояния виртуальной системы (как в системах резервного копирования) с возможностью быстро вернуться на любое ранее сохранённое состояние. Это позволяет после сборки/тестирования откатить ОС к чистому состоянию.

Для получения доступа к имеющимся виртуальным сборочным и тестировочным ОС обращайтесь к Сергею Хлопину.

Документация

Markdown

Markdown – язык разметки, широко используемый в git-репозиториях. Текстовым файлам, написанным с использованием markdown, принято присваивать расширение .md.

Традиционно репозитории содержат следующие файлы:

• README.md – описание проекта, процедур сборки, установки и использования ПО, ссылки на авторов и документацию;
• CHANGELOG.md – описание изменений между разными версиями ПО.

Файлы с разметкой markdown с помощью doxygen могут быть преобразованы в отдельные страницы документации.

Doxygen

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

Документация формируется по комментариям в исходном коде, дополнительно строятся списки функций, классов, методов и глобальных переменных. Рисуются схемы зависимостей и графы вызовов (call и caller). Подобная документация, сохранённая, к примеру, в формате html файлов, позволяет сформировать у пользователя более полное понимание структуры программы, её API, передаваемых параметрах и возможных ошибках. Преимущество такого подхода заключается в простоте обновления документации — достаточно поддерживать комментарии в актуальном состоянии, сама же документация может генерироваться автоматически при каждой новой сборке.

В числе прочих форматов doxygen позволяет сохранять документацию в виде pdf- или rtf-файла (с автоматической нумерацией и программируемыми полями), который затем можно открыть в Microsoft Word.

Также doxygen содержит компилятор latex, что позволяет дополнять документацию формулами.

По умолчанию doxygen поддерживает C++, Python и другие языки (список возможностей). Также есть ряд расширений, добавляющих поддержку Matlab, позволяющих интегрировать doxygen в Visual Studio и др.

Примеры

Gitignore

В файле .gitignore указываются файлы и папки в git-репозитории, появление и изменения которых не нужно отслеживать. Например, исполнительные файлы и различные временные файлы, генерируемые при сборке, по ряду причин не принято загружать в репозиторий.

Шаблоны gitignore для разных языков программирования

Makefile

[Пример для Windows] (zip)

[Пример для Unix] (zip)

NSIS

Примеры на сайте NSIS [Пример для NSIS2] (zip)

Doxygen

Все настройки указываются в текстовом файле конфигураций. Для старта генерации достаточно при запуске doxygen в качестве аргумента указать путь до конфигурационного файла. При использовании графического интерфейса конфигурации можно сохранять и загружать из текстового файла.

Пользователям Unix-систем нужно быть внимательными с выбором кодировок: по умолчанию лучше использовать кодировку utf-8, однако при генерации rtf-документа кодировка как конфигурационного файла, так и выходных файлов должна быть cp-1251.

Пример для C++ и Python (zip)

Catch2

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

Примеры на странице Catch2

Пример для C++ (zip)