Переходим на MQL5 Algo Forge (Часть 3): Использование чужих репозиториев в собственном проекте

Введение

Во второй части описания нашего перехода на MQL5 Algo Forge мы сосредоточились на решении одной из важных задач — работе с несколькими репозиториями. На примере связки библиотечного проекта Adwizard и проекта советника Simple Candles мы столкнулись и успешно решили возникшие проблемы, в основном связанные с путями включения файлов и слиянием веток. Весь процесс, от создания отдельной ветки для исправлений до её слияния через Pull Request, мы старались проделать с использованием инструментов MetaEditor. Но там, где его функциональности не хватало, переключались на веб-интерфейс хранилища MQL5 Algo Forge, сторонний клиент Git в интерфейсе Visual Studio Code или консольные команды Git. Это наглядно показало, как даже в рамках индивидуальной разработки можно применять лучшие практики Git для поддержания порядка и истории изменений в проекте.

Но это была лишь одна из двух сторон использования хранилища — «закрытая» экосистема, где разработчик является владельцем всех используемых репозиториев. Логичным следующим шагом, ради которого во многом и затевался переход на Git, является возможность полноценного использования публичных репозиториев других участников сообщества. Именно здесь открывается истинный потенциал распределённой разработки: возможность легко подключать и обновлять сторонний код, участвовать в его улучшении и собирать сложные проекты из готовых, отлаженных компонентов. 

В этой статье мы наконец обратимся к этой многообещающей, но и более сложной задаче: как на практике подключить и использовать в своём проекте библиотеки из чужих репозиториев хранилища MQL5 Algo Forge. Причём не когда-нибудь потом, а прямо сейчас, без ожидания будущего развития инструментов работы с репозиториями в MetaEditor. 

Намечаем путь

В этой статье мы продолжим работу над нашим проектным репозиторием Simple Candles, который послужит отличным полигоном для экспериментов. В существующей торговой стратегии уже реализован самостоятельный расчет волатильности, функционально похожий на стандартный Average True Range (ATR). Однако, вместо того чтобы довольствоваться собственным решением, мы посмотрим, как можно улучшить код, воспользовавшись готовыми специализированными наработками сообщества.

Для этого мы обратимся к публично доступному репозиторию SmartATR — предполагаем, что в нем содержится более совершенная и оптимизированная версия индикатора. Наша отдалённая практическая цель — модифицировать советник, предоставив ему возможность выбора: продолжать использовать внутренний расчет, или переключиться на алгоритм из внешней библиотеки SmartATR. Однако в рамках данной статьи не будем фокусироваться именно на создании работающего советника, а рассмотрим в основном сопутствующие вопросы, касающиеся взаимодействия с репозиториями кода.

Чтобы достичь этого, нам предстоит сделать следующее. Сначала нужно получить код библиотеки SmartATR на локальный компьютер и организовать его подключение к нашему проекту. Мы рассмотрим, как можно добавить чужой репозиторий в свою рабочую среду, чтобы в будущем его можно было легко обновлять при выходе новых версий. После этого, мы должны будем внести правки в код проекта Simple Candles и, как оказалось, в код библиотеки SmartATR. Без последнего, в более благоприятной ситуации, можно было бы и обойтись, но раз уж так вышло, то отработаем на этом примере алгоритм действий по внесению правок в чужой репозиторий. В конце проверим возможность подключения и совместной компиляции кода библиотечного индикатора в составе нашего проекта.

Такой подход позволит нам детально отработать весь процесс интеграции стороннего кода. Полученный опыт будет универсальным: успешно добавив одну библиотеку, мы сможем по той же схеме включать в свои проекты любые другие публичные репозитории из MQL5 Algo Forge.

Получаем чужой код

Тут проблем вроде бы нет. Любой Git-репозиторий можно клонировать на свой локальный компьютер, используя консольную команду

Но мы договорились сначала пробовать обходиться интерфейсом MetaEditor, затем веб-интерфейсом MQL5 Algo Forge и только после того, как там нельзя будет добиться результата, обращаться с сторонним средствам (Visual Studio Code) и консольным командам Git.

Поэтому первый вопрос — как увидеть чужой репозиторий в MetaEditor, чтобы выбрать его для клонирования? Частично ответ можно было бы найти на странице помощи, но мало кто сможет сразу узнать об этом месте и догадаться поискать там. Мы, к сожалению, нашли эту страницу только позже. А до этого мы столкнулись с тем, что сейчас в составе папки Shared Projects мы видим исключительно свои репозитории. Попробуем изучить контекстное меню для этой папки в Навигаторе MetaEditor. 

Пункт "New Project" нам не подходит, так как это создаст новый наш репозиторий. Использование "Refresh" тоже не добавляет каких либо чужих репозиториев. Пункт "Show All Files" пока работает как-то странно — после нажатия, в списке появились дубликаты названий тех наших репозиториев, которые не клонированы на этом компьютере. Но после нажатия "Refresh", они, к счастью, пропадают. Последняя надежда возлагалась на пункт "Show All Public Projects", но включение и отключение этого режима тоже ничего не меняло.

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

Путь первый: прямое клонирование

Для начала попробуем провести такой эксперимент. Если мы создадим пустую папку с произвольным именем (например, TestRepo) в папке Shared Projects, то она станет видна в MetaEditor. На ней можно даже выполнить команду "Clone" из контекстного меню, то есть этот пункт доступен для нажатия. Но если это сделать, то, судя по логам, мы пытаемся клонировать из хранилища наш репозиторий с именем TestRepo, которого, естественно, не существует:

Что ж, этот способ не подойдет для клонирования чужого репозитория. Попробуем теперь клонировать выбранный чужой репозиторий SmartATR в папку Shared Projects, используя консольную команду git clone..., и посмотреть что получится.

После клонирования в папке Shared Projects появилась новая папка SmartATR, которая отображается в Навигаторе в MetaEditor. Причем мы можем не только видеть этот репозиторий в списке в Навигаторе, но и работать с ним как с репозиторием: обновлять (Pull) и смотреть историю изменений (Log) из MetaEditor:

Таким образом, в интерфейсе MetaEditor пока не хватает пункта контекстного меню, наподобие "Clone from...", после выбора которого запрашивался бы адрес интересующего репозитория из хранилища, или предоставлялась бы возможность открыть диалог поиска и выбора среди всех публичных репозиториев хранилища MQL5 Algo Forge (как в веб-интерфейсе в разделе Explore). Другим возможным вариантом могло бы быть добавление отображения в списке Shared Projects не только своих репозиториев, но и чужих репозиториев, добавленных в избранные в веб-интерфейсе (Starred Repositories) с возможностью включения и отключения показа таких репозиториев. Но не будем загадывать наперёд, какие изменения будут сделаны в интерфейсе MetaEditor в дальнейшем.

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

Проверка работоспособности

В составе проекта SmartATR мы получили файл с исходным кодом индикатора для MetaTrader 5, который, как следует из описания проекта, позволяет рассчитывать показатель Average True Range (ATR) более изощрённым способом, чем стандартный индикатор ATR из поставки MetaTrader 5. Попробуем его скомпилировать... и получим ошибку. 

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

Но сначала представим, что публикацию исправлений мы решили отложить на будущее. В самом деле, прежде всего надо суметь исправить возникшие ошибки, и только потом будет уже предмет для публикации. Так что если сначала мы будем ориентироваться на внесение правок в проект SmartATR только для себя, то можно просто создать локальную ветку для изменений. 

Попробуем это сделать. В исходном репозитории есть единственная ветка main, поэтому создадим новую ветку с именем develop через контекстное меню папки проекта в MetaEditor. Ветка создалась и появилась в списке веток, показываемых MetaEditor. После нажатия Push, в логах выводится сообщение, что отправка успешно выполнена. Можно было бы ожидать, что новая ветка появилась в оригинальном репозитории, но проверка в веб-интерфейсе хранилища MQL5 Algo Forge показывает, что нет.

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

Однако повторная проверка в веб-интерфейсе хранилища MQL5 Algo Forge показывает, что в исходном репозитории снова ничего не поменялось. Это как минимум странно. Попробуем разобраться, что происходит, обратившись к VS Code. Открыв там папку с нашим клоном проекта SmartATR, видим следующее:

Как видно, последняя фиксация существует, но нам предлагается опубликовать ветку develop. То есть в вышестоящем репозитории эта ветка пока отсутствует, а значит, отсутствует там и наш последний коммит. Попробуем опубликовать ветку и получим такую ошибку:

Её причину можно посмотреть в логе:

То есть у нашего пользователя нет прав на запись в оригинальный репозиторий. Это в общем-то и логично, ведь если бы это было можно делать, то проект мог бы просто превратиться в непонятно что из-за бесконтрольного внесения правок со стороны любых пользователей. Поэтому получается, что мы можем вносить правки только в своей локальной копии, которая... никуда не может быть синхронизирована и будет существовать только в этом единственном клоне репозитория на данном локальном компьютере. Такого допускать нельзя, так как помимо возможности совместной работы, внешние хранилища обеспечивают выполнение ещё одной важной функции — хранения резервной копии кода проекта. И отказываться от такой возможности не стоит.

Отдельно ещё стоит отметить, что сейчас, работая только в MetaEditor, мы не можем увидеть, что что-то идёт не так. Если смотреть только на его логи, то из них следует, что всё в порядке, никаких ошибок нет, все правки благополучно отправляются... в несуществующий наш репозиторий. Надеемся, что в следующих билдах это будет исправлено.

Путь второй: клонирование форка

Попробуем пойти теперь другим путём. Здесь нам тоже придётся выйти за пределы текущих возможностей MetaEditor, но зато можно ограничиться только дополнительным использованием веб-интерфейса хранилища MQL5 Algo Forge. Для тех, кто испытывает сложности при использовании командной строки для работы с репозиториями, это будет компромиссным вариантом. Итак, в веб-интерфейсе хранилища можно сделать форк интересующего нас оригинального репозитория. 

Форк (Fork) — это фундаментальное понятие в системах контроля версий и платформах для совместной разработки, к которым относится и MQL5 Algo Forge, обозначающее процесс создания полной и независимой копии оригинального репозитория в рамках платформы.

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

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

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

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

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

Таким образом, если мы сделаем форк чужого репозитория, то у нас появляется новый собственный репозиторий. Значит, он станет доступным в генерируемом списке репозиториев в папке Shared Projects и готовым к клонированию из MetaEditor.

Проверяем работу с форком

Благодаря любезной помощи Fernando Carreiro, мы проверили этот механизм в действии. Для этого мы сделали форк его репозитория FMIC, добавив заодно исходный репозиторий в веб-интерфейсе хранилища в список отслеживаемых (Watch) и в избранное (Star).

Он появился в списке отображаемых репозиториев в Shared Projects в MetaEditor:

Так что мы смогли выполнить клонирование нашего только что созданного форка оригинального репозитория FMIC на локальный компьютер.

Далее мы попросили сделать фиксацию каких-нибудь изменений, чтобы посмотреть, каким образом мы сможем о них узнать для обновления форка. Фернандо добавил в качестве теста описание публикации Heikin Ashi в виде файла README.md и зафиксировал его в репозитории.

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

• Создание форка
• Конфигурирование upstream
• Синхронизация

Да, это написано не для конкретно MQL5 Algo Forge, но многое в веб-интерфейсе работает почти также, а консольные команды так вообще не привязаны к типу используемого хранилища. Главное, чтобы они использовали именно Git.

Например, руководствуясь материалами раздела конфигурирование upstream, мы можем настроить выполнение синхронизации клона форка с оригинальным репозиторием при каждом выполнении команд Pull/Push:

Но при работе через MetaEditor и веб-интерфейс хранилища MQL5 Algo Forge, этот шаг не является необходимым.

Форк SmartATR

Вернемся теперь к тому репозиторию, который изначально планировали задействовать. Повторим уже проделанные шаги по созданию форка в веб-интерфейсе хранилища MQL5 Algo Forge и клонированию его на локальный компьютер для репозитория SmatrATR.

Найдём нужный оригинальный репозиторий, указав на странице Explore название нужного репозитория:

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

Там нажимаем на кнопку создания форка:

После нажатия, мы попадаем на страницу свойств создаваемого форка. Тут мы можем, например, поменять имя репозитория форка, под которым он будет существовать в списке наших репозиториев, указать, какие ветки из оригинального репозитория мы хотим перенести в наш форк и отредактировать описание создаваемого форка:

По умолчанию при создании форка будет создаваться точная копия оригинального репозитория. Нас это вполне устраивает, поэтому просто нажимаем кнопку "Fork repository".

Форк успешно создан:

Теперь создадим клон этого репозитория на локальном компьютере. Перед этим удалим созданную ранее папку с оригинальным репозиторием на локальном компьютере. Если MetaEditor уже был запущен ранее, то чтобы в списке подпапок появилась папка SmartATR, понадобится выполнить команду "Refresh" из контекстного меню папки Shared Projects в Навигаторе. После этого, выберем в контекстном меню папки SmartATR пункт "Git Clone": 

Проект SmartATR успешно клонировался:

Мы можем начать работу по внесению правок.

Вносим правки

Поскольку мы хотим внести правки, исправляющие или, по крайней мере, нейтрализующие конкретную ошибку, то создадим новую ветку, в названии которой будет отражена наша цель (fixes/news-impact):

И переключимся на неё в контекстном меню проекта, выбрав "Git Branches → fixes-news-impact":

Обратите внимание, что несмотря на то, что при создании ветки мы использовали в названии символ "/", в реально созданной ветке этот символ автоматически заменился на "-". Хотя, вроде бы, со стороны Git таких ограничений нет, и через веб-интерфейс мы можем спокойно создать новую ветку со слешем в названии, MetaEditor запрещает использовать при создании ветки любые символы, кроме латинских букв и дефиса. 

Попробуем проверить, насколько критично следовать такому ограничению. Создадим ещё новую ветку через веб-интерфейс хранилища MQL5 Algo Forge, использовав слеш в названии, например "fixes/cast-warning". Для этого зайдём на страницу Branches и нажмем кнопку создания новой ветки из существующей ветки main:

Ветка успешно создана:

Однако, если мы выполним команду Pull в MetaEditor, то сталкиваемся с таким сообщением об ошибке:

Тем не менее новая ветка со слешем в названии появилась в списке веток в MetaEditor, и переключение на неё не вызывает каких-либо сообщений об ошибке:

Отметив эту особенность, переключимся снова на ветку fixes-news-impact и внесём правки, временно убирающие причину возникновения ошибки:

После этого файл индикатора компилируется без ошибок, и мы можем сделать фиксацию наших правок через пункт контекстного меню "Git Commit": 

В появившемся диалоге проверяем состав файлов, изменения в которых мы хотим зафиксировать. Для изменений в одном файле эта проверка очень проста. Также очень желательно добавить комментарий, описывающий, какие изменения делает этот коммит. Убедившись, что всё указано правильно, нажимаем OK.

После этого внесённые правки отправляются в наш вышестоящий репозиторий в хранилище MQL5 Algo Forge, являющийся форком оригинального репозитория проекта SmartATR. Исправленной версией индикатора мы уже можем пользоваться на локальном компьютере и её резервная копия также присутствует в нашем хранилище. Далее, при желании, мы можем отправить запрос на слияние наших правок автору оригинального репозитория, нажав в веб-интерфейсе на странице Branches кнопку "New pull request":

Но пока это делать рано, так как мы, по сути, не сделали каких либо полезных улучшений кода проекта, а только отключили часть функциональности, в реализации которой была обнаружена ошибка. Поэтому не будем сейчас создавать Pull Request.

Всё готово к использованию индикатора SmartATR в нашем проекте Simple Candles.

Подключаем индикатор

Следуя принятым правилам, для внесения изменений в проект Simple Candles создадим новую ветку article-19436-forge3 в репозитории проекта от ветки develop. Для разнообразия сделаем это в веб-интерфейсе хранилища MQL5 Algo Forge, как было описано выше.

Для того чтобы новая ветка появилась в клоне репозитория на нашем локальном компьютере, выполним в MetaEditor команду "Git Pull" из контекстного меню репозитория проекта и переключимся на появившуюся ветку article-19436-forge3.

Поскольку применять этот индикатор мы планируем в торговой стратегии, то и добавлять его будем в файл класса используемой торговой стратегии SimpleCandlesStrategy.mqh. Добавим в список полей класса переменную для хранения хендла этого индикатора:

//+------------------------------------------------------------------+
//| Торговая стратегия c использованием однонаправленных свечей      |
//+------------------------------------------------------------------+
class CSimpleCandlesStrategy : public CVirtualStrategy {
protected:
   //...

   int               m_iATRHandle;        // Хендл индикатора SmartATR

   //...
};

Затем в конструкторе класса вызовем функцию iCustom(), которой передадим в качестве параметров символ, таймфрейм, путь к файлу индикатора и список параметров для самого индикатора:

//+------------------------------------------------------------------+
//| Конструктор                                                      |
//+------------------------------------------------------------------+
CSimpleCandlesStrategy::CSimpleCandlesStrategy(string p_params) {
// Читаем параметры из строки инициализации
   // ...

   if(IsValid()) {
      // Загружаем индикатор SmartATR
      m_iATRHandle = iCustom(
                        m_symbol, m_timeframe,
                        "Shared Projects/SmartATR/SmartATR.ex5",
                        // Параметры индикатора
                        m_periodATR,   // Initial ATR period (used for first calculation, adaptively changes)
                        false,         // Enable adaptive period (dynamic lookback)
                        7,             // Minimum ATR period (adaptive mode)
                        28,            // Maximum ATR period (adaptive mode)
                        false,         // Weight True Range by volume
                        false,         // Weight True Range by economic news events (MT5 Calendar)
                        2.0,           // Multiplier: alert if ATR exceeds this factor of average
                        false          // Enable pop-up & sound alerts on high volatility
                     );

      // ...
   }
}

Обратите внимание, как мы указываем путь к файлу индикатора. Он начинается с имени папки Shared Projects, затем идёт название папки репозитория проекта SmartATR и, в самом конце, имя самого файла индикатора SmartATR.ex5. Расширение .ex5 можно опустить, но мы специально его оставили, чтобы было понятно, где название папки, а где название самого индикатора.

Есть ещё один важный нюанс, который следует учитывать при работе с проектами в папке Shared Projects. Не важно, будут ли это свои проекты или чужие. Он состоит в том, что при компиляции все исполняемые файлы создаются не в папке репозитория, а в другом месте! Это связано с тем, что папка Shared Projects находится в корне папки данных терминала, то есть MQL5/Shared Projects. С одной стороны, это хорошо — система контроля версий не будет пытаться предлагать добавить в индекс запускаемые файлы. С другой стороны, сначала это может несколько дезориентировать: где же нам искать скомпилированные файлы советников и индикаторов?

Оказывается, в папках, соответствующих разным типам программ (MQL5/Experts для советников, MQL5/Indicators для индикаторов и так далее) при компиляции автоматически создаются вложенные папки Shared Projects с подпапками проектов. Именно в них попадают скомпилированные файлы. То есть, если мы компилируем исходный файл по адресу MQL5/Shared Projects/SmartATR.mq5, то запускаемый файл индикатора надо искать по адресу MQL5/Indicators/Shared Projects/SmartATR/SmartATR.ex5.

Получается, что при вызове функции iCustom() мы должны указать путь к файлу индикатора относительно папки MQL5/Indicators.

Что же, скомпилируем файл советника SimpleCandles.mq5, в котором используются экземпляры торговых стратегий с подключенным индикатором и запустим его в тестере стратегий для проверки. В логах можно увидеть следующие сообщения:

То есть, код индикатора успешно загружен, проинициализирован и может использоваться при работе советника. Пока что индикатор никак не используется, так как мы хотели продемонстрировать прежде всего возможность его использования. Ну а к реальному использованию мы, может быть, приступим немного позже. Сделаем коммит наших правок и отправим сделанные изменения в хранилище MQL5 Algo Forge.

Заключение