Julia 開發(fā)擴(kuò)展包

開發(fā)擴(kuò)展包

Julia 中設(shè)有包管理器，當(dāng)你安裝了擴(kuò)展包時，你可以看到它的源代碼和完整的開發(fā)歷史。你也可以修改擴(kuò)展包，并使用 git 提交它們，為修復(fù)和增加擴(kuò)展包功能做貢獻(xiàn)。相似地，這個系統(tǒng)設(shè)計(jì)用來當(dāng)你想要創(chuàng)建一個新擴(kuò)展包時，最簡單的方法就是利用包管理器中提供的基礎(chǔ)設(shè)施。

初始化設(shè)置

由于擴(kuò)展包存儲于 git 倉庫中，所以在做擴(kuò)展包開發(fā)之前，你需要先設(shè)置如下全局 git 配置：

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

FULL NAME 是你真實(shí)的全名(雙引號之間允許有空格)并且 EMAIL 是你真實(shí)的郵箱地址。
盡管創(chuàng)建和發(fā)布 Julia 擴(kuò)展包時使用 GitHub 并不是必要的，然而大多數(shù) Julia 擴(kuò)展包都存在 GitHub 上并且包管理器知道如何正確地格式化源 URL，并在其他方面上順利的使用服務(wù)。我們建議你創(chuàng)建一個免費(fèi)賬號 在 GitHub 上然后做：

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

在這里 USERNAME 是你 GitHub 上正確的用戶名。只要你做了這一點(diǎn)，包管理器就知道你的 GitHub 用戶名然后可以配置相關(guān)事項(xiàng)。你還需要上傳 你的 SSH 公鑰到 GitHub 上并設(shè)置一個 SSH 代理在你的開發(fā)機(jī)器上，這樣你可以最簡單的推送你的修改。在將來，我們會讓這個系統(tǒng)具有擴(kuò)展性，支持更多其它的常見 git 工具例如 BitBucket 并且允許開發(fā)者選擇他們所喜歡的。

生成新擴(kuò)展包

假如你想創(chuàng)建一個新的 Julia 擴(kuò)展包，名為 FooBar。首先，你需要 Pkg.generate(pkg,license)，其中 pkg 是新擴(kuò)展包的名字并且 license 是生成器知曉的許可的名字：

    julia> Pkg.generate("FooBar","MIT")
    INFO: Initializing FooBar repo: /Users/stefan/.julia/v0.3/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 .travis.yml
    INFO: Committing FooBar generated files

這樣創(chuàng)建了一個目錄 ~/.julia/v0.3/FooBar，將它初始化為一個 git 倉庫，生成所有包需要有的一系列文件，并把它們提交到倉庫：

    $ cd ~/.julia/v0.3/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*]

     .travis.yml      | 16 +++++++++++++
     LICENSE.md       | 22 +++++++++++++++++++++++
     README.md        |  3 +++
     src/FooBar.jl    |  5 +++++
     test/runtests.jl |  5 +++++
     5 files changed, 51 insertions(+)

此時，包管理器知道 MIT "Expat" 證書用 "MIT" 表示，Simplified BSD 證書用 "BSD" 表示，2.0 版本的 Apache 軟件證書用 "ASL" 表示。如果你想要使用不同的證書，你可以讓我們把它添加到擴(kuò)展包生成器上，或者就選這三者之一然后在生成之后修改 ~/.julia/v0.3/PACKAGE/LICENSE.md 文件。

如果你創(chuàng)建了一個 GitHub 賬戶并且配置了 git,Pkg.generate 將會設(shè)置一個合適的源 URL 給你。它還會自動生成 .travis.yml 文件來使用 Travis 自動測試服務(wù)。你可以在 Travis website 上測試你的擴(kuò)展包倉庫，但是只要你做了這個它就已經(jīng)開始測試了。當(dāng)然，所有的默認(rèn)測試是查證 using FooBar 能否在 Julia 上工作。

使你的擴(kuò)展包具有可用性

只要你提交了一些內(nèi)容，那么你會為測試 FooBar 是否可以工作而感到高興，你可能想要一些其他人來測試一下。首先，你需要創(chuàng)建一個遠(yuǎn)程倉庫并把你的代碼推送進(jìn)去；我們不會自動的為你做這件事，但是未來將會，這配置起來并不難[3]。只要你完成了這個，只需將發(fā)布的倉庫的 URL 發(fā)給他們就可以請讓他們來試一下你的代碼 - 像這樣：

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

對于你的擴(kuò)展包而言，它將具有你的 GitHub 用戶名和你的擴(kuò)展包名，但是你明白是什么意思。收到你發(fā)的 URL 的人們可以使用 Pkg.clone 來安裝擴(kuò)展包并測試它:

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

[3]: 極度推薦安裝并使用 GitHub 的 "hub" 工具。它允許你在擴(kuò)展包倉庫中像運(yùn)行 hub create 那樣做事，然后它會通過 GitHub 的 API 自動創(chuàng)建。

發(fā)布你的擴(kuò)展包

一旦你決定 FooBar 已經(jīng)準(zhǔn)備好注冊成為一個官方正式擴(kuò)展包，你可以把它添加到你的本地 METADATA 的拷貝，并命名為 Pkg.register:

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

這會在 ~/.julia/v0.3/METADATA 倉庫中創(chuàng)建一次提交:

    $ cd ~/.julia/v0.3/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

然而，這次提交只是本地可見的。為了能將它公諸于世，你需要將你的本地 METADATA 上傳到正式庫中合并。Pkg.publish() 命令將在 GitHub 上創(chuàng)建 METADATA 倉庫的分支，并將你的修改提交到分支上，并打開一個拉取請求：

  julia> Pkg.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

由于各種各樣的原因 Pkg.publish() 有時并不會成功。在那些情況下，你可能在 GitHub 上做了一個拉取請求，這并不難。

只要 FooBar 擴(kuò)展包的 URL 在正式 METADATA 倉庫中注冊，人們就知道從哪里克隆這個擴(kuò)展包，但是這并沒有一些注冊過的版本可供下載。這意味著 Pkg.add("FooBar") 在只安裝正式版本時并沒有工作。Pkg.clone("FooBar") 沒有一個指定的 URL 指向它。此外，當(dāng)他們運(yùn)行 Pkg.update()，他們將會得到你上傳到倉庫中最新版本的 FooBar。當(dāng)你還在修改它，在它沒有成為正式版之前這是一個比較好的方式測試你的擴(kuò)展包。

擴(kuò)展包版本號標(biāo)簽

當(dāng)你準(zhǔn)備好為你的擴(kuò)展包制作一個正式版本時，你可以使用 Pkg.tag 命令為它添加版本號并注冊：

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

這個 v0.0.1 標(biāo)簽在 FooBar 倉庫中：

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

它也可以為 FooBar 在你的本地 METADATA 倉庫中創(chuàng)建一個新的版本入口：

    $ cd ~/.julia/v0.3/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

如果在你的擴(kuò)展包倉庫中有一個 REQUIRE 文件，它將會在你標(biāo)記版本時拷貝到 METADATA 中適當(dāng)?shù)奈恢?。擴(kuò)展包開發(fā)者們需要確定他們的擴(kuò)展包中的 REQUIRE 文件確實(shí)反應(yīng)他們擴(kuò)展包的需求，如果你使用 Pkg.tag 命令，這將自動進(jìn)入你的正式版?？?Requirements Specification 來了解完整格式的 REQUIRE。

Pkg.tag 命令有第二個可選參數(shù)是一個顯示的版本號對象如 v"0.0.1" 或者一個標(biāo)志 :patch，:minor 或者 :major。這會智能地添加你的擴(kuò)展包的補(bǔ)丁、副本或者主版本號。

正如使用 Pkg.register，這些對于 METADATA 的修改不會對其它任何人可見直到這些修改被上傳。再一次使用 Pkg.publish()命令行，它第一次使用的時候要確定每個獨(dú)立的擴(kuò)展包倉庫已經(jīng)被標(biāo)記，如果它們沒有被標(biāo)記要提交它們，然后打開一個到 METADATA 的拉取請求：

  julia> Pkg.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

修改擴(kuò)展包需求

如果你需要修改一個已發(fā)布擴(kuò)展包版本的注冊需求，你只需要修改這個版本的 metadata 即可，這樣可以保持相同的提交散列值 – 散列值與一個版本永久相關(guān):

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

  $ vi requires

為了保持提交的散列值保持一致，需要檢驗(yàn)倉庫中的 REQUIRE 文件的內(nèi)容是否與在 METADATA 中的在修改之后不匹配；這是不可避免的。

盡管當(dāng)你在 METADATA 中為之前版本的擴(kuò)展包修改了需求，你仍需要在當(dāng)前版本的擴(kuò)展包中修改 REQUIRE 文件。

依賴關(guān)系

在擴(kuò)展包中的 ~/.julia/v0.3/REQUIRE 文件, REQUIRE 文件，和 METADATA 包 requires 文件使用一個簡單的基于行的格式來顯示需要安裝的擴(kuò)展包版本的范圍。包 REQUIRE 和 METADATA requires 文件也需要包括擴(kuò)展包兼容的 julia 的版本范圍。

這里是這些包如何被解析和解釋的。

• 所有在 # 號后的內(nèi)容被從行中剝離成為注釋。
• 如果出了空白什么都沒有，那么這一行被忽略。
• 如果剩下的都是非空字符，那么這一行是一個依賴關(guān)系，并且需要用空格分開每個單詞。

最簡單的有可能的依賴關(guān)系是這一行只有擴(kuò)展包的名字：

    Distributions

這個依賴將被任何版本的 Distributions 擴(kuò)展包滿足。這個擴(kuò)展包的名字可以緊隨零活更多升序版本號之后，指明可以接受的那個擴(kuò)展包的版本間隔。一個版本號開始一個間距，下一個是這個間距的結(jié)束，然后下一個又是一個新的開始，然后繼續(xù)；如果出現(xiàn)了一個奇怪的版本號，那么任意更高的版本都將兼容；如果給出了一個相同的版本號，那么后一個是可以兼容的最高版本。舉個例子，這一行：

    Distributions 0.1

0.1.0 及其之后的版本的 Distributions 都將被兼容。一個版本號以 - 作為后綴也允許任何相同前綴的發(fā)布版本兼容。例如：

    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

如果一個依賴行以引導(dǎo)字符 @ 開始，這是一個系統(tǒng)依賴關(guān)系。如果你的系統(tǒng)匹配這些系統(tǒng)環(huán)境，依賴關(guān)系就會被包含，否則將被忽略。例如：

    @osx Homebrew

將僅在操作系統(tǒng)是 OS X 時需要 Homebrew 擴(kuò)展包。當(dāng)前支持的系統(tǒng)環(huán)境包括：

    @windows
    @unix
    @osx
    @linux

@unix 環(huán)境適應(yīng)于所有的 UNIX 操作系統(tǒng)，包括 OS X, Linux 和 FreeBSD。在引導(dǎo)字符 @ 后添加 ! 表示否定的操作系統(tǒng)。例子：

    @!windows
    @unix @!osx

第一個環(huán)境應(yīng)用于任何系統(tǒng)除了 Windows ，第二個環(huán)境應(yīng)用于任何 UNIX 系統(tǒng)除了 OS X。

運(yùn)行時檢查 Julia 的當(dāng)前版本可以應(yīng)用在內(nèi)置 VERSION 變量，這是一種 VersionNumber。這些代碼偶爾是必要的用來跟蹤在發(fā)布的 Julia 版本之間的新功能或棄用的功能。運(yùn)行時檢查的例子：

    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

到 version number literals 查看跟過更完整的描述細(xì)節(jié)。