开始本教程之前，请确认你已安装以下工具。
本教程面向 macOS 和 Linux 系统。其他系统可能需要额外的前置条件。

​
Go

示例链要求使用 Go 1.25 或更高版本。 
go version
# go version go1.25.0 linux/amd64   # Linux
# go version go1.25.0 darwin/arm64  # macOS
如果尚未安装 Go，请从 go.dev/dl 下载。

​
配置 Go 环境变量

安装 Go 后，请确保 $GOPATH/bin 已加入你的 PATH，这样已安装的二进制文件（例如 exampled）才能被访问。 打开你的 shell 配置文件（macOS 上为 ~/.zshrc，Linux 上为 ~/.bashrc），并添加： 
export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin
然后应用更改： 
source ~/.zshrc    # macOS
source ~/.bashrc   # Linux
验证：go env GOPATH

​
Make

Make 用于在整个教程中执行构建和开发命令。 
make --version
# GNU Make 3.81
大多数 Linux 和 macOS 系统都已预装 Make。如果缺失：
  • macOS: xcode-select --install
  • Linux (Debian/Ubuntu): sudo apt install build-essential

​
Docker

运行 make proto-gen 需要 Docker。该命令会使用 buf 根据模块的 proto 文件生成 Go 代码。 
docker --version
# Docker version 29.2.1
请从 docs.docker.com/get-docker 下载 Docker。 在执行 make proto-gen 之前，必须先启动 Docker。

​
Git

git --version
# git version 2.52.0

​
克隆仓库

克隆 cosmos/example 并进入目录： 
git clone https://github.com/cosmos/example
cd example
该仓库包含本教程系列中会用到的两个分支：
  • main：完整链，已接入完整的 x/counter 模块。
  • tutorial/start：同一条链，但移除了 counter 模块。如果你想从零开始自行构建该模块，请从这里开始。

​
仓库结构

克隆后，仓库结构如下： 
example/
├── exampled/         # Binary entrypoint (main.go + CLI root command)
├── app.go            # Chain application, module wiring lives here
├── proto/            # Proto definitions for all modules
├── x/                # Module implementations
│   └── counter/      # The example counter module
├── tests/            # E2E and integration tests
├── scripts/          # Local node and proto generation scripts
├── docs/             # This tutorial series
└── Makefile          # Build, test, and dev commands

​
各部分所在位置

本节教程将带你了解最常见的链改动类型，并说明它们通常在仓库中的位置：
  • 新增或修改模块：x/<module>/ 和 proto/
  • 将模块接入链：app.go
  • 修改二进制或 CLI：exampled/
  • 运行链或测试：Makefile targets
下一步：快速开始 →
Before starting the tutorial, make sure you have the following tools installed.
This tutorial is intended for macOS and Linux systems. Other systems may have additional requirements.

​
Go

The example chain requires Go 1.25 or higher. 
go version
# go version go1.25.0 linux/amd64   # Linux
# go version go1.25.0 darwin/arm64  # macOS
If Go is not installed, download it from go.dev/dl.

​
Configure Go Environment Variables

After installing Go, make sure $GOPATH/bin is on your PATH so installed binaries (like exampled) are accessible. Open your shell config file (~/.zshrc on macOS or ~/.bashrc on Linux) and add: 
export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin
Then apply the changes: 
source ~/.zshrc    # macOS
source ~/.bashrc   # Linux
Verify: go env GOPATH

​
Make

Make is used to run build and development commands throughout the tutorial. 
make --version
# GNU Make 3.81
Make is pre-installed on most Linux and macOS systems. If it is missing:
  • macOS: xcode-select --install
  • Linux (Debian/Ubuntu): sudo apt install build-essential

​
Docker

Docker is required to run make proto-gen, which generates Go code from the module’s proto files using buf. 
docker --version
# Docker version 29.2.1
Download Docker from docs.docker.com/get-docker. Docker must be running before you execute make proto-gen.

​
Git

git --version
# git version 2.52.0

​
Clone the repository

Clone cosmos/example and navigate into it: 
git clone https://github.com/cosmos/example
cd example
The repo has two branches used in this tutorial series:
  • main — the complete chain with the full x/counter module wired in.
  • tutorial/start — the same chain with the counter module stripped out. Start here if you want to build the module yourself from scratch.

​
Repository Layout

After cloning, the repository looks like this: 
example/
├── exampled/         # Binary entrypoint (main.go + CLI root command)
├── app.go            # Chain application, module wiring lives here
├── proto/            # Proto definitions for all modules
├── x/                # Module implementations
│   └── counter/      # The example counter module
├── tests/            # E2E and integration tests
├── scripts/          # Local node and proto generation scripts
├── docs/             # This tutorial series
└── Makefile          # Build, test, and dev commands

​
Where things live

The tutorials in this section will walk you through the most common kinds of chain changes and show you where they usually live in the repo:
  • Add or modify a module: x/<module>/ and proto/
  • Wire a module into the chain: app.go
  • Change the binary or CLI: exampled/
  • Run the chain or tests: Makefile targets
Next: Quickstart →