Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions vermeer/.gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -87,3 +87,14 @@ node_modules/
# Others #
######################
test/case/

# Downloaded binaries (should be downloaded via scripts/download_binaries.sh) #
######################
tools/supervisord/*/supervisord
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ 建议补充 .gitignore 模式

当前的 .gitignore 只忽略了特定架构的文件。建议添加通配符模式以支持更多平台:

Suggested change
tools/supervisord/*/supervisord
# Downloaded binaries (should be downloaded via scripts/download_binaries.sh) #
######################
tools/supervisord/*/supervisord*
tools/protoc/*/protoc*
tools/protoc/*/bin/
tools/protoc/*/include/

这样可以覆盖 Windows 下的 .exe 文件以及其他平台变体。

tools/protoc/*/protoc
tools/protoc/*/bin/
tools/protoc/*/include/

# Generated files (should be generated via go generate) #
######################
asset/assets_vfsdata.go
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

正确处理生成文件

删除 assets_vfsdata.go 并将其加入 .gitignore 是正确的做法。这个文件应该在构建时动态生成,而不应该提交到版本控制中。

这样可以:

  • 减少代码库大小
  • 避免每次 UI 更新时产生大量 diff
  • 确保使用最新的 UI 资源构建

85 changes: 85 additions & 0 deletions vermeer/Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
#
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements. See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#

.PHONY: all init download-binaries generate-assets build clean help
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Makefile 最佳实践

.PHONY 声明建议按功能分组,并添加注释说明每个目标的用途,提高可维护性:

Suggested change
.PHONY: all init download-binaries generate-assets build clean help
# Build targets
.PHONY: all init build build-linux-amd64 build-linux-arm64
# Setup and generation targets
.PHONY: download-binaries generate-assets
# Cleanup targets
.PHONY: clean clean-all
# Help target
.PHONY: help


# Default target
all: generate-assets build

# Initialize project (first time setup)
init: download-binaries
@echo "Installing Go dependencies..."
go mod download
@echo "Project initialized successfully!"

# Download binary dependencies (supervisord, protoc)
download-binaries:
@echo "Downloading binary dependencies..."
@./scripts/download_binaries.sh

# Generate assets (vfsdata.go for web UI)
generate-assets:
@echo "Generating assets..."
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

‼️ Critical - 缺少错误处理

Makefile 中的多个目标没有进行错误检查。建议在关键步骤后添加错误处理,特别是 download-binariesgenerate-assets 命令。

建议改进:

Suggested change
@echo "Generating assets..."
download-binaries:
@echo "Downloading binary dependencies..."
@./scripts/download_binaries.sh || (echo "Failed to download binaries" && exit 1)
generate-assets:
@echo "Generating assets..."
@cd asset && go generate || (echo "Failed to generate assets" && exit 1)
@echo "Assets generated successfully!"

@cd asset && go generate
@echo "Assets generated successfully!"

# Build vermeer binary
build:
@echo "Building vermeer..."
@go build -o vermeer
@echo "Build completed: ./vermeer"

# Build for specific platform
build-linux-amd64:
@echo "Building for linux/amd64..."
@CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o vermeer

build-linux-arm64:
@echo "Building for linux/arm64..."
@CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o vermeer

# Clean generated files and binaries
clean:
@echo "Cleaning..."
@rm -f vermeer
@rm -f asset/assets_vfsdata.go
@echo "Clean completed!"

# Clean including downloaded binaries
clean-all: clean
@echo "Cleaning downloaded binaries..."
@rm -rf tools/supervisord/*/supervisord
@rm -rf tools/protoc/*/protoc
@rm -rf tools/protoc/*/bin
@rm -rf tools/protoc/*/include
@echo "All clean completed!"

# Help
help:
@echo "Vermeer Build System"
@echo ""
@echo "Usage:"
@echo " make init - First time setup (download binaries + go mod download)"
@echo " make download-binaries - Download supervisord and protoc binaries"
@echo " make generate-assets - Generate assets_vfsdata.go from web UI"
@echo " make build - Build vermeer for current platform"
@echo " make build-linux-amd64 - Build for Linux AMD64"
@echo " make build-linux-arm64 - Build for Linux ARM64"
@echo " make clean - Remove generated files and binaries"
@echo " make clean-all - Remove everything including downloaded tools"
@echo " make all - Generate assets and build (default)"
@echo " make help - Show this help message"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 文档完善建议

help 目标中的描述可以更详细一些,建议添加使用场景说明:

Suggested change
@echo " make help - Show this help message"
help:
@echo "Vermeer Build System"
@echo ""
@echo "Usage:"
@echo " make init - First time setup (download binaries + go mod download)"
@echo " make download-binaries - Download supervisord and protoc binaries for your platform"
@echo " make generate-assets - Generate assets_vfsdata.go from web UI (required before build)"
@echo " make build - Build vermeer for current platform (default: local architecture)"
@echo " make build-linux-amd64 - Build for Linux AMD64 (for deployment)"
@echo " make build-linux-arm64 - Build for Linux ARM64 (for ARM servers)"
@echo " make clean - Remove generated files and binaries (keep downloaded tools)"
@echo " make clean-all - Remove everything including downloaded tools"
@echo " make all - Generate assets and build (default target)"
@echo " make help - Show this help message"

74 changes: 52 additions & 22 deletions vermeer/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,42 +48,72 @@ Configuration file reference config/supervisor.conf
./supervisord -c supervisor.conf -d
````

## Compile
Required
* go 1.23
## Build from Source

### Install dependencies
### Requirements
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ 跨平台兼容性说明不足

README 中提到需要 curlunzip 工具,但没有说明不同操作系统(Linux、macOS、Windows)的具体要求和差异。

建议补充:

### Requirements
* Go 1.23 or later
* `curl` and `unzip` utilities (for downloading dependencies)
  - Linux: Usually pre-installed, or install via package manager
  - macOS: Pre-installed
  - Windows: Install via WSL, Git Bash, or use native alternatives
* Internet connection (for first-time setup)

* Go 1.23 or later
* `curl` and `unzip` utilities (for downloading dependencies)
* Internet connection (for first-time setup)

### Quick Start

**Recommended**: Use Makefile for building:

```bash
# First time setup (downloads binary dependencies)
make init

# Build vermeer
make
```
go mod tidy

**Alternative**: Use the build script:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

‼️ build.sh 使用说明不完整

文档中提到可以使用 ./build.sh amd64./build.sh arm64,但是:

  1. 没有说明 build.sh 的完整参数列表
  2. 没有说明如果不传参数会发生什么(默认行为是什么?)
  3. 没有说明构建失败时如何排查

建议补充:

**Alternative**: Use the build script:

```bash
# For AMD64 (default if no parameter provided)
./build.sh amd64

# For ARM64
./build.sh arm64

# The script will:
# - Auto-detect your OS and architecture if no parameter is provided
# - Download required tools if not present
# - Generate assets and build the binary
# - Exit with error message if any step fails


```bash
# For AMD64
./build.sh amd64

# For ARM64
./build.sh arm64
```

### Local compile
The build process will automatically:
1. Download required binary tools (supervisord, protoc)
2. Generate web UI assets
3. Build the vermeer binary

### Build Targets

```bash
make build # Build for current platform
make build-linux-amd64 # Build for Linux AMD64
make build-linux-arm64 # Build for Linux ARM64
make clean # Clean generated files
make help # Show all available targets
```
go build

### Development Build

For development with hot-reload of web UI:

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ 开发构建说明不清晰

文档中提到 go build -tags=dev 用于开发环境的热重载,但是:

  1. 没有说明 dev tag 的具体作用机制
  2. 没有说明如何实现热重载(需要额外的工具吗?)
  3. 与 assets_vfsdata.go 的关系不明确

建议改进:

### Development Build

For development with hot-reload of web UI:

```bash
# Build with dev tag - serves UI files directly from disk instead of embedded assets
go build -tags=dev

# This allows you to modify UI files and see changes immediately without rebuilding
# Note: assets_vfsdata.go is not used when dev tag is enabled

```bash
go build -tags=dev
```

---

### install grpc protobuf dependencies
````
go install google.golang.org/protobuf/cmd/[email protected] \
go install google.golang.org/grpc/cmd/[email protected]
````

### protobuf build
````
../../tools/protoc/osxm1/protoc *.proto --go-grpc_out=. --go_out=.
````
### Protobuf Development

If you need to regenerate protobuf files:

### Cross Compile
```bash
# Install protobuf Go plugins
go install google.golang.org/protobuf/cmd/[email protected]
go install google.golang.org/grpc/cmd/[email protected]

````
linux: GOARCH=amd64 GOOS=linux go build
CC=x86_64-linux-musl-gcc CGO_ENABLED=1 GOOS=linux GOARCH=amd64 go build -buildmode=plugin
````
# Generate protobuf files
tools/protoc/osxm1/protoc *.proto --go-grpc_out=. --go_out=.
```

---

Expand Down
72 changes: 50 additions & 22 deletions vermeer/README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,44 +48,72 @@ worker: ./vermeer --env=worker01
./supervisord -c supervisor.conf -d
````

## 编译
## 从源码编译

* Go 1.23
### 环境要求
* Go 1.23 或更高版本
* `curl` 和 `unzip` 工具(用于下载依赖)
* 互联网连接(首次构建时需要)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ 中文文档与英文文档一致性

中文文档和英文文档存在相同的问题:

  1. 跨平台兼容性说明不足
  2. build.sh 使用说明不完整
  3. 开发构建(dev tag)的说明不够清晰

建议参考英文 README 的改进建议,在中文文档中也做相应补充。保持两个版本的文档同步更新。


### 安装依赖项
### 快速开始

```
go mod tidy
**推荐**: 使用 Makefile 进行构建:

```bash
# 首次设置(下载二进制依赖)
make init

# 构建 vermeer
make
```

### 本地编译
**替代方案**: 使用构建脚本:

```bash
# AMD64 架构
./build.sh amd64

# ARM64 架构
./build.sh arm64
```
go build

构建过程会自动:
1. 下载所需的二进制工具(supervisord, protoc)
2. 生成 Web UI 资源文件
3. 构建 vermeer 二进制文件

### 构建目标

```bash
make build # 为当前平台构建
make build-linux-amd64 # 为 Linux AMD64 构建
make build-linux-arm64 # 为 Linux ARM64 构建
make clean # 清理生成的文件
make help # 显示所有可用目标
```

### grpc protobuf 依赖项安装
````
go install google.golang.org/protobuf/cmd/[email protected] \
go install google.golang.org/grpc/cmd/[email protected]
````
### 开发构建

如需在开发环境中热重载 Web UI:

```bash
go build -tags=dev
```

### protobuf build
生成protobuf文件
````
../../tools/protoc/osxm1/protoc *.proto --go-grpc_out=. --go_out=.
````
---

### Protobuf 开发

如需重新生成 protobuf 文件:

### 交叉编译
```bash
# 安装 protobuf Go 插件
go install google.golang.org/protobuf/cmd/[email protected]
go install google.golang.org/grpc/cmd/[email protected]

````
linux: GOARCH=amd64 GOOS=linux go build
CC=x86_64-linux-musl-gcc CGO_ENABLED=1 GOOS=linux GOARCH=amd64 go build -buildmode=plugin
````
# 生成 protobuf 文件
tools/protoc/osxm1/protoc *.proto --go-grpc_out=. --go_out=.
```

---

Expand Down
609 changes: 0 additions & 609 deletions vermeer/asset/assets_vfsdata.go
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This file can not be generated automatically. I am working on this.

This file was deleted.

10 changes: 10 additions & 0 deletions vermeer/build.sh
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,16 @@ go env -w GONOSUMDB=\* ## 目前有一些代码库还
#go env -w CXX=/opt/compiler/gcc-8.2/bin/g++

go mod download

# Download binary dependencies if not exist
echo "Checking binary dependencies..."
./scripts/download_binaries.sh

# Generate assets if not exist
if [ ! -f "asset/assets_vfsdata.go" ]; then
echo "Generating assets..."
cd asset && go generate && cd ..
fi
ARCH=$1
CGO_ENABLED=0 GOOS=linux GOARCH="$ARCH" go build

Expand Down
Loading
Loading