Package Control新方式(2.0)でのJSON記述方法 #SublimeText3

Package Control のパッケージ公開方法が変更になりました#JSONの書き方でも説明したように、Package Controlのスキーマバージョンが1.2から2.0に上がりました。大幅に変わったので、対応する場合は新しく書き直す方がよいでしょう。以下は、本家のサンプルファイルで説明されている内容を参考にしています。

書く場所

Package Control Channelのrepository/*.jsonの中か、自分のリポジトリのpackage.jsonの中。

{
    "schema_version": "2.0",
    "packages": [
        ------ ここから ------
        {
            パッケージAの定義
        },
        ------ ここまで ------
        {
            パッケージBの定義
        },
        ...
    ]
}

ここからここまでと書いてある単位が、１つのパッケージです。以下、そこだけを抜き出して解説します。

書き方サンプル

JSON的に、インデントは空白でもタブでも動作しますが、空白にするとパッケージ申請時に引っかかるため、タブにする必要があります。

超シンプルな書き方

GitHubかBitBucketにリポジトリがある
URLのpackage_nameの部分をそのままパッケージの名前にしてよい
"master"や"default"にコミットされるたびにパッケージが更新されたとみなしてよい

以上の条件に当てはまれば、以下の書き方でOK。

GitHub

{
    "details": "https://github.com/YourName/package_name"
}

BitBucket

{
    "details": "https://bitbucket.org/YourName/package_name"
}

1.2には無かった details というキーワードが肝になります。GitHubやBitBucketにリポジトリがあれば、detailsに指定したURLで、これまで自分で書いていた情報(description, author, homepageなど)を全自動で引っ張ってきてくれます。

作者推奨の書き方

パッケージの名前はpackage_nameとは違う(YourPackageName)
タグを切るたびにパッケージが更新されたとみなしてほしい

のであれば、次のような書き方となります。

GitHub

{
    "name": "YourPackageName",
    "details": "https://github.com/YourName/package_name",
    "releases": [
        {
            "sublime_text": "*",
            "details": "https://github.com/YourName/package_name/tags"
        }
    ]
}

BitBucket

{
    "name": "YourPackageName",
    "details": "https://bitbucket.org/YourName/package_name",
    "releases": [
        {
            "sublime_text": "*",
            "details": "https://bitbucket.org/YourName/package_name#tags"
        }
    ]
}

sublime_text の行は本来冗長ですが、書いていないとPackage Control Channelに申請するときにチェックツールで引っかかるため、実質必須となっています。

X.X.X (Xは数字) という名前でタグを作成するたびに、パッケージが更新されることになります。releasesのdetailsは、先のdetailsと同様、Package Controlがバージョンに関する情報を取得するのに使うURLです。これを元にdate(以前のlast_modified), version, urlが自動設定されます。ZIPファイルのパスではないので注意。

タグではなく特定のブランチを指定することもできます。詳細は後述。

GitHubやBitBucketの情報に頼らない書き方(1.2風)

そもそもGitHubやBitBucketに置いていなければ、detailsを指定しても全自動で引っ張ってきてくれません。また、detailsで引っ張ってきた情報をそのまま掲載されると困る場合もあるかもしれません。そんな時のために、自分で書く手段が残されています。以下の例ではdetailsを書いていませんが、detailsを書いて、自動で設定されたくないものだけ上書き指定することもできます。

{
    "name": "パッケージの名前",
    "homepage": "ホームページのURL",
    "author": "作者",
    "readme": "READMEのURL",
    "issues": "バグトラッカーのURL",
    "donate": "寄付のURL",
    "buy": "ライセンス購入先URL",
    "releases": [
        {
            "version": "2.0.0",
            "url": "ZIPのファイルパス(https必須)",
            "date": "2011-09-18 20:12:41"
        }
    ]
}

README

raw(生ファイル)のパスを指定します。ちゃんと指定すると、Package Controlの自分のパッケージのページに内容が表示されます。.markdown, .mdown, .mkd, .md, .texttile, .creole, .rst の場合は、いい感じに整形してくれます。その他の場合はテキストファイルとして表示されます。

パッケージの変名

変名前の名前のリストをprevious_namesで指定すれば、以前の名前のパッケージがインストールされている場合に、削除して現在の名前のパッケージをインストールしてくれます。

例: "previous_names": ["sublime_alignment"]

ラベル

Qiitaで言うところの「タグ」のようなものをつけられます。別に何をつけてもいいのですが、サンプルファイルにある文字列で設定しておくと、検索しやすくなるようです。

例: "labels": ["text manipulation", "formatting"]

タグでなく、特定のブランチをパッケージとして使う

releasesのdetailsのURLを次のようにすると、指定したブランチが更新されたタイミングでパッケージが更新されるようになります(ブランチ名がcustom_branchの例)。

GitHub:
https://github.com/YourName/package_name/tree/custom_branch
BitBucket:
https://bitbucket.org/YourName/package_name/src/custom_branch

Sublime Text 2(3)にだけ対応する

<3000でSublime Text 2用、>2999でSublime Text 3用と指定できます。Package Controlのサイトに対応バージョンが載るほか、対応していないバージョンのSublime TextのInstall Packageで、一覧に表示されなくなります。以下は、バージョンによってパッケージの取得先を変えたい場合の書き方の例です。

"releases": [
    {
        "sublime_text": "<3000",
        "details": "Sublime Text 2用のブランチ"
    },
    {
        "sublime_text": ">2999",
        "details": "Sublime Text 3用のブランチ"
    }
]

特定のOSにだけ対応する

以前は platforms - windows/osx/linux - パッケージという階層構造でしたが、sublime_textと同じような感じで指定するようになりました。

"releases": [
    {
        "sublime_text": "*",
        "platforms": ["osx", "linux"],
        "details": "Mac/Linux用のパッケージ"
    },
    {
        "sublime_text": "*",
        "platforms": "windows",
        "details": "Windows用のパッケージ"
    }
]