Пакеты

Julia имеет встроенный менеджер пакетов для установки дополнительных функциональных возможностей, написанных на Julia. Он также может устанавливать внешние библиотеки, используя стандартную систему вашей операционной системы для этого или компилируя их из исходного кода. Список зарегистрированных пакетов Julia можно найти по адресу http://pkg.julialang.org. Все команды менеджера пакетов находятся в модуле Pkg , включенном в установку Julia Base.

Сначала мы рассмотрим механику команд семейства Pkg , а затем дадим рекомендации по регистрации вашего пакета. Обязательно прочитайте раздел ниже о соглашениях об именовании пакетов, маркировке версий и важности файла REQUIRE , когда вы будете готовы добавить свой код в репозиторий METADATA.

Статус пакета

Функция Pkg.status() выводит сводку состояния установленных пакетов. Изначально у вас нет установленных пакетов:

julia> Pkg.status()
INFO: Initializing package repository /Users/stefan/.julia/v0.6
INFO: Cloning METADATA from git://github.com/JuliaLang/METADATA.jl
No packages installed.

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

julia> Pkg.status()
Required packages:
 - Distributions                 0.2.8
 - SHA                           0.3.2
Additional packages:
 - NumericExtensions             0.2.17
 - Stats                         0.2.6

Все эти пакеты находятся в зарегистрированных версиях, управляемых Pkg. Пакеты могут находиться в более сложных состояниях, указанных аннотациями справа от установленной версии пакета; мы объясним эти состояния и аннотации по мере их появления. Для программирования Pkg.installed() возвращает словарь, сопоставляющий имена установленных пакетов с версией этого пакета, которая установлена:

julia> Pkg.installed()
Dict{String,VersionNumber} with 4 entries:
"Distributions"     => v"0.2.8"
"Stats"             => v"0.2.6"
"SHA"               => v"0.3.2"
"NumericExtensions" => v"0.2.17"

Добавление и удаление пакетов

Менеджер пакетов Julia немного необычен тем, что он декларативный, а не императивный. Это означает, что вы сообщаете ему, что хотите, и он определяет, какие версии установить (или удалить), чтобы оптимально и минимально удовлетворить эти требования. Итак, вместо установки пакета вы просто добавляете его в список требований, а затем «разрешаете», что нужно установить. В частности, это означает, что если какой-либо пакет был установлен, потому что он был необходим предыдущей версией того, что вы хотели, а новая версия больше не требует этого, обновление фактически удалит этот пакет.

Ваши требования к пакету находятся в файле ~/.julia/v0.6/REQUIRE . Вы можете изменить этот файл вручную, а затем вызвать Pkg.resolve(), чтобы установить, обновить или удалить пакеты оптимально, чтобы удовлетворить требования, или вы можете выполнить Pkg.edit(), которое откроет REQUIRE в вашем редакторе (настроенном с помощью переменных среды EDITOR или VISUAL), а затем автоматически вызовет Pkg.resolve(), если это необходимо. Если вы хотите добавить или удалить требование только для одного пакета, вы также можете использовать неинтерактивные команды Pkg.add() и Pkg.rm(), которые добавляют или удаляют одно требование к REQUIRE и затем вызывают Pkg.resolve().

Вы можете добавить пакет в список требований с помощью функции Pkg.add(), и пакет, а также все пакеты, от которых он зависит, будут установлены:

julia> Pkg.status()
No packages installed.

julia> Pkg.add("Distributions")
INFO: Cloning cache of Distributions from git://github.com/JuliaStats/Distributions.jl.git
INFO: Cloning cache of NumericExtensions from git://github.com/lindahua/NumericExtensions.jl.git
INFO: Cloning cache of Stats from git://github.com/JuliaStats/Stats.jl.git
INFO: Installing Distributions v0.2.7
INFO: Installing NumericExtensions v0.2.17
INFO: Installing Stats v0.2.6
INFO: REQUIRE updated.

julia> Pkg.status()
Required packages:
 - Distributions                 0.2.7
Additional packages:
 - NumericExtensions             0.2.17
 - Stats                         0.2.6

Это делает сначала добавление Distributions в ваш файл ~/.julia/v0.6/REQUIRE.

$ cat ~/.julia/v0.6/REQUIRE
Distributions

Затем он выполняет Pkg.resolve() с использованием этих новых требований, что приводит к выводу о том, что пакет Distributions должен быть установлен, так как он требуется, но не установлен. Как уже говорилось, вы можете добиться того же, изменив файл ~/.julia/v0.6/REQUIRE вручную, а затем сами запустив Pkg.resolve():

$ echo SHA >> ~/.julia/v0.6/REQUIRE

julia> Pkg.resolve()
INFO: Cloning cache of SHA from git://github.com/staticfloat/SHA.jl.git
INFO: Installing SHA v0.3.2

julia> Pkg.status()
Required packages:
 - Distributions                 0.2.7
 - SHA                           0.3.2
Additional packages:
 - NumericExtensions             0.2.17
 - Stats                         0.2.6

Это функционально эквивалентно вызову Pkg.add("SHA"), за исключением того, что Pkg.add() не изменяет REQUIRE до тех пор, пока установка не будет завершена, поэтому, если возникнут проблемы, REQUIRE останется таким, каким был до вызова Pkg.add(). Формат файла REQUIRE описан в разделе «Спецификация требований»; он позволяет, помимо прочего, требовать определенных диапазонов версий пакетов.

Когда вы решите, что больше не хотите иметь пакет, вы можете использовать Pkg.rm(), чтобы удалить требование к нему из файла REQUIRE:

julia> Pkg.rm("Distributions")
INFO: Removing Distributions v0.2.7
INFO: Removing Stats v0.2.6
INFO: Removing NumericExtensions v0.2.17
INFO: REQUIRE updated.

julia> Pkg.status()
Required packages:
 - SHA                           0.3.2

julia> Pkg.rm("SHA")
INFO: Removing SHA v0.3.2
INFO: REQUIRE updated.

julia> Pkg.status()
No packages installed.

Еще раз, это эквивалентно редактированию файла REQUIRE для удаления строки с каждым именем пакета, а затем запуску Pkg.resolve() для обновления набора установленных пакетов в соответствии с ними. Хотя Pkg.add() и Pkg.rm() удобны для добавления и удаления требований к одному пакету, когда вы хотите добавить или удалить несколько пакетов, вы можете вызвать Pkg.edit() для ручного изменения содержимого REQUIRE и затем обновить свои пакеты соответственно. Pkg.edit() не отменяет содержимого REQUIRE , если Pkg.resolve() завершается неудачей — вместо этого вам нужно снова запустить Pkg.edit() для исправления содержимого файлов.

Поскольку менеджер пакетов использует libgit2 для управления репозиториями пакетов Git, пользователи могут столкнуться с проблемами протокола (например, если они находятся за брандмауэром) при запуске Pkg.add(). По умолчанию все пакеты, размещенные на GitHub, будут доступны через «https»; этот параметр по умолчанию можно изменить, вызвав Pkg.setprotocol!(). Следующую команду можно выполнить из командной строки, чтобы указать git использовать «https» вместо протокола «git» при клонировании всех репозиториев, где бы они ни находились:

git config --global url."https://".insteadOf git://

Однако, это изменение будет системным, и поэтому предпочтительнее использовать Pkg.setprotocol!().

Pkg.add("Distributions.jl")
Pkg.rm("Distributions.jl")

Офлайн-установка пакетов

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

Pkg.add() выполняет следующие действия в корневом каталоге пакета:

1. Добавляет имя пакета в REQUIRE.

2. Загружает пакет в .cache, а затем копирует пакет в корневой каталог пакета.

3. Рекурсивно выполняет шаг 2 для всех пакетов, перечисленных в файле REQUIRE пакета.

4. Выполняет Pkg.build()

Установка незарегистрированных пакетов

Пакеты Julia — это просто репозитории git, клонируемые с помощью любого поддерживаемого git протокола, и содержащие код Julia, который соответствует определённым соглашениям об организации. Официальные пакеты Julia зарегистрированы в репозитории METADATA.jl, доступном по известному адресу [1]. Команды Pkg.add() и Pkg.rm() в предыдущем разделе взаимодействуют с зарегистрированными пакетами, но менеджер пакетов может также устанавливать и работать с незарегистрированными пакетами. Для установки незарегистрированного пакета используйте Pkg.clone(url), где url — это URL git, из которого пакет можно клонировать:

julia> Pkg.clone("git://example.com/path/to/Package.jl.git")
INFO: Cloning Package from git://example.com/path/to/Package.jl.git
Cloning into 'Package'...
remote: Counting objects: 22, done.
remote: Compressing objects: 100% (10/10), done.
remote: Total 22 (delta 8), reused 22 (delta 8)
Receiving objects: 100% (22/22), 2.64 KiB, done.
Resolving deltas: 100% (8/8), done.

По соглашению имена репозиториев Julia заканчиваются на .jl (дополнительное .git указывает на «голый» репозиторий git), что предотвращает их столкновение с репозиториями других языков, а также делает пакеты Julia легко находимыми в поисковых системах. Однако, когда пакеты установлены в вашем каталоге .julia/v0.6 , расширение избыточно, поэтому мы его опускаем.

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

Обновление пакетов

Когда разработчики пакетов публикуют новые зарегистрированные версии пакетов, которые вы используете, вы, конечно же, захотите новые блестящие версии. Чтобы получить самые последние и лучшие версии всех ваших пакетов, просто выполните Pkg.update():

julia> Pkg.update()
INFO: Updating METADATA...
INFO: Computing changes...
INFO: Upgrading Distributions: v0.2.8 => v0.2.10
INFO: Upgrading Stats: v0.2.7 => v0.2.8

Первый шаг обновления пакетов — это получение новых изменений в ~/.julia/v0.6/METADATA и проверка, были ли опубликованы новые зарегистрированные версии пакетов. После этого Pkg.update() пытается обновить пакеты, которые находятся на ветке и не изменены (т.е. в файлы, отслеживаемые git, не были внесены изменения), подтягивая изменения из репозитория пакета upstream. Изменения upstream будут применены только в том случае, если не требуется слияние или перебазирование — то есть, если ветка может быть "быстро перемещена вперед". Если ветку нельзя быстро переместить вперёд, предполагается, что вы работаете над ней и сами обновите репозиторий.

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

1. Незарегистрированный: пакет не находится в METADATA — вы установили его с помощью Pkg.clone().

2. Ветвь разработки: репозиторий пакета находится на ветке разработки.

3. Изменённый: в файлы репозитория были внесены изменения.

Если это так, менеджер пакетов не может свободно менять установленную версию пакета, поэтому его требования должны быть удовлетворены другими версиями пакетов. Комбинация требований верхнего уровня в ~/.julia/v0.6/REQUIRE и требований закреплённых пакетов используется для определения того, что должно быть установлено.

Вы также можете обновить только подмножество установленных пакетов, передав аргументы функции Pkg.update. В этом случае будут обновлены только указанные пакеты и их зависимости:

julia> Pkg.update("Example")
INFO: Updating METADATA...
INFO: Computing changes...
INFO: Upgrading Example: v0.4.0 => 0.4.1

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

Выделение, Закрепление и Освобождение

Возможно, вы захотите использовать master версию пакета вместо одной из зарегистрированных версий. Может быть, есть исправления или функциональность на ветке master, которые вам необходимы, но ещё не опубликованы в зарегистрированных версиях, или вы являетесь разработчиком пакета и хотите внести изменения на master или какой-то другой ветке разработки. В таких случаях вы можете выполнить Pkg.checkout(pkg) для выделения master ветки pkg или Pkg.checkout(pkg,branch) для выделения другой ветки:

julia> Pkg.add("Distributions")
INFO: Installing Distributions v0.2.9
INFO: Installing NumericExtensions v0.2.17
INFO: Installing Stats v0.2.7
INFO: REQUIRE updated.

julia> Pkg.status()
Required packages:
 - Distributions                 0.2.9
Additional packages:
 - NumericExtensions             0.2.17
 - Stats                         0.2.7

julia> Pkg.checkout("Distributions")
INFO: Checking out Distributions master...
INFO: No packages to install, update or remove.

julia> Pkg.status()
Required packages:
 - Distributions                 0.2.9+             master
Additional packages:
 - NumericExtensions             0.2.17
 - Stats                         0.2.7

Сразу после установки Distributions с помощью Pkg.add() он находится на последней зарегистрированной версии — 0.2.9 на момент написания этого текста. После выполнения Pkg.checkout("Distributions"), из вывода Pkg.status() видно, что Distributions находится на незарегистрированной версии, большей чем 0.2.9, что показано номером «псевдо-версии» 0.2.9+.

При выделении незарегистрированной версии пакета, копия файла REQUIRE в репозитории пакета имеет приоритет перед любыми зарегистрированными требованиями в METADATA, поэтому важно, чтобы разработчики поддерживали этот файл точным и обновлённым, отражающим фактические требования текущей версии пакета. Если файл REQUIRE в репозитории пакета некорректен или отсутствует, зависимости могут быть удалены при выделении пакета. Этот файл также используется для заполнения вновь опубликованных версий пакета, если вы используете API, предоставляемый Pkg для этого (описано ниже).

Когда вы больше не хотите выделять пакет на ветке, вы можете «освободить» его под контроль менеджера пакетов с помощью Pkg.free(pkg):

julia> Pkg.free("Distributions")
INFO: Freeing Distributions...
INFO: No packages to install, update or remove.

julia> Pkg.status()
Required packages:
 - Distributions                 0.2.9
Additional packages:
 - NumericExtensions             0.2.17
 - Stats                         0.2.7

После этого, поскольку пакет находится на зарегистрированной версии и не на ветке, его версия будет обновляться по мере публикации новых зарегистрированных версий пакета.

Если вы хотите закрепить пакет на определенной версии, чтобы вызов Pkg.update() не менял версию пакета, вы можете использовать функцию Pkg.pin():

julia> Pkg.pin("Stats")
INFO: Creating Stats branch pinned.47c198b1.tmp

julia> Pkg.status()
Required packages:
 - Distributions                 0.2.9
Additional packages:
 - NumericExtensions             0.2.17
 - Stats                         0.2.7              pinned.47c198b1.tmp

После этого пакет Stats останется закреплённым на версии 0.2.7 — или, точнее, на коммите 47c198b1, но поскольку версии постоянно связаны с определённым git-хешем, это одно и то же. Pkg.pin() работает, создавая временную ветку для коммита, на котором вы хотите закрепить пакет, а затем выделяя эту ветку. По умолчанию он закрепляет пакет на текущем коммите, но вы можете выбрать другую версию, передав второй аргумент:

julia> Pkg.pin("Stats",v"0.2.5")
INFO: Creating Stats branch pinned.1fd0983b.tmp
INFO: No packages to install, update or remove.

julia> Pkg.status()
Required packages:
 - Distributions                 0.2.9
Additional packages:
 - NumericExtensions             0.2.17
 - Stats                         0.2.5              pinned.1fd0983b.tmp

Теперь пакет Stats закреплён на коммите 1fd0983b, что соответствует версии 0.2.5. Когда вы захотите «открепить» пакет и позволить менеджеру пакетов обновить его снова, вы можете использовать Pkg.free(), как и для перехода с любой ветки:

julia> Pkg.free("Stats")
INFO: Freeing Stats...
INFO: No packages to install, update or remove.

julia> Pkg.status()
Required packages:
 - Distributions                 0.2.9
Additional packages:
 - NumericExtensions             0.2.17
 - Stats                         0.2.7

После этого пакет Stats снова управляется менеджером пакетов, и будущие вызовы Pkg.update() будут обновлять его до новых версий по мере их публикации. Временная ветка pinned.1fd0983b.tmp остаётся в вашем локальном репозитории Stats, но поскольку ветки git очень лёгкие, это не имеет большого значения; если вы хотите их очистить, вы можете войти в репозиторий и удалить эти ветки [2].

Пользовательский репозиторий METADATA

По умолчанию Julia предполагает, что вы будете использовать официальный репозиторий METADATA.jl для скачивания и установки пакетов. Вы также можете указать другой репозиторий METADATA. Распространённый подход — поддерживать свою ветку metadata-v2 в актуальном состоянии с официальной веткой Julia и добавить другую ветку со своими пользовательскими пакетами. Вы можете инициализировать свой локальный репозиторий METADATA, используя это пользовательское расположение и ветку, а затем периодически перебазировать свою пользовательскую ветку с официальной веткой metadata-v2 . Для использования пользовательского репозитория и ветки выполните следующую команду:

julia> Pkg.init("https://me.example.com/METADATA.jl.git", "branch")

Аргумент ветки необязателен и по умолчанию равен metadata-v2. После инициализации файл с именем META_BRANCH в вашем ~/.julia/vX.Y/ пути будет отслеживать ветку, с которой был инициализирован ваш репозиторий METADATA. Если вы хотите изменить ветку, вам потребуется либо напрямую изменить файл META_BRANCH (будьте осторожны!), либо удалить каталог vX.Y и повторно инициализировать свой репозиторий METADATA, используя команду Pkg.init.

Разработка пакетов

Менеджер пакетов Julia разработан таким образом, что при установке пакета у вас уже есть возможность ознакомиться с исходным кодом и полной историей разработки. Вы также можете вносить изменения в пакеты, коммитить их с помощью git и легко вносить исправления и улучшения upstream. Аналогично, система разработана таким образом, что если вы хотите создать новый пакет, самый простой способ сделать это — в рамках инфраструктуры, предоставляемой менеджером пакетов.

Начальная настройка

Поскольку пакеты являются git-репозиториями, перед выполнением любой разработки пакетов необходимо настроить следующие стандартные глобальные настройки git:

$ git config --global user.name "FULL NAME"
$ git config --global user.email "EMAIL"

где FULL NAME — ваше фактическое полное имя (между двойными кавычками можно использовать пробелы), а EMAIL — ваш фактический адрес электронной почты. Хотя для создания или публикации пакетов Julia не обязательно использовать GitHub, большинство пакетов Julia на момент написания этого текста размещаются на GitHub, и менеджер пакетов знает, как правильно форматировать адреса origin и иначе плавно работать с сервисом. Мы рекомендуем создать бесплатную учётную запись на GitHub и затем сделать следующее:

$ git config --global github.user "USERNAME"

где USERNAME — ваше фактическое имя пользователя GitHub. После этого менеджер пакетов знает ваше имя пользователя GitHub и может настроить соответствующие параметры. Вы также должны загрузить свой публичный SSH-ключ на GitHub и настроить SSH-агент на вашей машине разработки, чтобы вы могли отправлять изменения с минимальными неудобствами. В будущем мы сделаем эту систему расширяемой и будем поддерживать другие распространённые варианты размещения git, такие как BitBucket, и предоставим разработчикам возможность выбора своего любимого варианта. Поскольку функции разработки пакетов перенесены в пакет PkgDev, вам необходимо выполнить Pkg.add("PkgDev"); import PkgDev для доступа к функциям, начинающимся с PkgDev. в документе ниже.

Внесение изменений в существующий пакет

Изменения документации

Если вы хотите улучшить онлайн-документацию пакета, самый простой способ (по крайней мере, для небольших изменений) — использовать онлайн-редактор GitHub. Сначала перейдите на домашнюю страницу репозитория на GitHub, найдите файл (например, README.md) в структуре папок репозитория и щелкните по нему. Вы увидите содержимое, отображённое вместе с маленькой иконкой «карандаша» в верхнем правом углу. Нажав на эту иконку, откроется режим редактирования файла. Внесите изменения, кратко опишите изменения, которые вы хотите внести (это ваше сообщение коммита), и нажмите «Предложить изменение файла». Ваши изменения будут представлены на рассмотрение владельцу(ам) пакета и соавторам.

Для более крупных изменений документации — и особенно для изменений, которые, как ожидается, придётся обновлять в ответ на отзывы — вам может быть проще использовать процедуру для изменений кода, описанную ниже.

Изменения кода

Резюме

Здесь мы предполагаем, что вы уже настроили git на своем локальном компьютере и имеете учетную запись на GitHub (см. выше). Предположим, что вы исправляете ошибку в пакете Images:

Pkg.checkout("Images")           # check out the master branch
<here, make sure your bug is still a bug and hasn't been fixed already>
cd(Pkg.dir("Images"))
;git checkout -b myfixes         # create a branch for your changes
<edit code>                      # be sure to add a test for your bug
Pkg.test("Images")               # make sure everything works now
;git commit -a -m "Fix foo by calling bar"   # write a descriptive message
using PkgDev
PkgDev.submit("Images")

Последняя строка предоставит вам ссылку для отправки запроса на включение ваших изменений.

Подробное описание

Если вы хотите исправить ошибку или добавить новую функциональность, вы хотите протестировать свои изменения, прежде чем отправлять их на рассмотрение. Вам также нужен простой способ обновить свой проект в ответ на отзывы владельца пакета. Следовательно, в данном случае стратегия заключается в работе локально на вашем компьютере; как только вы будете удовлетворены своими изменениями, вы отправите их на рассмотрение. Этот процесс называется запросом на включение (pull request), потому что вы просите «взять» свои изменения в основной репозиторий проекта. Поскольку онлайн-репозиторий не может видеть код на вашем личном компьютере, вы сначала отправьте (push) свои изменения в общедоступное место — вашу собственную онлайн-вилку (fork) пакета (размещенную на вашей личной учетной записи GitHub).

Предположим, что у вас уже установлен пакет Foo. В описании ниже все, что начинается с Pkg. или PkgDev., должно быть набрано в командной строке Julia; все, что начинается с git, должно быть набрано в режиме командной строки Julia (или с помощью командной строки вашей операционной системы). В Julia вы можете комбинировать эти два режима:

julia> cd(Pkg.dir("Foo"))          # go to Foo's folder

shell> git command arguments...    # command will apply to Foo

Теперь предположим, что вы готовы внести некоторые изменения в Foo. Хотя существует несколько подходов, вот один из наиболее распространенных:

• В командной строке Julia введите Pkg.checkout("Foo"). Это гарантирует, что вы используете последнюю версию кода (ветвь master), а не просто какую-то "официальную релизную" версию, которую у вас установлена. (Если вы планируете исправить ошибку, на этом этапе неплохо снова проверить, не была ли ошибка уже исправлена кем-то другим. Если это так, вы можете запросить добавление новой официальной версии, чтобы исправление распространилось на всю сообщество.) Если вы получите ошибку Foo is dirty, bailing, см. «Загрязненные пакеты» ниже.

• Создайте ветвь для своих изменений: перейдите в папку пакета (ту, которую Julia сообщает из Pkg.dir("Foo")) и (в режиме командной строки) создайте новую ветвь с помощью git checkout -b <newbranch>, где <newbranch> может быть каким-то описательным именем (например, fixbar). Создавая ветвь, вы обеспечиваете возможность легко переключаться между своей новой работой и текущей ветвью master (см. https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell).

  Если вы забудете сделать этот шаг, пока не внесете какие-то изменения, не волнуйтесь: см. более подробную информацию о ветвлении ниже.

• Внесите свои изменения. В большинстве случаев изменения должны включать обновления в папках src/ и test/, будь то исправление ошибки или добавление новой функциональности. Если вы исправляет ошибку, добавьте свой минимальный пример, демонстрирующий ошибку (в текущем коде), в набор тестов; внеся тест для ошибки, вы гарантируете, что ошибка не появится случайно в будущем из-за других изменений. Если вы добавляете новую функциональность, создание тестов демонстрирует владельцу пакета, что вы убедились, что ваш код работает как задумывалось.

• Запустите тесты пакета и убедитесь, что они пройдены. Есть несколько способов запустить тесты:

  • Из Julia запустите Pkg.test("Foo"): это запустит ваши тесты в отдельном (новом) julia процессе.

  • Из Julia, include("runtests.jl") из папки test/ пакета (возможно, файл имеет другое имя, найдите тот, который запускает все тесты): это позволяет вам запускать тесты многократно в одной сессии без перезагрузки всего кода пакета; для пакетов, которые долго загружаются, это может быть намного быстрее. При этом подходе вам нужно будет выполнить дополнительные действия, чтобы внести изменения в код пакета.

  • Из командной строки запустите julia ../test/runtests.jl из папки src/ пакета.

• Зафиксируйте свои изменения: см. https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository.

• Отправьте свои изменения: В командной строке Julia введите PkgDev.submit("Foo"). Это отправит ваши изменения на вашу вилку GitHub, создав её, если она не существует. (Если вы столкнулись с ошибкой, убедитесь, что вы настроили свои SSH-ключи.) Julia предоставит вам гиперссылку; откройте эту ссылку, отредактируйте сообщение и нажмите «Отправить». В этот момент владелец пакета будет уведомлен о ваших изменениях и, возможно, начнёт обсуждение. (Если вы знакомы с git, вы можете выполнить эти шаги вручную из командной строки.)

• Владелец пакета может предложить дополнительные улучшения. Чтобы ответить на эти предложения, вы можете легко обновить запрос на включение (это работает только для изменений, которые ещё не были объединены; для объединённых запросов на включение делайте новые изменения, начав новую ветвь):

  • Если вы между тем переключили ветви, убедитесь, что вы вернулись в ту же ветвь с помощью git checkout fixbar (из режима командной строки) или Pkg.checkout("Foo", "fixbar") (из командной строки Julia).

  • Как и выше, внесите свои изменения, запустите тесты и зафиксируйте свои изменения.

  • В командной строке введите git push. Это добавит ваши новые коммиты в тот же запрос на включение; вы должны увидеть их автоматически на странице, содержащей обсуждение вашего запроса на включение.

  Владелец может запросить сжатие коммитов. См. Сжатие ниже.

Загрязнённые пакеты

Если вы не можете изменить ветви, потому что менеджер пакетов жалуется, что пакет загрязнён, это означает, что у вас есть некоторые изменения, которые не были зафиксированы. Из командной строки используйте git diff для просмотра этих изменений; вы можете либо отбросить их (git checkout changedfile.jl), либо зафиксировать их перед переключением ветвей. Если вы не можете легко решить проблемы вручную, в крайнем случае вы можете удалить всю папку "Foo" и переустановить свежую копию с помощью Pkg.add("Foo"). Естественно, это удалит все внесённые вами изменения.

Создание ветви задним числом

Особенно для новичков в git, часто забывают создать новую ветвь, пока не внесут некоторые изменения. Если вы ещё не подготовили или не зафиксировали свои изменения, вы можете создать новую ветвь с помощью git checkout -b <newbranch> как обычно — git вежливо покажет вам, что некоторые файлы были изменены, и создаст новую ветвь за вас. Ваши изменения ещё не зафиксированы в этой новой ветви, поэтому обычные правила работы по-прежнему применимы.

Однако, если вы уже зафиксировали изменение в master, но хотите вернуться к официальной ветви master (называемой origin/master), воспользуйтесь следующей процедурой:

• Создайте новую ветвь. Эта ветвь будет содержать ваши изменения.

• Убедитесь, что всё зафиксировано в этой ветви.

• git checkout master. Если это не удаётся, не продолжайте дальше, пока не решите проблемы, иначе вы можете потерять свои изменения.

• Сбросьтеmaster (вашу текущую ветвь) до более раннего состояния с помощью git reset --hard origin/master (см. https://git-scm.com/blog/2011/07/11/reset.html).

Это требует немного большего знакомства с git, поэтому лучше сразу привыкнуть создавать ветвь на начальном этапе.

Сжатие и перебазирование

В зависимости от предпочтений владельца пакета (он/она) могут попросить вас «сжать» ваши коммиты. Это особенно вероятно, если ваше изменение достаточно простое, но история коммитов выглядит так:

WIP: add new 1-line whizbang function (currently breaks package)
Finish whizbang function
Fix typo in variable name
Oops, don't forget to supply default argument
Split into two 1-line functions
Rats, forgot to export the second function
...

Это затрагивает область более продвинутого использования git, и вам рекомендуется почитать (https://git-scm.com/book/en/v2/Git-Branching-Rebasing). Однако краткое изложение процедуры таково:

• Чтобы защитить себя от ошибок, начните с ветви fixbar и создайте новую ветвь с помощью git checkout -b fixbar_backup. Поскольку вы начали с fixbar, это будет копия. Теперь вернитесь к той, которую вы собираетесь изменить, с помощью git checkout fixbar.

• В командной строке введите git rebase -i origin/master.

• Чтобы объединить коммиты, измените pick на squash (для дополнительных опций, обратитесь к другим источникам). Сохраните файл и закройте окно редактора.

• Отредактируйте объединённое сообщение коммита.

Если перебазирование пройдёт неудачно, вы можете вернуться к началу, чтобы попробовать снова:

git checkout fixbar
git reset --hard fixbar_backup

Теперь предположим, что вы успешно перебазировали. Поскольку ваш репозиторий fixbar теперь разошёлся с репозиторием на вашей вилке GitHub, вам придётся сделать принудительное обновление:

• Чтобы легко ссылаться на вашу вилку GitHub, создайте для неё «обработку» с помощью git remote add myfork https://github.com/myaccount/Foo.jl.git, где URL берётся из «URL для клонирования» на странице вашей вилки GitHub.

• Принудительно обновите вашу вилку с помощью git push myfork +fixbar. + указывает, что это должно заменить ветвь fixbar в myfork.

Создание нового пакета

REQUIRE говорит сам за себя

В репозитории вашего пакета должен быть файл REQUIRE, с минимальной директивой о том, какую версию Julia ожидают ваши пользователи для работы пакета. Ограничение поддерживаемых версий Julia делается путем добавления julia 0.x в этот файл. Хотя эта строка частично информационная, она также влияет на то, будет ли Pkg.update() обновлять код, обнаруженный в каталогах версии .julia. Он не будет обновлять код в каталогах версий ниже минимально поддерживаемой версии, указанной в вашем REQUIRE.

По мере того, как версия разработки 0.y созревает, вы можете использовать её всё чаще и захотите, чтобы ваш пакет поддерживал её. Будьте осторожны, ветвь разработки Julia — это территория разрывов, и вы можете ожидать, что вещи сломаются. Когда вы будете исправлять то, что сломало ваш пакет в ветви разработки 0.y , вы, вероятно, обнаружите, что вы просто сломали свой пакет в стабильной версии.

В пакете Compat есть механизм, который позволит вам поддерживать как стабильную версию, так и изменения, внесённые в версию разработки. Если вы решите использовать это решение, вам нужно добавить Compat в ваш файл REQUIRE. В этом случае у вас всё ещё будет julia 0.x в вашем REQUIRE. x — это минимальная версия, которую поддерживает ваш пакет.

Также возможно, вы не заинтересованы в поддержке версии разработки Julia. Так же, как вы можете указать минимальную версию, которую должны использовать ваши пользователи, вы можете установить верхнюю границу. В этом случае вы должны поместить julia 0.x 0.y- в ваш файл REQUIRE. - в конце номера версии означает предварительные версии этой конкретной версии, начиная с первого коммита. Установив его как верхнюю границу, вы указываете, что код поддерживает всё до, но не включая, версию с этой верхней границей.

Ещё один сценарий — вы пишете большую часть кода для своего пакета с использованием Julia 0.y и не хотите поддерживать текущую стабильную версию Julia. Если вы выберете такой вариант, просто добавьте julia 0.y- в ваш файл REQUIRE. Не забудьте изменить julia 0.y- на julia 0.y в вашем файле REQUIRE после того, как 0.y будет официально выпущена. Если вы не отредактируете эту часть, вы предполагаете поддержку как версии разработки, так и стабильной версии с одним и тем же номером! Это будет безумие. Полный формат REQUIRE см. в разделе «Спецификация требований».

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

Руководство по наименованию пакета

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

1. Избегайте жаргонной лексики. В частности, избегайте аббревиатур, если нет минимальной возможности для путаницы.

   • Можно использовать USA при обсуждении США.

   • Нельзя использовать PMA, даже если вы говорите о положительном отношении к жизни.

2. Избегайте использования Julia в имени вашего пакета.

   • Обычно из контекста и для ваших пользователей очевидно, что пакет — это пакет Julia.

   • Наличие слова «Julia» в имени может подразумевать, что пакет связан с разработчиками языка Julia или одобрен ими.

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

   • DataFrames предоставляет тип DataFrame.

   • BloomFilters предоставляет тип BloomFilter.

   • В отличие от JuliaParser, который не предоставляет новых типов, но вместо этого предоставляет новую функциональность в функции JuliaParser.parse().

4. Отдавайте предпочтение ясности, даже если ясность кажется вам длинной.

   • RandomMatrices — менее неоднозначное имя, чем RndMat или RMT, хотя последние и короче.

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

   • У Julia нет одного универсального пакета для визуализации. Вместо этого Gadfly, PyPlot, Winston и другие пакеты реализуют уникальный подход, основанный на определённой философии проектирования.

   • В отличие от этого, SortingAlgorithms предоставляет согласованный интерфейс для использования многих хорошо зарекомендовавших себя алгоритмов сортировки.

6. Пакеты, которые оборачивают внешние библиотеки или программы, должны быть названы в соответствии с этими библиотеками или программами.

   • CPLEX.jl оборачивает библиотеку CPLEX, которую легко найти в поисковой системе.

   • MATLAB.jl предоставляет интерфейс для вызова движка MATLAB изнутри Julia.

Создание пакета

Предположим, вы хотите создать новый пакет Julia под названием FooBar. Чтобы начать, выполните PkgDev.generate(pkg,license), где pkg — новое имя пакета, а license — имя лицензии, известное генератору пакетов:

julia> PkgDev.generate("FooBar","MIT")
INFO: Initializing FooBar repo: /Users/stefan/.julia/v0.6/FooBar
INFO: Origin: git://github.com/StefanKarpinski/FooBar.jl.git
INFO: Generating LICENSE.md
INFO: Generating README.md
INFO: Generating src/FooBar.jl
INFO: Generating test/runtests.jl
INFO: Generating REQUIRE
INFO: Generating .travis.yml
INFO: Generating appveyor.yml
INFO: Generating .gitignore
INFO: Committing FooBar generated files

Это создаёт директорию ~/.julia/v0.6/FooBar, инициализирует её как репозиторий git, генерирует набор файлов, необходимых для всех пакетов, и сохраняет их в репозитории:

$ cd ~/.julia/v0.6/FooBar && git show --stat

commit 84b8e266dae6de30ab9703150b3bf771ec7b6285
Author: Stefan Karpinski <stefan@karpinski.org>
Date:   Wed Oct 16 17:57:58 2013 -0400

    FooBar.jl generated files.

        license: MIT
        authors: Stefan Karpinski
        years:   2013
        user:    StefanKarpinski

    Julia Version 0.3.0-prerelease+3217 [5fcfb13*]

 .gitignore       |  2 ++
 .travis.yml      | 13 +++++++++++++
 LICENSE.md       | 22 +++++++++++++++++++++++
 README.md        |  3 +++
 REQUIRE          |  1 +
 appveyor.yml     | 34 ++++++++++++++++++++++++++++++++++
 src/FooBar.jl    |  5 +++++
 test/runtests.jl |  5 +++++
 8 files changed, 85 insertions(+)

В данный момент менеджер пакетов знает о лицензии MIT «Expat», обозначенной как "MIT", лицензии Simplified BSD, обозначенной как "BSD", и версии 2.0 лицензии Apache Software License, обозначенной как "ASL". Если вы хотите использовать другую лицензию, вы можете попросить нас добавить её в генератор пакетов, или просто выбрать одну из этих трёх и затем изменить файл ~/.julia/v0.6/PACKAGE/LICENSE.md после его генерации.

Если вы создали учётную запись GitHub и настроили git для работы с ней, PkgDev.generate() установит соответствующий URL для origin. Он также автоматически сгенерирует файл .travis.yml для использования службы автоматизированного тестирования Travis и файл appveyor.yml для использования AppVeyor. Вам нужно будет включить тестирование на веб-сайтах Travis и AppVeyor для вашего репозитория пакета, но после этого тесты будут уже работать. Конечно, все стандартные тесты проверяют, что using FooBar в Julia работает.

Загрузка статических файлов, не являющихся файлами Julia

Если код вашего пакета должен загружать статические файлы, которые не являются кодом Julia, например, внешнюю библиотеку или файлы данных, и они расположены в каталоге пакета, используйте макрос @__DIR__ для определения каталога текущего исходного файла. Например, если FooBar/src/FooBar.jl нужно загрузить FooBar/data/foo.csv, используйте следующий код:

datapath = joinpath(@__DIR__, "..", "data")
foo = readcsv(joinpath(datapath, "foo.csv"))

Доступ к вашему пакету

После внесения некоторых изменений и проверки работы FooBar, вы можете захотеть предоставить возможность другим пользователям попробовать его. Сначала вам нужно создать удалённый репозиторий и загрузить свой код в него; мы пока не делаем это автоматически, но в будущем мы это добавим, и это не так сложно выяснить [3]. После этого, чтобы предоставить возможность другим пользователям попробовать ваш код, достаточно отправить им URL опубликованного репозитория — в данном случае:

git://github.com/StefanKarpinski/FooBar.jl.git

Для вашего пакета это будет ваше имя пользователя GitHub и имя вашего пакета, но вы поняли суть. Люди, которым вы отправляете этот URL, могут использовать Pkg.clone() для установки пакета и его тестирования:

julia> Pkg.clone("git://github.com/StefanKarpinski/FooBar.jl.git")
INFO: Cloning FooBar from git@github.com:StefanKarpinski/FooBar.jl.git

Маркирование и публикация вашего пакета

После того, как вы решили, что FooBar готов для регистрации в качестве официального пакета, вы можете добавить его в свою локальную копию METADATA с помощью PkgDev.register().

julia> PkgDev.register("FooBar")
INFO: Registering FooBar at git://github.com/StefanKarpinski/FooBar.jl.git
INFO: Committing METADATA for FooBar

Это создаёт коммит в репозитории ~/.julia/v0.6/METADATA.

$ cd ~/.julia/v0.6/METADATA && git show

commit 9f71f4becb05cadacb983c54a72eed744e5c019d
Author: Stefan Karpinski <stefan@karpinski.org>
Date:   Wed Oct 16 18:46:02 2013 -0400

    Register FooBar

diff --git a/FooBar/url b/FooBar/url
new file mode 100644
index 0000000..30e525e
--- /dev/null
+++ b/FooBar/url
@@ -0,0 +1 @@
+git://github.com/StefanKarpinski/FooBar.jl.git

Однако этот коммит виден только локально. Чтобы сделать его видимым для сообщества Julia, необходимо объединить ваш локальный METADATA с официальным репозиторием. Команда PkgDev.publish() создаст форк репозитория METADATA на GitHub, загрузит ваши изменения в свой форк и откроет запрос на вытягивание:

julia> PkgDev.publish()
INFO: Validating METADATA
INFO: No new package versions to publish
INFO: Submitting METADATA changes
INFO: Forking JuliaLang/METADATA.jl to StefanKarpinski
INFO: Pushing changes as branch pull-request/ef45f54b
INFO: To create a pull-request open:

  https://github.com/StefanKarpinski/METADATA.jl/compare/pull-request/ef45f54b

ERROR: key not found: "token"

После того, как URL пакета FooBar будет зарегистрирован в официальном репозитории METADATA, пользователи будут знать, откуда клонировать пакет, но ещё не будет зарегистрированных версий. Вы можете пометить и зарегистрировать его с помощью команды PkgDev.tag().

julia> PkgDev.tag("FooBar")
INFO: Tagging FooBar v0.0.1
INFO: Committing METADATA for FooBar

Это помечает v0.0.1 в репозитории FooBar.

$ cd ~/.julia/v0.6/FooBar && git tag
v0.0.1

Это также создаёт новую запись версии в вашем локальном репозитории METADATA для FooBar.

$ cd ~/.julia/v0.6/FooBar && git show
commit de77ee4dc0689b12c5e8b574aef7f70e8b311b0e
Author: Stefan Karpinski <stefan@karpinski.org>
Date:   Wed Oct 16 23:06:18 2013 -0400

    Tag FooBar v0.0.1

diff --git a/FooBar/versions/0.0.1/sha1 b/FooBar/versions/0.0.1/sha1
new file mode 100644
index 0000000..c1cb1c1
--- /dev/null
+++ b/FooBar/versions/0.0.1/sha1
@@ -0,0 +1 @@
+84b8e266dae6de30ab9703150b3bf771ec7b6285

Команда PkgDev.tag() принимает необязательный второй аргумент, который является либо явным объектом номера версии, например v"0.0.1", либо одним из символов :patch, :minor или :major. Эти символы позволяют разумно увеличить номер патча, мажорной или минорной версии вашего пакета.

Добавление помеченной версии вашего пакета ускорит официальную регистрацию в METADATA.jl соавторами. Настоятельно рекомендуется выполнить этот процесс, независимо от того, полностью ли готов ваш пакет к официальному выпуску.

Как общее правило, пакеты должны быть помечены 0.0.1 в первую очередь. Поскольку сама Julia ещё не достигла статуса 1.0, лучше проявлять осторожность при маркировке версий вашего пакета.

Как и в случае с PkgDev.register(), эти изменения в METADATA недоступны для других пользователей до тех пор, пока они не будут включены в upstream. Снова используйте команду PkgDev.publish(), которая сначала проверяет, были ли помечены отдельные репозитории пакетов, затем отправляет их, если они ещё не были отправлены, и затем открывает запрос на вытягивание в METADATA:

julia> PkgDev.publish()
INFO: Validating METADATA
INFO: Pushing FooBar permanent tags: v0.0.1
INFO: Submitting METADATA changes
INFO: Forking JuliaLang/METADATA.jl to StefanKarpinski
INFO: Pushing changes as branch pull-request/3ef4f5c4
INFO: To create a pull-request open:

  https://github.com/StefanKarpinski/METADATA.jl/compare/pull-request/3ef4f5c4

Ручное опубликование METADATA

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

Создав «вилку» основного репозитория METADATA, вы можете создать личную копию (METADATA.jl) в своём аккаунте GitHub. После создания этой копии вы можете отправить свои локальные изменения в вашу копию (точно так же, как и любой другой проект GitHub).

1. Создайте вилку METADATA.jl.

2. Добавьте свою вилку в качестве удаленного репозитория для репозитория METADATA на вашем локальном компьютере (в терминале, где USERNAME — это ваше имя пользователя GitHub):

   cd ~/.julia/v0.6/METADATA
   git remote add USERNAME https://github.com/USERNAME/METADATA.jl.git

3. Отправьте ваши изменения в свою вилку:

   git push USERNAME metadata-v2

4. Если всё прошло успешно, вернитесь на страницу GitHub своей вилки и нажмите ссылку «pull request».

Исправление требований к пакетам

Если вам нужно исправить зарегистрированные требования к версии уже опубликованного пакета, вы можете сделать это, просто отредактировав метаданные для этой версии, которая будет иметь тот же хэш коммита — хэш, связанный с версией, является постоянным:

$ cd ~/.julia/v0.6/METADATA/FooBar/versions/0.0.1 && cat requires
julia 0.3-
$ vi requires

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

Спецификация требований

Файл ~/.julia/v0.6/REQUIRE, файл REQUIRE внутри пакетов и файлы пакета METADATA requires используют простой формат на основе строк для выражения диапазонов версий пакетов, которые необходимо установить. Файлы пакета REQUIRE и METADATA requires также должны включать диапазон версий julia пакета, с которым он должен работать. Кроме того, пакеты могут включать файл test/REQUIRE для указания дополнительных пакетов, которые необходимы только для тестирования.

Вот как эти файлы анализируются и интерпретируются.

• Всё после отметки # удаляется из каждой строки в качестве комментария.

• Если остаётся только пробел, строка игнорируется.

• Если остаются символы, отличные от пробелов, строка является требованием, и она разбивается по пробелам на слова.

Самое простое возможное требование — это просто имя пакета в строке само по себе:

Distributions

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

Distributions 0.1

удовлетворяется любой версией Distributions, большей или равной 0.1.0. Добавление суффикса - к версии также позволяет любые предварительные версии. Например:

Distributions 0.1-

удовлетворяется предварительными версиями, такими как 0.1-dev или 0.1-rc1, или любой версией, большей или равной 0.1.0.

Эта запись требования:

Distributions 0.1 0.2.5

удовлетворяется версиями от 0.1.0 до, но не включая 0.2.5 Если вы хотите указать, что любая версия 0.1.x подойдёт, напишите:

Distributions 0.1 0.2-

Если вы хотите начать принимать версии после 0.2.7, напишите:

Distributions 0.1 0.2- 0.2.7

Если строка требования содержит ведущие слова, начинающиеся с @, это требование, зависящее от системы. Если ваша система соответствует этим условным системам, требование включается, в противном случае требование игнорируется. Например:

@osx Homebrew

будет требовать пакета Homebrew только на системах, где операционная система — OS X. Текущие поддерживаемые условные обозначения систем (иерархически):

• @unix

  • @linux

  • @bsd

    • @osx

• @windows

Условие @unix выполняется на всех UNIX-системах, включая Linux и BSD. Также поддерживаются условные обозначения систем с отрицанием, добавив ! после ведущих @. Примеры:

@!windows
@unix @!osx

Первое условие относится к любой системе, кроме Windows, а второе — к любой UNIX-системе, кроме OS X.

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

VERSION < v"0.3-" #exclude all pre-release versions of 0.3

v"0.2-" <= VERSION < v"0.3-" #get all 0.2 versions, including pre-releases, up to the above

v"0.2" <= VERSION < v"0.3-" #To get only stable 0.2 versions (Note v"0.2" == v"0.2.0")

VERSION >= v"0.2.1" #get at least version 0.2.1

См. раздел версий чисел для более подробного описания.