GF开发人员指南

2021-07-15

---

• 开始之前
• 设置用于构建GF的系统
  • 堆栈
  • 吉特
  • 哈斯克林
• 获取源代码
  • 只读访问：克隆主存储库
  • 贡献您的更改：派生主存储库
• 从源代码编译
  • 主要建议：使用Stack
  • 备选方案：使用Cabal
• 使用C运行时系统支持编译GF
  • 使用其他编程语言的C运行时
  • 使用支持C运行时的GF shell
  • 在C运行时中使用GF服务器模式
• RGL的编制
  • 简单
  • 高级
  • 无Haskell
• 创建二进制分发包
• 运行测试套件

---

开始之前

本指南适用于希望为GF编译器或资源语法库的开发做出贡献的人。如果你是一个GF用户，只想下载并安装GF（例如开发自己的语法）GF下载页面应该足够了。

设置用于构建GF的系统

要从源代码构建GF，您需要在系统上安装一些工具：Haskell构建工具堆栈、版本控制软件吉特和哈斯克林库。

堆栈

主要安装方法是通过堆栈（您也可以使用Cabal，但我们建议初学者使用Stack。）

要安装Stack：

• 在Linux和Mac OS上，请选择其中之一

  $curl-sSLhttps://get.haskellstack.org网址/|小时

  或

  $wget-qO-https://get.haskellstack.org网址/|小时

• 在其他操作系统上，请参阅安装指南.

吉特

要获得GF源代码，您还需要吉特，一个分布式版本控制系统。

• 在Linux上，最好的选择是通过标准软件分发渠道安装工具：

  • 在Ubuntu上：sudo apt-get安装git-all
  • 在Fedora上：sudo dnf安装git-all

• 在其他操作系统上，请参阅https://git-scm.com/book/en/v2/Getting-Started-Installing-git网站用于安装。

哈斯克林

GF使用哈斯克林在GF shell中启用命令行编辑。

• 在Mac OS和Windows上，这应该会自动运行。

• 在Linux上，需要额外的步骤来确保哈斯克林已安装：

  • 在Ubuntu上：sudo apt-get安装libghc-haskeline-dev
  • 在Fedora上：sudo-dnf安装ghc-haskeline级别

获取源代码

一旦你有了所有的工具，你就可以从github:

• https://github.com/语法框架/gf-core对于GF编译器
• https://github.com/语法框架/gf-rgl用于资源语法库

只读访问：克隆主存储库

如果您只想编译和使用GF，您只需克隆存储库，如下所示：

$git克隆https://github.com/Grammatic Framework/gf-core.git（语法框架）$git克隆https://github.com/Grammatic Framework/gf-rgl.git（语法框架）

要获取新更新，请在存储库的本地副本中的任意位置运行以下操作：

$git拉动

贡献您的更改：派生主存储库

如果您希望能够贡献您的更改，您应该创建自己的fork，在那里进行更改，然后向主存储库发送一个pull请求。

1. 创建和克隆分叉-有关如何执行以下操作的说明，请参阅GitHub文档创建自己的分叉存储库的。完成后，将分叉克隆到本地计算机。

   $git克隆https://github.com/<YOUR_USERNAME>/gf-core.git（您的用户名）

2. 更新您的副本-克隆分叉后，需要将主存储库设置为远程存储库：

   $git远程添加上游https://github.com/Grammatic Framework/gf-core.git（语法框架）

   然后，您可以通过运行以下命令来获取最新更新：

   $git拉动上游主服务器

3. 记录本地更改-请参阅Git教程了解如何记录并推送您的更改到你的叉子上。

4. Pull请求-当您想将更改贡献到主gf-core存储库时，创建拉请求从你的叉子里。

如果您也想为RGL贡献资源，请对RGL存储库执行相同的过程。

从源代码编译

现在，您应该已经在自己的计算机上安装了Stack和Haskeline，并克隆了Git存储库，位于名为gf-芯.

主要建议：使用Stack

打开终端，转到顶层目录(gf-芯)，然后键入以下命令。

$stack安装

它将安装GF和所有必要的工具和库来完成这项工作。

备选方案：使用Cabal

如果您喜欢Cabal而不是Stack，也可以使用Cabal安装GF。在这种情况下，您可能需要自己安装一些必备组件。

实际安装过程与Stack类似：打开终端，转到顶部目录(gf-芯)，然后键入以下命令。

$cabal安装

Cabal的旧（可能过时）说明被移至单独的页面.如果你遇到麻烦电缆安装，你可能想看看。

使用C运行时系统支持编译GF

C运行时系统是PGF运行时服务的单独实现。它可以使用概率模型来获得可能的解析，从而处理非常大、模糊的语法。在某些平台上，C运行时系统可能比Haskell运行时系统更易于使用，例如Android和iOS。

要安装C运行时系统，请转到src/运行时/c目录。

• 在Linux和Mac OS上-您应该有autoconf、automake、libtool和make。如果您缺少其中一些，请按照安装文件。

  一旦您有了所需的库，安装C运行时的最简单方法是使用安装.sh脚本。只需键入

  $bash安装.sh

  这将安装编写使用PGF语法的C程序所需的C头文件和库。

• 在其他操作系统上-遵循中的说明安装文件。

根据您想对C运行时执行的操作，可以执行以下一个或多个步骤。

使用其他编程语言的C运行时

• 什么-这是C运行时最常见的用例：使用标准GF可执行文件将GF语法编译为PGF，并使用与C运行时的绑定从另一种编程语言操作PGF。

• 如何-Python、Java和Haskell绑定位于src/runtime/{python、java、haskell-bind}目录。按照安装或自述文件这些目录中的文件。

  还可以使用以下命令从PyPI安装Python库pip安装pgf.

如果你在Mac上，得到一个关于叮当作响版本，你可以试试这些解决方案-但在删除任何现有安装之前，请小心。

使用支持C运行时的GF shell

• 什么-如果您想将GF shell与C运行时功能结合使用，则需要使用特殊标志（重新）编译GF。

  GF外壳可通过以下方式启动gf-c外壳或gf-凝块使用C运行时系统而不是Haskell运行时系统。在这些模式下运行shell时，只有有限的功能可用（使用帮助命令）。

  （重新）使用这些标志编译GF还将为您提供到C运行时的Haskell绑定，如一个名为前列腺素F2，但如果需要Python或Java绑定，则需要上一步.

• 如何-如果使用cabal，请运行以下命令：

  电缆安装-fc-运行时间

  从顶部目录(gf-芯).

  如果使用堆栈，请取消注释堆垛山药文件：

  旗帜：玻璃纤维：c运行时：true类外目录：-/usr/local/lib

  然后运行烟囱安装从顶部目录(gf-芯).

如果您得到“加载共享库时出错“当尝试使用C运行时运行GF时，请记住声明您的LD_LIBRARY_PATH（本地_远程_路径）. 添加export LD_LIBRARY_PATH=“/usr/local/lib”到您的.bashrc或.配置文件。您现在应该可以用C运行时启动GF了。

在C运行时中使用GF服务器模式

• 什么-使用此功能，gf-服务器模式通过调用C运行时系统的新请求进行扩展，例如。c-解析,c线性化和中文翻译.

• 如何-如果使用cabal，请运行以下命令：

  电缆安装-fc-runtime-fserver

  从顶部目录。

  如果使用堆栈，请在堆垛山药文件：

  旗帜：玻璃纤维：c运行时：true服务器：true类外目录：-/usr/local/lib

  然后运行烟囱安装，也来自顶层目录。

RGL的编制

截至2018-07-26，RGL与GF编译器和运行时分开发布。

要获取源代码，请按照前面的说明操作如何使用Git克隆存储库.

克隆RGL后，应该有一个名为绿色荧光灯在您的计算机上。

简单

要安装RGL，可以从中使用以下命令绿色荧光灯存储库：

$make安装

还有生成build,制作副本和使干净这就是你所期望的。

高级

对于高级构建选项，请直接调用Haskell构建脚本：

$runghc Setup.hs。。。

有关更多详细信息，请参阅自述文件.

无Haskell

如果没有安装Haskell，可以使用简单的构建脚本设置.sh（或设置.bat适用于Windows）。

创建二进制分发包

二进制文件是用Github Actions生成的。更多详细信息可在此处查看：

https://github.com/语法框架/gf-core/actions/workflows/build-binary-packages.yml

运行测试套件

GF测试套件使用顶级目录中的以下命令之一运行：

$cabal测试

或

$堆栈测试

GF的测试套件架构非常简单，但仍然非常灵活。GF本身是一个解释器，可以以批处理模式执行命令。这就是组织测试套件所需的一切。测试套件的根是测试套件/目录。它包含子目录，子目录本身包含GF批处理文件（扩展名为.gfs（平方英尺）). 上述命令搜索测试套件/扩展名为的文件的目录.gfs（平方英尺）当它找到一个时，它将由GF解释器执行。脚本的输出存储在扩展名为的文件中.输出并与具有扩展名的相应文件的内容进行比较.黄金，如果有。

每次当您对GF进行一些需要测试的更改时，不要在GF shell中手动编写命令，而是将它们添加到一个.gfs（平方英尺）testsuite子目录中的.gf（平方英尺）文件驻留并运行测试。通过这种方式，您可以稍后使用相同的测试，我们将确保以后不会意外地破坏您的代码。

测试结果-通过：如果带有.输出扩展名与具有扩展名的相应命名文件相同.黄金，该命令将报告测试成功通过，例如。

正在运行1个测试套件。。。测试套件gf-tests:RUNNING。。。测试套件gf-tests:PASS1个测试套件（1个测试用例中的1个）通过。

测试结果-失败：如果文件与.输出扩展名及其与扩展名对应的文件.黄金，测试诊断将显示故障和故障区域。例如

测试套件/编译器/compute/Records.gfs:OK测试套件/编译器/计算/变量.gfs:FAIL测试套件/编译器/params/params.gfs:OK测试套件gf-tests:FAIL0个测试套件（共1个测试用例）通过。

gf-tests.html中提供了失败结果概述，其中显示了4列：

1. 结果-只会显示失败的区域。（注意：gf-tests.html中有3个失败，标记为（预期）。应忽略这些故障。）
2. 输入-这是在.gfs文件中编写的测试
3. 黄金-运行.gfs文件中设置的测试的预期输出。此列引用扩展名为.gold的文件中的内容。
4. Output（输出）—此列是指作为测试输出生成的.out扩展名文件中的内容。修复失败的区域后，重新运行测试命令。重复修复和测试的整个过程，直到测试套件通过，然后再提交包含更改的请求。