Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Agda-zh/PLFA-zh
《编程语言基础：Agda 描述》，Programming Language Foundations in Agda 中文版
https://github.com/Agda-zh/PLFA-zh
Last synced: 8 days ago
JSON representation
《编程语言基础：Agda 描述》，Programming Language Foundations in Agda 中文版
- Host: GitHub
- URL: https://github.com/Agda-zh/PLFA-zh
- Owner: Agda-zh
- License: cc-by-4.0
- Created: 2019-01-17T06:01:32.000Z (almost 6 years ago)
- Default Branch: dev
- Last Pushed: 2024-10-28T11:14:57.000Z (19 days ago)
- Last Synced: 2024-10-28T13:26:42.360Z (19 days ago)
- Language: Haskell
- Homepage: https://agda-zh.github.io/PLFA-zh/
- Size: 120 MB
- Stars: 207
- Watchers: 9
- Forks: 22
- Open Issues: 26
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
---
title : 使用说明
permalink: /GettingStarted/
translators : ["Rongxiao Fu", "Oling Cat"]
---
[![CI][plfa-zh-badge-status-svg]][plfa-zh-badge-status-url]
[![pre-commit.ci status][zh-pre-commit-status-svg]][zh-pre-commit-status-url]
[![Release Version][plfa-zh-badge-version-svg]][plfa-zh-badge-version-url]
[![agda][agda-badge-version-svg]][agda-badge-version-url]
[![standard-library][agda-stdlib-version-svg]][agda-stdlib-version-url]
## 读者指南 {#getting-started-for-readers}
《编程语言基础：Agda 语言描述》的使用方法与《Programming Language Foundations in Agda》一致。
**本书可访问 [PLFA-zh][plfa-zh] 在线阅读。**
**要参与翻译，请先阅读[翻译规范][trans-spec]。**
你可以[在线阅读][plfa-zh] PLFA，无需安装任何东西。
然而，如果你想要交互式编写代码或完成习题，那么就需要几样东西：
- macOS 上：[XCode 命令行工具](#on-macos-install-the-xcode-command-line-tools)
- [Git](#install-git)
- [GHC and Cabal](#install-ghc-and-cabal)
- [Agda](#install-agda)
- [Agda 标准库](#install-plfa-and-the-agda-standard-library)
- [PLFA](#install-plfa-and-the-agda-standard-library)
PLFA 只针对特定的 Agda 和 标准库版本进行了测试，相应版本已在前面的徽章中指明。
Agda 和标准库变化得十分迅速，而这些改变经常搞坏 PLFA，因此使用旧版或新版通常会出现问题。
Agda 和 Agda 标准库有多个版本。如果你使用了包管理器（如 Homebrew 或者 Debian
apt），Agda 的版本可能不是最新的。除此之外，Agda
仍然在活跃的开发之中，如果你从 GitHub
上安装了开发版本，开发者的新变更也可能让这里的代码出现问题。
因此，使用上述版本的 Agda 和 Agda 标准库很重要。
### macOS 平台：安装 XCode 命令行工具 {#on-macos-install-the-xcode-command-line-tools}
在 macOS 平台，你需要安装 [XCode 命令行工具][xcode]。
在大多数 macOS 系统版本上，你可以用下面的命令安装它们：
```bash
xcode-select --install
```
### 安装 Git {#install-git}
你可以使用下面的命令来检查你是否安装了 Git。
```bash
git --version
```
如果你没有 Git，请参阅 [Git 下载页面][git]。
### 安装 GHC 和 Cabal {#install-ghc-and-cabal}
Agda 是用 Haskell 写成的，所以为了安装它我们需要 _Glorious Haskell Compiler_
和它的包管理器 _Cabal_。PLFA 应该在任何 >=8.10 的 GHC 版本下运行，在 8.10 到 9.8 版本下完成测试。我们建议使用 [ghcup][ghcup] 来安装两者。
在 `ghcup` 安装好之后，输入下列命令：
```bash
ghcup install ghc 9.4.8
ghcup install cabal recommended
ghcup set ghc 9.4.8
ghcup set cabal recommended
```
或使用 `ghcup tui` 来『设置』合适的工具。
### 安装 Agda {#install-agda}
安装 Agda 最简单的方法是通过 Cabal。PLFA 使用 Agda 版本
2.7.0。运行下面的命令：
```bash
cabal update
cabal install Agda-2.7.0
```
这一步会消耗很长时间和很多内存来完成。
如果你遇到了问题，或者想参考替代的方法，可参阅 [Agda 安装指引][agda-readthedocs-installation]。
如果你愿意，你可以[测试 Agda 是否已正确安装][agda-readthedocs-hello-world]。
### 安装 PLFA 和 Agda 标准库 {#install-plfa-and-the-agda-standard-library}
我们建议您使用下面的命令把 PLFA 安装至你的家目录：
```bash
git clone --depth 1 https://github.com/plfa/plfa.github.io plfa
```
PLFA 包括了所需的 Agda 标准库版本，你可以在安装 PLFA 的目录下运行以下命令来下载它。
```bash
git submodule update --init
```
最后，我们需要让 Agda 知道如何找到标准库。
你需要两个配置文件，一个用于指定库的路径，一个用于指定默认载入的库。
在 macOS 和 Unix 上，如果 PLFA
已经安装至 Home 目录，且你没有希望保存的配置文件，运行下面的命令：
```bash
mkdir -p ~/.agda
cp ~/plfa/data/dotagda/* ~/.agda
```
这条命令提供了 Agda 标准库，也让 PLFA 可以当作一个 Agda 库来使用。
否则，你需要手动编辑相关的配置文件。两者都位于 `AGDA_DIR` 目录下。
在 UNIX 和 macOS 平台，`AGDA_DIR` 默认为
`~/.agda`。在 Windows 平台，`AGDA_DIR` 一般默认为 `%AppData%\agda`，而
`%AppData%` 默认为 `C:\Users\USERNAME\AppData\Roaming`。
- 如果 `AGDA_DIR` 文件夹不存在，创建它。
- 在 `AGDA_DIR` 中，创建一个纯文本文件 `libraries`，内容为
`/path/to/standard-library.agda-lib` （即上文中记录的路径）。
这个文件让 Agda 知道有一个名为 `standard-library` 的库可用。
- 在 `AGDA_DIR` 中，创建一个纯文本文件 `defaults`，内容__仅__为 `standard-library` 这一行。
- 如果你想导入书中的模块，那么需要将 PLFA 设置为 Agda 库。假设 `PLFA` 是 PLFA
的根目录，完成此设置需要将 `PLFA/src/plfa.agda-lib` 作为单独的一行添加到
`AGDA_DIR/libraries`，并将 `plfa` 作为单独的一行添加到 `AGDA_DIR/defaults`。
关于放置标准库的更多信息可以参阅 Agda 文档中的[库管理][agda-readthedocs-package-system]。
## 设置 Agda 的编辑器
### Emacs
推荐的 Agda 编辑器是 Emacs。安装 Emacs 可以用下面的方法：
- __UNIX__：包管理器中的 Emacs 应该可以使用（只要它的版本比较新），[GNU
Emacs 下载页面][emacs]也有最近发布版本的链接。
- __MacOS__：推荐的 Emacs 是 [Aquamacs][aquamacs]，但是 GNU Emacs
也可以通过 Homebrew 或者 MacPorts 安装。参阅 [GNU Emacs
下载页面][emacs]中的指示。
- __Windows__：参阅 [GNU Emacs 下载页面][emacs]中的指示。
确保你可以用你安装的版本打开、编辑、保存文件。GNU Emacs 网站上的 [Emacs
向导][emacs-tour]描述了如果打开 Emacs 安装中的教程。
Agda 自带了 Emacs 编辑器支持，如果你安装了 Agda，运行下面的命令来配置 Emacs：
```bash
agda-mode setup
agda-mode compile
```
如果你已经是 Emacs 用户，并有自己的设置，你会发现 `setup` 命令向你的 `.emacs`
文件中追加了配置，来配合你已有的设置。
#### 在 Emacs 中自动加载 `agda-mode`
从版本 2.6.0 开始，Agda 支持 Markdown 风格的文学编程，文件使用 `.lagda.md` 扩展名。
该扩展名的一个问题就是 Emacs 默认会进入 Markdown 编辑模式。
而为了让 `agda-mode` 在你打开 `.agda` 或 `.lagda.md` 文件时自动加载，
请将以下内容放到你的 Emacs 配置文件中：
```elisp
;; auto-load agda-mode for .agda and .lagda.md
(setq auto-mode-alist
(append
'(("\\.agda\\'" . agda2-mode)
("\\.lagda.md\\'" . agda2-mode))
auto-mode-alist))
```
如果你的配置中已有了改变 `auto-mode-alist`
的设置，将上述内容放置在已有的设置__之后__，或者将其与已有设置合并（如果你对
Emacs Lisp 足够了解）。
Emacs 的配置文件通常位于 `~/.emacs` 或 `~/.emacs.d/init.el`，然而
Aquamacs 用户需要将启动设置放到位于 `~/Library/Preferences/Aquamacs Emacs/Preferences`
的 `Preferences.el` 文件中。
对于 Windows 平台，请参阅 [GNU Emacs 文档][emacs-home] 来寻找配置文件的位置。
#### 可选：在 Emacs 中使用 Mononoki 字体
Agda 中的很多重要符号是用 Unicode 来表示的，因此用来显示和编辑 Agda
的字体需要正确地显示这些符号。最重要的是你使用的字体需要有好的 Unicode
字符支持。我们推荐 [Mononoki][font-mononoki]，
其他的备选字体有 [Source Code Pro][font-sourcecodepro]、
[DejaVu Sans Mono][font-dejavusansmono] 和 [FreeMono][font-freemono]。
你可以直接从[此网站][font-mononoki] 下载并安装
Mononoki。对于大多数系统来说，安装字体只是简单的下载 `.otf` 或者 `.ttf` 文件。
如果你的包管理器提供了 Mononoki 的包，那样可能更加简单。
例如，macOS 的 Homebrew 提供了
`font-mononiki` 包；Debian 的 APT 提供了 `fonts-mononoki` 包。
将下面的内容加入 Emacs 配置文件，可以把 Mononoki 设置为 Emacs 的默认字体：
```elisp
;; default to mononoki
(set-face-attribute 'default nil
:family "mononoki"
:height 120
:weight 'normal
:width 'normal)
```
#### 检查 `agda-mode` 是否正确安装
在 Emacs 中打开本书的第一章 (`plfa/src/plfa/part1/Naturals.lagda.md`)，输入
[`C-c C-l`][agda-readthedocs-emacs-notation] 来载入和类型检查这个文件。
#### 在 Emacs 中使用 `agda-mode`
要加载文件并对其执行类型检查，请使用 [`C-c C-l`][agda-readthedocs-emacs-notation]。
Agda 的编辑是通过使用「[洞][agda-readthedocs-holes]」来交互的，它表示程序中尚未填充的片段。
如果用问号作为表达式，并用 `C-c C-l` 加载缓冲区，Agda 会将问号替换为一个「洞」。
当光标在洞中时，你可以做以下这些事情：
- `C-c C-c`: 分项（询问变量名，**c**ase）
- `C-c C-空格`：填洞
- `C-c C-r`：用构造子精化（**r**efine）
- `C-c C-a`：自动填洞（**a**utomatic）
- `C-c C-,`：目标类型和语境
- `C-c C-.`：目标类型，语境，以及推断的类型
更多细节请见 [emacs-mode 文档][agda-readthedocs-emacs-mode]。
如果你想在 Agda 代码的侧边而非底栏查看信息，那么可以这样做：
- 打开 Agda 文件并按 `C-c C-l`；
- 按 `C-x 1` 来仅显示当前 Agda 文件；
- 按 `C-x 3` 来垂直分割窗口；
- 将光标移动到右侧窗口；
- 按 `C-x b` 并输入「Agda information」切换到该缓冲区。
现在，Agda 的错误消息将会在代码右侧显示，而非被挤压在底部的狭小空间里。
#### 在 Emacs 中使用 `agda-mode` 输入 Unicode 字符
当你书写 Agda 代码时，你需要输入标准键盘上没有的字符。Emacs
的「Agda-mode」定义了字符翻译来让这件事更容易：当你输入特定普通字符的序列时，Emacs
会在 Agda 文件中使用对应的特殊字符来替换。
例如，我们可以在之前的 `.agda` 测试文件中加入一条注释。
比如说，我们想要加入下面的注释：
```agda
{- I am excited to type ∀ and → and ≤ and ≡ !! -}
```
前几个字符都是普通字符，我们可以如往常的方式输入它们……
```agda
{- I am excited to type
```
在最后一个空格之后，我们无法在键盘上找到 ∀ 这个键。这个字符的输入序列是四个字符
`\all`，所以我们输入这四个字符，当我们完成时，Emacs 会把它们替换成我们想要的……
```agda
{- I am excited to type ∀
```
我们继续输入其他字符。有时字符会在输入时发生变化，因为一个字符的输入序列是另一个字符输入序列的前缀。
在我们输入箭头时会出现这样的情况，它的输入序列是 `\->`。在输入 `\-`
之后我们会看到……
```agda
{- I am excited to type ∀ and -
```
……因为输入序列 `\-` 对应了一定长度的短横。当我们输入 `>` 时，`` 变成了 `→`！
`≤` 的输入序列是 `\<=`，`≡` 的是 `\==`。
```agda
{- I am excited to type ∀ and → and ≤ and ≡
```
最后几个字符又回归了普通字符……
```agda
{- I am excited to type ∀ and → and ≤ and ≡ !! -}
```
如果你在 Emacs 中输入 Unicode 时遇到了问题，可以在每章的最后找到当前章节中用到的
Unicode 字符。
带有 `agda-mode` 的 Emacs 提供了很多有用的命令，其中有两个对处理 Unicode
字符时特别有用。
支持的字符的完整列表可使用 `agda-input-show-translations` 命令查看：
M-x agda-input-show-translations
`agda-mode` 支持的所有字符都会列出来。
如果你想知道如何在 agda 文件输入一个特定的 Unicode 字符，请将光标移动到该字符上并输入以下命令：
M-x quail-show-key
你会在迷你缓冲区中看到该字符对应的按键序列。
### Spacemacs
[Spacemacs][spacemacs] 是一个「社区引领的 Emacs 版本」，对 Emacs 和 Vim
的编辑方式都有很好的支持。它自带[集成了
`agda-mode`][spacemacs-agda]，所需的只是将 `.spacemacs` 中启用 Agda 支持。
### Visual Studio Code
[Visual Studio Code][vscode] 是一个微软开发的开源代码编辑器。
Visual Studio 市场中有 [Agda 插件][vscode-agda]。
## Getting Started for Contributors
If you plan to build PLFA locally, please refer to [Contributing][plfa-contributing] for additional instructions.
[epub-zh]: https://agda-zh.github.io/PLFA-zh/out/epub/plfa.epub
[plfa-zh]: https://agda-zh.github.io/PLFA-zh/
[plfa-zh-dev]: https://github.com/Agda-zh/PLFA-zh/archive/dev.zip
[trans-spec]: https://github.com/Agda-zh/PLFA-zh/issues/1
[plfa-zh-badge-status-svg]: https://github.com/Agda-zh/PLFA-zh/actions/workflows/ci.yml/badge.svg
[plfa-zh-badge-status-url]: https://github.com/Agda-zh/PLFA-zh/actions/workflows/ci.yml
[plfa-zh-badge-version-svg]: https://img.shields.io/github/v/tag/plfa/plfa.github.io?label=release
[plfa-zh-badge-version-url]: https://github.com/plfa/plfa.github.io/releases/latest
[zh-pre-commit-status-svg]: https://results.pre-commit.ci/badge/github/Agda-zh/PLFA-zh/dev.svg
[zh-pre-commit-status-url]: https://results.pre-commit.ci/latest/github/Agda-zh/PLFA-zh/dev
[agda-zh]: https://agda-zh.rtfd.io/zh_CN/latest/getting-started/installation.html
[FiraCode]: https://github.com/tonsky/FiraCode
[plfa-badge-status-svg]: https://github.com/plfa/plfa.github.io/actions/workflows/ci.yml/badge.svg
[plfa-badge-status-url]: https://github.com/plfa/plfa.github.io/actions/workflows/ci.yml
[pre-commit-status-svg]: https://results.pre-commit.ci/badge/github/plfa/plfa.github.io/dev.svg
[pre-commit-status-url]: https://results.pre-commit.ci/latest/github/plfa/plfa.github.io/dev
[plfa-badge-version-svg]: https://img.shields.io/github/v/tag/plfa/plfa.github.io?label=release
[plfa-badge-version-url]: https://github.com/plfa/plfa.github.io/releases/latest
[agda-badge-version-svg]: https://img.shields.io/badge/agda-v2.7.0-blue.svg
[agda-badge-version-url]: https://github.com/agda/agda/releases/tag/v2.7.0.
[agda-stdlib-version-svg]: https://img.shields.io/badge/agda--stdlib-v2.1-blue.svg
[agda-stdlib-version-url]: https://github.com/agda/agda-stdlib/releases/tag/v2.1
[plfa]: https://plfa.inf.ed.ac.uk
[plfa-epub]: https://plfa.github.io/plfa.epub
[plfa-contributing]: https://plfa.github.io/Contributing/
[ghcup]: https://www.haskell.org/ghcup/
[git]: https://git-scm.com/downloads
[xcode]: https://developer.apple.com/xcode/
[agda-readthedocs-installation]: https://agda.readthedocs.io/en/v2.7.0/getting-started/installation.html
[agda-readthedocs-hello-world]: https://agda.readthedocs.io/en/v2.7.0/getting-started/hello-world.html
[agda-readthedocs-holes]: https://agda.readthedocs.io/en/v2.7.0/getting-started/a-taste-of-agda.html#preliminaries
[agda-readthedocs-emacs-mode]: https://agda.readthedocs.io/en/v2.7.0/tools/emacs-mode.html
[agda-readthedocs-emacs-notation]: https://agda.readthedocs.io/en/v2.7.0/tools/emacs-mode.html#notation-for-key-combinations
[agda-readthedocs-package-system]: https://agda.readthedocs.io/en/v2.7.0/tools/package-system.html#example-using-the-standard-library
[emacs]: https://www.gnu.org/software/emacs/download.html
[emacs-tour]: https://www.gnu.org/software/emacs/tour/
[emacs-home]: https://www.gnu.org/software/emacs/manual/html_node/efaq-w32/Location-of-init-file.html
[aquamacs]: https://aquamacs.org/
[spacemacs]: https://www.spacemacs.org/
[spacemacs-agda]: https://develop.spacemacs.org/layers/+lang/agda/README.html
[vscode]: https://code.visualstudio.com/
[vscode-agda]: https://marketplace.visualstudio.com/items?itemName=banacorn.agda-mode
[font-sourcecodepro]: https://github.com/adobe-fonts/source-code-pro
[font-dejavusansmono]: https://dejavu-fonts.github.io/
[font-freemono]: https://www.gnu.org/software/freefont/
[font-mononoki]: https://madmalik.github.io/mononoki/
[font-mononoki-debian]: https://packages.debian.org/sid/fonts/fonts-mononoki