From 5b740779555c6c3cebb0d37bd3d311cfd1f888b6 Mon Sep 17 00:00:00 2001 From: Shunsuke Shibayama Date: Sat, 6 Jan 2024 00:39:09 +0900 Subject: [PATCH] doc: update tools/pack.md --- doc/EN/tools/pack.md | 100 ++++++++++++++++++++++++++++++++++++------- doc/JA/tools/pack.md | 95 +++++++++++++++++++++++++++++++++------- 2 files changed, 163 insertions(+), 32 deletions(-) diff --git a/doc/EN/tools/pack.md b/doc/EN/tools/pack.md index f26ac50f8..a80b9844d 100644 --- a/doc/EN/tools/pack.md +++ b/doc/EN/tools/pack.md @@ -35,28 +35,96 @@ Also see [package_system.md](../syntax/35_package_system.md) for the Erg package Below is an example of `package.er`. ```python -name = "example" # package name -author = "John Smith" # package author name -version="0.1.0" -description = "An awesome package" -categories = ["cli"] # package categories -type = "app" # "app" or "lib" -license = "" # e.g. "MIT", "APACHE-2.0", "MIT OR Apache-2.0" -pre_build = "" # script filename to be executed before build -post_build = "" # script filename to be executed after build -dependencies = { +.name = "example" # package name +.authors = ["John Smith"] # package author name +.version = "0.1.0" +.description = "An awesome package" +.categories = ["cli"] # package categories +.type = "app" # "app" or "lib" +.license = "" # e.g. "MIT", "APACHE-2.0", "MIT OR Apache-2.0" +.pre_build = "" # script filename to be executed before build +.post_build = "" # script filename to be executed after build +.dependencies = { # The latest one is selected if the version is not specified # If the version specification is omitted, the package manager automatically adds the version of the last successful build to the comments - foo = pack("foo") # [INFO] the last successfully built version: 1.2.1 + foo = "foo" # [INFO] the last successfully built version: 1.2.1 # Packages can be renamed - bar1 = pack("bar", "1.*.*") # [INFO] the last successfully built version: 1.2.0 - bar2 = pack("bar", "2.*.*") # [INFO] the last successfully built version: 2.0.0 - baz = pack("baz", "1.1.0") + bar1 = { name = "bar"; version = "1.*.*"} # [INFO] the last successfully built version: 1.2.0 + bar2 = { name = "bar"; version = "2.*.*"} # [INFO] the last successfully built version: 2.0.0 + baz = { name = "baz"; version = "1.1.0"} } -deprecated=False -successors = [] # alternative packages (when a package is deprecated) +.deprecated = False +.successors = [] # alternative packages (when a package is deprecated) ``` +### name + +The name of the package. Package names are case-insensitive. Also, `_` and `-` are not distinguished. Non-alphabetic characters may be used. + +### authors + +The names of the package maintainer. It is recommended to include an email address. + +### version + +The version of the package. Versions must follow semantic versioning. + +### description + +A brief description of the package. + +### categories + +The category of the package. [package.erg-lang.org](https://package.erg-lang.org) classifies packages based on this. + +### type + +The type of the package. Specify `app` or `lib`. If `app` is specified, an executable file is generated. If `lib` is specified, it becomes a library. + +### license + +The license of the package. License specification is required when registering a package in the registry. + +### pre_build + +The path to the script to be executed before building. + +### post_build + +The path to the script to be executed after building. + +### dependencies + +The dependencies of the package. + +```bnf +dependencies ::= '{' dependency* '}' +dependency ::= + name '=' package_name + | name '=' '{' 'name' '=' package_name (';' 'version' '=' version_spec)? ';'? '}' + | name '=' '{' 'git' '=' git_url ';'? '}' +name ::= +package_name ::= +version_spec ::= +git_url ::= +``` + +`name` is the package name to be specified when importing, and by giving it a different name, you can also use a different version of the same dependency. + +`package_name` is the identifier of the package registered in the registry. + +`version_spec` is the version of the package and is optional. If omitted, the latest version is used. It must follow semantic versioning. + +`git` is specified when installing a package directly from a git repository without using the registry. `git_url` is the URL of the git repository. + +### deprecated + +If the package is no longer maintained for some reason, specify `True`. + +### successors + +Specify the package that can be used instead of the package that has been deprecated. + ## Semantic versioning Erg packages are versioned based on [semantic versioning](https://semver.org/lang/en/). diff --git a/doc/JA/tools/pack.md b/doc/JA/tools/pack.md index 3e284eafc..8f2d896d9 100644 --- a/doc/JA/tools/pack.md +++ b/doc/JA/tools/pack.md @@ -37,28 +37,91 @@ Ergは標準でパッケージマネージャーが付属しており、`pack` 以下は`package.er`の記述例である。 ```python -name = "example" # package name -author = "John Smith" # package author name -version = "0.1.0" -description = "An awesome package" -categories = ["cli"] # package categories -type = "app" # "app" or "lib" -license = "" # e.g. "MIT", "APACHE-2.0", "MIT OR Apache-2.0" -pre_build = "" # script filename to be executed before build -post_build = "" # script filename to be executed after build -dependencies = { +.name = "example" # package name +.authors = ["John Smith"] # package author name +.version = "0.1.0" +.description = "An awesome package" +.categories = ["cli"] # package categories +.type = "app" # "app" or "lib" +.license = "" # e.g. "MIT", "APACHE-2.0", "MIT OR Apache-2.0" +.pre_build = "" # script filename to be executed before build +.post_build = "" # script filename to be executed after build +.dependencies = { # The latest one is selected if the version is not specified # If the version specification is omitted, the package manager automatically adds the version of the last successful build to the comments - foo = pack("foo") # [INFO] the last successfully built version: 1.2.1 + foo = "foo" # [INFO] the last successfully built version: 1.2.1 # Packages can be renamed - bar1 = pack("bar", "1.*.*") # [INFO] the last successfully built version: 1.2.0 - bar2 = pack("bar", "2.*.*") # [INFO] the last successfully built version: 2.0.0 - baz = pack("baz", "1.1.0") + bar1 = { name = "bar"; version = "1.*.*"} # [INFO] the last successfully built version: 1.2.0 + bar2 = { name = "bar"; version = "2.*.*"} # [INFO] the last successfully built version: 2.0.0 + baz = { name = "baz"; version = "1.1.0"} } -deprecated = False -successors = [] # alternative packages (when a package is deprecated) +.deprecated = False +.successors = [] # alternative packages (when a package is deprecated) ``` +### name + +パッケージ名を指定する。パッケージ名は大文字小文字を区別しない。また、`_`と`-`は区別されない。アルファベット以外の文字も使用可能。 + +### authors + +パッケージの管理者名を指定する。メールアドレスの付記が推奨される。 + +### version + +パッケージのバージョンを指定する。バージョンはセマンティックバージョニングに従う必要がある。 + +### description + +パッケージの簡潔な説明。 + +### categories + +パッケージのカテゴリ。[package.erg-lang.org](https://package.erg-lang.org)ではこれを元にパッケージが分類される。 + +### type + +パッケージの種類。`app`か`lib`を指定する。`app`の場合は実行ファイルが生成される。`lib`の場合はライブラリとなる。 + +### license + +パッケージのライセンス。パッケージをレジストリに登録する際にはライセンスの指定が必須となる。 + +### pre_build + +ビルド前に実行するスクリプトファイル名を指定する。 + +### post_build + +ビルド後に実行するスクリプトファイル名を指定する。 + +### dependencies + +パッケージの依存関係を指定する。 + +```bnf +dependencies ::= '{' dependency* '}' +dependency ::= + name '=' package_name + | name '=' '{' 'name' '=' package_name (';' 'version' '=' version_spec)? ';'? '}' + | name '=' '{' 'git' '=' git_url ';'? '}' +name ::= +package_name ::= +version_spec ::= +git_url ::= +``` + +`name`はimportする際に指定するパッケージ名であり、別名をつけることで同じ依存関係の別バージョンも利用できる。`package_name`はレジストリに登録されているパッケージの識別子である。`version_spec`はパッケージのバージョンであり、省略可能である。省略した場合は最新のバージョンが利用される。セマンティックバージョニングに従う必要がある。 +`git`はレジストリを使わずにgitリポジトリから直接パッケージをインストールする場合に指定する。`git_url`はgitリポジトリのURLである。 + +### deprecated + +パッケージがもうメンテナンスされていないなどの理由で非推奨になっている場合は`True`を指定する。 + +### successors + +パッケージが非推奨になった場合に代わりに使えるパッケージを指定する。 + ## セマンティックバージョニング Ergのパッケージは[セマンティックバージョニング](https://semver.org/lang/ja/)に基づいてバージョンの指定を行います。