Julia 笔记系列:

唠唠闲话

今年参与了 OSPP’22 的 Julia 开源项目,期间学习了 Julia 模块从开发到测试的完整过程。借这个机会,整理这段时间学习到的知识。Julia 在开发方面提供了便捷丰富的工具,且对新人尤其友好。

推荐阅读:

概要

本篇内容包括:

  • 文件结构和文件作用
  • 简易 Demo 及常用包管理命令

作为例子,可以参考:QRCoders.jlQRDecoders.jl.

项目开发通常用 Git 工具,所以这里假定已经有了一定的 Git 基础。如果不熟悉 Git,可以参考 廖雪峰的 Git 教程


文件结构和作用

文件可以分三部分:

  • 开源项目常用文件,比如 README.mdLICENSE
  • 项目代码,比如 src, docstest
  • 环境文件:Project.tomlManifest.toml

其中环境文件是本节讨论重点。

文件结构

打开一个 Julia 包,查看文件结构,比如

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# tree QRCoders.jl/ -L 2
QRCoders.jl/
├── docs
│ ├── make.jl
│ ├── Manifest.toml
│ ├── Project.toml
│ └── src
├── LICENSE
├── Manifest.toml
├── Project.toml
├── README.md
├── src
│ ├── QRCoders.jl
│ └── tables.jl
└── test
├── runtests.jl
└── tst_overall.jl

最外层有这几个文件、文件夹:

文件(夹) 作用
LICENSE 开源协议
README.md 包的介绍说明
docs 包的使用文档,用于生成网页
src 存放源代码的地方
test 测试代码
Manifest.toml 项目依赖的具体版本
Project.toml 项目依赖的包

一般开源仓库都有 LICENSEREADME.mdLICENSE 为开源协议,用得比较广泛的是 MIT LICENSE;README.md 用于介绍项目信息,使用方法、贡献者等等,打开 GitHub 仓库,直接看到的页面就是由 README.md 展示。

仓库通常还有 .gitignore 文件,用于忽略不需要上传的文件,比如测试过程产生的临时文件,或者使用 Jupyter 产生的 .ipynb_checkpoints 文件等。

src/test/docs 是 Julia 包约定或规定要有的文件夹:

  • src 存放源代码,且要求必须有模块的同名文件;假设模块名为 QRCoders,则必须存在文件 src/QRCoders.jl;当我们使用 using/import 导入 Julia 包时,背后是在执行 src/<模块名>.jl 文件
  • test 可选,存放测试代码;test 目录下需存放 runtests.jl 文件;当使用包管理模式执行 test 命令时,会自动执行 test/runtests.jl 的内容
    20221002172213
  • docs 可选,用于生成使用文档;通常配合 Documenter.jl 使用,并在 docs 目录下存放 make.jl 文件,用于生成网页

关于测试 test 和文档 docs,我们在下篇单独展开介绍。

还有两个文件 Manifest.tomlProject.toml,用于管理包依赖的,比较重要,接下来单独介绍。

环境文件

Project.tomlManifest.toml 的几点比较:

  1. Pkg 模式下执行 instanitate,将在当前环境所在目录生成 Manifest.tomlProject.toml,用于记录包的依赖信息,比如
    深度截图_选择区域_20221002174047
    每次执行包的安装、删除、更新等操作时,Pkg 会自动更新这两个文件

  2. 模块主目录必须有 Project.toml 文件,而 Manifest.toml 是可选的

  3. Mainifest.toml 可读性较差,通常只通过执行 Pkg 命令自动更改,不建议手动修改;而 Project.toml 内容要简洁很多,可以手动维护

  4. Project.toml 记录项目的基本信息,一般来说是 Pkg 和程序员共同控制的内容Manifest.toml 是包管理器 Pkg 基于 Project.toml 生成的内容(以及执行包操作触发的修改),其记录了执行这个项目所需要的全部依赖的信息

  5. 多数项目只提供 Project.toml 就足够了指定环境和依赖了,但一些特殊情况,可能需要提供 Manifest.toml,下一小节在介绍具体参数

  6. 文档 docs 和测试 test 也可以设置环境依赖,通过在相应目录添加 Project.toml(和 Manifest.toml)来设置

  7. 从可复现性的角度来说, 从高可复现至低可复现依次是:

    • 提供 Project.toml/Manifest.toml: 常用于各种一次性项目
    • 提供 Project.toml:常用于工具箱开发
    • 啥也没有:单纯的代码库,不能用 using 调用

Project.toml

注:实践通常用 PkgTemplate 生成环境文件,而不需要自己手动编辑,但了解参数含义还是很有必要

推荐阅读:Project.toml and Manifest.toml

QRCoders.jl 为例,查看 Project.toml 的参数:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
name = "QRCoders"
uuid = "f42e9828-16f3-11ed-2883-9126170b272d"
authors = ["Jérémie Gillet <jie.gillet@gmail.com> and contributors"]
version = "1.0.1"

[deps]
FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
ImageCore = "a09fc81d-aa75-5fe9-8630-4744c3626534"
ImageIO = "82e4d734-157c-48bb-816b-45c225c6df19"

[compat]
FileIO = "1"
ImageCore = "0.8, 0.9"
ImageIO = "0.4, 0.5, 0.6"
julia = "1.3"

[extras]
Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

[targets]
test = ["Test", "Random"]

文件包括了五个部分:

  1. 顶部是项目的基本信息

    • name:模块名称,Julia 通过识别 name 来确定当前环境名称;此外 src/ 目录下必须有name 内容命名的 .jl 文件
    • uuid 全称 Universally Unique Identifier(通用唯一识别码),用于标识 Julia 包
    • authors 作者信息
    • version 当前模块的版本号,使用 Semantic Versioning(语义化版本)
  2. deps 是当前项目依赖的包,使用 pkg> add 添加环境依赖时会自动更新

  3. compat 是项目依赖的包的版本要求,需手动指定。按开发规范应为非自带包设置版本要求,并指定兼容的 Julia 版本

  4. extras 是额外的依赖,比如测试环境依赖的包。比如 QRCoders 在这里添加了测试环境需要的 Test, Random,因而省去了 test 目录下的 Project.toml 文件

  5. targets 似乎是按 extras 对应出现的,目前了解不多

通常,只有 compat 要手动指定依赖版本,其他的都是自动生成,或者在用包管理器时自动更新。

语义化版本

在注册包时,可能会遇到关于版本号的相关问题,这里简单介绍一下,内容摘自 短课笔记-8

  1. 代码工程中很容易遇到的一个问题就是版本冲突,例如: A 与 B 都是项目中需要的包, 而 A 与 B 都依赖于一个共同的包 C, 这时候如果 A 仅支持 C == 0.4.0 而 B 仅支持 C == 1.0.0 的话,那么就出现了版本冲突现象。

  2. 为了降低版本冲突的可能性,包管理器 Pkg 采用了语义化版本 Semantic Versioning。大概意思是说,所有版本分为四个主要类别: 主版本 major, 小版本 minor, 补丁版本 patch 以及构建版本 build。在 Julia 中大部分时候仅使用前三个版本。

  3. 版本格式:主版本号.次版本号.修订号,版本号递增规则如下:

  • 主版本号:当你做了不兼容的 API 修改
  • 次版本号:当你做了向下兼容的功能性新增
  • 修订号:当你做了向下兼容的问题修正

先行版本号及版本编译信息可以加到 主版本号.次版本号.修订号的后面,作为延伸。

基于 SemVer,我们可以做出类似于这样的假设:

如果 A 兼容 C == 1.0.0, 那么 A 应该也兼容 C == 1.0.1C == 1.1.0,但未必兼容 C == 2.0.0

为此,Project.toml 引入了 [compat] 块,例如:

  • FileIO = "1" 代表仅兼容 1.x.y 版本的 FileIO
  • ImageCore = "0.8, 0.9" 代表仅兼容 0.8.x0.9.x
  • 版本号还支持 "≥ 1.2.3" 等语法,相关规则参看 Version specifier format

此外,以 0 开始的版本通常表示仍在开发中,此时次版本不一定能向下兼容,比如 0.2 不一定能兼容 0.1

Manifest.toml

Mainfest.toml 由一系列格式如下的片段构成,记录了项目详细的依赖信息

1
2
3
4
5
[[QRCoders]]
deps = ["FileIO", "ImageCore", "ImageIO"]
git-tree-sha1 = "a7a56a2550dbea3b603b357adf81710385d1d3c7"
uuid = "f42e9828-16f3-11ed-2883-9126170b272d"
version = "1.0.1"

其中 git-tree-sha1 记录了该模块所在 commit 的哈希结果,其他参数与前边讨论类似。

多数时候,我们并不需要添加 Manifest.toml 来记录环境。但一些情况,比如依赖的模块未注册,或者依赖模块是在本地开发,就得提供 Manifest.toml 来保证环境的可复现。比较常见的两种情况:

  1. 安装未注册的 Github 包,比如

    1
    pkg> add https://github.com/JuliaImages/QRCoders.jl

    Manifest.toml 中会出现类似的片段

    1
    2
    3
    4
    5
    6
    7
    [[QRCoders]]
    deps = ["FileIO", "ImageCore", "ImageIO"]
    git-tree-sha1 = "a7a56a2550dbea3b603b357adf81710385d1d3c7"
    repo-rev = "master"
    repo-url = "https://github.com/JuliaImages/QRCoders.jl"
    uuid = "f42e9828-16f3-11ed-2883-9126170b272d"
    version = "1.0.1"

    其中 repo-rev 记录模块所在分支,repo-url 记录模块所在地址。当然不只是 GitHub 仓库,本地仓库或其他 Git 仓库也能用这种方式添加

  2. 安装本地开发的包

    1
    2
    # dev /path/to/your/package
    pkg> dev /home/rex/ospp/QRDecoders.jl

    Manifest.toml 中出现的片段

    1
    2
    3
    4
    5
    [[QRDecoders]]
    deps = ["FileIO", "ImageIO", "ImageTransformations", "QRCoders"]
    path = "/home/rex/ospp/QRDecoders.jl/"
    uuid = "d4999880-6331-4276-8b7d-7ee1f305cff8"
    version = "0.1.0"

以上两种情况均需要使用 Manifest.toml 来完整记录环境。

小结

本节介绍了 Julia 包的文件结构,包括

  1. GitHub 仓库常用的

    • README.md 项目介绍
    • LICENSE 开源协议
    • .gitignore 忽略无关文件
  2. Julia 代码文件:

    • src 存放源代码
    • test 存放测试代码
    • docs 存放文档
  3. Julia 环境文件

    • Project.toml 项目依赖
    • Manifest.toml 项目详细依赖

对多数包来说,只使用 Project.toml 记录环境,而将 Manifest.toml 放在 .gitignore 中忽略。但当使用未注册的包时,或有更严格的复现需求时,就得提供 Manifest.toml 来记录环境。

如果 Manifest.toml 已被 .gitignore 设置了忽略,可以通过 git add -f Manifest.toml 强制添加;相反的,如果 Manifest.toml 已被添加,可以通过 git rm --cached Manifest.toml 来取消添加。

简易教程

这节演示如何通过包管理创建模板,跟开发需求有关的更多使用 PkgTemplates,我们下一篇再介绍。

Demo

作为示例,新建目录 TestPackage,后续操作都在这里进行。

  1. 创建 git 环境

    1
    2
    cd TestPackage # 进入目录
    git init # 初始化 git

    以下为 Git 仓库常用文件(可选)

    1
    2
    3
    4
    5
    6
    # 取消对某些文件的追踪
    touch .gitignore
    # 仓库介绍
    touch README.md
    # 开源协议
    touch LICENSE # 粘贴合适的协议
  2. 以当前目录作为开发环境启动 Julia

    1
    2
    # julia --project=<环境位置>
    julia --project=.

    等价地,可以先启动 Julia ,然后在包管理模式中使用 activate 切换开发环境

    1
    2
    3
    # 先启动 Julia
    ] # 输入 ] 进入包管理模式
    activate . # 启用当前目录作为开发环境

    深度截图_选择区域_20220424102838

  3. 包管理模式下,使用 generate + 模块名 创建模板

    1
    pkg> generate TestPackage

    如下图,操作后 Project.tomlsrc 文件夹已创建
    深度截图_选择区域_20221002193256

    打开文件并查看,Project.toml 已自动生成了 nameuuid 等字段,其中 authors 由当前环境的 Git 信息生成

    1
    2
    3
    4
    name = "TestPackage"
    uuid = "83012822-a8b3-402d-b3e2-a8f809b7e3a3"
    authors = ["rex <1073853456@qq.com>"]
    version = "0.1.0"

    src 代码内容

    1
    2
    3
    module TestPackage
    greet() = print("Hello World!")
    end # module
  4. 我们需要将 TestPackage 文件夹中的文件挪到模块主目录

    1
    2
    mv TestPackage/* ./
    rmdir TestPackage
  5. 包管理模式下,使用 instantiate 命令初始化

    1
    pkg> instantiate

    该命令会根据 Project.toml 文件生成 Manifest.toml 文件;当 Project.toml 文件不存在时,会生成空白的 Project.tomlManifest.toml
    深度截图_选择区域_20220424103956

  6. 提交更改

    1
    2
    git add --all
    git commit -m "initialize commit"

大功告成,一个简单的包已经创建好了!

包管理命令

包管理模式常用命令:

命令 说明
add <模块名> 安装模块;若模块已安装,则根据环境文件执行更新操作
add <链接> 通过链接(地址)安装模块
rm/remove <模块名> 删除模块依赖
instantiate 实例化,也即更新 Project.toml, Manifest.toml 文件
test 执行 test/ 目录下的 runtests.jl
st/status 查看依赖信息
activate <环境目录> 将开发环境切换到指定目录,不加参数则切换到默认环境
generate <模块名称> 生成模板
update 更新环境依赖中的模块
dev <模块目录> 本地开发,添加本地模块作为依赖
build 构建依赖
precompile 环境预编译

简单来说,如果仓库没有 Project.toml 文件,则执行 instatiate 命令初始化。之后在执行 add, rm, update, dev 等操作时,仓库会自动更新 Project.tomlManifest.toml 文件。

注:一些环境错误,比如执行 test 提示的文件错误,可能是 Manifest.toml 的问题,如该文件非必要可将其删除再运行试试

其他知识点:

  1. 模块定义

    1
    2
    3
    4
    module ExamplePackage
    export greet, notdefine
    greet() = print("Hello World!")
    end

    其中 export 导出符号。当使用 using <模块名> 时,这些符号将导入到当前环境。特别注意,export 只是导入符号而不做检查,哪怕符号对应的变量没有定义也能正常进行,且能够触发代码补全功能
    深度截图_选择区域_20220424151131

  2. 导入模块除了 using,也可以用 import,区别参看之前回答的一个帖子

开发相关

Julia 提供了 Revise 包,可以实现模块热更新,即修改模块后无需重新使用 using 重新导入,也会自动更新模块变化。

但需要注意的是,Revise 只影响在它之后导入的模块,因此建议将其添加到 startup.jl,每次启动 Julia 都会先执行这个脚本。

具体添加方式:直接编辑 ~/.julia/config/startup.jl 文件或者使用命令行

1
echo "using Revise" >> ~/.julia/config/startup.jl

其他知识点:

  1. 项目代码通常不止一个文件,当 src 下写了多个文件时,可以用 include 命令将它们导入到主文件中

    1
    2
    3
    4
    5
    ## 主文件内
    module ExamplePackage
    greet() = print("Hello World!")
    include("temp.jl") # 导入文件
    end

    include 命令不仅适用于模块开发,普通场景的代码导入也是有效的

  2. 在模块 module 内,引用内部模块可以略写模块名,比如

    1
    2
    3
    4
    5
    6
    7
    8
    module Outer
    module Inner
    hi() = print("hi")
    end
    # 引用子模块
    using .Inner
    # 等价效果 using Outer.Inner
    end
  3. 变量及所在模块

    • 使用 @which 可以查看变量所在模块
    • 在 REPL 中定义的变量和函数属于全局环境 Main
      深度截图_选择区域_20220424153320
  4. 查看源码技巧:

    • 在 Jupyter 下,使用 @which 还能获取函数源码的 GitHub 链接
    • 使用 @edit func(para..) 可以查看 func 关于该派发的源码
    • @edit 默认使用 vim 作为编辑器,但可以用下边代码指定 vscode
    1
    ENV["EDITOR"] = "code"

    也建议将这段代码写在 startup.jl 中,每次启动 Julia 都会执行该文件

模块开发还有些其他内容,比如 __init__ 函数等,后续接触再进行补充。


以上是模块开发的第一部分知识,如果内容存在纰漏,欢迎在评论区指出~