标签 Compiler 下的文章

通过实例理解Go静态单赋值(SSA)

本文永久链接 – https://tonybai.com/2022/10/21/understand-go-ssa-by-example

在上一篇文章《通过实例理解Go内联优化》中,我们探讨了Go编译器在编译中端进行的内联优化。内联优化基于IR中间表示进行,不过Go编译过程不止有一种IR表示,这点和龙书《编译原理(第二版)》的在第六章“中间代码生成”一开始处的讲解是一致的,即在将给定源语言的一个程序翻译成特定的目标机器代码的过程中,一个编译器可能构造出一系列中间表示(IR),如下图:

高层中间表示更接近于源语言,而低层的中间表示则更接近于目标机器。在Go编译过程中,如果说内联优化使用的IR是高层中间表示,那么低层中间表示非支持静态单赋值(SSA)的中间代码形式莫属。

在这一篇中,我们将沿着Go编译器的后端优化之路继续走下去,我们来认识一下静态单赋值(SSA)

1. 静态单赋值(SSA)的历史

静态单赋值(Static Single Assignment,SSA),也有称为Single Static Assignment的,是一种中间代码的表示形式(IR),或者说是某种中间代码所具备的属性,它是由IBM的三位研究员:Barry K. Rosen、Mark N. Wegman和F. Kenneth Zadeck于1988年提出的。

具有SSA属性的IR都具有这样的特征:

  • 每个变量在使用前都需要被定义
  • 每个变量被精确地赋值一次(使得一个变量的值与它在程序中的位置无关)

下面是一个简单的例子(伪代码):

y = 1
y = 2
x = y

转换为SSA形式为:

y1 = 1
y2 = 2
x1 = y2

我们看到由于SSA要求每个变量只能赋值一次,因此在转换为SSA后,变量y用y1和y2来表示,后面的序号越大,表明y的版本越新。从这一段三行的代码我们也可以看到,在SSA层面,y1 = 1这行代码就是一行死代码(dead code),即对结果不会产生影响的代码,可以在中间代码优化时被移除掉。

1991年,同样来自IBM研究院的Ron Cytron和Jeanne Ferrante以及前面的三位研究员又一起给出了构建SSA的快速算法,这进一步推动了SSA在编译器领域的快速应用。

SSA的提出以及后续的流行正是因为SSA形式中间代码具有很好的优化空间,基于SSA可以开启一些新的编译器优化算法或增强现有的优化算法,因此自SSA提出后,各种主流语言编译器后端均逐渐开始支持SSA,包括GCC、llvm、hotspot JVM、v8 js等。SSA也成为了一种IR表示的事实标准。

那么Go语言是何时开始与SSA结缘的呢?我们继续往下看。

2. Go与SSA

相对于GCC、LLVM,Go编译器还相对年轻,因此SSA加入Go的时间还不算太长。

Go SSA的工作始于Go 1.5版本实现自举之前,2015年2月初,负责编译器后端的Go团队核心成员的Keith Randall博士就在golang-dev google group上提出要让Go支持SSA的工作计划:

“我想从目前基于语法树的IR转换到更现代的基于SSA的IR。有了SSA IR,我们可以实现很多在当前编译器中难以做到的优化” - Keith Randall

同期,Keith Randall博士还编写了“New SSA Backend for the Go Compiler”文档,具体介绍了Go要支持SSA的理由以及分几步走的实现方案。

在为什么选择自己实现SSA IR,而不是转换为当时现成的诸如gcc, llvm等支持的IR形式并利用成熟后端进行中间代码优化这个问题上,Keith Randall博士给出了三点理由:

  • 从Go编译速度考虑:Go团队和社区对编译速度有着格外的青睐,Randall的目标是设计一个线性时间的SSA算法,实现快速SSA优化,但gcc, llmv等IR显然没有在速度方面给予额外的考虑;

  • 从功能完整性上考虑:Go运行时需要精确的栈帧地图(the map of stack frame),用来支持GC和栈拷贝,这些在gcc, llvm中都不会提供;

  • 从Go核心开发者的编译器使用体验方面考虑:如果使用llvm、gcc等ir,显然Go核心开发人员在编译go的时候还需要依赖llvm或gcc,这种额外的依赖对他们来说很难说是体验友好的。

2016年3月1日,在Go 1.7版本的master分支提交权限刚刚打开之后,Keith Randall就将支持ssa的dev.ssa分支合并到Go项目主线中了。

Go 1.7版本中,Go正式支持SSA,不过由于时间有限,Go 1.7 SSA仅支持针对amd64架构的优化。即便如此,Go支持SSA后,Keith Randall的benchmark显示性能提升12%,代码段缩小13%:


图:go 1.7 benchmark(图来自keith博士的slide)

Go 1.7正式发布时,其发布文档称Go程序的性能因对SSA的支持而提升5%-35%以上。由此看,Go SSA的实现达到了Keith Randall博士的预期目标,也为Go编译器后续的持续优化奠定了基础。

在2017年2月发布的Go 1.8版本中,Go SSA的支持范围扩展到其他所有Go支持的cpu架构,包括arm和arm64、mips和mips64、ppc64等。

了解了Go SSA的演进后,我们再来简单说说Go编译器中SSA的实现。

3. 转换为SSA

我们先来看看转换为SSA以及SSA优化在编译过程中所处的位置:


图:Go SSA所处的环节(图来自keith博士的slide)

上图是keith博士在2017年gophercon大会上slide中的一幅图,这幅图中明确了生成SSA形式以及SSA优化所处的环节。不过较新的Go版本中,convert to SSA之前也有一种不同于最初的抽象语法树的ir(比如:Go 1.19),SSA是由此种ir转换过来的。

从代码上来看,ir到SSA形式的转换发生在下面环节(Go 1.19版本代码,其他版本可能代码位置和内容均由不同):

// $GOROOT/src/cmd/compile/internal/gc/main.go
func Main(archInit func(*ssagen.ArchInfo)) {
    base.Timer.Start("fe", "init")

    defer handlePanic()

    archInit(&ssagen.Arch)
    ... ...

    // Compile top level functions.
    // Don't use range--walk can add functions to Target.Decls.
    base.Timer.Start("be", "compilefuncs")
    fcount := int64(0)
    for i := 0; i < len(typecheck.Target.Decls); i++ {
        if fn, ok := typecheck.Target.Decls[i].(*ir.Func); ok {
            // Don't try compiling dead hidden closure.
            if fn.IsDeadcodeClosure() {
                continue
            }
            enqueueFunc(fn)
            fcount++
        }
    }
    base.Timer.AddEvent(fcount, "funcs")

    compileFunctions()

    ... ...
}

在Main中,我们看到代码会将所有Target.Decls(函数)通过enqueueFunc入队列(compilequeue),然后调用compileFunctions来实现各个函数从AST ir到SSA形式的转换,compileFunctions在compile.go中,其实现如下:

// $GOROOT/src/cmd/compile/internal/gc/compile.go
func compileFunctions() {
    if len(compilequeue) == 0 {
        return
    }

    ... ...
    // By default, we perform work right away on the current goroutine
    // as the solo worker.
    queue := func(work func(int)) {
        work(0)
    }
    ... ...

    var compile func([]*ir.Func)
    compile = func(fns []*ir.Func) {
        wg.Add(len(fns))
        for _, fn := range fns {
            fn := fn
            queue(func(worker int) {
                ssagen.Compile(fn, worker)
                compile(fn.Closures)
                wg.Done()
            })
        }
    }
    types.CalcSizeDisabled = true // not safe to calculate sizes concurrently
    base.Ctxt.InParallel = true

    compile(compilequeue)
    ... ...
}

在compileFunctions中我们看到,编译器从compilequeue取出AST IR形式的函数,并调用ssagen.Compile将其编译为SSA形式。下面是ssagen.Compile的代码:

// $GOROOT/src/cmd/compile/internal/ssagen/pgen.go

// Compile builds an SSA backend function,
// uses it to generate a plist,
// and flushes that plist to machine code.
// worker indicates which of the backend workers is doing the processing.
func Compile(fn *ir.Func, worker int) {
    f := buildssa(fn, worker)
    // Note: check arg size to fix issue 25507.
    if f.Frontend().(*ssafn).stksize >= maxStackSize || f.OwnAux.ArgWidth() >= maxStackSize {
        largeStackFramesMu.Lock()
        largeStackFrames = append(largeStackFrames, largeStack{locals: f.Frontend().(*ssafn).stksize, args: f.OwnAux.ArgWidth(), pos: fn.Pos()})
        largeStackFramesMu.Unlock()
        return
    }
    pp := objw.NewProgs(fn, worker)
    defer pp.Free()
    genssa(f, pp)
    // Check frame size again.
    // The check above included only the space needed for local variables.
    // After genssa, the space needed includes local variables and the callee arg region.
    // We must do this check prior to calling pp.Flush.
    // If there are any oversized stack frames,
    // the assembler may emit inscrutable complaints about invalid instructions.
    if pp.Text.To.Offset >= maxStackSize {
        largeStackFramesMu.Lock()
        locals := f.Frontend().(*ssafn).stksize
        largeStackFrames = append(largeStackFrames, largeStack{locals: locals, args: f.OwnAux.ArgWidth(), callee: pp.Text.To.Offset - locals, pos: fn.Pos()})
        largeStackFramesMu.Unlock()
        return
    }

    pp.Flush() // assemble, fill in boilerplate, etc.
    // fieldtrack must be called after pp.Flush. See issue 20014.
    fieldtrack(pp.Text.From.Sym, fn.FieldTrack)
}

这里贴出了Compile的完整实现,Compile函数中真正负责生成具有SSA属性的中间代码的是buildssa函数,看了一下buildssa函数有近300行代码,有点复杂,这里挑挑拣拣,把主要的调用摘录出来:

// $GOROOT/src/cmd/compile/internal/ssagen/ssa.go

// buildssa builds an SSA function for fn.
// worker indicates which of the backend workers is doing the processing.
func buildssa(fn *ir.Func, worker int) *ssa.Func {
    name := ir.FuncName(fn)
    ... ...

    // Convert the AST-based IR to the SSA-based IR
    s.stmtList(fn.Enter)
    s.zeroResults()
    s.paramsToHeap()
    s.stmtList(fn.Body)

    // fallthrough to exit
    if s.curBlock != nil {
        s.pushLine(fn.Endlineno)
        s.exit()
        s.popLine()
    }
    ... ...

    // Main call to ssa package to compile function
    ssa.Compile(s.f)
    ... ...
}

buildssa中的ssa.Compile咱们后续再看,那个涉及到SSA的多轮(pass)优化,我们看一下从基于AST形式的IR到基于SSA形式的IR的转换,无论是fn.Enter还是fn.Body,本质都是一组ir Node,stmtList将这些node逐个转换为SSA形式。Go提供了可视化的ssa dump工具,我们可以更直观的来看一下。

Go语言隶属于命令式编程语言(imperative programming language),这类编程范式有三大典型控制结构:顺序结构、选择结构和循环结构,我们先来看看一个最简单的顺序结构是如何翻译为SSA的:

// github.com/bigwhite/experiments/tree/master/ssa-examples/sequential.go

package main

func sum(a, b, c int) int {
    d := a + b
    e := d + c
    return e
}

func main() {
    println(sum(1, 2, 3))
}

我们通过下面命令来生成函数sum的SSA转换过程:

$GOSSAFUNC=sum go build sequential.go
dumped SSA to ./ssa.html
$mv ssa.html ssa-sequential.html
$open ./ssa-sequential.html

上面的open命令会在本地打开浏览器并显示ssa-sequential.html页面:

上图中,最左侧是源码(源码显示两次,感觉是bug),中间的是AST形式的IR,最右侧的框框中就是Go编译器生成的第一版SSA,为了更好说明,我们将其贴到下面来:

// github.com/bigwhite/experiments/tree/master/ssa-examples/ssa-sequential.html

b1:-
  v1 (?) = InitMem <mem>
  v2 (?) = SP <uintptr>
  v3 (?) = SB <uintptr>
  v4 (?) = LocalAddr <*int> {a} v2 v1
  v5 (?) = LocalAddr <*int> {b} v2 v1
  v6 (?) = LocalAddr <*int> {c} v2 v1
  v7 (?) = LocalAddr <*int> {~r0} v2 v1
  v8 (3) = Arg <int> {a} (a[int])
  v9 (3) = Arg <int> {b} (b[int])
  v10 (3) = Arg <int> {c} (c[int])
  v11 (?) = Const64 <int> [0]
  v12 (+4) = Add64 <int> v8 v9 (d[int])
  v13 (+5) = Add64 <int> v12 v10 (e[int])
  v14 (+6) = MakeResult <int,mem> v13 v1
Ret v14 (+6)

name a[int]: v8
name b[int]: v9
name c[int]: v10
name d[int]: v12
name e[int]: v13

从结构上来看,SSA分为两部分,一部分是由b1、Ret组成的blocks,另一部分则是命名变量与SSA value的对应关系。

在SSA中,一个block代表了一个函数控制流图(control flow graph)中的基本代码块(basic block),从代码注释中可以看到SSA有四种block类型:Plain,If、Exit和Defer:

// $GOROOT/src/cmd/compile/internal/ssa/block.go

// BlockKind is the kind of SSA block.
//
//    kind          controls        successors
//  ------------------------------------------
//    Exit      [return mem]                []
//   Plain                []            [next]
//      If   [boolean Value]      [then, else]
//   Defer             [mem]  [nopanic, panic]  (control opcode should be OpStaticCall to runtime.deferproc)
type BlockKind int16

但实际的BlockKind已经与注释不一致了,opGen.go是一个自动生成的文件,其中的BlockKind类型的常量值有数十个,即便滤掉CPU架构相关的常量,剩下的还有8个(从BlockPlain到BlockFirst):

// $GOROOT/src/cmd/compile/internal/ssa/opGen.go

const (
    BlockInvalid BlockKind = iota
    ... ...

    BlockPlain
    BlockIf
    BlockDefer
    BlockRet
    BlockRetJmp
    BlockExit
    BlockJumpTable
    BlockFirst
)

上面的sum函数的SSA代码例子中,b1应该就是Plain类型的,Ret显然是BlockRet类型。

Plain类型的Block中是一组values,value是SSA的基本构成要素。根据SSA的定义,一个value只能被精确地定义一次,但是它可以被使用任意多次。如示例,一个value主要包括一个唯一的标识符,一个操作符,一个类型和一些参数,下面的Value类型的LongString和LongHTML方法返回的字符串更能说明Value的格式。尤其是LongHTML方法就是输出ssa html中内容的方法:

// $GOROOT/src/cmd/compile/internal/ssa/value.go

// long form print.  v# = opcode <type> [aux] args [: reg] (names)
func (v *Value) LongString() string {
    ... ...
}

// $GOROOT/src/cmd/compile/internal/ssa/html.go
func (v *Value) LongHTML() string {
    // TODO: Any intra-value formatting?
    // I'm wary of adding too much visual noise,
    // but a little bit might be valuable.
    // We already have visual noise in the form of punctuation
    // maybe we could replace some of that with formatting.
    s := fmt.Sprintf("<span class=\"%s ssa-long-value\">", v.String())

    linenumber := "<span class=\"no-line-number\">(?)</span>"
    if v.Pos.IsKnown() {
        linenumber = fmt.Sprintf("<span class=\"l%v line-number\">(%s)</span>", v.Pos.LineNumber(), v.Pos.LineNumberHTML())
    }

    s += fmt.Sprintf("%s %s = %s", v.HTML(), linenumber, v.Op.String())

    s += " &lt;" + html.EscapeString(v.Type.String()) + "&gt;"
    s += html.EscapeString(v.auxString())
    for _, a := range v.Args {
        s += fmt.Sprintf(" %s", a.HTML())
    }
    r := v.Block.Func.RegAlloc
    if int(v.ID) < len(r) && r[v.ID] != nil {
        s += " : " + html.EscapeString(r[v.ID].String())
    }
    var names []string
    for name, values := range v.Block.Func.NamedValues {
        for _, value := range values {
            if value == v {
                names = append(names, name.String())
                break // drop duplicates.
            }
        }
    }
    if len(names) != 0 {
        s += " (" + strings.Join(names, ", ") + ")"
    }

    s += "</span>"
    return s
}

以例子中的v12这一个value为例:

  v12 (+4) = Add64 <int> v8 v9 (d[int])
  • v12是该value的唯一标识符,其中的12为ID,ID是从1开始的整数;
  • (+4)是对应的源码的行号;
  • Add64是操作符;
  • 是value的类型(v.Type());
  • v8, v9则是Add64操作符的参数;
  • (d[int])是v12对应的LocalSlot,LocalSlot代表栈帧上的一个位置(location),用来识别和存储输出参数、输出参数或其他变量node。

ssa dump输出的另一部分则是命名变量与SSA value的对应关系,其格式也是:name LocalSlot: value:

name a[int]: v8
name b[int]: v9
name c[int]: v10
name d[int]: v12
name e[int]: v13

输出上述第二部分的代码如下:

// $GOROOT/src/cmd/compile/internal/ssa/print.go
func (p stringFuncPrinter) named(n LocalSlot, vals []*Value) {
    fmt.Fprintf(p.w, "name %s: %v\n", n, vals)
}

顺序结构的代码执行流是从上到下的,每个block后面仅有一个后继block,这样的SSA转换较为好理解。

下面我们再来看看一个选择控制结构 – if控制语句的ssa,下面是我们的示例Go源码:

// github.com/bigwhite/experiments/tree/master/ssa-examples/selection_if.go

package main

func foo(b bool) int {
    if b {
        return 2
    }
    return 3
}

func main() {
    println(foo(true))
}

我们通过下面命令输出函数foo的SSA中间代码:

$GOSSAFUNC=foo go build selection_if.go
dumped SSA to ./ssa.html
$mv ssa.html ssa-selection-if.html
$open ./ssa-selection-if.html

open命令启动浏览器显示foo函数的SSA形式:

有了上面关Go SSA格式的基础,这段SSA代码分析起来就容易一些了。

这段SSA中有多个block,包括plain block、if block、ret block等。我们重点关注SSA对if语句的处理。

经典SSA转换理论中,SSA将if分支转换为带有Φ函数的SSA代码(如下图):


图:if语句的SSA转换(图来自keith博士的slide)

Φ函数(希腊字母fài)是代码中的一个merge point,它可以将其前置的n个block的执行路径汇聚在一起。不过它仅用于代码分析使用,最终生成的代码中并不会有Φ函数的存在。关于在何处插入Φ函数等算法太理论了,这里就不展开了。

我们看看现实中go针对if语句的处理:

b1:
  v1 (?) = InitMem <mem>
  v2 (?) = SP <uintptr>
  v3 (?) = SB <uintptr>
  v4 (?) = LocalAddr <*bool> {b} v2 v1
  v5 (?) = LocalAddr <*int> {~r0} v2 v1
  v6 (3) = Arg <bool> {b} (b[bool])
  v7 (?) = Const64 <int> [0]
  v8 (?) = Const64 <int> [2]
  v11 (?) = Const64 <int> [3]
If v6 → b3 b2 (4)

b2: ← b1
  v13 (7) = Copy <mem> v1
  v12 (7) = MakeResult <int,mem> v11 v13
Ret v12 (+7)

b3: ← b1
  v10 (5) = Copy <mem> v1
  v9 (5) = MakeResult <int,mem> v8 v10
Ret v9 (+5)

name b[bool]: v6

这里关键是if block,if判断v6即变量b的值,如果为true,代码执行就流向block b3,否则流向block b2。

下面的b2、b3 block也都包含了前置block的属性,以b2为例,对于来自b1 block的流,执行对应block的代码。基于switch的选择语句更为复杂,有兴趣的朋友可以自己看一下ssa-selection-switch.html。

我们最后看一下循环结构,下面是Go代码:

// github.com/bigwhite/experiments/tree/master/ssa-examples/for_loop.go
package main

func sumN(n int) int {
    var r int
    for i := 1; i <= n; i++ {
        r = r + i
    }
    return r
}

func main() {
    println(sumN(10))
}

其生成的SSA如下图:

我们看到循环结构的ssa block更多,流向更为复杂,如果将其转换为一张图的话,那就应该是这样的:

我们看到:无论是选择结构还是循环结构,SSA实质上构建了一个函数的控制流图(control flow graph),图中每个节点就是一个block,函数的执行控制流在各个block间转移。而后续基于SSA的优化就是基于block中value的仅赋值一次的特性以及block的控制流图进行的

接下来,我们简单看看目前Go基于SSA IR都做了哪些优化。

4. 基于SSA的多轮(pass)优化

buildssa函数中ssa.Compile调用执行了基于SSA IR的多轮(passes)优化:

// $GOROOT/src/cmd/compile/internal/ssa/compile.go

func Compile(f *Func) {
    ... ...
    for _, p := range passes {
        ... ...
        tStart := time.Now()
        p.fn(f)
        tEnd := time.Now()
        ... ...
    }
}

我们看到,针对某个函数,Compile函数对其安装预置的passes进行多轮优化,都有哪些pass呢?我们来看看:

// $GOROOT/src/cmd/compile/internal/ssa/compile.go

// list of passes for the compiler
var passes = [...]pass{
    {name: "number lines", fn-3693: numberLines, required: true},
    {name: "early phielim", fn-3693: phielim},
    {name: "early copyelim", fn-3693: copyelim},
    {name: "early deadcode", fn-3693: deadcode}, // remove generated dead code to avoid doing pointless work during opt
    {name: "short circuit", fn-3693: shortcircuit},
    {name: "decompose user", fn-3693: decomposeUser, required: true},
    {name: "pre-opt deadcode", fn-3693: deadcode},
    ... ...
    {name: "regalloc", fn-3693: regalloc, required: true},   // allocate int & float registers + stack slots
    {name: "loop rotate", fn-3693: loopRotate},
    {name: "stackframe", fn-3693: stackframe, required: true},
    {name: "trim", fn-3693: trim}, // remove empty blocks
}

粗略数了一下,这里约有50个pass(其中包含多轮的deadcode清理),每个pass执行的代码都位于$GOROOT/src/cmd/compile/internal/ssa目录下,我们也可以通过dump出的html查看每一pass后得到的SSA结果,以ssa-sequential.html为例,其多轮优化的示意图如下:

点击浏览器页面上的黑体字优化标题(比如:lowered deadcode for cse),这一步产生的SSA代码都会显示出来,最后一个框框中是基于SSA生成目标架构的汇编代码。

每一个pass都有其独特性,比如cse,代表Common Subexpression Elimination(共同子表达式删除) ,下面是一个cse优化的例子:

y = x + 5
...
z = x + 5

cse优化后(前提中间过程中x值没变过):

y = x + 5
...
z = y

在这个示例中,经过一轮cse,Go便可以节省下一次没必要的加法运算(z = x + 5)。别看一次加法运算不起眼,积累多了也是不小的性能提升,

如果你对某一pass的优化动作感兴趣,可以对照$GOROOT/src/cmd/compile/internal/ssa目录下的代码与浏览器中生成的SSA来对其进行深入研究。

5. 小结

编译器后端的逻辑总是很难理解的,本文对Go编译器与SSA的渊源、Go编译器中驱动SSA转换和优化的环节以及Go生成的SSA的形式与过程做了介绍,算是对SSA入了个门。但要想真正搞懂SSA转换以及基于SSA的优化步骤的细节,认真阅读SSA相关的paper和资料(见参考资料)以及相关code是不可或缺的。

本文涉及的代码在这里可以下载。

6. 参考资料

  • 《编译原理(第二版)》- https://book.douban.com/subject/3296317/
  • SSA: Static Single-Assignment Form – https://www.slideserve.com/heidi-farmer/ssa-static-single-assignment-form
  • 《Static Single Assignment Book》 – https://pfalcon.github.io/ssabook/latest/book-full.pdf
  • Static single-assignment form – https://en.wikipedia.org/wiki/Static_single_assignment_form
  • GopherCon 2017: Keith Randall – Generating Better Machine Code with SSA – https://about.sourcegraph.com/blog/go/generating-better-machine-code-with-ssa
  • Generating Better Machine Code with SSA(slide) – https://raw.githubusercontent.com/gophercon/2017-talks/master/KeithRandall-GeneratingBetterMachineCodeWithSSA/GeneratingBetterMachineCodeWithSSA.pdf
  • New SSA Backend for the Go Compiler – https://docs.google.com/document/d/1szwabPJJc4J-igUZU4ZKprOrNRNJug2JPD8OYi3i1K0/edit

“Gopher部落”知识星球旨在打造一个精品Go学习和进阶社群!高品质首发Go技术文章,“三天”首发阅读权,每年两期Go语言发展现状分析,每天提前1小时阅读到新鲜的Gopher日报,网课、技术专栏、图书内容前瞻,六小时内必答保证等满足你关于Go语言生态的所有需求!2022年,Gopher部落全面改版,将持续分享Go语言与Go应用领域的知识、技巧与实践,并增加诸多互动形式。欢迎大家加入!

img{512x368}
img{512x368}

img{512x368}
img{512x368}

Gopher Daily(Gopher每日新闻)归档仓库 – https://github.com/bigwhite/gopherdaily

我的联系方式:

  • 微博:https://weibo.com/bigwhite20xx
  • 博客:tonybai.com
  • github: https://github.com/bigwhite

商务合作方式:撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

让reviewdog支持gitlab-push-commit,守住代码质量下限

本文永久链接 – https://tonybai.com/2022/09/08/make-reviewdog-support-gitlab-push-commit-to-preserve-the-code-quality-floor

一. 代码质量保证的手段

从世界上首款计算机高级程序设计语言Fortran自上世纪50年代诞生以来,编程这个行当已经走过了近70年。虽然年头已不少,但不可否认的一点是:软件生产依然无法像硬件那样标准化,同一个小功能,N个程序员的有N种实现方法

那么如何保证生产出的软件的质量符合我们的要求呢?不同领域的程序员都在进行着努力,比如:做编译器的让编译器更加严格,努力将内存安全问题彻底消除(如Rust);做工具链的为程序员提供了内置于语言的各种单测、集成测试、接口测试、fuzzing test等工具(如Go工具链),让程序员可以更容易地对自己所写的代码进行全方位的测试,以期找出更多的代码中的潜在问题…

当然,还有一种主观的代码质量保证方法目前依旧是主流,它就是是同行的代码评审(code review, cr)

代码评审的方法主要有两种,一种是大家坐到一个会议室中,对某个人的某段代码“发表大论”;另外一种则是利用像gerrit这样的工具,在线对其他人的某次提交的代码或某PR的代码进行“评头论足”。

不过无论哪种,最初的时候大家都会细无巨细地从语法层面看到代码结构设计,再到业务逻辑层面,但这样做的弊端也是很显而易见,那就是效率低下,不聚焦(focus)

于是人们想到了:能否利用工具来尽可能地发现语法层面的问题,这样代码评审时,人类专家便可以聚焦代码结构设计与业务逻辑层面的问题,分工明确后,效率自然提升(如下图):

注:目前绝大多数工具链仅能自动帮助程序员解决语法层面的问题。将来,随着工具的日益强大,工具可以不断升级关注层次,逐渐进化到具备发现代码结构设计问题,甚至可以发现业务层面逻辑问题的能力。

于是就有了reviewdog这样的可以调用各种linter工具对代码进行自动扫描并将问题以comment的形式自动提交的代码仓库的工具。

到这里很多朋友会问,即便让工具来关注语法层面的问题,为何要用reviewdog这样的工具,git的pre-commit hook、git server hooks、利用Make等工具做开发阶段检查等手段也能检查代码中的语法问题,它们不再香了吗?

下面简单看看这些方法的“问题”(我们假设大家都已经在使用git作为代码版本管理工具):

  • git pre-commit-hook

git pre-commit hook是一个客户端的git hook,它是放在开发人员本地代码copy中的.git/hooks目录下的钩子,当开发人员在本地执行git commit时会被唤起执行。pre-commot hook的问题就在于我们没法在中心代码仓库对pre-commit hook的脚本内容做统一管理和维护。这个更适合开发人员根据自己的喜好、代码素养在自己的开发环境下部署。

此外,有些代码并不一定是在开发者自己的开发机上提交的,换环境后,pre-commit hook就不在生效。

  • 利用Make等工具做本地检查

利用make工具,我们可以在本地build代码之前对代码做lint等各种静态检查,但和pre-commit-hook一样,虽然Makefile可以提交代码仓库,但真正用于检查代码的工具依旧是在开发人员本地,难于对工具版本,设定的检查规则进行统一管理维护,可能导致不同开发人员环境有不一致的情况。另外同样的情况,有些代码并不一定是在开发者自己的开发机上提交的,换环境后,Make工具依赖的代码检查工具可能并不存在,检查环节就无法有效实施。

  • git server hooks

git支持server hooksgitlab自12.8版本也开始支持server hooks(替换之前的custom hooks)。

Git server支持以下钩子:

  • pre-receive
  • post-receive
  • update

我倒是没有深研究过这些server hooks是否能满足我们的功能要求,但就git server hooks的部署特点就决定了,它不适合,因为它要在gitlab的server上执行,这就意味着我们需要的所有静态代码检查工具都要部署和配置在与gitlab server同一个环境中,这耦合性太强,根本不便于我们对这些静态代码检查工具的管理与日常维护。

而像reviewdog这样的工具将与ci工具(比如gitlab-ci)集成,运行在slave/worker/runner的机器上,而这些机器上的环境便很容易统一的定制与管理。

好了,下面进入reviewdog时间!

注:我们以代码仓库为gitlab为例,我曾做过小调查,目前企业内部基本都在使用gitlab搭建私有git仓库,除了那些自实现code仓库平台的大厂。

二. reviewdog是什么

reviewdog是一个什么样的工具呢?我们来看看下面这幅示意图:

我们看到,这是一幅基于gitlab的ci执行流程图,在这个流程中,reviewdog运行在gitlab-runner节点,也就是负责真正执行ci job的节点上。每当开发人员执行一次git push,将commit同步到代码仓库,一次ci job将被触发,在承载该ci job的gitlab-runner节点上,reviewdog被唤起,它做了三件事:

  • 调用静态代码检查工具对最新pull下来的代码进行检查;
  • 将代码检查结果(第几行有问题)与commit diff的结果进行比对,得到交集(即commit diff中变更(add和update)的代码行与代码检查结果的行一致的,放入交集中);
  • 将交集中代码检查结果信息以gitlab commit comment的形式post到gitlab仓库中

这样开发人员就可以通过commit页面看到这些comments,并应对这些comment,必要情况下,会修复这些问题。

我们看到reviewdog和其他工具相比,最大的不同就是可以找出commit diff与lint结果中的交集,并与代码仓库交互,将这些交集中的结果以comments的形式放入commit页面,就像同行代码评审时,同行直接在你的commit页面添加comment一样

然而当前版本的reviewdog还不支持直接在gitlab-push-commit上做检查与提交comment,可能是这样的场景较为少见,因为目前开源项目更多采用基于pr(pull request)的工作流,所以reviewdog内置了诸如github-pr-check、github-pr-review、gitlab-mr-commit等工作流的代码review。而像我们使用的基于gitlab-push-commit可能并不多见(当然我们内部使用这种也是有特定上下文的)。

那么如何让reviewdog支持gitlab-push-commit,即对push动作中的commit进行静态代码检查并将结果以comment的形式放入commit页面呢?我们只能fork reviewdog项目,并在fork后的项目中自行添加对gitlab-push-commit模式的支持。

三. 改造reviewdog以支持gitlab-push-commit模式

reviewdog就是一个命令行工具,通常就是一次性执行,因此它的代码结构较为清晰。我们可以简单围绕它支持的几种reporter模式来搞清楚如何增加对gitlab-push-commit模式的支持。

这里说明一下gitlab-push-commit模式的含义,首先该模式适用于开发人员通过git push推送代码到gitlab时触发的ci job。在该ci job中,reviewdog会运行配置的静态代码分析工具(比如golangci-lint等)对最新的代码进行扫描,并得到问题集合;然后获取最新的commit的sha值(CI_COMMIT_SHA)以及push之前的latest commit的sha值(CI_COMMIT_BEFORE_SHA),并比较这两个版本间的diff。最后通过文件名与行号将问题集合与diff集合中的“交集”找出来,并将结果以comment形式通过gitlab client api提交到的此次push的最新的那个commit的页面。

目前该模式尚存在一个“瑕疵”,那就是如果一个push中有多个commit,那么gitlab-push-commit模式不会针对每个commit做diff和comment,而只是会用push中的latest commit与push之前的最新commit做比较。

定义清除gitlab-push-commit模式含义后,我们就可以“照葫芦画瓢”的为reviewdog增加该模式的支持了!

在main.go中,我们主要是在run函数中增加一个reporter case分支:

// https://github.com/bigwhite/reviewdog/blob/master/cmd/reviewdog/main.go
func run(r io.Reader, w io.Writer, opt *option) error {
... ...

case "gitlab-push-commit":
    build, cli, err := gitlabBuildWithClient(opt.reporter)
    if err != nil {
        return err
    }
    log.Printf("reviewdog: [gitlab-push-commit-report] gitlabBuildWithClient ok\n")

    gc, err := gitlabservice.NewGitLabPushCommitsCommenter(cli, build.Owner, build.Repo, build.SHA)
    if err != nil {
        return err
    }
    log.Printf("reviewdog: [gitlab-push-commit-report] NewGitLabPushCommitsCommenter ok\n")

    cs = reviewdog.MultiCommentService(gc, cs)
    ds, err = gitlabservice.NewGitLabPushCommitsDiff(cli, build.Owner, build.Repo, build.SHA, build.BeforeSHA)
    if err != nil {
        return err
    }
    log.Printf("reviewdog: [gitlab-push-commit-report] NewGitLabPushCommitsDiff ok\n")
... ...

}

在这个case中,我们主要是为后面的project.Run或reviewdog.Run方法准备gitlab client对象、PushCommitsCommenter对象(位于service/gitlab/gitlab_push_commits.go中)、PushCommitsDiff对象(位于service/gitlab/gitlab_push_commits_diff.go中)等。

gitlab_push_commits.go和gitlab_push_commits_diff.go是新增的两个go源文件,也是参考了同目录下的gitlab_mr_commit.go和gitlab_mr_diff.go改写而成的。具体代码这里就不列出来了,大家有兴趣可以自行阅读。

四. 部署gitlab-runner验证新版reviewdog

下面我们就来验证一下上述改造后的reviewdog。

1. 安装gitlab-runner

我们先在gitlab上建立一个实验项目,然后为该项目配置ci。如果你的gitlab还没有注册gitlab-runner,可以按下面步骤安装和注册runner节点(可以在顶层group下面建立,这样runner可以在group内共享:settings => CI/CD => Runners => Show runner installation instructions 有部署runner的详细命令说明):

//假设我们有一个ubuntu 20.04的主机,我们可以按下面命令安装和注册一个gitlab-runner:

sudo curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64

# Give it permissions to execute
sudo chmod +x /usr/local/bin/gitlab-runner

# Create a GitLab CI user
sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash

# Install and run as service
sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start

# 注册该runner
sudo gitlab-runner register --url http://{gitlab-server-ip-addr}/ --registration-token {registration token}

上面命令会在/etc/gitlab-runner下面建立一个runner自用配置文件:config.toml:

//  /etc/gitlab-runner/config.toml

concurrent = 1
check_interval = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "runner for ard group"
  url = "http://gitlab_ip_addr/"
  id = 1
  token = "{registration token}"
  token_obtained_at = 2022-09-01T11:03:43Z
  token_expires_at = 0001-01-01T00:00:00Z
  executor = "shell"
  shell = "bash"
  environment = ["PATH=/home/tonybai/.bin/go1.18/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin"]
  [runners.custom_build_dir]
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]

这里我选择了shell executor,即基于主机shell执行ci job中的命令。runners下的environment可以设置shell的环境变量,这里的设置将覆盖对应账号(比如gitlab-runner)下的环境变量值。

gitlab-runner部署成功后,我们在group的runners下面便可以看到下面的available runners:

注:在创建runner时,我为该runner设置了两个tag:ard和ci。

注:确保runner执行的命令在主机的PATH下面可以找到。

2. 创建personal access token

reviewdog需要通过gitlab client API访问gitlab仓库获取信息并提交comments,这就需要我们为runner执行的命令提供access token。

gitlab有多种access token,比如:personal access token、project access token等。我们创建personal access token,我也测试过project access token,使用project access token可以成功提交comment,但是notify mail十有八九无法发送出来。

access token要保存好,因为它只显示一次。

我们将personal access token配置到实验项目的variable中(Settings => CI/CD => variables),variable的key为REVIEWDOG_GITLAB_API_TOKEN,值为刚刚创建的token。

后续每次CI job执行,该variable会作为预定义的环境变量对job生效。我们的reviewdog便可以使用该token访问gitlab。

3. 配置实验项目的ci pipeline

我们可以通过代码的形式配置实验项目的ci pipeline,我们在项目根目录下建立.gitlab-ci.yml文件,其内容如下:

// .gitlab-ci.yml

build-job:
  tags:
      - ard
  stage: build
  script:
    - export CI_REPO_OWNER=ard/incubators
    - export CI_REPO_NAME=learn-gitlab
    - reviewdog -reporter=gitlab-push-commit
  only:
    - master
    - pushes

.gitlab-ci.yml的具体字段含义可以参考gitlab文档。在这个配置中,值得注意的有几点:

  • 使用tags关联runner(这里用ard这个tag);
  • script部分是job具体执行的命令列表,这里先设置CI_REPO_OWNER和CI_REPO_NAME两个环境变量,供reviewdog使用;然后执行reviewdog;
  • only部分描述仅针对master分支的push事件触发ci job。

4. 配置.reviewdog.yml

最后,我们来配置一下适合实验项目的reviewdog的配置文件。我们同样在项目根目录下建立.reviewdog.yml文件,其内容如下:

runner:
  golangci:
    cmd: golangci-lint run --max-same-issues=0 --out-format=line-number ./...
    errorformat:
      - '%E%f:%l:%c: %m'
      - '%E%f:%l: %m'
      - '%C%.%#'
    level: warning

在这里我们看到,我们使用golangci-lint这个静态检查工具对实验项目的代码进行检查。这里的–max-same-issues=0的含义是不限制相同错误的数量。至于.reviewdog.yml的具体格式,reviewdog项目自身的.reviewdog.yml很具参考价值,大家需要时可以仔细研究。

5. 推送代码并验证reviewdog的执行结果

我们可以故意在代码中写下有问题的一些代码,这些问题要保证可以被golangci-lint工具扫描出来,比如:

package main

type Foo struct {
    A int
    B string
    C bool
}

func Demo1() error {
    return nil
}

func Demo2() error {
    return nil
}

func Demo3() error {
    return nil
}

func main() {
    f := &Foo{1, "tony", false}
    _ = f
    Demo2()
    Demo1()
    Demo3()
}

这里并没有对Demo函数调用进行错误处理,golangci-lint中的errcheck可以检测出这个问题。提交并push这些代码到仓库,稍等片刻,我们便可收到notify mail,打开commit页面,便会看到下面这样的commit comments:

看到这样的结果,说明reviewdog按预期工作了!

五. 小结

本文介绍了如何基于reviewdog对push提交的commit进行静态代码检查并像一个“同行”一样在commit中提交评论的方法。

这样做的目的就是希望通过工具提升代码评审的效率,同时也守住代码质量的下限。

就像本文开始所说的那样,随着检查工具能力的增强,这样的基于reviewdog自动检查代码的方案在保证代码质量方面还可以继续提升。

Go开源了go/ast等工具链,有能力的童鞋可以基于go/ast自行开发具有“特定目的”的检查工具并集成到reviewdog中,这将使得检查更有针对性和有效性。

本文涉及源码在这里下载 – https://github.com/bigwhite/reviewdog/


“Gopher部落”知识星球旨在打造一个精品Go学习和进阶社群!高品质首发Go技术文章,“三天”首发阅读权,每年两期Go语言发展现状分析,每天提前1小时阅读到新鲜的Gopher日报,网课、技术专栏、图书内容前瞻,六小时内必答保证等满足你关于Go语言生态的所有需求!2022年,Gopher部落全面改版,将持续分享Go语言与Go应用领域的知识、技巧与实践,并增加诸多互动形式。欢迎大家加入!

img{512x368}
img{512x368}

img{512x368}
img{512x368}

我爱发短信:企业级短信平台定制开发专家 https://tonybai.com/。smspush : 可部署在企业内部的定制化短信平台,三网覆盖,不惧大并发接入,可定制扩展; 短信内容你来定,不再受约束, 接口丰富,支持长短信,签名可选。2020年4月8日,中国三大电信运营商联合发布《5G消息白皮书》,51短信平台也会全新升级到“51商用消息平台”,全面支持5G RCS消息。

著名云主机服务厂商DigitalOcean发布最新的主机计划,入门级Droplet配置升级为:1 core CPU、1G内存、25G高速SSD,价格5$/月。有使用DigitalOcean需求的朋友,可以打开这个链接地址:https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻)归档仓库 – https://github.com/bigwhite/gopherdaily

我的联系方式:

  • 微博:https://weibo.com/bigwhite20xx
  • 博客:tonybai.com
  • github: https://github.com/bigwhite

商务合作方式:撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

如发现本站页面被黑,比如:挂载广告、挖矿等恶意代码,请朋友们及时联系我。十分感谢! Go语言第一课 Go语言精进之路1 Go语言精进之路2 商务合作请联系bigwhite.cn AT aliyun.com

欢迎使用邮件订阅我的博客

输入邮箱订阅本站,只要有新文章发布,就会第一时间发送邮件通知你哦!

这里是 Tony Bai的个人Blog,欢迎访问、订阅和留言! 订阅Feed请点击上面图片

如果您觉得这里的文章对您有帮助,请扫描上方二维码进行捐赠 ,加油后的Tony Bai将会为您呈现更多精彩的文章,谢谢!

如果您希望通过微信捐赠,请用微信客户端扫描下方赞赏码:

如果您希望通过比特币或以太币捐赠,可以扫描下方二维码:

比特币:

以太币:

如果您喜欢通过微信浏览本站内容,可以扫描下方二维码,订阅本站官方微信订阅号“iamtonybai”;点击二维码,可直达本人官方微博主页^_^:
本站Powered by Digital Ocean VPS。
选择Digital Ocean VPS主机,即可获得10美元现金充值,可 免费使用两个月哟! 著名主机提供商Linode 10$优惠码:linode10,在 这里注册即可免费获 得。阿里云推荐码: 1WFZ0V立享9折!


View Tony Bai's profile on LinkedIn
DigitalOcean Referral Badge

文章

评论

  • 正在加载...

分类

标签

归档



View My Stats