GF徽标

GF开发人员指南

2021-07-15



开始之前

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

设置用于构建GF的系统

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

堆栈

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

要安装Stack:

吉特

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

哈斯克林

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

获取源代码

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

只读访问:克隆主存储库

如果您只想编译和使用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目录。

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

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

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

使用支持C运行时的GF shell

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

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

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个)通过。

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

测试套件/编译器/计算/记录.gfs:正常测试套件/编译器/计算/变体.gfs:失败测试套件/编译器/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扩展名文件中的内容。修复失败的区域后,重新运行测试命令。重复修复和测试的整个过程,直到测试套件通过,然后再提交包含更改的请求。