Несколько месяцев назад компания Wolfram Research открыла общий доступ к Wolfram Language Paclet Repository. Это централизованное хранилище пользовательских пакетов, написанных на языке Wolfram. Данное хранилище не является чем-то новым само по себе. Для языка Wolfram уже есть несколько возможных способов публикации пакетов. Однако, у официального репозитория есть несколько очень важный преимуществ перед существующими решениями. В этой статье я сначала коротко расскажу что из себя представляет репозиторий, а затем пошагово покажу как опубликовать в него свой собственный пакет при помощи предоставленных компанией Wolfram Research инструментов.
Что такое пакет на языке Wolfram
Пакет - это почти любой код, который можно загрузить в текущую сессию пользователя. Это может быть всего один файл, где есть одна функция, а может быть довольно большая библиотека, где много файлов с исходным кодом и функций. Обычно расширение у файлов с кодом это *.wl или *.m, однако, иногда попадаются пакеты с файлами *.mx, которые представляют собой сериализованный варианты *.m и *.wl. Чаще всего, к сожалению, пользователи свои пакеты распространяют как есть в виде одного файла или папки с набором файлов. Но чуть-чуть более ответственные пользователи для удобства других людей упаковывают свой код в специальный файл с расширением *.paclet. Изначально паклеты придумали исключительно для того, чтобы стандартизировать создание документации для модулей Mathematica, однако, позже их возможности применения увеличились и на сегодняшний день *.paclet - это по сути архив, где содержится код, документация к нему и специальный файл PacletInfo.wl, который выполняет функцию, похожую на ту, что несет в себе например файл package-info.java для файлов *.jar. И что самое важное - PacletInfo.wl содержит в себе информацию для функции PacletInstall, которая выполняет стандартную установку пакетов. Интересно, что как и с файлам *.jar, файлы *.paclet можно просто распаковать архиватором, взять файлы с исходным кодом и в ручную поместить в нужную директорию, по сути выполнив установку.
Как устанавливать пакеты
Будем считать, что у пользователя уже установлены Wolfram Mathematica или Wolfram Engine. Тогда если он вдруг каким-то образом уже нашел необходимый для себя пакет, то у него есть несколько вариантов этот пакет установить.
Если это просто папка с файлами или один файл
Самый просто вариант - это использовать пакет без установки, а просто поместить найденный файл или папку рядом с вашим рабочим блокнотом, а в самом блокноте тогда нужно будет просто выполнить следующий код:
SetDirectory[NotebookDirectory[]];
Get["PackageName`"]Или даже без изменения рабочей директории для текущей сессии:
Get["/path/to/the/package"]Или даже без скачивания на свой компьютер - вы можете импортировать исходники прямо из github (или из любого другого места, доступного по http/https), если там всего один файл:
Get["https://raw.githubusercontent.com/UserName/RepoName/master/PackageName.wl"]Однако, удобнее всего поместить пакет в ту директорию, где Wolfram Language всегда сможет его найти без необходимости указания полного пути или изменения рабочий директории. Такое расположение всегда можно посмотреть если посмотреть значение системной переменной:
$PathЭта переменная - просто список директорий, по которым проходит ядро Wolfram в поисках пакета или при импорте любого файла. И там скорее всего будет строка примерно вот такого вида (для пользователей Windows и Mathematica):
C:\Users\UserName\AppData\Roaming\Mathematica\ApplicationsВот это и есть та самая папка, куда стоит помещать готовые пакеты, если вы их устанавливаете в ручную. Кроме того, путь к это директории можно получить использую другую системную переменную языка Wolfram:
FileNameJoin[{$UserBaseDirectory, "Applications"}]Т.е. вам будет достаточно скопировать любой скачанный на компьютер файл в эту директорию, после чего код из него он станет доступен для импорта в любом блокноте Wolfram:
CopyFile[
FileNameJoin[{$HomeDirectory, "Downloads", "PackageName.wl"}],
FileNameJoin[{$UserBaseDirectory, "Applications", "PackageName.wl"}]
]
Get["PackageName`"]Если это упакованный паклет
Тогда все очень просто. Либо распаковать его при помощи специальной функции и поместить файлы в папку с локальными пользовательскими пакетами:
dir = ExtractPacletArchive[
FileNameJoin[{$HomeDirectory, "Downloads", "PackageName.paclet"}]
]
CopyDirectory[
dir,
FileNameJoin[{$UserBaseDirectory, "Applications", "PackageName"}]
]Либо воспользоваться недавно (в 2020 году) добавленной функций, которая сделает это автоматически, но еще и с сохранением информации о версии пакета:
PacletInstall[FileNameJoin[{$HomeDirectory, "Downloads", "PackageName.paclet"}]]Тогда скачанный пакет установится в папку, путь в которой можно получить вот так:
FileNameJoin[{$UserBasePacletsDirectory, "Repository"}]Кроме того, начиная с версии 12.1 в языке Wolfram стала доступна подобная установка пакетов прям по http/https. Выглядеть это будет примерно вот так:
PacletInstall["https://github.com/UserName/PackageName/releases/download\
/vX.Y.Z/PackageName-X.Y.Z.paclet"]Где можно найти пакеты
Чаще всего пользователи, как и для всех остальных языков программирования, публикуют исходный код своих пакетов на github. Там же в разделе с релизами можно добавить и упакованные пакеты или архивы с исходными файлами. Выше мы рассмотрели как установить упакованный пакет напрямую по ссылке на загрузку файла, однако, некоторые пользователи либо запускаются собственные паклет-сайты. Кроме того, достаточно долгое время существовал официальный закрытый репозиторий компании Wolfram Research, из которого скачивались встроенные в Wolfram Language пакеты. Этот репозиторий является хранилищем по умолчанию, из него можно получать обновления встроенных пакетов, но в него никто ничего не может добавлять.
О Wolfram Language Paclet Repository
Не так давно появился Wolfram Function Repository, статья о котором есть на хабре (перевод статьи опубликовал Пётр Тенишев, который является администратором в группе по Wolfram Mathematica. Если вдруг читатели заинтересуются дополнительными материалами по языку Wolfram, то там постоянно появляется что-то новое на русском языке). Теперь компания добавила примерно тоже самое, но не для конкретных функций, а для пакетов. Пользователи получили возможность выложить в репозиторий любой свой пакет, после чего он станет доступен всем. Ключевым отличием является то, что данный репозиторий включен в список мест, откуда Wolfram Language может скачивать пакеты по умолчанию. То есть больше не нужно самостоятельно добавлять в системные настройки путь до паклет-сайта или указывать расположение архива напрямую.
Вторым отличием является то, что компания Wolfram Research выложила заранее заготовленный блокнот на языке Wolfram, в котором в виде дополнительного пользовательского интерфейса реализованы основные действия с пакетами. По сути этот блокнот похож чем-то на maven или ms build, но в достаточно необычной оболочке. На самом деле далее мы увидим какие именно шаги позволяет делать этот блокнот-сборщик.
Третье отличие - в репозиторий пакетов по умолчанию можно выкладывать и документацию на языке Wolfram. Т.е. сразу же писать блокноты с документацией и их отправлять в репозиторий. В общем лучше один раз увидеть...
Получаем PublisherID
Это просто необходимая системная переменная, которая будет связана с вашим аккаунтов в Wolfram Cloud. Для того чтобы его получить нужно просто иметь аккаунт на wolframcloud.com. А затем перейти на страницу, где можно заполнить форму и отправить запрос на получение PublisherID. Я уже выкладывал пакеты в репозиторий, поэтому у меня есть PublisherID == KirillBelov. Именно под этим именем я могу публиковать свои пакеты в репозитоии. Сделано это очевидно для того, чтобы не возникало ситуации когда пользователи выкладывают одинаковые пакеты. Ниже скриншот формы для получения идентификатора:
Создаем проект
Собственно перейдем к практике. В данный момент, пока я пишу эти строки, у меня на компьютере есть совсем небольшой пакет, где есть чуть-чуть исходного кода и он хорошо подходит для демонстрационных целей. В статье мы не будем описывать сам процесс написания пакета, а сосредоточимся только на его подготовке и публикации. Мой пакет называется BankCalculator. Он умеет показывать ожидаемый доход от банковских вкладов. В данный момент папка с проектом выглядит следующим образом:
Файл BankCalculator.wl переместим во внутреннюю папку Kernel. Если этой папки нет, то ее можно просто создать. Это нужно для удобства сборщика, т.к. сборщик ищет файлы в определенной папке. Если же файлы с исходным кодом будут находиться рядом с файлом PacletInfo.wl, то сборщик может найти лишние файлы.
Так же нужно добавить в эту директорию файл PacletInfo.wl и заполнить его необходимо следующими данными:
PacletObject[<|
"Name" -> "KirillBelov/BankCalculator",
"Description" -> "Bank calculator",
"Creator" -> "Kirill Belov",
"License" -> "MIT",
"Version" -> "1.0.0",
"WolframVersion" -> "13.0+",
"PublisherID" -> "KirillBelov",
"Extensions" -> {
{
"Kernel",
"Root" -> "Kernel",
"Context" -> {
{"KirillBelov`BankCalculator`", "BankCalculator.wl"}
},
"Symbols" -> {}
},
{"Documentation", "Language" -> "English"}
}
|>]PacletObject это просто тип, который говорит о том, что это файл с описанием пакета. $PublisherID мы получали в одном из пунктов выше. Значение ключа "Name" должно соответствовать шаблону "$PublisherID/$PackageName", Контекст соответственно должен выглядеть как "$PublisherID`PackageName`". Контекст - это аналог пространств имен, в котором будут находится все функции пакета. Этот же контекст должен быть указан в файле BankCalculator.wl. Все остальные ключи ассоциации интуитивно понятны. Теперь папка с проектом выглядит следующим образом:
Скачиваем шаблон сборщика
Для того, чтобы перейти к дальнейшей работе нам необходимо скачать специальный блокнот по следующей ссылке: https://resources.wolframcloud.com/PacletRepository/Unnamed-Paclet.nb. Это пустой шаблон для любого пакета. Нам не важно куда скачать и поместить данный блокнот.
Создаем PacletResource.nb
Открываем только что скачанный блокнот:
Нас приветствует всего одна кнопка Select Paclet Directory. Нажимаем на нее, после чего откроется следующее окно с полем ввода, где можно указать путь до нашего пакета:
Подтверждаем выбор, после чего открывается следующее окно, где нас уже информируют о том, что в указанной директории нашелся файл PacletInfo.wl с указанными именем пакета, контекстом и директорий. Опять подтверждаем выбор:
Далее мы получили почти окончательный результат настройки - сгенерированный блокнот, в котором добавлено меню для проверки, сборки и выкладки проекта в репозиторий. Выглядит он следующим образом:
Опять же, все достаточно интуитивно понятно. Правда первое, что я бы рекомендовал сделать сохранить данный блокнот в директорию с проектом. Назвать его можно как угодно, я назывe этот файл ResourceDefenition.nb. Теперь в папке с проектом уже 3 файла, плюс добавилась новая (пустая на данный момент) директория для документации к проекту:
После того, как файл с определением пакета был сохранен в папку с проектом можно переключить галочку с указанием расположения файлов в поле "Paclet Directory":
Рассмотрим внимательнее дополнительный пункты меню (которые на сером фоне и ниже). Там есть несколько разделов, которые отвечают как раз за шаги поверки, сборки и публикации пакета.
Open Sample - тут все понятно - просто показывает примеры
Guidelines - открывает в браузере ссылку на небольшое руководство
Tools - в данный момент этот раздел как раз развернут на скриншоте выше и содержит в себе дополнительное меню
[Template Input | Literal Input | ... ].Check - позволяет запустить анализатор кода пакета. Причем можно отдельно выбрать что анализировать: документацию, исходный код или текущий блокнот с определением пакета
Build - собирает пакет или документацию
Deploy - публикует пакет в собственное хранилище в облаке Wolfram
Submit to Repository - то ради чего написана эта статья. Возможность выложить результат в публичный репозиторий пакетов
Заполнение шаблона
Сначала заполним все самые простые поля ввода. Вставим картинку для заголовка:
Укажем базовое описание. Basic Description автоматически добавилось описание из файла PacletInfo.wl. Путь к основном файлу документации мы пока не можем указать, так как пока что документации не написана:
Вот этот раздел можно не трогать, так как ячейки с таким стилем не публикуются, а нужны только для разработчика. Но стоит отметить, что точно так же эти ячейки были сгенерированы автоматически на основе информации из PacletInfo.wl:
Добавим несколько базовых примеров:
И дополнительные примеры:
В последнем разделе должно быть автоматически добавлено имя автора. так же выберем подходящие разделы для пакета и укажем ключевые слова.
В самом низу отмечаем тип пакета, т.е. с чем он будет взаимодействовать. В нашем случае - это просто пакет, который используется встроенные функции Wolfram Language и не читает никакие файлы и не обращается к внешним сервисам:
Документация
Приступим к созданию документации. В версии 13 стали доступны встроенные средства для создания документации к функциям. Эти же средства встроены в виде дополнительного меню в наш рабочий блокнот. В нашем пакете всего два имени, поэтому создать для них документацию не составит труда. Для этого выбираем пункт меню "New Function Page":
После нажатия откроется автоматически форма, где можно ввести имя функции:
После подтверждения откроется автоматически сгенерированный файл для этой функции. При этом, опции (если есть) и описание использования копируются напрямую из определения. Страница документации будет выглядеть вот так:
В таких блокнотах необходимо заполнить описание, добавить ссылки на связанные руководства и функции. Но самое главное добавить максимально показательные примеры.
После того как страницы будут созданы и заполнены - можно создать одно объединяющее руководство или "гайд", где будут список доступных функций пакета. Для этого в том же меню определения пакета нужно выбрать уже "New Guide Page". Введем название и получим блокнот вот такого вида:
Отдельно стоит сказать про то, как нужно пользоваться палитрой Documentation Tools. Вот она:
Это набор кнопок, который чаще всего форматирует выделенный мышкой текст. Т.е. например, я хочу вставить внутреннюю ссылку на страницу CalcROI из страницы Deposit. Для этого я пишу имя CalcROI там где хочу чтобы была ссылка, выделяю его, а затем мышкой кликаю п кнопке Link to Function, которую можно увидеть на скриншоте выше. В принципе с остальными кнопками все работает примерно так же. На этом наша первая версия документации закончена, перейдем к следующим шагам.
Проверка и сборка
После того как определение пакета оформлено, документация написана (документация на самом деле не обязательна) можно проверить пакет. Из дополнительного меню просто выбирает пункт Check > All. С нажатием этой кнопки запустится процесс анализа кода блокнота и пакета, результат которого визуально отобразится в виде сообщений под дополнительным меню и прямо в блокноте:
В общем-то в нашем случае есть только рекомендации, которые мы пока что проигнорируем, но часто анализатор показывает и серьезные ошибки. Если они были - их необходимо исправить. А мы перейдем уже к шагу сборки. Из дополнительного меню запустим процесс сборки пакета - Build > All:
После подтверждения в папке проекта появится директория build, в которой окажется результат сборки:
Это уже упакованный файл с расширением *.paclet, который можно установить на локальный компьютер при помощи PacletInstall и тот же самый пакет в виде папки - по сути содержание паклета.
Отправка в облако
Если выбрать пункт Deploy > Publicy in the Cloud, то готовый пакет будет опубликован в вашем личном хранилище в Wolfram Cloud. После завершения сборки автоматически откроется браузер на странице этого пакета. Выглядеть страница в браузере будет вот так:
Соответственно здесь контент из определения пакета, а так же слева видно ссылки на документацию. Вот как выглядит собранная документация:
Отправка в публичный репозиторий
Собственно кульминация всей этой статьи. Давайте просто нажмем на кнопку и опубликуем пакет в Wolfram Language Paclet Repository. :
Перейдем на страницу со опубликованными пакетами:
Теперь пакет можно найти в публичном репозитории или читатели просто могут посмотреть его по прямой ссылке: https://resources.wolframcloud.com/PacletRepository/resources/KirillBelov/BankCalculator/.
Установка
Собственно заключительный шаг - пробуем установить пакет, посчитать доход. Следуем инструкции на странице пакета, открываем любой блокнот Mathematica или консоль Wolfram Engune и выполняем код:
PacletSiteUpdate /@ PacletSites[];
PacletInstall["KirillBelov/BankCalculator"]Пакет установлен и можно что-то посчитать:
Заключение
На этом на сегодня все. В заключении я хочу описать свои личные эмоции по поводу появления такого хранилища пользовательских пакетов. Я являюсь давним фанатом языка Wolfram и очень давно хотел чтобы нечто подобное NuGet или Maven появилось и для Wolfram Language. Сначала я своим глазам не поверил, когда появился Wolfram Engine, затем когда появился Function Repository, а теперь еще и репозиторий пакетов. Для меня лично это одна из лучших новостей касающихся языка Wolfram за последние годы вместе с бесплатным ядром. Я очень надеюсь, что читателям будет полезна эта статья и что она у кого-то вызовет интерес к языку Wolfram. Всем спасибо за внимание!
