Golang基于README.md定义任务的可执行Markdown任务运行器插件xc的使用

简介

xc 是一个类似于 Make 或 npm run 的任务运行器，旨在更加易于发现和使用。它解决了脚本与其文档分离维护的问题，通过将脚本定义与文档内联来实现。

主要特点

在Markdown文件中将任务定义为代码块
编辑器集成支持（如VSCode、Vim等）

安装

安装说明可以在官方文档中找到。

使用示例

基本示例

在README.md中定义任务：

tag

Deploys a new tag for the repo.

Requires: test

export VERSION=`git rev-list --count HEAD`
echo Adding git tag with version v0.0.${VERSION}
git tag v0.0.${VERSION}
git push origin v0.0.${VERSION}

然后可以通过 xc tag 命令运行此任务。

完整示例

以下是一个完整的README.md示例，展示了如何定义多个任务：

项目任务

test

Test the project.

go test ./...

lint

Run linters.

golangci-lint run

build

Builds the xc binary.

go build ./cmd/xc

tag

Deploys a new tag for the repo.

Specify major/minor/patch with VERSION

Inputs: VERSION

Requires: test

CURRENT_VERSION=`git describe --abbrev=0 --tags 2>/dev/null`
CURRENT_VERSION_PARTS=(${CURRENT_VERSION//./ })
VNUM1=${CURRENT_VERSION_PARTS[0]}
VNUM2=${CURRENT_VERSION_PARTS[1]}
VNUM3=${CURRENT_VERSION_PARTS[2]}

if [[ $VERSION == 'major' ]]
then
  VNUM1=$((VNUM1+1))
  VNUM2=0
  VNUM3=0
elif [[ $VERSION == 'minor' ]]
then
  VNUM2=$((VNUM2+1))
  VNUM3=0
elif [[ $VERSION == 'patch' ]]
then
  VNUM3=$((VNUM3+1))
else
  echo "Invalid version"
  exit 1
fi

NEW_TAG="$VNUM1.$VNUM2.$VNUM3"

echo Adding git tag with version ${NEW_TAG}
git tag ${NEW_TAG}
git push origin ${NEW_TAG}

run-docs

Run the hugo development server.

Directory: doc

hugo serve

build-docs

Build production docs site.

Directory: doc

./build.sh


## 任务特性

1. **依赖管理**：通过 `Requires` 指定任务依赖
2. **输入参数**：通过 `Inputs` 指定任务参数
3. **工作目录**：通过 `Directory` 指定任务运行目录
4. **内联文档**：每个任务都有清晰的描述和使用说明

## 优势

- 任务定义与文档一体化，保持同步
- 即使没有安装 `xc` 工具，用户也可以从README中获取有用的命令
- 简单易用，降低学习成本
- 支持复杂的任务依赖和参数传递

通过这种方式，`xc` 提供了一种简单而强大的方式来管理和执行项目任务，同时保持优秀的文档记录。

更多关于golang基于README.md定义任务的可执行Markdown任务运行器插件xc的使用的实战教程也可以访问 https://www.itying.com/category-94-b0.html

songsunli 1楼

更多关于golang基于README.md定义任务的可执行Markdown任务运行器插件xc的使用的实战系列教程也可以访问 https://www.itying.com/category-94-b0.html

Golang 基于 README.md 定义任务的可执行 Markdown 任务运行器插件 xc

xc 是一个创新的任务运行器，它允许你直接在项目的 README.md 文件中定义可执行任务，然后通过简单的命令行调用这些任务。这种设计使得项目文档和任务定义保持同步，提高了项目的可维护性。

安装 xc

go install github.com/joerdav/xc@latest

基本使用

1. 在 README.md 中定义任务

在项目的 README.md 文件中，使用特殊的代码块标记来定义任务：

# 任务名称
任务描述（可选）

命令1
命令2
命令3


### 2. 示例任务定义

`
```xc
# build
构建项目

go build -o myapp ./cmd/main.go
```

```xc
# test
运行测试并生成覆盖率报告

go test -v -coverprofile=coverage.out ./...
go tool cover -html=coverage.out -o coverage.html
```

3. 运行任务

xc build
xc test

高级功能

任务依赖

xc 支持任务依赖，可以在一个任务中调用其他任务：

# all
运行构建和测试

xc build
xc test


### 环境变量支持

xc 可以读取环境变量：

`
```xc
# run
运行应用程序

./myapp -port=${PORT:-8080}
```

参数传递

可以向任务传递参数：

# greet
输出问候语

echo "Hello, ${1}!"


运行带参数的任务：
```bash
xc greet "World"
```

## Golang 集成示例

以下是一个完整的 Golang 项目 README.md 示例，展示了如何与 Go 工具链集成：

`
# My Go Project

```xc
# deps
安装依赖

go mod download
```

```xc
# build
构建项目

go build -o bin/app ./cmd/app
```

```xc
# test
运行测试

go test -v ./...
```

```xc
# coverage
生成测试覆盖率报告

go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out -o coverage.html
```

```xc
# lint
运行静态分析

golangci-lint run
```

```xc
# all
运行完整构建流程

xc deps
xc lint
xc test
xc build
```

创建自定义 xc 插件

你还可以创建自己的 xc 插件来扩展功能。以下是创建一个简单插件的示例：

package main

import (
	"fmt"
	"os"

	"github.com/joerdav/xc/plugin"
)

func main() {
	p := plugin.New("myplugin", "A custom xc plugin", func(args []string) error {
		if len(args) > 0 {
			fmt.Printf("Hello from myplugin, you said: %s\n", args[0])
		} else {
			fmt.Println("Hello from myplugin!")
		}
		return nil
	})
	if err := p.Run(); err != nil {
		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
		os.Exit(1)
	}
}

安装并运行自定义插件：

go build -o ~/.xc/plugins/myplugin myplugin.go
xc myplugin

总结

xc 提供了一种创新的方式来管理项目任务：

任务定义与文档保持同步
减少了对复杂构建系统（如Makefile）的依赖
支持任务依赖和参数传递
易于扩展的自定义插件系统

对于Golang项目，xc可以很好地与go工具链集成，提供清晰、可维护的任务定义方式。