11# 包开发
2- ## 流程
3- 通常来说，包的全部数据应该是一个 [ git ] ( ../meta/tools/ git.md ) 仓库，置于 github（或其它保证长期稳定的服务器）中，建议添加一份 [ 许可证 ] ( ../knowledge/licenseknowledge .md ) 。每次更新时应在本地操作再推送到远程仓库并注册更新（若需要）
2+ ## Git 仓库
3+ 通常来说，包的全部数据应该是一个 [ Git ] ( ../knowledge/ git.md ) 仓库，并且被置于 [ Github ] ( ../knowledge/github .md ) （或其它保证长期稳定的服务器）中。
44
5- ## 结构生成
6- 设置好路径后，可以在包管理器模式下使用 ` generate foo ` 生成基本框架。
5+ 按照惯例，建议在仓库中添加如下内容，特别是如果你想要开源你的包
6+ * 一个名为 ` README.md ` 的文件介绍你的包（也可不用 Markdown）
7+ * 一份[ 许可证] ( ../knowledge/licenseknowledge.md )
78
8- 在[ 相对路径] ( ../advanced/filesystem.md#路径 ) ` ./foo ` 处生成一个目录，包含包的基本结构：
9- - ` src/foo.jl ` ，包含一个[ 模块] ( ../advanced/module.md ) 的基本结构
10- - ` Project.toml ` ，包含相关注册信息
9+ 如果需要团队合作，可以参考
10+ - [ 约定式提交规范（中文）] ( https://www.conventionalcommits.org/zh-hans/v1.0.0/ )
11+ - [ 经典文：Angular 贡献规范] ( https://github.com/angular/angular.js/blob/main/CONTRIBUTING.md )
12+ - [ Contributor's Guide on Collaborative Practices for Community Packages] ( https://github.com/SciML/ColPrac )
13+
14+ ## 包结构初始化
15+ 挑选好你的目标路径后，在包管理器模式下使用 ` generate 名称 ` 生成包的基本框架。
16+
17+ 例如 ` generate foo ` 将在[ 相对路径] ( ../advanced/filesystem.md#路径 ) ` ./foo ` 处生成一个目录，包含包的基本结构。
18+ ``` julia-repl
19+ (@v1.11) pkg> generate foo
20+ Generating project foo:
21+ foo\Project.toml
22+ foo\src\foo.jl
23+ ```
24+
25+ ` src/foo.jl ` 文件包含一个[ 模块] ( ../advanced/module.md ) 的基本结构。
26+
27+ 如果还需初始化 Git，可使用 ` git init ` 命令。
1128
1229也可以参照：
1330- [ 官方提供的包示例] ( https://github.com/JuliaLang/Example.jl )
1431- [ 包模板生成器] ( https://invenia.github.io/PkgTemplates.jl/stable/ )
1532
16- ## Project.toml
17- ` Project.toml ` 使用 [ TOML 格式] ( ../knowledge/toml.md ) ，数据中必须含有以下内容
18- - ` name ` 表示包名，应与模块名一致
33+ 获得更丰富的模板。
34+
35+ ## 包的配置
36+ 包的配置数据写在 ` Project.toml ` 文件中。这个文件使用 [ TOML 格式] ( ../knowledge/toml.md )
37+
38+ 配置数据中必须含有以下内容：
39+ - ` name ` 包名，应与模块名一致
1940- ` uuid ` 一个独一无二的 UUID，可以使用 [ UUIDs] ( ../packages/uuids.md ) 生成
20- - ` version ` 当前 [ 版本] ( ../advanced/versionnumber.md )
21- - ` [deps] ` 一个字典，包含 ` 基于的包名 = "它的UUID " ` ，后者可以通过查找对应仓库中填写的 ` uuid ` 项或其它调用了它的包中的 ` [deps] ` 项获取
41+ - ` version ` 包的当前 [ 版本] ( ../advanced/versionnumber.md )
42+ - ` [deps] ` 一个字典，包含 ` 基于的包名 = "它的 UUID " ` ，后者可以通过查找对应仓库中填写的 ` uuid ` 项或其它调用了它的包中的 ` [deps] ` 项获取
2243- ` [compat] ` 一个字典，包含 ` 包名 = "支持的版本" ` ，特别地，` julia ` 项表示支持的 Julia 版本
23- - [ ` extras ` 与 ` target ` 的用途] ( https://discourse.juliacn.com/t/topic/6341/2 )
2444
25- 示例
45+ 此外，还可选择填写 [ ` extras ` 与 ` target ` ] ( https://discourse.juliacn.com/t/topic/6341/2 )
46+
47+ 示例的文件内容如下：
2648``` julia-repl
2749name = "LightLearn"
2850uuid = "aea05ee4-eee8-4bb2-9be1-ccb376bfd141"
@@ -39,15 +61,19 @@ ColorTypes = "0.11"
3961PNGFiles = "0.3"
4062```
4163
42- ## build
43- 该功能的必要性与实际情况有关。
64+ ## 包的构建
65+ 这个功能仅在包比较复杂，需要主动控制包的构建流程时用到。
66+
4467当包第一次被安装或运行 ` build ` 命令时，会调用 ` deps/build.jl ` 中的代码。
45- 若 ` build ` 失败，提示信息会在终端显示
4668
47- ## test
48- 该功能不是必要的；可参考 [ Test 的使用] ( ../packages/test.md )
69+ 若构建失败，提示信息会在终端显示失败的详细信息。
70+
71+ ## 包的测试
72+ 可参阅：如何编写有效的单元测试？
73+
74+ 关于 ` test ` 命令，可参考 [ Test 的使用] ( ../packages/test.md ) 。
4975
50- ## 手动测试
76+ ### 手动测试
5177` add ` 命令允许参数是一个本地路径，从而在本地安装包，以模拟包环境。
5278
5379该路径指向的资源必须是一个 ` git ` 仓库，且它会读取最近的 ` commit ` 数据。
@@ -90,7 +116,7 @@ Julia 1.5 以后，[Scratch](../packages/scratch.md)提供了*临时空间*的
90116### Preferences
91117Julia 1.6 以后，` Preferences ` 允许包读写首选项到顶级的 ` Project.toml ` 。这些首选项可以在运行时或编译时读取，以启用或禁用包行为的不同方面（以前，包会将文件写入到它们自己的包目录中以记录由用户或环境设置的选项，但现在不鼓励该行为）
92118
93- ### 其它
94- 如果希望团队协助，可以参考 [ 经典文：贡献规范 ] ( https://github.com/angular/angular.js/blob/main/CONTRIBUTING.md ) 。
119+ ## 参阅
120+ - [ Modern Julia Workflows ] ( https://modernjuliaworkflows.org/ )
95121
96122[ ^ 1 ] : https://juliaregistries.github.io/RegistryCI.jl/stable/guidelines/
0 commit comments