Учебник о том, как быстро и легко разработать собственный пакет Julia
Мы пошагово покажем, как разработать свой первый пакет в Julia. Для этого мы используем очень полезный PkgTemplate.jl и основываем наше Учебное пособие на этом руководстве от Quantecon и на этом видео от Криса Ракаукаса.
Перво-наперво. Начните с создания папки для хранения вашего пакета. В нашем случае мы будем создавать пакет под названием «VegaGraphs», который я разрабатываю. Итак, внутри этой папки откройте свой Julia REPL и установите PkgTemplate.jl.
1. Создание шаблона пакета
Во-первых, нам нужно создать шаблон для нашего пакета. Этот шаблон будет включать такие вещи, как лицензирование, плагины, авторов и т. Д. В нашем примере мы будем использовать простой шаблон с лицензией MIT. Будут использоваться плагины GitHub Actions и Codecov. Я не буду углубляться в эти плагины, но для ясности кратко объясню, что они делают.
- GitHub Actions - это плагин, который автоматически создает виртуальную машину и тестирует ваш код, поэтому вы можете контролировать конфигурации машины, необходимые для запуска вашего пакета.
- Codecov - это плагин, который анализирует ваш код и оценивает, какая его часть покрыта вашими тестами. Так, например, предположим, что вы написали 3 разные функции, но забыли написать тест для одной из них. Затем Codecov укажет на отсутствие тестов для такой функции.
По-прежнему внутри REPL выполните следующие команды:
using PkgTemplates
t = Template(;user="YourUserNameOnGithub", plugins = [GitHubActions(), Codecov()], manifest = true)
generate("VegaGraphs.jl",t)
Первая строка кода определяет шаблон, а вторая сгенерирует ваш пакет. Обратите внимание, что я не указал папку, поэтому пакет будет создан в местоположении по умолчанию, которым будет ~/.julia/dev (для Linux).
Теперь просто скопируйте файлы из ~/.julia/dev/VegaGraphs в папку, из которой вы будете работать, а затем настройте свой репозиторий git, выполнив следующие команды в терминале:
# inside the VegaGraphs working folder git init git add -A git commit -m "first commit" git branch -M master git remote add origin [email protected]:YOURUSERNAME/VegaGraphs.git git push -u origin master
Заглянув внутрь созданной папки, вы увидите две папки и четыре файла:
./src ./test README.md LICENSE Manifest.toml Project.toml
/src: В этой папке вы будете писать код для вашего пакета как такового;/test: Здесь для хранения ваших тестов;Project.toml: здесь вы будете хранить такую информацию, как автор, зависимости, версия julia и т. Д .;Manifest.toml: Это файл, созданный машиной, и вы должны просто оставить его как есть;
Остальные файлы говорят сами за себя.
2. Написание кода
Мы готовы начать кодирование нашего пакета. Обратите внимание, что внутри папки /src у нас уже есть файл с именем VegaGraphs.jl, который является основным файлом нашего пакета. Мы можем выполнять весь код прямо внутри VegaGraphs.jl, но по мере того, как наш код становится большим, это может стать беспорядочным.
Вместо этого мы можем написать много разных файлов для организации нашего кода, а затем использовать VegaGraphs.jl, чтобы объединить все вместе. Приведем пример. Мы запрограммируем очень простую функцию и сохраним ее в другом файле с именем graph_functions.jl, который также будет находиться в папке ./src .
Вот пример кода:
# code inside graph_functions.jl function sum_values(x,y) return x+y end
Приведенный выше код представляет собой простую реализацию функции. Ниже я покажу, как на самом деле сделать эту функцию доступной для пользователей. Достаточно просто «включить» graph_functions.jl файл и экспортировать plot_scatter. После экспорта функция теперь доступна всем, кто импортирует наш пакет.
# code inside VegaGraphs.jl
module VegaGraphs
using VegaLite
export sum_values
include("graph_functions.jl")
end
Обратите внимание, что, помимо нашей функции, я также импортировал пакет VegaLite. Следовательно, мне нужно указать VegaLite.jl как зависимость. Мы сделаем это снова, используя REPL.
Перейдите в корень вашего пакета и откройте REPL, выполнив команду julia в терминале. Теперь нажмите ]. Это переведет вас в «пакетный режим». Затем напишите activate ., что активирует среду Julia в вашей текущей папке. Наконец, напишите add VegaLite, и это добавит VegaLite.jl к вашим зависимостям внутри файла Project.toml.
3. Создание и запуск тестов.
Итак, мы реализовали функцию и добавили зависимость в наш пакет. Следующим шагом является написание теста, чтобы гарантировать, что наш код действительно работает. Код не требует пояснений, мы просто пишем наш тест внутри набора тестов. Вы можете написать сколько угодно, чтобы гарантировать правильную работу вашей функции.
# code inside ./test/runtests.jl using VegaGraphs using Test @testset "VegaGraphs.jl" begin x = 2 y = 2 @test VegaGraphs.sum_values(x,y) == 4 end
После того, как тест написан, мы должны запустить его и посмотреть, все ли работает. Снова зайдите в корень проекта и откройте свой REPL. Убедитесь, что ваша среда активирована, и запустите тесты, как показано на изображении ниже:
Это запустит ваши тесты и увидит, все ли проходит. Как только все пройдет, мы можем быть уверены, что наш код работает правильно, и можем перейти к другим реализациям.
4. Рабочий процесс - текстовый редактор + блокнот Jupyter
Со всем, что было показано до сих пор, вы уже готовы разработать свой пакет в Julia. Тем не менее, вам может быть интересно, как разработать эффективный рабочий процесс. Здесь есть много возможностей, например, использование таких IDE, как Juno и VsCode. Я предпочитаю использовать Jupyter Notebooks с Vim (мой любимый текстовый редактор) и делать все из терминала.
Чтобы использовать ваш пакет разработки в своем блокноте, вам нужно будет активировать свою среду таким же образом, как мы делали до сих пор. Открывая новую записную книжку, запустите следующий код в самой первой ячейке.
Обратите внимание, что помимо активации среды мы также импортировали пакет под названием Revise. Этот пакет очень полезен, и его следует импортировать в самом начале записной книжки, прежде чем вы фактически импортируете собственный пакет, иначе он не будет работать должным образом!
Каждый раз, когда вы изменяете код в своем пакете, чтобы загрузить изменения в записную книжку, вам придется перезапускать ядро. Но когда вы используете Revise.jl, вам не нужно перезапускать ядро, просто снова импортируйте свой пакет, и изменения будут применены.
Теперь мой рабочий процесс очень прост. Я использую Vim для изменения кода в моем пакете и использую Notebook для проверки. Как только у меня все работает как надо, я записываю несколько тестов и все тестирую.
5. Регистрация / публикация вашего пакета
Наконец, предположим, что вы закончили писать свой пакет и готовы поделиться им с сообществом Julia. Как и в случае с другими пакетами, вы хотите, чтобы пользователи могли написать простой Pkg.add("MyPackage") и установить его. Этот процесс называется регистрацией.
Для этого сначала перейдите на Registrator.jl и установите приложение в свою учетную запись Github.
Затем перейдите на страницу своего пакета на Github и перейдите на вкладку «Проблемы». Создайте новую проблему, напишите @JuliaRegistrator register(), как показано на изображении ниже.
Как только вы это сделаете, бот JuliaRegistrator откроет запрос на перенос для регистрации вашего пакета. Если вы на самом деле не хотите, чтобы ваш пакет был зарегистрирован, не сообщайте о проблеме.
И это все.
