标签 GCC 下的文章

Go编译的几个细节,连专家也要停下来想想

本文永久链接 – https://tonybai.com/2024/11/11/some-details-about-go-compilation

在Go开发中,编译相关的问题看似简单,但实则蕴含许多细节。有时,即使是Go专家也需要停下来,花时间思考答案或亲自验证。本文将通过几个具体问题,和大家一起探讨Go编译过程中的一些你可能之前未曾关注的细节。

注:本文示例使用的环境为Go 1.23.0、Linux Kernel 3.10.0和CentOS 7.9。

1. Go编译默认采用静态链接还是动态链接?

我们来看第一个问题:Go编译默认采用静态链接还是动态链接呢?

很多人脱口而出:动态链接,因为CGO_ENABLED默认值为1,即开启Cgo。也有些人会说:“其实Go编译器默认是静态链接的,只有在使用C语言库时才会动态链接”。那么到底哪个是正确的呢?

我们来看一个具体的示例。但在这之前,我们要承认一个事实,那就是CGO_ENABLED默认值为1,你可以通过下面命令来验证这一点:

$go env|grep CGO_ENABLED
CGO_ENABLED='1'

验证Go默认究竟是哪种链接,我们写一个hello, world的Go程序即可:

// go-compilation/main.go

package main

import "fmt"

func main() {
    fmt.Println("hello, world")
}

构建该程序:

$go build -o helloworld-default main.go

之后,我们查看一下生成的可执行文件helloworld-default的文件属性:

$file helloworld-default
helloworld-default: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked, not stripped
$ldd helloworld-default
   不是动态可执行文件

我们看到,虽然CGO_ENABLED=1,但默认情况下,Go构建出的helloworld程序是静态链接的(statically linked)。

那么默认情况下,Go编译器是否都会采用静态链接的方式来构建Go程序呢?我们给上面的main.go添加一行代码:

// go-compilation/main-with-os-user.go

package main

import (
    "fmt"
    _ "os/user"
)

func main() {
    fmt.Println("hello, world")
}

和之前的hello, world不同的是,这段代码多了一行包的空导入,导入的是os/user这个包。

编译这段代码,我们得到helloworld-with-os-user可执行文件。

$go build -o helloworld-with-os-user main-with-os-user.go

使用file和ldd检视文件helloworld-with-os-user:

$file helloworld-with-os-user
helloworld-with-os-user: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked (uses shared libs), not stripped

$ldd helloworld-with-os-user
    linux-vdso.so.1 =>  (0x00007ffcb8fd4000)
    libpthread.so.0 => /lib64/libpthread.so.0 (0x00007fb5d6fce000)
    libc.so.6 => /lib64/libc.so.6 (0x00007fb5d6c00000)
    /lib64/ld-linux-x86-64.so.2 (0x00007fb5d71ea000)

我们看到:一行新代码居然让helloworld从静态链接变为了动态链接,同时这也是如何编译出一个hello world版的动态链接Go程序的答案。

通过nm命令我们还可以查看Go程序依赖了哪些C库的符号:

$nm -a helloworld-with-os-user |grep " U "
                 U abort
                 U __errno_location
                 U fprintf
                 U fputc
                 U free
                 U fwrite
                 U malloc
                 U mmap
                 U munmap
                 U nanosleep
                 U pthread_attr_destroy
                 U pthread_attr_getstack
                 U pthread_attr_getstacksize
                 U pthread_attr_init
                 U pthread_cond_broadcast
                 U pthread_cond_wait
                 U pthread_create
                 U pthread_detach
                 U pthread_getattr_np
                 U pthread_key_create
                 U pthread_mutex_lock
                 U pthread_mutex_unlock
                 U pthread_self
                 U pthread_setspecific
                 U pthread_sigmask
                 U setenv
                 U sigaction
                 U sigaddset
                 U sigemptyset
                 U sigfillset
                 U sigismember
                 U stderr
                 U strerror
                 U unsetenv
                 U vfprintf

由此,我们可以得到一个结论,在默认情况下(CGO_ENABLED=1),Go会尽力使用静态链接的方式,但在某些情况下,会采用动态链接。那么究竟在哪些情况下会默认生成动态链接的程序呢?我们继续往下看。

2. 在何种情况下默认会生成动态链接的Go程序?

在以下几种情况下,Go编译器会默认(CGO_ENABLED=1)生成动态链接的可执行文件,我们逐一来看一下。

2.1 一些使用C实现的标准库包

根据上述示例,我们可以看到,在某些情况下,即使只依赖标准库,Go 仍会在CGO_ENABLED=1的情况下采用动态链接。这是因为代码依赖的标准库包使用了C版本的实现。虽然这种情况并不常见,但os/user包net包是两个典型的例子。

os/user包的示例在前面我们已经见识过了。user包允许开发者通过名称或ID查找用户账户。对于大多数Unix系统(包括linux),该包内部有两种版本的实现,用于解析用户和组ID到名称,并列出附加组ID。一种是用纯Go编写,解析/etc/passwd和/etc/group文件。另一种是基于cgo的,依赖于标准C库(libc)中的例程,如getpwuid_r、getgrnam_r和getgrouplist。当cgo可用(CGO_ENABLED=1),并且特定平台的libc实现了所需的例程时,将使用基于cgo的(libc支持的)代码,即采用动态链接方式。

同样,net包在名称解析(Name Resolution,即域名或主机名对应IP查找)上针对大多数Unix系统也有两个版本的实现:一个是纯Go版本,另一个是基于C的版本。C版本会在cgo可用且特定平台实现了相关C函数(比如getaddrinfo和getnameinfo等)时使用。

下面是一个简单的使用net包并采用动态链接的示例:

// go-compilation/main-with-net.go

package main

import (
    "fmt"
    _ "net"
)

func main() {
    fmt.Println("hello, world")
}

编译后,我们查看一下文件属性:

$go build -o helloworld-with-net main-with-net.go 

$file helloworld-with-net
helloworld-with-net: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked (uses shared libs), not stripped

$ldd helloworld-with-net
    linux-vdso.so.1 =>  (0x00007ffd75dfd000)
    libresolv.so.2 => /lib64/libresolv.so.2 (0x00007fdda2cf9000)
    libpthread.so.0 => /lib64/libpthread.so.0 (0x00007fdda2add000)
    libc.so.6 => /lib64/libc.so.6 (0x00007fdda270f000)
    /lib64/ld-linux-x86-64.so.2 (0x00007fdda2f13000)

我们看到C版本实现依赖了libresolv.so这个用于名称解析的C库。

由此可得,当Go在默认cgo开启时,一旦依赖了标准库中拥有C版本实现的包,比如os/user、net等,Go编译器会采用动态链接的方式编译Go可执行程序。

2.2 显式使用cgo调用外部C程序

如果使用cgo与外部C代码交互,那么生成的可执行文件必然会包含动态链接。下面我们来看一个调用cgo的简单示例。

首先,建立一个简单的C lib:

// go-compilation/my-c-lib

$tree my-c-lib
my-c-lib
├── Makefile
├── mylib.c
└── mylib.h

// go-compilation/my-c-lib/Makefile

.PHONY:  all static

all:
        gcc -c -fPIC -o mylib.o mylib.c
        gcc -shared -o libmylib.so mylib.o
static:
        gcc -c -fPIC -o mylib.o mylib.c
        ar rcs libmylib.a mylib.o

// go-compilation/my-c-lib/mylib.h

#ifndef MYLIB_H
#define MYLIB_H

void hello();
int add(int a, int b);

#endif // MYLIB_H

// go-compilation/my-c-lib/mylib.c

#include <stdio.h>

void hello() {
    printf("Hello from C!\n");
}

int add(int a, int b) {
    return a + b;
}

执行make all构建出动态链接库libmylib.so!接下来,我们编写一个Go程序通过cgo调用libmylib.so中:

// go-compilation/main-with-call-myclib.go 

package main

/*
#cgo CFLAGS: -I ./my-c-lib
#cgo LDFLAGS: -L ./my-c-lib -lmylib
#include "mylib.h"
*/
import "C"
import "fmt"

func main() {
    // 调用 C 函数
    C.hello()

    // 调用 C 中的加法函数
    result := C.add(3, 4)
    fmt.Printf("Result of addition: %d\n", result)
}

编译该源码:

$go build -o helloworld-with-call-myclib main-with-call-myclib.go

通过ldd可以看到,可执行文件helloworld-with-call-myclib是动态链接的,并依赖libmylib.so:

$ldd helloworld-with-call-myclib
    linux-vdso.so.1 =>  (0x00007ffcc39d8000)
    libmylib.so => not found
    libpthread.so.0 => /lib64/libpthread.so.0 (0x00007f7166df5000)
    libc.so.6 => /lib64/libc.so.6 (0x00007f7166a27000)
    /lib64/ld-linux-x86-64.so.2 (0x00007f7167011000)

设置LD_LIBRARY_PATH(为了让程序找到libmylib.so)并运行可执行文件helloworld-with-call-myclib:

$ LD_LIBRARY_PATH=./my-c-lib:$LD_LIBRARY_PATH ./helloworld-with-call-myclib
Hello from C!
Result of addition: 7

2.3 使用了依赖cgo的第三方包

在日常开发中,我们经常依赖一些第三方包,有些时候这些第三方包依赖cgo,比如mattn/go-sqlite3。下面就是一个依赖go-sqlite3包的示例:

// go-compilation/go-sqlite3/main.go
package main

import (
    "database/sql"
    "fmt"
    "log"

    _ "github.com/mattn/go-sqlite3"
)

func main() {
    // 打开数据库(如果不存在,则创建)
    db, err := sql.Open("sqlite3", "./test.db")
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    // 创建表
    sqlStmt := `CREATE TABLE IF NOT EXISTS user (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT);`
    _, err = db.Exec(sqlStmt)
    if err != nil {
        log.Fatalf("%q: %s\n", err, sqlStmt)
    }

    // 插入数据
    _, err = db.Exec(`INSERT INTO user (name) VALUES (?)`, "Alice")
    if err != nil {
        log.Fatal(err)
    }

    // 查询数据
    rows, err := db.Query(`SELECT id, name FROM user;`)
    if err != nil {
        log.Fatal(err)
    }
    defer rows.Close()

    for rows.Next() {
        var id int
        var name string
        err = rows.Scan(&id, &name)
        if err != nil {
            log.Fatal(err)
        }
        fmt.Printf("%d: %s\n", id, name)
    }

    // 检查查询中的错误
    if err = rows.Err(); err != nil {
        log.Fatal(err)
    }
}

编译和运行该源码:

$go build demo
$ldd demo
    linux-vdso.so.1 =>  (0x00007ffe23d8e000)
    libdl.so.2 => /lib64/libdl.so.2 (0x00007faf0ddef000)
    libpthread.so.0 => /lib64/libpthread.so.0 (0x00007faf0dbd3000)
    libc.so.6 => /lib64/libc.so.6 (0x00007faf0d805000)
    /lib64/ld-linux-x86-64.so.2 (0x00007faf0dff3000)
$./demo
1: Alice

到这里,有些读者可能会问一个问题:如果需要在上述依赖场景中生成静态链接的Go程序,该怎么做呢?接下来,我们就来看看这个问题的解决细节。

3. 如何在上述情况下实现静态链接?

到这里是不是有些烧脑了啊!我们针对上一节的三种情况,分别对应来看一下静态编译的方案。

3.1 仅依赖标准包

在前面我们说过,之所以在使用os/user、net包时会在默认情况下采用动态链接,是因为Go使用了这两个包对应功能的C版实现,如果要做静态编译,让Go编译器选择它们的纯Go版实现即可。那我们仅需要关闭CGO即可,以依赖标准库os/user为例:

$CGO_ENABLED=0 go build -o helloworld-with-os-user-static main-with-os-user.go
$file helloworld-with-os-user-static
helloworld-with-os-user-static: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked, not stripped
$ldd helloworld-with-os-user-static
    不是动态可执行文件

3.2 使用cgo调用外部c程序(静态链接)

对于依赖cgo调用外部c的程序,我们要使用静态链接就必须要求外部c库提供静态库,因此,我们需要my-c-lib提供一份libmylib.a,这通过下面命令可以实现(或执行make static):

$gcc -c -fPIC -o mylib.o mylib.c
$ar rcs libmylib.a mylib.o

有了libmylib.a后,我们还要让Go程序静态链接该.a文件,于是我们需要修改一下Go源码中cgo链接的flag,加上静态链接的选项:

// go-compilation/main-with-call-myclib-static.go
... ...
#cgo LDFLAGS: -static -L my-c-lib -lmylib
... ...

编译链接并查看一下文件属性:

$go build -o helloworld-with-call-myclib-static main-with-call-myclib-static.go

$file helloworld-with-call-myclib-static
helloworld-with-call-myclib-static: ELF 64-bit LSB executable, x86-64, version 1 (GNU/Linux), statically linked, for GNU/Linux 2.6.32, BuildID[sha1]=b3da3ed817d0d04230460069b048cab5f5bfc3b9, not stripped

我们得到了预期的结果!

3.3 依赖使用cgo的外部go包(静态链接)

最麻烦的是这类情况,要想实现静态链接,我们需要找出外部go依赖的所有c库的.a文件(静态共享库)。以我们的go-sqlite3示例为例,go-sqlite3是sqlite库的go binding,它依赖sqlite库,同时所有第三方c库都依赖libc,我们还要准备一份libc的.a文件,下面我们就先安装这些:

$yum install -y gcc glibc-static sqlite-devel
... ...

已安装:
  sqlite-devel.x86_64 0:3.7.17-8.el7_7.1                                                                                          

更新完毕:
  glibc-static.x86_64 0:2.17-326.el7_9.3

接下来,我们就来以静态链接的方式在go-compilation/go-sqlite3-static下编译一下:

$go build -tags 'sqlite_omit_load_extension' -ldflags '-linkmode external -extldflags "-static"' demo

$file ./demo
./demo: ELF 64-bit LSB executable, x86-64, version 1 (GNU/Linux), statically linked, for GNU/Linux 2.6.32, BuildID[sha1]=c779f5c3eaa945d916de059b56d94c23974ce61c, not stripped

这里命令行中的-tags ‘sqlite_omit_load_extension’用于禁用SQLite3的动态加载功能,确保更好的静态链接兼容性。而-ldflags ‘-linkmode external -extldflags “-static”‘的含义是使用外部链接器(比如gcc linker),并强制静态链接所有库。

我们再看完略烧脑的几个细节后,再来看一个略轻松的话题。

4. Go编译出的可执行文件过大,能优化吗?

Go编译出的二进制文件一般较大,一个简单的“Hello World”程序通常在2MB左右:

$ls -lh helloworld-default
-rwxr-xr-x 1 root root 2.1M 11月  3 10:39 helloworld-default

这一方面是因为Go将整个runtime都编译到可执行文件中了,另一方面也是因为Go静态编译所致。那么在默认情况下,Go二进制文件的大小还有优化空间么?方法不多,有两种可以尝试:

  • 去除符号表和调试信息

在编译时使用-ldflags=”-s -w”标志可以去除符号表和调试符号,其中-s用于去掉符号表和调试信息,-w用于去掉DWARF调试信息,这样能显著减小文件体积。以helloworld为例,可执行文件的size减少了近四成:

$go build -ldflags="-s -w" -o helloworld-default-nosym main.go
$ls -l
-rwxr-xr-x 1 root root 2124504 11月  3 10:39 helloworld-default
-rwxr-xr-x 1 root root 1384600 11月  3 13:34 helloworld-default-nosym
  • 使用tinygo

TinyGo是一个Go语言的编译器,它专为资源受限的环境而设计,例如微控制器、WebAssembly和其他嵌入式设备。TinyGo的目标是提供一个轻量级的、能在小型设备上运行的Go运行时,同时尽可能支持Go语言的特性。tinygo的一大优点就是生成的二进制文件通常比标准Go编译器生成的文件小得多:

$tinygo build -o helloworld-tinygo main.go
$ls -l
总用量 2728
-rwxr-xr-x  1 root root 2128909 11月  5 05:43 helloworld-default*
-rwxr-xr-x  1 root root  647600 11月  5 05:45 helloworld-tinygo*

我们看到:tinygo生成的可执行文件的size仅是原来的30%。

注:虽然TinyGo在特定场景(如IoT和嵌入式开发)中非常有用,但在常规服务器环境中,由于生态系统兼容性、性能、调试支持等方面的限制,可能并不是最佳选择。对于需要高并发、复杂功能和良好调试支持的应用,标准Go仍然是更合适的选择。

注:这里使用的tinygo为0.34.0版本。

5. 未使用的符号是否会被编译到Go二进制文件中?

到这里,相信读者心中也都会萦绕一些问题:到底哪些符号被编译到最终的Go二进制文件中了呢?未使用的符号是否会被编译到Go二进制文件中吗?在这一小节中,我们就来探索一下。

出于对Go的了解,我们已经知道无论是GOPATH时代,还是Go module时代,Go的编译单元始终是包(package),一个包(无论包中包含多少个Go源文件)都会作为一个编译单元被编译为一个目标文件(.a),然后Go链接器会将多个目标文件链接在一起生成可执行文件,因此如果一个包被依赖,那么它就会进入到Go二进制文件中,它内部的符号也会进入到Go二进制文件中。

那么问题来了!是否被依赖包中的所有符号都会被放到最终的可执行文件中呢?我们以最简单的helloworld-default为例,它依赖fmt包,并调用了fmt包的Println函数,我们看看Println这个符号是否会出现在最终的可执行文件中:

$nm -a helloworld-default | grep "Println"
000000000048eba0 T fmt.(*pp).doPrintln

居然没有!我们初步怀疑是inline优化在作祟。接下来,关闭优化再来试试:

$go build -o helloworld-default-noinline -gcflags='-l -N' main.go

$nm -a helloworld-default-noinline | grep "Println"
000000000048ec00 T fmt.(*pp).doPrintln
0000000000489ee0 T fmt.Println

看来的确如此!不过当使用”fmt.”去过滤helloworld-default-noinline的所有符号时,我们发现fmt包的一些常见的符号并未包含在其中,比如Printf、Fprintf、Scanf等。

这是因为Go编译器的一个重要特性:死码消除(dead code elimination),即编译器会将未使用的代码和数据从最终的二进制文件中剔除。

我们再来继续探讨一个衍生问题:如果Go源码使用空导入方式导入了一个包,那么这个包是否会被编译到Go二进制文件中呢?其实道理是一样的,如果用到了里面的符号,就会存在,否则不会。

以空导入os/user为例,即便在CGO_ENABLED=0的情况下,因为没有使用os/user中的任何符号,在最终的二进制文件中也不会包含user包:

$CGO_ENABLED=0 go build -o helloworld-with-os-user-noinline -gcflags='-l -N' main-with-os-user.go
[root@iZ2ze18rmx2avqb5xgb4omZ helloworld]# nm -a helloworld-with-os-user-noinline |grep user
0000000000551ac0 B runtime.userArenaState

但是如果是带有init函数的包,且init函数中调用了同包其他符号的情况呢?我们以expvar包为例看一下:

// go-compilation/main-with-expvar.go

package main

import (
    _ "expvar"
    "fmt"
)

func main() {
    fmt.Println("hello, world")
}

编译并查看一下其中的符号:

$go build -o helloworld-with-expvar-noinline -gcflags='-l -N' main-with-expvar.go
$nm -a helloworld-with-expvar-noinline|grep expvar
0000000000556480 T expvar.appendJSONQuote
00000000005562e0 T expvar.cmdline
00000000005561c0 T expvar.expvarHandler
00000000005568e0 T expvar.(*Func).String
0000000000555ee0 T expvar.Func.String
00000000005563a0 T expvar.init.0
00000000006e0560 D expvar..inittask
0000000000704550 d expvar..interfaceSwitch.0
... ...

除此之外,如果一个包即便没有init函数,但有需要初始化的全局变量,比如crypto包的hashes:

// $GOROOT/src/crypto/crypto.go
var hashes = make([]func() hash.Hash, maxHash)

crypto包的相关如何也会进入最终的可执行文件中,大家自己动手不妨试试。下面是我得到的一些输出:

$go build -o helloworld-with-crypto-noinline -gcflags='-l -N' main-with-crypto.go
$nm -a helloworld-with-crypto-noinline|grep crypto
00000000005517b0 B crypto.hashes
000000000048ee60 T crypto.init
0000000000547280 D crypto..inittask

有人会问:os/user包也有一些全局变量啊,为什么这些符号没有被包含在可执行文件中呢?比如:

// $GOROOT/src/os/user/user.go
var (
    userImplemented      = true
    groupImplemented     = true
    groupListImplemented = true
)

这就要涉及Go包初始化的逻辑了。我们看到crypto包包含在可执行文件中的符号中有crypto.init和crypto..inittask这两个符号,显然这不是crypto包代码中的符号,而是Go编译器为crypto包自动生成的init函数和inittask结构。

Go编译器会为每个包生成一个init函数,即使包中没有显式定义init函数,同时每个包都会有一个inittask结构,用于运行时的包初始化系统。当然这么说也不足够精确,如果一个包没有init函数、需要初始化的全局变量或其他需要运行时初始化的内容,则编译器不会为其生成init函数和inittask。比如上面的os/user包。

os/user包确实有上述全局变量的定义,但是这些变量是在编译期就可以确定值的常量布尔值,而且未被包外引用或在包内用于影响控制流。Go编译器足够智能,能够判断出这些初始化是”无副作用的”,不需要在运行时进行初始化。只有真正需要运行时初始化的包才会生成init和inittask。这也解释了为什么空导入os/user包时没有相关的init和inittask符号,而crypto、expvar包有的init.0和inittask符号。

6. 如何快速判断Go项目是否依赖cgo?

在使用开源Go项目时,我们经常会遇到项目文档中没有明确说明是否依赖Cgo的情况。这种情况下,如果我们需要在特定环境(比如CGO_ENABLED=0)下使用该项目,就需要事先判断项目是否依赖Cgo,有些时候还要快速地给出判断。

那究竟是否可以做到这种快速判断呢?我们先来看看一些常见的作法。

第一类作法是源码层面的静态分析。最直接的方式是检查源码中是否存在import “C”语句,这种引入方式是CGO使用的显著标志。

// 在项目根目录中执行
$grep -rn 'import "C"' .

这个命令会递归搜索当前目录下所有文件,显示包含import “C”的行号和文件路径,帮助快速定位CGO的使用位置。

此外,CGO项目通常包含特殊的编译指令,这些指令以注释形式出现在源码中,比如前面见识过的#cgo CFLAGS、#cgo LDFLAGS等,通过对这些编译指令的检测,同样可以来判断项目是否依赖CGO。

不过第一类作法并不能查找出Go项目的依赖包是否依赖cgo。而找出直接依赖或间接依赖是否依赖cgo,我们需要工具帮忙,比如使用Go工具链提供的命令分析项目依赖:

$go list -deps -f '{{.ImportPath}}: {{.CgoFiles}}' ./...  | grep -v '\[\]'

其中ImportPath是依赖包的导入路径,而CgoFiles则是依赖中包含import “C”的Go源文件。我们以go-sqlite3那个依赖cgo的示例来验证一下:

// cd go-compilation/go-sqlite3

$go list -deps -f '{{.ImportPath}}: {{.CgoFiles}}' ./...  | grep -v '\[\]'
runtime/cgo: [cgo.go]
github.com/mattn/go-sqlite3: [backup.go callback.go error.go sqlite3.go sqlite3_context.go sqlite3_load_extension.go sqlite3_opt_serialize.go sqlite3_opt_userauth_omit.go sqlite3_other.go sqlite3_type.go]

用空导入os/user的示例再来看一下:

$go list -deps -f '{{.ImportPath}}: {{.CgoFiles}}'  main-with-os-user.go | grep -v '\[\]'
runtime/cgo: [cgo.go]
os/user: [cgo_lookup_cgo.go getgrouplist_unix.go]

我们知道os/user有纯go和C版本两个实现,因此上述判断只能说“对了一半”,当我关闭CGO_ENABLED时,Go编译器不会使用基于cgo的C版实现。

那是否在禁用cgo的前提下对源码进行一次编译便能验证项目是否对cgo有依赖呢?这样做显然谈不上是一种“快速”的方法,那是否有效呢?我们来对上面的go-sqlite3项目做一个测试,我们在关闭CGO_ENABLED时,编译一下该示例:

// cd go-compilation/go-sqlite3
$ CGO_ENABLED=0 go build demo

我们看到,Go编译器并未报错!似乎该项目不需要cgo! 但真的是这样吗?我们运行一下编译后的demo可执行文件:

$ ./demo
2024/11/03 22:10:36 "Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work. This is a stub": CREATE TABLE IF NOT EXISTS user (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT);

我们看到成功编译出来的程序居然出现运行时错误,提示需要cgo!

到这里,没有一种方法可以快速、精确的给出项目是否依赖cgo的判断。也许判断Go项目是否依赖CGO并没有捷径,需要从源码分析、依赖检查和构建测试等多个维度进行。

7. 小结

在本文中,我们深入探讨了Go语言编译过程中的几个重要细节,尤其是在静态链接和动态链接的选择上。通过具体示例,我们了解到:

  • 默认链接方式:尽管CGO_ENABLED默认值为1,Go编译器在大多数情况下会采用静态链接,只有在依赖特定的C库或标准库包时,才会切换到动态链接。

  • 动态链接的条件:我们讨论了几种情况下Go会默认生成动态链接的可执行文件,包括依赖使用C实现的标准库包、显式使用cgo调用外部C程序,以及使用依赖cgo的第三方包。

  • 实现静态链接:对于需要动态链接的场景,我们也提供了将其转为静态链接的解决方案,包括关闭CGO、使用静态库,以及处理依赖cgo的外部包的静态链接问题。

  • 二进制文件优化:我们还介绍了如何通过去除符号表和使用TinyGo等方法来优化生成的Go二进制文件的大小,以满足不同场景下的需求。

  • 符号编译与死码消除:最后,我们探讨了未使用的符号是否会被编译到最终的二进制文件中,并解释了Go编译器的死码消除机制。

通过这些细节探讨,我希望能够帮助大家更好地理解Go编译的复杂性,并在实际开发中做出更明智的选择,亦能在面对Go编译相关问题时,提供有效的解决方案。

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


Gopher部落知识星球在2024年将继续致力于打造一个高品质的Go语言学习和交流平台。我们将继续提供优质的Go技术文章首发和阅读体验。同时,我们也会加强代码质量和最佳实践的分享,包括如何编写简洁、可读、可测试的Go代码。此外,我们还会加强星友之间的交流和互动。欢迎大家踊跃提问,分享心得,讨论技术。我会在第一时间进行解答和交流。我衷心希望Gopher部落可以成为大家学习、进步、交流的港湾。让我相聚在Gopher部落,享受coding的快乐! 欢迎大家踊跃加入!

img{512x368}
img{512x368}

img{512x368}
img{512x368}

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

Gopher Daily(Gopher每日新闻) – https://gopherdaily.tonybai.com

我的联系方式:

  • 微博(暂不可用):https://weibo.com/bigwhite20xx
  • 微博2:https://weibo.com/u/6484441286
  • 博客:tonybai.com
  • github: https://github.com/bigwhite
  • Gopher Daily归档 – https://github.com/bigwhite/gopherdaily
  • Gopher Daily Feed订阅 – https://gopherdaily.tonybai.com/feed

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

Gopher的Rust第一课:Rust代码组织

本文永久链接 – https://tonybai.com/2024/06/06/gopher-rust-first-lesson-organizing-rust-code

在上一章的讲解中,我们编写了第一个Rust示例程序”hello, world”,并给出了rustc版和cargo版本。在真实开发中,我们都会使用cargo来创建和管理Rust包。不过,Hello, world示例非常简单,仅仅由一个Rust源码文件组成,而且所有源码文件都在同一个目录中。但真实世界中的实用Rust程序,无论是公司商业项目,还是一些知名的开源项目,甚至是一些稍复杂一些的供教学使用的示例程序,它们通常可不会这么简单,都有着复杂的代码结构。

Rust初学者在阅读这些项目源码时便仿佛进入了迷宫,不知道该走哪条(阅读代码的)路径,不知道每个目录代表的含义,也不知道自己想看的源码究竟在哪个目录下。但目前市面上的Rust入门教程大多没有重视初学者的这一问题,要么没有对Rust项目代码组织结构进行针对性的讲解,要么是将讲解放到书籍的后面章节。

根据我个人的学习经验来看,理解一个实用Rust项目的代码组织结构越早,对后续的Rust学习越有益处。同时,掌握Rust项目的代码组织结构也是Rust开发者走向编写复杂Rust程序的必经的一步。并且,初学者在了解项目的代码组织结构后,便可以自主阅读一些复杂的Rust项目的源码,可提高Rust学习的效率,提升学习效果。因此,我决定在介绍Rust基础语法之前先在本章中系统地介绍Rust的代码组织结构,以满足很多Rust初学者的述求。

但在介绍Rust代码组织结构之前,我们需要先来系统说明一下Rust代码组织结构中的几个重要概念,它们是了解Rust项目代码组织结构的前提。

4.1 回顾Go代码组织

Go项目代码组织由module和package两级组成。通常来说,每个Go repo就是一个module,由repo根目录下的go.mod定义,go.mod文件所在目录也被称为module root。go.mod中典型内容如下:

// go.mod
module github.com/user/mymodule[/vN]

go 1.22.1

... ...

go.mod中的module directive一行后面的github.com/user/mymodule/[vN]是module path。module path一来可以反映该module的具体网络位置,同时也是该module下面的Go package导入(import)路径的组成部分。module root下的子目录中通常存放着该module下面的Go package,比如module root/foo目录下存放的Go包的导入路径为github.com/user/mymodule[/vN]/foo。

Go package是Go的编译单元,也是功能单元,代码内外部导入和引用的单位也都是包。而go module是后加入的,更多用于管理包的版本(一个module下的所有包都统一进行版本管理)以及构建时第三方依赖和版本的管理。

更多关于Go module和package管理以及Go项目布局的内容,可以详见我的极客时间《Go语言第一课》专栏。

个人认为Go的module和package的两级管理还是很好理解和管理的,在这方面Rust的代码组织形式又是怎样的呢?接下来,我们就来正式看看Rust的代码组织。

4.2 rustc-only的Rust项目

Rust是系统编程语言,这让我想起了当初在Go成为我个人主力语言之前使用C/C++进行开发的岁月。C/C++是没有像go或Rust的cargo那样的统一的包依赖管理器和项目构建管理工具的。编译器(如gcc等)是核心工具,而项目构建管理则经常由其他工具负责,如Makefile、CMake,或者是Google的Bazel等。在Windows上开发应用的,则往往使用微软或其他开发者工具公司提供的IDE,如当年炙手可热的Visual Studio系列。

下面表格展示了各语言的编译器/链接器和构建管理工具的关系:

像cargo、go这样的“一站式”工具链都旨在为开发者提供体验更为友好的交互接口的,在幕后,它们仍然依赖于底层的编译器和链接器(如rustc和go tool compile/link)来执行实际的代码编译。

不过,像cargo这样的高级工具也给开发人员带来了额外的抽象,或是叫“掩盖”了一些真相,这有时候让人看不清构建过程的本质,比如:很多Gopher用了很多年Go,但却不知道go tool compile/link的存在。

本着只有in hard way,才能看到和抓住本质的思路,以及之前学习用系统编程语言C/C++时经验,这里我们先来看一些rustc-only的Rust项目。Rustc-only的Rust项目是指不使用Cargo创建和管理的Rust项目,而是直接使用rustc编译器来编译和构建项目。这意味着开发者需要编写自己的构建脚本,例如使用Makefile或其他构建工具来管理项目的构建过程。

不过,请注意:这类项目极少用于生产,即便是那些不需要复杂的依赖管理的小型项目。这里使用rustc-only的Rust项目仅仅是为了学习和了解Rustc编译器的主要功能机制以及Rust语言在代码组织上的一些抽象,比如module等。

下面我们就从最简单的rustc-only项目开始,先来看看只有一个Rust源文件且无其他依赖项的“最简项目”。

4.2.1 单文件项目

所谓单文件项目,即只有一个Rust源文件,例如前面章节中的hello_world.rs,这种项目可以直接使用rustc编译器来编译和运行:

// rust-guide-for-gopher/organizing-rust-code/rustc-only/single/hello-world/hello_world.rs
fn main() {
    println!("Hello, world!");
}

对于顶层带有main函数的源文件,rustc会默认将其视为binary crate类型的源文件,并将其编译为可执行二进制文件hello_world。

我们当然也可以强制的让rustc将该源文件视为library crate类型的源文件,并将其编译为其他类型的crate输出文件,rustc支持多种crate type:

      --crate-type [bin|lib|rlib|dylib|cdylib|staticlib|proc-macro]
                        Comma separated list of types of crates
                        for the compiler to emit

rustc的文档中,各种crate类型的含义如下:

lib — Generates a library kind preferred by the compiler, currently defaults to rlib.
rlib — A Rust static library.
staticlib — A native static library.
dylib — A Rust dynamic library.
cdylib — A native dynamic library.
bin — A runnable executable program.
proc-macro — Generates a format suitable for a procedural macro library that may be loaded by the compiler.

不过,如果强制将带有顶层main函数的rust源文件视为lib crate型的,那么rustc将会报warning,提醒你函数main将是死代码,永远不会被用到:

$rustc --crate-type lib hello_world.rs
warning: function `main` is never used
 --> hello_world.rs:1:4
  |
1 | fn main() {
  |    ^^^^
  |
  = note: `#[warn(dead_code)]` on by default

warning: 1 warning emitted

但即便如此,一个名为libhello_world.rlib的文件依然会被rustc生成出来!(目前–crate-type lib等同于–create-type rlib)。

4.2.2 有外部依赖项的单文件项目

日常开发中,像上面的Hello, World级别的trivial应用是极其少见的,一个non-trivial的Rust应用或多或少都会有一些依赖。这里我们也来看一下如何基于rustc来构建带有外部依赖的单文件项目。下面是一个带有外部依赖的示例:

// organizing-rust-code/rustc-only/single/hello-world-with-deps/hello_world.rs
extern crate rand;

use rand::Rng;

fn main() {
    let mut rng = rand::thread_rng();
    let num: u32 = rng.gen();
    println!("Random number: {}", num);
}

这个示例程序依赖一个名为rand的crate,要编译该程序,我们必须先手动下载rand的crate源码,并在本地将rand源码编译为示例程序所需的rust library。下面步骤展示了如何下载和构建rand crate:

$curl -LO https://crates.io/api/v1/crates/rand/0.8.5/download
$tar -xvf download

解压后,我们将看到rand-0.8.5这样的一个crate目录,进入该目录,我们执行cargo build来构建rand crate:

$cd rand-0.8.5
$cargo build
... ...
   Finished dev [unoptimized + debuginfo] target(s) in 0.19s

cargo构建出的librand.rlib就在rand-0.8.5/target/debug下。

注:rlib的命名方式:lib+{crate_name}.rlib

接下来,我们就来构建一下依赖rand crate的hello_world.rs:

// 在organizing-rust-code/rustc-only/single/hello-world-with-deps下面执行

$rustc --verbose  -L ./rand-0.8.5/target/debug  --extern rand=librand.rlib hello_world.rs
error[E0463]: can't find crate for `rand_core` which `rand` depends on
 --> hello_world.rs:1:1
  |
1 | extern crate rand;
  | ^^^^^^^^^^^^^^^^^^ can't find crate

error: aborting due to 1 previous error

For more information about this error, try `rustc --explain E0463`.

我们看到rustc的编译错误提示:无法找到rand crate依赖的rand_core crate!也就是说我们除了向rustc提供hello_world.rs依赖的rand crate之外,还要向rustc提供rand crate的各种依赖!

rand crate的各种依赖在哪里呢?我们在构建rand crate时,cargo build将各种依赖都放在了rand-0.8.5/target/debug/deps目录下了:

$ls -l|grep ".rlib"
-rw-r--r--   1 tonybai  staff     6896  4 29 06:45 libcfg_if-cd6bebf18fb9c234.rlib
-rw-r--r--   1 tonybai  staff   204072  4 29 06:45 libgetrandom-df6a8e95e188fc56.rlib
-rw-r--r--   1 tonybai  staff  1651320  4 29 06:45 liblibc-f16531562d07b476.rlib
-rw-r--r--   1 tonybai  staff   959408  4 29 06:45 libppv_lite86-f1d97d485bc43617.rlib
-rw-r--r--   1 tonybai  staff  1784376  4 29 06:45 librand-9a91ea8db926e840.rlib
-rw-r--r--   1 tonybai  staff   987936  4 29 06:45 librand_chacha-6fe22bd8b3bb228c.rlib
-rw-r--r--   1 tonybai  staff   256768  4 29 06:45 librand_core-fc905f6ca5f8533b.rlib

我们看到其中还包含了librand自身:librand-9a91ea8db926e840.rlib。我们来试试基于deps目录下的这些依赖rlib编译一下:

$rustc --verbose  --extern rand=rand-0.8.5/target/debug/deps/librand-9a91ea8db926e840.rlib -L rand-0.8.5/target/debug/deps  --extern rand_core=librand_core-fc905f6ca5f8533b.rlib --extern getrandom=libgetrandom-df6a8e95e188fc56.rlib --extern cfg_if=libcfg_if-cd6bebf18fb9c234.rlib --extern libc=liblibc-f16531562d07b476.rlib --extern rand_chacha=librand_chacha-6fe22bd8b3bb228c.rlib --extern ppv_lite86=libppv_lite86-f1d97d485bc43617.rlib  hello_world.rs

我们用rustc成功编译了带有外部依赖的Rust源码。不过这里要注意的是rustc对直接依赖和间接依赖的crate的定位方式有所不同。

对于直接依赖的crate,比如这里的rand crate,我们需要给出具体路径,它不依赖-L的位置指示,所以这里我们使用了–extern rand=rand-0.8.5/target/debug/deps/librand-9a91ea8db926e840.rlib。

对于间接依赖的crate,比如rand crate依赖的rand_core,rust会结合-L指示的位置以及–extern一起来定位,这里-L指示路径为rand-0.8.5/target/debug/deps,–extern rand_core=librand_core-fc905f6ca5f8533b.rlib,那么rustc就会在rand-0.8.5/target/debug/deps下面搜索librand_core-fc905f6ca5f8533b.rlib是否存在。

我们运行rustc构建出的可执行文件,输出如下:

$./hello_world
Random number: 431751199

4.2.3 有外部依赖的多文件项目

在Go中,如果某个目录下有多个源文件,那么通常这几个源文件均归属于同一个Go包(可能的例外的是*_test.go文件的包名)。但在Rust中,情况就会变得复杂了一些,我们来看一个例子:

// organizing-rust-code/rustc-only/multi/multi-file-with-deps

$tree -F -L 2
.
├── main.rs
├── sub1/
│   ├── bar.rs
│   ├── foo.rs
│   └── mod.rs
└── sub2.rs

在这个示例中,我们看到除了main.rs之外,还有一个sub2.rs以及一个目录sub1,sub1下面还有三个rs文件。我们从main.rs开始,逐一看一下各个源文件的内容:

// organizing-rust-code/rustc-only/multi/multi-file-with-deps/main.rs
 1 extern crate rand;
 2 use rand::Rng;
 3
 4 mod sub1;
 5 mod sub2;
 6
 7 mod sub3 {
 8     pub fn func1() {
 9         println!("called {}::func1()", module_path!());
10     }
11     pub fn func2() {
12         self::func1();
13         println!("called {}::func2()", module_path!());
14         super::func1();
15     }
16 }
17
18 fn func1() {
19     println!("called {}::func1()", module_path!());
20 }
21
22 fn main() {
23     println!("current module: {}", module_path!());
24     let mut rng = rand::thread_rng();
25     let num: u32 = rng.gen();
26     println!("Random number: {}", num);
27
28     sub1::func1();
29     sub2::func1();
30     sub3::func2();
31 }

在main.rs中,我们除了看到了第1~2行的对外部rand crate的依赖外,我们还看到了一种新的语法元素:rust module。这里涉及sub1~sub3三个module,我们分别来看一下。先来看一下最直观的、定义在main.rs中的sub3 module。

第7行~第16行的代码定义了一个名为sub3的module,它包含两个函数func1和func2,这两个函数前面的pub关键字表明他们是sub3 module的publish函数,可以被module之外的代码所访问。任何未标记为pub的函数都是私有的,只能在模块内部及其子模块中使用。

在sub3 module的func2函数中,我们调用了self::func1()函数,self指代是模块自身,因此这个self::func1()函数就是sub3的func1函数。而接下来调用的super::func1()调用的语义你大概也能猜到。super指代的是sub3的父模块,而super::func1()就是sub3的父模块中的func1函数。

sub3的父模块就是这个项目的顶层模块,我们在main函数的入口处使用module_path!宏输出了该顶层模块的名称。

和sub3在main.rs中定义不同,sub1和sub2也分别代表了另外两种module的定义方式。

当Rust编译器看到第4行mod sub1后,它会寻找当前目录下是否有名为sub1.rs的源文件或是sub1/mod.rs源文件。在这个示例中,sub1定义在sub1目录下的mod.rs中:

// organizing-rust-code/rustc-only/multi/multi-file-with-deps/sub1/mod.rs

pub mod bar;
pub mod foo;

pub fn func1() {
    println!("called {}::func1()", module_path!());
    foo::func1();
    bar::func1();
}

我们看到sub1/mod.rs中定义了一个公共函数func1,同时也在最开始处又嵌套定义了bar和foo两个module,并在func1中调用了两个嵌套子module的函数:

bar和foo两个module都是使用单文件module定义的,编译器会在sub1目录下搜寻foo.rs和bar.rs:

// organizing-rust-code/rustc-only/multi/multi-file-with-deps/sub1/foo.rs
pub fn func1() {
    println!("called {}::func1()", module_path!());
}

// organizing-rust-code/rustc-only/multi/multi-file-with-deps/sub1/bar.rs
pub fn func1() {
    println!("called {}::func1()", module_path!());
}

而main.rs中的sub2也是一个单文件的module,其源码位于顶层目录下的sub2.rs文件中:

// organizing-rust-code/rustc-only/multi/multi-file-with-deps/sub2.rs
pub fn func1() {
    println!("called {}::func1()", module_path!());
}

现在我们来编译和执行一下这个既有外部依赖,又是多文件且有多个module的rustc-only项目:

$rustc --verbose  --extern rand=rand-0.8.5/target/debug/deps/librand-9a91ea8db926e840.rlib -L rand-0.8.5/target/debug/deps  --extern rand_core=librand_core-fc905f6ca5f8533b.rlib --extern getrandom=libgetrandom-df6a8e95e188fc56.rlib --extern cfg_if=libcfg_if-cd6bebf18fb9c234.rlib --extern libc=liblibc-f16531562d07b476.rlib --extern rand_chacha=librand_chacha-6fe22bd8b3bb228c.rlib --extern ppv_lite86=libppv_lite86-f1d97d485bc43617.rlib  main.rs 

$./main
current module: main
Random number: 2691905579
called main::sub1::func1()
called main::sub1::foo::func1()
called main::sub1::bar::func1()
called main::sub2::func1()
called main::sub3::func1()
called main::sub3::func2()
called main::func1()

上面示例演示了三种rust module的定义方法:

  1. 直接将定义嵌入在某个rust源文件中:
mod module_name {

}
  1. 通过module_name.rs
  2. 通过module_name/mod.rs

在一个单crate的项目中,通过rust module可以满足项目内部代码组织的需要。

最后,我们再来看一个有多个crate的项目形式。

4.2.4 有多个crate的项目

下面是一个有着多个crate项目的示例:

// organizing-rust-code/rustc-only/workspace

$tree -L 2 -F
.
├── main.rs
├── my_local_crate1/
│   └── lib.rs
└── my_local_crate2/
    └── lib.rs

在这个示例中有三个crate,一个是顶层的binary类型的crate,入口为main.rs,另外两个都是lib类型的crate,入口都在lib.rs中,我们贴一下他们的源码:

// organizing-rust-code/rustc-only/workspace/main.rs
extern crate my_local_crate1;
extern crate my_local_crate2;

fn main() {
    let x = 5;
    let y = my_local_crate1::add_one(x);
    let z = my_local_crate2::multiply_two(y);
    println!("Result: {}", z);
}

// organizing-rust-code/rustc-only/workspace/my_local_crate1/lib.rs
pub fn add_one(x: i32) -> i32 {
    x + 1
}

// organizing-rust-code/rustc-only/workspace/my_local_crate2/lib.rs
pub fn multiply_two(x: i32) -> i32 {
    x * 2
}

要构建这个带有三个crate的项目,我们需要首先编译my_local_crate1和my_local_crate2这两个lib crates:

$rustc --crate-type lib --crate-name my_local_crate1 my_local_crate1/lib.rs
$rustc --crate-type lib --crate-name my_local_crate2 my_local_crate2/lib.rs

这会在项目顶层目录下生成两个rlib文件:

$ls  |grep rlib
libmy_local_crate1.rlib
libmy_local_crate2.rlib

之后,我们就可以用之前学到的方法编译binary crate了:

$rustc --extern my_local_crate1=libmy_local_crate1.rlib --extern my_local_crate2=libmy_local_crate2.rlib main.rs

上述的几个rustc-only的rust项目都是hard模式的,即一切都需要手工去做,包括下载crate、编译crate时传入各种路径等。在真正的生产中,Rustacean们是不会这么做的,而是会直接使用cargo对rust项目进行管理。接下来,我们就来系统地看一下使用cargo进行rust项目管理以及对应的rust代码组织形式。

4.3 使用cargo管理的Rust项目

在前面的章节中,我们见识过了:Rust的包管理器Cargo是一个强大的工具,可以帮助我们轻松地管理Rust项目,cargo才是生产类项目的项目构建管理工具标准,它可以让Rustacean避免复杂的手工rustc操作。Cargo提供了许多功能,包括依赖项管理、构建和测试等。不过在这篇文章中,我不会介绍这些功能,而是看看使用cargo管理的Rust项目都有哪些代码组织模式。

Rust项目的代码组织结构可以分为两类:单一package和多个package。

什么是package?在之前的rust-only项目中,我们可从未见到过package!package是cargo引入的一个管理单元概念,它指的是一个独立的Rust项目,包含了源代码、依赖项和配置信息。每个Package都有一个唯一的名称和版本号,用于标识和管理项目。因此,在the cargo book中,cargo也被称为“Rust package manager”,crates.io也被称为“the Rust community’s package registry”。

最能直观体现package存在的就是下面Cargo.toml中的配置了:

[package]
name = "hello_world"
version = "0.1.0"
edition = "2021"

[dependencies]

下面我们就来看看不同类型的rust package的代码组织形式。我们先从单一package形态的项目来开始。

4.3.1 单一package的rust项目

单一package项目是指整个项目只有一个Cargo.toml文件。这种项目还可以进一步分为三类:

  1. 单一Binary Crate
  2. 单一Library Crate
  3. 多个Binary Crate和一个Library Crate

下面我们分别举例来说明一下这三类项目。

4.3.1.1 单一Binary Crate

我们进入organizing-rust-code/cargo/single-package/single-binary-crate,然后执行下面命令来创建一个单一Binary Crate的项目:

$cargo new hello_world --bin
     Created binary (application) `hello_world` package

这个例子我们在之前的章节中也是见过的,它的结构如下:

$tree hello_world
hello_world
├── Cargo.toml
└── src
    └── main.rs

1 directory, 2 files

默认生成的Cargo.toml内容如下:

[package]
name = "hello_world"
version = "0.1.0"
edition = "2021"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]

使用cargo build即可完成该项目的构建:

$cargo build
   Compiling hello_world v0.1.0 (/Users/tonybai/Go/src/github.com/bigwhite/experiments/rust-guide-for-gopher/organizing-rust-code/cargo/single-package/single-binary-crate/hello_world)
    Finished dev [unoptimized + debuginfo] target(s) in 1.16s

为了更显式地体现这是一个binary crate,我们可以在Cargo.toml增加如下内容:

[[bin]]
name = "hello_world"
path = "src/main.rs"

这不会影响cargo的构建结果!

通过cargo run可以查看构建出的可执行文件的运行结果:

$cargo run
    Finished dev [unoptimized + debuginfo] target(s) in 0.06s
     Running `target/debug/hello_world`
Hello, world!

接下来,我们再来看看单一library crate的rust项目。

4.3.1.2 单一Library Crate

我们进入organizing-rust-code/cargo/single-package/single-library-crate,然后执行下面命令来创建一个单一Library Crate的项目:

$cargo new my_library --lib
     Created library `my_library` package

创建后的my_library项目的结构如下:

$tree
.
├── Cargo.toml
└── src
    └── lib.rs

默认生成的Cargo.toml如下:

[package]
name = "my_library"
version = "0.1.0"
edition = "2021"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]

和binary crate的一样,我们也可以显式指定target:

[lib]
name = "my_library"
path = "src/lib.rs"

注意,这里是[lib]而不是[[lib]],这是因为在一个carge package中最多只能存在一个library crate,但binary crate可以有多个。

接下来,我们就看看一个由多个binary crate和一个library crate混合构成的rust项目。

4.3.1.3 多个Binary Crate和一个Library Crate

我们在organizing-rust-code/cargo/single-package/hybrid-crates下面执行如下命令创建这个多crates混合项目:

$cargo new my_project
     Created binary (application) `my_project` package

上述命令默认创建了一个binary crate的project,我们需要配置一下Cargo.toml,将其改造为多个crates并存的project:

[package]
name = "my_project"
version = "0.1.0"
edition = "2021"

[[bin]]
name = "cmd1"
path = "src/main1.rs"

[[bin]]
name = "cmd2"
path = "src/main2.rs"

[lib]
name = "my_library"
path = "src/lib.rs"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]

这里定义了三个crates。两个binary crates: cmd1、cmd2以及一个library crate:my_library。

如果我们执行cargo build,cargo会将三个crate都构建出来:

$cargo build
   Compiling my_project v0.1.0 (/Users/tonybai/Go/src/github.com/bigwhite/experiments/rust-guide-for-gopher/organizing-rust-code/cargo/single-package/hybrid-crates/my_project)
    Finished dev [unoptimized + debuginfo] target(s) in 0.80s

我们可以在target/debug下找到构建出的crates:cmd1、cmd2和libmy_library.rlib:

$ls target/debug
build/          cmd1.d          cmd2.d          examples/       libmy_library.d
cmd1*           cmd2*           deps/           incremental/        libmy_library.rlib

我们也可以通过cargo分别运行两个binary crate:

$cargo run --bin cmd1
    Finished dev [unoptimized + debuginfo] target(s) in 0.02s
     Running `target/debug/cmd1`
cmd1

$cargo run --bin cmd2
    Finished dev [unoptimized + debuginfo] target(s) in 0.00s
     Running `target/debug/cmd2`
cmd2

4.3.1.4 典型的cargo package

在The cargo book中,有一个典型的cargo package的示例:

.
├── Cargo.lock
├── Cargo.toml
├── src/
│   ├── lib.rs
│   ├── main.rs
│   └── bin/
│       ├── named-executable.rs
│       ├── another-executable.rs
│       └── multi-file-executable/
│           ├── main.rs
│           └── some_module.rs
├── benches/
│   ├── large-input.rs
│   └── multi-file-bench/
│       ├── main.rs
│       └── bench_module.rs
├── examples/
│   ├── simple.rs
│   └── multi-file-example/
│       ├── main.rs
│       └── ex_module.rs
└── tests/
    ├── some-integration-tests.rs
    └── multi-file-test/
        ├── main.rs
        └── test_module.rs

在这样一个典型的项目中:

  • Cargo.toml和Cargo.lock文件存储在包的根目录(包根目录)中。
  • 源代码位于src目录中。
  • 默认的库文件是src/lib.rs。
  • 默认的可执行文件是src/main.rs。
  • 其他可执行文件可以放在src/bin/目录中。
  • 基准测试位于benches目录中。
  • 示例位于examples目录中。
  • 集成测试位于tests目录中。

4.3.2 多package的rust项目

一些中大型的Rust项目都是多package的,比如rust的异步编程事实标准tokio库、刚刚升级为Apache基金会顶级项目的SQL查询引擎datafusion等。以tokio为例,这些项目的顶层Cargo.toml都是这样的:

// https://github.com/tokio-rs/tokio/blob/master/Cargo.toml
[workspace]
resolver = "2"
members = [
  "tokio",
  "tokio-macros",
  "tokio-test",
  "tokio-stream",
  "tokio-util",

  # Internal
  "benches",
  "examples",
  "stress-test",
  "tests-build",
  "tests-integration",
]

[workspace.metadata.spellcheck]
config = "spellcheck.toml"

上面这个Cargo.toml示例与我们在前面见到的Cargo.toml都不一样,它并不包含package配置,其主要的配置为workspace。我们看到workspace的members字段中配置了该项目下的其他package。正是通过这个配置,cargo可以在一个项目里管理和构建多个package。

工作空间(Workspace)是一组一个或多个包(Package)的集合,这些包称为工作空间成员(Workspace Members),它们一起被管理。接下来,我们就来创建一个多package的cargo项目。

4.3.2.1 cargo管理的多package项目

由于cargo并没有提供cargo new my-pakcage –workspace这样的命令行参数,项目的顶层Cargo.toml需要我们手动创建和编辑。

$cd organizing-rust-code/cargo/multi-packages
$mkdir my-workspace
$cd my-workspace
$cargo new package1 --bin
     Created binary (application) `package1` package
$cargo new package2 --lib
     Created library `package2` package
$cargo new package3 --lib
     Created library `package3` package

接下来,我们手工创建和编辑一下项目顶层的Cargo.toml如下:

// organizing-rust-code/cargo/multi-packages/my-workspace/Cargo.toml
[workspace]
resolver = "2"
members = [
    "package1",
    "package2",
    "package3",
]

保存后,我们可以在项目顶层目录下使用下面命令检查整个工作空间(workspace)中的所有包(package),确保它们的代码正确无误,不包含任何编译错误:

$cargo check --workspace
    Checking package1 v0.1.0 (/Users/tonybai/Go/src/github.com/bigwhite/experiments/rust-guide-for-gopher/organizing-rust-code/cargo/multi-packages/my-workspace/package1)
    Checking package2 v0.1.0 (/Users/tonybai/Go/src/github.com/bigwhite/experiments/rust-guide-for-gopher/organizing-rust-code/cargo/multi-packages/my-workspace/package2)
    Checking package3 v0.1.0 (/Users/tonybai/Go/src/github.com/bigwhite/experiments/rust-guide-for-gopher/organizing-rust-code/cargo/multi-packages/my-workspace/package3)
    Finished dev [unoptimized + debuginfo] target(s) in 0.18s

在顶层目录执行cargo build,cargo会build工作空间中的所有package:

$cargo build
   Compiling package3 v0.1.0 (/Users/tonybai/Go/src/github.com/bigwhite/experiments/rust-guide-for-gopher/organizing-rust-code/cargo/multi-packages/my-workspace/package3)
   Compiling package2 v0.1.0 (/Users/tonybai/Go/src/github.com/bigwhite/experiments/rust-guide-for-gopher/organizing-rust-code/cargo/multi-packages/my-workspace/package2)
   Compiling package1 v0.1.0 (/Users/tonybai/Go/src/github.com/bigwhite/experiments/rust-guide-for-gopher/organizing-rust-code/cargo/multi-packages/my-workspace/package1)
    Finished dev [unoptimized + debuginfo] target(s) in 0.64s

构建后,该项目的目录结构变成下面这个样子:

$tree -L 2 -F
.
├── Cargo.lock
├── Cargo.toml
├── package1/
│   ├── Cargo.toml
│   └── src/
├── package2/
│   ├── Cargo.toml
│   └── src/
├── package3/
│   ├── Cargo.toml
│   └── src/
└── target/
    ├── CACHEDIR.TAG
    └── debug/

我们看到该项目下的所有package共享一个共同的 Cargo.lock 文件,该文件位于工作空间的根目录下。并且,所有包共享一个共同的输出目录,默认情况下是工作空间根目录下的一个名为target的目录,该target目录下的布局如下:

$tree -F -L 2 ./target
./target
├── CACHEDIR.TAG
└── debug/
    ├── build/
    ├── deps/
    ├── examples/
    ├── incremental/
    ├── libpackage2.d
    ├── libpackage2.rlib
    ├── libpackage3.d
    ├── libpackage3.rlib
    ├── package1*
    └── package1.d

我们在这下面可以找到所有package的编译输出结果,比如package1、libpackage2.rlib以及libpackage3.rlib。

当然,你也可以指定一个package来构建或运行:

$cargo build -p package1
    Finished dev [unoptimized + debuginfo] target(s) in 0.00s
$cargo build -p package2
    Finished dev [unoptimized + debuginfo] target(s) in 0.00s
$cargo run -p package1
    Finished dev [unoptimized + debuginfo] target(s) in 0.00s
     Running `target/debug/package1`
Hello, world!

4.3.2.2 带有外部依赖和内部依赖的多package项目

我们复制一份my-workspace,改名为my-workspace-with-deps,修改一下package1/src/main.rs,为其增加外部依赖rand crate:

// organizing-rust-code/cargo/multi-packages/my-workspace-with-deps/package1/src/main.rs
extern crate rand;

use rand::Rng;

fn main() {
    let mut rng = rand::thread_rng();
    let num: u32 = rng.gen();
    println!("Random number: {}", num);
}

接下来,我们需要修改一下package1/Cargo.toml,手工加上对rand crate的依赖配置:

// organizing-rust-code/cargo/multi-packages/my-workspace-with-deps/package1/Cargo.toml
[package]
name = "package1"
version = "0.1.0"
edition = "2021"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]
rand = "0.8.5"

保存后,我们执行package1的构建:

$cargo build -p package1
  Downloaded getrandom v0.2.14 (registry `rsproxy`)
  Downloaded libc v0.2.154 (registry `rsproxy`)
  Downloaded 2 crates (780.6 KB) in 1m 07s
   Compiling libc v0.2.154
   Compiling cfg-if v1.0.0
   Compiling ppv-lite86 v0.2.17
   Compiling getrandom v0.2.14
   Compiling rand_core v0.6.4
   Compiling rand_chacha v0.3.1
   Compiling rand v0.8.5
   Compiling package1 v0.1.0 (/Users/tonybai/Go/src/github.com/bigwhite/experiments/rust-guide-for-gopher/organizing-rust-code/cargo/multi-packages/my-workspace-with-deps/package1)
    Finished dev [unoptimized + debuginfo] target(s) in 1m 46s

我们看到:cargo会自动下载package1的直接外部依赖以及相关间接依赖。构建成功后,可以执行一下package1的编译结果:

$cargo run -p package1
    Finished dev [unoptimized + debuginfo] target(s) in 0.09s
     Running `target/debug/package1`
Random number: 3840180495

接下来,我们再为package1添加内部依赖,比如依赖package2的编译结果:

// organizing-rust-code/cargo/multi-packages/my-workspace-with-deps/package1/src/main.rs

extern crate package2;
extern crate rand;

use rand::Rng;

fn main() {
    let mut rng = rand::thread_rng();
    let num: u32 = rng.gen();
    println!("Random number: {}", num);
    let result = package2::add(2, 2);
    println!("result: {}", result);
}

// organizing-rust-code/cargo/multi-packages/my-workspace-with-deps/package1/Cargo.toml
[package]
name = "package1"
version = "0.1.0"
edition = "2021"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]
rand = "0.8.5"
package2 = { path = "../package2" }

我们看到:package1的main.rs依赖package2这个crate中的add函数,我们在package1的Cargo.toml中为package1添加了新依赖package2,由于package2仅仅存放在本地,所以这里我们使用了path方式指定package2的位置。

我们执行一下添加内部依赖后的package1:

$cargo run -p package1
    Finished dev [unoptimized + debuginfo] target(s) in 0.02s
     Running `target/debug/package1`
Random number: 2485645524
result: 4

4.4 小结

本文循序渐进地讨论了在Rust项目中如何组织代码的问题,这对于Rust初学者来说尤为有用。

我们首先回顾了Go语言中的代码组织方式,介绍了Go项目代码组织的两个层级:module和package。然后,我们将Rust项目可以分为两种类型:使用rustc编译器的项目和使用Cargo的项目。

对于rustc-only的项目,开发者需要编写自己的构建脚本来管理项目的构建过程。

文章从最简单的单文件rustc-only项目开始介绍,展示了如何使用rustc编译器来编译和运行这种项目,并逐步介绍了带有外部依赖的rustc-only项目以及多文件项目的情况,引出了rust module概念。

rustc-only项目很少用于生产环境,这种方式主要用于学习和了解Rustc编译器的功能机制以及Rust语言的代码组织抽象。

在实际开发中,使用Cargo来创建和管理Rust包是常见的做法。在本章的后半段,我们介绍了使用cargo管理的rust项目的代码组织情况,包括单package项目和多package项目以及如何为项目引入外部和内部依赖。

总体而言,本文旨在帮助初学者理解和掌握Rust项目的代码组织结构,以提高学习效率和学习效果。通过介绍rustc-only项目和cargo管理的项目,读者可以逐步了解Rust代码组织的基本概念和实践方法。

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

4.5 参考资料


Gopher部落知识星球在2024年将继续致力于打造一个高品质的Go语言学习和交流平台。我们将继续提供优质的Go技术文章首发和阅读体验。同时,我们也会加强代码质量和最佳实践的分享,包括如何编写简洁、可读、可测试的Go代码。此外,我们还会加强星友之间的交流和互动。欢迎大家踊跃提问,分享心得,讨论技术。我会在第一时间进行解答和交流。我衷心希望Gopher部落可以成为大家学习、进步、交流的港湾。让我相聚在Gopher部落,享受coding的快乐! 欢迎大家踊跃加入!

img{512x368}
img{512x368}

img{512x368}
img{512x368}

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

Gopher Daily(Gopher每日新闻) – https://gopherdaily.tonybai.com

我的联系方式:

  • 微博(暂不可用):https://weibo.com/bigwhite20xx
  • 微博2:https://weibo.com/u/6484441286
  • 博客:tonybai.com
  • github: https://github.com/bigwhite
  • Gopher Daily归档 – https://github.com/bigwhite/gopherdaily

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

如发现本站页面被黑,比如:挂载广告、挖矿等恶意代码,请朋友们及时联系我。十分感谢! Go语言第一课 Go语言精进之路1 Go语言精进之路2 Go语言编程指南
商务合作请联系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