Редактирование: GitHub

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

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

На сайте '''[https://github.com GitHub]''' создан общий аккаунт для размещения ПО, разрабатываемого в НОЦ «Газпромнефть-Политех». Каждому проекту может быть создан свой приватный '''[https://ru.wikipedia.org/wiki/Git git]'''-репозиторий для сохранения исходных кодов, библиотек, документации и прочих файлов.

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

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

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

Общий пользователь НОЦ: [https://github.com/gpn-polytech @gpn-polytech]

Подключение к приватным репозиториям требует аккаунт на '''[https://github.com/join GitHub]'''. Регистрация полностью бесплатна (помимо этого существуют платные тарифы). По адресу почты в домене '''@spbstu.ru''' легко оформить [https://education.github.com/pack студенческий аккаунт], предоставляющий больше возможностей для личного использования.

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

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

=== Ограничения ===

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

Подробнее:
* [https://help.github.com/articles/what-is-my-disk-quota/ Conditions for large files]
* [https://help.github.com/articles/conditions-for-large-files/ What is my disk quota?]

== Участники ==

* [[Илья Антонов|Антонов Илья]] – [https://github.com/antoidco @antoidco]
* [[Калюжнюк Александр Всеволодович | Калюжнюк Александр]] – [https://github.com/iomguy @iomguy]
* [[Краева Светлана]] – [https://github.com/svetlanakraeva @svetlanakraeva]
* [[Лапин Руслан Леонидович | Лапин Руслан]] – [https://github.com/FanOfRammstein @FanOfRammstein]
* [[Марков Николай]] – [https://github.com/mksfmksf @mksfmksf]
* [[Мурачёв Андрей]] – [https://github.com/anewmur @anewmur]
* [[Мущак Никита]] – [https://github.com/NikitaMushchak @NikitaMushchak]
* [[Осокина Алена]] – [https://github.com/ElaineEddington @ElaineEddington]
* [[Старобинский Егор]] – [https://github.com/starobinskii @starobinskii]
* [[Хлопин_С._В. | Хлопин Сергей]] – [https://github.com/hlserg @hlserg]
* [[Цветков Денис Валерьевич | Цветков Денис]] – [https://github.com/AHuxley @AHuxley]
* [[Шварёв Николай Григорьевич | Шварёв Николай]] – [https://github.com/megameowmeow @megameowmeow]

== Проекты ==

=== [https://github.com/gpn-polytech/FractureGUI FractureGUI] ===
Графический интерфейс для программных средств моделирования гидроразрыва пласта.

'''Ответственный''': [[Шварёв Николай Григорьевич|Шварёв Николай]]

=== [https://github.com/gpn-polytech/Planar3D-LL Planar3D-LL] ===
Программа расчета геометрии трещины ГРП с использованием функции Грина для слоистой среды и универсальных асимптотик для отслеживания фронта трещины ГРП для плоской трехмерной трещины ГРП с учетом контраста упругих модулей.

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

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

Использование систем контроля версий позволяет упростить процесс разработки ПО, с одной стороны раздельно сохраняя модификации файлов, а с другой — обеспечивая разработчика инструментом объединения различных модификаций в единую версию. Примерами таких систем являются '''[https://git-scm.com Git]''', '''[https://subversion.apache.org Subversion]''' ('''svn'''), '''[https://www.mercurial-scm.org Mercurial]'''.

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

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

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

Использование '''git'''-систем особенно удобно при разработке открытого ПО, так как существует большой набор бесплатных (для открытых лицензий) инструментов для '''[https://ru.m.wikipedia.org/wiki/Непрерывная_интеграция непрерывной интеграции]''' ('''Continuous Integration''').

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

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

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

Как на '''Unix'''-системах, так и на '''Windows''' возможно использование '''Make'''-файлов ('''[https://en.m.wikipedia.org/wiki/Make_(software) Makefile]''') — мощного инструмента автоматизации и настройки сборки. На '''Linux''' и '''macOS''' сборка с '''Makefile''' может быть осуществлена программой '''make''' или '''gmake''', на '''Windows''' — программой '''[https://msdn.microsoft.com/en-us/library/dd9y37ha.aspx nmake]''', идущей в комплекте с '''Visual C++ Build Tools''' и '''Visual Studio'''. Существует также специальная утилита '''[https://cmake.org CMake]''', позволяющая сгенерировать '''Makefile''' под целевую платформу автоматически (на основе конфигурационных файлов).

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

=== Python ===
Программа '''[https://www.pyinstaller.org PyInstaller]''' позволяет собирать '''python'''-проекты в исполнительные файлы на разных платформах (включая '''Windows''', '''Linux''', '''macOS'''), автоматически подгружая [https://github.com/pyinstaller/pyinstaller/wiki/Supported-Packages необходимые библиотеки]. Модификация исходного кода не требуется. Доступна сборка графических интерфейсов ('''Qt4''', '''Qt5''', '''wxWidgets''', '''GTK''') без консольного окна. Собранный проект не будет зависеть от того, установлен ли '''python''' нужной версии и требуемые библиотеки на компьютер пользователя.

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

== Тестирование ==
Современные методы тестирования направлены на проверку всех элементов программы, включая пользовательские интерфейсы. На практике проверка корректности работы включает перебор слишком большого количества параметров, чтобы проводить регулярное тестирование в ручном режиме. Если какая-то функция перестала работать корректно несколько сборок тому назад, поиск ошибки даже при использовании систем контроля версий может потребовать много времени. Библиотеки для автоматического тестирования (к примеру, для '''C++''' можно использовать '''[https://github.com/catchorg/Catch2 Catch2]''') позволяют существенно упростить эту процедуру.

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

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

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

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

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

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

=== [https://guides.github.com/features/mastering-markdown/ Markdown] ===

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

Традиционно репозитории содержат следующие файлы:
* [https://gist.github.com/PurpleBooth/109311bb0361f32d87a2 '''README.md'''] – описание проекта, процедур сборки, установки и использования ПО, ссылки на авторов и документацию;
* [https://keepachangelog.com/ru/1.0.0/ '''CHANGELOG.md'''] – описание изменений между разными версиями ПО.

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

=== [http://www.stack.nl/~dimitri/doxygen/index.html Doxygen] ===
'''Doxygen''' — гибкий инструмент генерации программной документации по исходному коду. Его основополагающая функция — это построение структуры программы в виде '''xml'''-дерева, которая может быть проанализирована с помощью различных утилит (зависимости, уязвимости, схемы вызовов и пр.).

Документация формируется по [http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html комментариям в исходном коде], дополнительно строятся списки функций, классов, методов и глобальных переменных. Рисуются схемы зависимостей и графы вызовов ('''call''' и '''caller'''). Подобная документация, сохранённая, к примеру, в формате '''html''' файлов, позволяет сформировать у пользователя более полное понимание структуры программы, её API, передаваемых параметрах и возможных ошибках. Преимущество такого подхода заключается в простоте обновления документации — достаточно поддерживать комментарии в актуальном состоянии, сама же документация может генерироваться автоматически при каждой новой сборке.

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

Также '''doxygen''' содержит компилятор '''latex''', что позволяет дополнять документацию [https://www.stack.nl/~dimitri/doxygen/manual/formulas.html формулами].

По умолчанию '''doxygen''' поддерживает '''C++''', '''Python''' и другие языки ([http://www.stack.nl/~dimitri/doxygen/manual/features.html список возможностей]).
Также есть [http://www.stack.nl/~dimitri/doxygen/helpers.html ряд расширений], добавляющих поддержку '''Matlab''', позволяющих интегрировать '''doxygen''' в '''Visual Studio''' и др.

== Примеры ==

=== Gitignore ===

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

[https://github.com/github/gitignore Шаблоны '''gitignore''' для разных языков программирования]

=== Makefile ===

'''Make'''-файлы для '''Window''' и '''Unix''' имеют [https://cognitivewaves.wordpress.com/makefiles-windows/ существенные различия]. Выбор, какой '''Makefile''' использовать при сборке, обычно делается с помощью ключа '''-f'''.

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

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

=== NSIS ===

[https://nsis.sourceforge.io/Category:Code_Examples Примеры на сайте '''NSIS''']

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

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

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

[http://mech.spbstu.ru/images/2/27/Doxygen.zip Пример для '''C++''' и '''Python'''] (zip)

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

[https://github.com/catchorg/Catch2/blob/master/docs/tutorial.md Примеры на странице '''Catch2''']

[http://mech.spbstu.ru/images/c/cc/Catch.zip Пример для '''C++'''] (zip)