# gobuild

**Repository Path**: vipkwds/gobuild

## Basic Information

- **Project Name**: gobuild
- **Description**: -
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-02
- **Last Updated**: 2026-08-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# gobuild

一个简单易用的跨平台 Go 二进制文件打包工具，封装 `go build` / `go install` 的常用参数。

## 安装

### 1. 标准安装（远程拉取）

直接从 gitee 上的 module 路径安装，免 clone：

```bash
go install gitee.com/vipkwds/gobuild@latest
```

会装到 `$GOBIN`，默认是 `$GOPATH/bin`（Windows 下通常是 `%USERPROFILE%\go\bin`）。

### 2. clone 到本地构建

```bash
git clone https://gitee.com/vipkwds/gobuild.git
cd gobuild

# 装到 $GOBIN
go install .

# 或本地构建（默认产物在当前目录）
go build -o gobuild.exe .
```

自定义构建时间戳（让 `gobuild -h` 末端显示日期）：

```bash
go build -ldflags="-X main.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)" -o gobuild.exe .
```

## 子命令

### `gobuild build [platform]`

构建 Go 程序到指定平台。平台支持：

- 单个：`linux` / `darwin` / `windows`
- 精确：`linux/amd64` / `windows/386` 等
- 多个：逗号分隔 `linux,darwin`
- 全部：`all`

示例：

```bash
gobuild build                       # 当前平台
gobuild build linux                 # linux/amd64（linux 默认仅 amd64）
gobuild build linux,darwin          # 多个平台
gobuild build linux/amd64           # 精确到 arch
gobuild build all --upx             # 所有平台 + UPX 压缩
```

### `gobuild install [package]`

对齐 `go install`：默认输出到 `$GOBIN`，文件名不带 `-os-arch` 后缀。

- positional arg 是 Go package 路径（`./cmd/foo`、`../sibling/cmd/bar`、`.` 等），不是 platform
- 仅安装当前平台（`go install` 也是）
- 仅支持单个 package，不支持多 package / `@version` 远程 install（这是 `go install` 已经做好的事）
- `--name` 默认取 package 路径最后一段（`./cmd/foo` → `foo`）；`--name` 显式给值则覆盖
- `-o, --output` 默认 `$GOBIN`，可覆盖

示例：

```bash
gobuild install                       # 等价 go install .
gobuild install ./cmd/foo             # 等价 go install ./cmd/foo，binary 名 foo
gobuild install ./cmd/foo --name bar  # binary 名覆盖为 bar
gobuild install -o /usr/local/bin     # 自定义安装目录
gobuild install ./cmd/foo --upx       # 装并 UPX 压缩（隐式禁用 CGo）
```

### `gobuild list`

列出所有支持的平台。

### `gobuild init`

在当前目录创建 `gobuild.yml` 配置文件（占位）。

### `gobuild -h`

显示帮助 + 一行 `Build Time: <RFC3339 UTC>`，可用于间接判断二进制是否为新构建。

## 通用 Flag

| Flag | 默认 | 说明 |
|---|---|---|
| `-o, --output` | `.`（build）/ `$GOBIN`（install） | 输出/安装目录 |
| `--name` | 当前目录名 | 输出文件名 |
| `--tags` | （空） | 构建标签 |
| `--ldflags` | `-s -w` | 链接参数 |
| `--static` | `false` | 静态链接：追加 `-extldflags=-static` |
| `--no-cgo` | `false` | 禁用 CGo：设置 `CGO_ENABLED=0` |
| `--upx` | `false` | 使用 UPX 压缩，**隐式禁用 CGo** |
| `--hide-console` | `false` | 隐藏 Windows 控制台窗口：Windows 目标追加 `-H windowsgui`；其它平台 no-op |

### `--static` 与 `--no-cgo` 的区别

- `--no-cgo`：禁用 CGo，二进制不再依赖 libc 等动态库。**纯 Go 项目想要静态二进制通常这一个就够**。
- `--static`：追加 `-extldflags=-static`，让 CGo 项目的外部链接器也静态。纯 Go 项目下该 flag 是 no-op。
- 两个 flag 独立，可单独或组合使用。

### `--upx` 与 CGo

UPX 不支持 CGo 链接的 PE 格式。使用 `--upx` 时会自动设置 `CGO_ENABLED=0` 并打 warning，不需要再单独传 `--no-cgo`。

### `--hide-console`（Windows）

链接时切到 GUI 子系统（`-H windowsgui`），运行时不弹黑色 console 窗口。常用于后台 daemon / 托盘工具 / 不想让用户看到命令行的程序。**只在 Windows 目标下生效**；其它平台传了也是 no-op，不会污染 ldflags。

注意：这只决定"运行时是否弹 console 窗口"，不解决"代码本身是否调用了 GUI API"。一个纯 CLI 工具加上 `--hide-console` 后，stdout/stderr 仍然写到那扇隐藏的 console，只是用户看不到。

## 已知缺口

- `--app <file.go>`：单文件 Go 编译（已讨论，未实现）