{
"canonical_name": "simonw/go-to-wheel",
"compilation_id": "pack_a8c6af568ee54403903d81f8c67b393a",
"created_at": "2026-05-15T09:28:56.200087+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install go-to-wheel` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install go-to-wheel",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_f4f172b2f33f47ac906ae987bd2e2a0e"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_04c7c99d230620fedb9909997c475aa9",
"canonical_name": "simonw/go-to-wheel",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/simonw/go-to-wheel",
"slug": "go-to-wheel",
"source_packet_id": "phit_0077971de1814c1c8661ac9e17450fbb",
"source_validation_id": "dval_b7241181c1994477a8167e0e79e3c2a9"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": null,
"github_stars": null,
"one_liner_en": "[](https://pypi.org/project/go-to-wheel/)",
"one_liner_zh": "[](https://pypi.org/project/go-to-wheel/)",
"primary_category": {
"category_id": "software-development",
"confidence": "medium",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, cli"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "go-to-wheel",
"title_zh": "go-to-wheel 能力包",
"visible_tags": [
{
"label_en": "Knowledge Retrieval",
"label_zh": "知识检索",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-knowledge-retrieval",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Automated Workflow",
"label_zh": "自动化工作流",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-automated-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Local-first",
"label_zh": "本地优先",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-local-first",
"type": "selection_signal"
}
]
},
"packet_id": "phit_0077971de1814c1c8661ac9e17450fbb",
"page_model": {
"artifacts": {
"artifact_slug": "go-to-wheel",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install go-to-wheel",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/simonw/go-to-wheel#readme",
"verified": true
}
],
"display_tags": [
"知识检索",
"知识库问答",
"流程自动化",
"自动化工作流",
"本地优先"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "[](https://pypi.org/project/go-to-wheel/)"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": null,
"forks": null,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": null
},
"source_url": "https://github.com/simonw/go-to-wheel",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "[](https://pypi.org/project/go-to-wheel/)",
"title": "go-to-wheel 能力包",
"trial_prompt": "# go-to-wheel - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 go-to-wheel 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: [](https://pypi.org/project/go-to-wheel/) 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：Introduction。围绕“Introduction”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：Installation。围绕“Installation”模拟一次用户任务，不展示安装或运行结果。\n3. page-quick-start：Quick Start Guide。围绕“Quick Start Guide”模拟一次用户任务，不展示安装或运行结果。\n4. page-cli-options：CLI Options Reference。围绕“CLI Options Reference”模拟一次用户任务，不展示安装或运行结果。\n5. page-examples：Usage Examples。围绕“Usage Examples”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“Introduction”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“Installation”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-quick-start\n输入：用户提供的“Quick Start Guide”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-cli-options\n输入：用户提供的“CLI Options Reference”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-examples\n输入：用户提供的“Usage Examples”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“Introduction”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“Installation”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-quick-start：Step 3 必须围绕“Quick Start Guide”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-cli-options：Step 4 必须围绕“CLI Options Reference”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-examples：Step 5 必须围绕“Usage Examples”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://news.ycombinator.com/item?id=48109677\n- https://github.com/simonw/go-to-wheel#readme\n- README.md\n- spec.md\n- pyproject.toml\n- go_to_wheel/__init__.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 go-to-wheel 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "当前没有项目级社区来源；不会把未抓取讨论包装成社会证明。",
"items": [],
"status": "待发现 Agent 补证",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "[](https://pypi.org/project/go-to-wheel/)",
"effort": "安装已验证",
"forks": null,
"icon": "code",
"name": "go-to-wheel 能力包",
"risk": "需复核",
"slug": "go-to-wheel",
"stars": null,
"tags": [
"知识检索",
"知识库问答",
"流程自动化",
"自动化工作流",
"本地优先"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/simonw/go-to-wheel 项目说明书\n\n生成时间：2026-05-15 08:31:09 UTC\n\n## 目录\n\n- [Introduction](#page-introduction)\n- [Installation](#page-installation)\n- [Quick Start Guide](#page-quick-start)\n- [CLI Options Reference](#page-cli-options)\n- [Usage Examples](#page-examples)\n- [System Architecture](#page-architecture)\n- [Supported Platforms](#page-platforms)\n- [Wheel Generation Process](#page-wheel-generation)\n- [Development Guide](#page-development-guide)\n- [Configuration and Metadata](#page-configuration)\n\n\n\n## Introduction\n\n### 相关页面\n\n相关主题：[Installation](#page-installation), [Quick Start Guide](#page-quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n- [spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n- [go_to_wheel/__init__.py](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n \n\n# Introduction\n\n## Overview\n\n`go-to-wheel` is a Python command-line tool that compiles Go CLI programs into Python wheels, enabling Go binaries to be distributed and installed through the Python packaging ecosystem via `pip` or `pipx`. This tool bridges the Go and Python communities by providing a seamless way to package and distribute Go applications to Python developers who are accustomed to installing tools through Python package managers. The project was created to address the gap in the ecosystem—there was no equivalent to Rust's `maturin --bindings bin` for Go, and `go-to-wheel` fills that void by providing a straightforward solution for bundling Go binaries into standard Python wheel packages.\n\n资料来源：[README.md:1-10]()\n\nThe tool takes a Go module directory as input, cross-compiles the Go binary for multiple target platforms, and produces properly-tagged Python wheels that can be installed via standard Python package management tools. This approach allows Go developers to leverage the extensive Python packaging infrastructure for distribution, including PyPI hosting, pipx for isolated installations, and standard Python dependency resolution.\n\n资料来源：[spec.md:1-15]()\n\n## Core Functionality\n\n### What go-to-wheel Does\n\nAt its core, `go-to-wheel` performs three main operations to transform a Go module into a distributable Python wheel. First, it validates that the input directory is a valid Go module containing a `go.mod` file. Second, it cross-compiles the Go binary for each requested target platform using environment variables `GOOS` and `GOARCH` with `CGO_ENABLED=0` to produce static binaries. Third, it creates a Python package structure with a thin wrapper that executes the bundled binary, then packages everything into a wheel file following PEP 427 conventions.\n\n资料来源：[spec.md:80-95]()\n\nThe resulting wheel can be installed with pip, which extracts the bundled Go binary and creates console entry points that make the tool available on the system PATH. This means users can install and run Go-compiled tools exactly as they would any other Python package, without needing to understand that the underlying implementation is written in Go.\n\n资料来源：[README.md:55-65]()\n\n### How It Works\n\nThe build process follows a precise sequence of operations to ensure compatibility across all supported platforms. The tool begins by validating the input Go module directory and verifying that Go is installed and accessible. It then iterates through each requested platform, setting the appropriate environment variables and running the Go compiler with flags optimized for static binary production.\n\n```mermaid\ngraph TD\n A[Start: go-to-wheel] --> B{Validate Go Module}\n B -->|go.mod exists| C[Parse Package Metadata]\n B -->|No go.mod| E[Error: Not a Go module]\n C --> D{For each target platform}\n D --> F[Cross-compile with GOOS/GOARCH]\n F --> G[CGO_ENABLED=0 for static binary]\n G --> H[Generate Python wrapper]\n H --> I[Create wheel structure]\n I --> J[Zip into .whl file]\n J --> D\n D -->|All platforms done| K[Output wheels to ./dist]\n K --> L[Success]\n```\n\n资料来源：[spec.md:85-100]()\n\nThe cross-compilation step uses `CGO_ENABLED=0` to ensure that the resulting binaries are fully static and have no libc dependencies, which is essential for compatibility across different Linux distributions and container environments. The `-ldflags=\"-s -w\"` flags strip debug information and reduce binary size for more efficient distribution.\n\n资料来源：[README.md:45-50]()\n\n## Supported Platforms\n\n`go-to-wheel` supports a comprehensive range of target platforms across Linux, macOS, and Windows operating systems, covering both x86_64 and ARM architectures. The tool provides different wheel tags depending on whether the target uses glibc (standard Linux) or musl (Alpine Linux and similar distributions).\n\n### Platform Mapping\n\n| Target Platform | GOOS | GOARCH | Wheel Tag |\n|-----------------|------|--------|-----------|\n| linux-amd64 | linux | amd64 | manylinux_2_17_x86_64 |\n| linux-arm64 | linux | arm64 | manylinux_2_17_aarch64 |\n| linux-amd64-musl | linux | amd64 | musllinux_1_2_x86_64 |\n| linux-arm64-musl | linux | arm64 | musllinux_1_2_aarch64 |\n| darwin-amd64 | darwin | amd64 | macosx_10_9_x86_64 |\n| darwin-arm64 | darwin | arm64 | macosx_11_0_arm64 |\n| windows-amd64 | windows | amd64 | win_amd64 |\n| windows-arm64 | windows | arm64 | win_arm64 |\n\n资料来源：[README.md:35-45]()\n\n### Default Platform Behavior\n\nBy default, `go-to-wheel` builds wheels for all eight supported platforms, ensuring maximum compatibility for distribution. Users can optionally specify a subset of platforms using the `--platforms` flag with a comma-separated list of target platforms, which is useful when building for specific deployment environments or when cross-compilation toolchains are not available for all targets.\n\n资料来源：[spec.md:40-45]()\n\n## Installation and Requirements\n\n### Prerequisites\n\nThe tool itself requires Python 3.10 or later and has no external Python dependencies—it uses only the Python standard library. For building Go binaries, Go 1.16 or later is required due to the use of `go mod` commands.\n\n资料来源：[spec.md:115-120]()\n\n### Installation Methods\n\n`go-to-wheel` can be installed using standard Python package installation tools:\n\n```bash\npip install go-to-wheel\n# or\npipx install go-to-wheel\n```\n\n资料来源：[README.md:20-25]()\n\nAfter installation, Go must be available in the system PATH. The tool will automatically detect the Go binary or can be configured to use a specific path via the `--go-binary` option.\n\n## Command Line Interface\n\n### Basic Usage\n\nThe simplest usage of `go-to-wheel` requires only a path to the Go module directory:\n\n```bash\ngo-to-wheel path/to/go-module\n```\n\n资料来源：[README.md:30-35]()\n\nThis command creates wheels in the `./dist` directory for all supported platforms using default metadata values.\n\n### Command Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--name NAME` | Python package name | Directory basename |\n| `--version VERSION` | Package version | `0.1.0` |\n| `--output-dir DIR` | Directory for built wheels | `./dist` |\n| `--entry-point NAME` | CLI command name | Same as package name |\n| `--platforms PLATFORMS` | Comma-separated list of targets | All supported platforms |\n| `--go-binary PATH` | Path to Go binary | `go` |\n| `--description TEXT` | Package description | `\"Go binary packaged as Python wheel\"` |\n| `--license LICENSE` | License identifier | None |\n| `--author AUTHOR` | Author name | None |\n| `--author-email EMAIL` | Author email | None |\n| `--url URL` | Project URL | None |\n| `--requires-python VERSION` | Python version requirement | `>=3.10` |\n| `--readme PATH` | Path to README markdown file | None |\n| `--set-version-var VAR` | Go variable for version via `-X` ldflag | None |\n| `--ldflags FLAGS` | Additional Go linker flags | None |\n\n资料来源：[spec.md:25-45]()\n\n## Wheel Structure\n\nEach generated wheel follows PEP 427 format with a specific internal structure that enables proper execution of the bundled Go binary.\n\n### File Structure\n\n```\n{package_name}-{version}-py3-none-{platform_tag}.whl\n├── {package_name}/\n│ ├── __init__.py\n│ ├── __main__.py\n│ └── bin/\n│ └── {binary_name}[.exe]\n├── {package_name}-{version}.dist-info/\n│ ├── METADATA\n│ ├── WHEEL\n│ ├── RECORD\n│ └── entry_points.txt\n```\n\n资料来源：[spec.md:60-70]()\n\n### Python Wrapper Mechanism\n\nThe Python wrapper in `__init__.py` provides the execution mechanism for the bundled binary. It uses `os.execvp()` on Unix systems to replace the Python process with the Go binary, ensuring proper signal handling and exit code propagation. On Windows, it uses `subprocess.call()` to achieve similar behavior with proper signal handling.\n\n资料来源：[spec.md:60-90]()\n\n```python\ndef main():\n \"\"\"Execute the bundled binary.\"\"\"\n binary = get_binary_path()\n if sys.platform == \"win32\":\n # On Windows, use subprocess to properly handle signals\n sys.exit(subprocess.call([binary] + sys.argv[1:]))\n else:\n # On Unix, exec replaces the process\n os.execvp(binary, [binary] + sys.argv[1:])\n```\n\n资料来源：[spec.md:75-85]()\n\n### Why Python Wrapper vs .data/scripts\n\nThe specification uses a Python wrapper with `console_scripts` entry point rather than placing the binary directly in `.data/scripts/` for several important reasons. First, it provides consistent behavior across all platforms without platform-specific edge cases. Second, it enables better error messages if the binary is missing or incompatible with the system. Third, it offers future flexibility for adding Python-side features such as version checking or update notifications. Fourth, it works seamlessly with `pipx install` for isolated application installations.\n\n资料来源：[spec.md:90-100]()\n\n## Use Cases\n\n### Distributing Go Tools to Python Users\n\nThe primary use case for `go-to-wheel` is distributing Go CLI tools to Python developers who prefer to use `pip` or `pipx` for managing command-line tools. This is particularly valuable for tools that have natural appeal to the Python community or tools that need to be installed alongside Python packages as dependencies.\n\n资料来源：[README.md:8-12]()\n\n### PyPI Distribution\n\nGo binaries packaged as wheels can be uploaded to PyPI, making them available through the standard Python package index. This enables distribution to millions of Python developers who can install the tool with a single `pip install` command, without needing to understand Go compilation or maintain separate release artifacts.\n\n### pipx Isolation\n\nWheels built with `go-to-wheel` work seamlessly with `pipx`, which provides isolated Python environments for command-line tools. Users can install Go-compiled tools in isolation to avoid dependency conflicts:\n\n```bash\npipx install ./dist/mytool-1.0.0-py3-none-manylinux_2_17_x86_64.whl\n```\n\n资料来源：[README.md:60-65]()\n\n## Advanced Features\n\n### Version Embedding\n\nGo-to-wheel supports embedding the package version into the Go binary at compile time using Go linker flags. This requires a `var version` declaration in the Go source code. When the `--set-version-var` option is used, the tool automatically passes the value from `--version` to the Go linker via the `-X` flag.\n\n资料来源：[README.md:50-55]()\n\nA typical Go pattern for version embedding:\n\n```go\nvar version = \"dev\"\n\nfunc main() {\n if os.Args[1] == \"--version\" {\n fmt.Println(version) // prints \"2.0.0\" when built with --set-version-var\n }\n}\n```\n\n资料来源：[README.md:50-60]()\n\n### Custom Linker Flags\n\nAdditional Go linker flags can be passed using the `--ldflags` option, which are appended to the default `-s -w` flags. This allows for custom version strings, commit hashes, or other build-time information:\n\n```bash\ngo-to-wheel ./mytool --version 2.0.0 \\\n --ldflags \"-X main.version=2.0.0 -X main.commit=abc123\"\n```\n\n资料来源：[README.md:60-65]()\n\n### README Integration\n\nThe `--readme` option allows embedding a README markdown file into the wheel's METADATA, which is displayed on the PyPI package page:\n\n```bash\ngo-to-wheel ./mytool --readme README.md\n```\n\n资料来源：[spec.md:42]()\n\n## Development\n\n### Running Tests\n\nThe project uses pytest for testing. After cloning the repository, tests can be run with:\n\n```bash\ngit clone https://github.com/simonw/go-to-wheel\ncd go-to-wheel\nuv run pytest\n```\n\n资料来源：[README.md:70-75]()\n\n### Project Architecture\n\nThe tool is implemented as a single Python module (`go_to_wheel/__init__.py`) with no external dependencies. The main components include argument parsing, cross-compilation orchestration, wheel file generation, and metadata file creation. This simple architecture makes the tool easy to understand, maintain, and extend.\n\n## Related Tools\n\n`go-to-wheel` was inspired by similar tools in the Rust ecosystem. The primary inspiration is `maturin`, which provides the same functionality for Rust programs with Python bindings. Additionally, `pip-binary-factory` serves as a template for packaging pre-built binaries.\n\n资料来源：[README.md:75-80]()\n\n| Tool | Language | Repository |\n|------|----------|------------|\n| go-to-wheel | Go | simonw/go-to-wheel |\n| maturin | Rust | PyO3/maturin |\n| pip-binary-factory | Template | Bing-su/pip-binary-factory |\n\n## License\n\n`go-to-wheel` is released under the Apache 2.0 license, allowing for both personal and commercial use with minimal restrictions.\n\n资料来源：[README.md:12]()\n\n## Summary\n\n`go-to-wheel` provides a valuable bridge between the Go and Python ecosystems by enabling Go CLI programs to be packaged and distributed as standard Python wheels. With support for eight target platforms, flexible metadata configuration, and seamless integration with pip and pipx, it offers Go developers a straightforward path to reaching Python's extensive user base. The tool's single-file implementation with no external dependencies ensures reliability and ease of installation, making it a practical choice for distributing Go tools to the Python community.\n\n---\n\n\n\n## Installation\n\n### 相关页面\n\n相关主题：[Introduction](#page-introduction), [Development Guide](#page-development-guide)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n- [spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n- [go_to_wheel/__init__.py](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n \n\n# Installation\n\n`go-to-wheel` is a Python tool that compiles Go CLI programs into Python wheels. Installing this tool correctly is the first step to packaging Go binaries for PyPI distribution.\n\n## Prerequisites\n\nBefore installing `go-to-wheel`, ensure your environment meets the following requirements:\n\n| Requirement | Version | Description |\n|-------------|---------|-------------|\n| Python | >= 3.10 | The tool is implemented in Python and requires this version or higher |\n| Go | >= 1.16 | Required for building Go modules with `go mod` support |\n\n资料来源：[spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n### Python Dependencies\n\n`go-to-wheel` has **no external Python dependencies**. The tool uses only Python's standard library for all operations:\n\n- `argparse` - Command-line argument parsing\n- `zipfile` - Wheel creation\n- `subprocess` - Go compilation execution\n- `hashlib` / `base64` - RECORD file hash generation\n- `tempfile` / `shutil` - Temporary directory management\n\n资料来源：[go_to_wheel/__init__.py:1-20](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### Go Installation Verification\n\nTo verify Go is installed and accessible:\n\n```bash\ngo version\n```\n\nEnsure `go` is in your system's `PATH` environment variable.\n\n## Installation Methods\n\n### Via pip (Recommended for Users)\n\n```bash\npip install go-to-wheel\n```\n\n资料来源：[README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n\nThis method installs `go-to-wheel` globally in your Python environment.\n\n### Via pipx (Recommended for CLI Tools)\n\n```bash\npipx install go-to-wheel\n```\n\n资料来源：[README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n\n`pipx` is preferred for CLI applications because it:\n\n- Creates an isolated virtual environment for the tool\n- Automatically manages PATH shims for the installed command\n- Avoids dependency conflicts with other Python packages\n\n## Installation Workflow\n\n```mermaid\ngraph TD\n A[Choose Installation Method] --> B{pip or pipx?}\n B -->|pip| C[Run pip install go-to-wheel]\n B -->|pipx| D[Run pipx install go-to-wheel]\n C --> E[Download from PyPI]\n D --> E\n E --> F[Install to Python environment]\n F --> G[Create executable entry point]\n G --> H[go-to-wheel ready to use]\n```\n\n## Post-Installation Verification\n\nAfter installation, verify the tool is working:\n\n```bash\ngo-to-wheel --version\n```\n\nExpected output:\n```\ngo-to-wheel v0.1.0\n```\n\n资料来源：[go_to_wheel/__init__.py](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Usage Requirements\n\nOnce installed, you need a Go module to package:\n\n```bash\n# Verify you have a Go module\ncd path/to/your-go-module\nls go.mod\n```\n\nThe tool will:\n1. Cross-compile the Go binary for multiple platforms\n2. Create Python wheels with proper metadata\n3. Bundle everything into installable packages\n\n资料来源：[spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n## Quick Start After Installation\n\n```bash\n# Build wheels for all platforms\ngo-to-wheel path/to/go-module\n\n# Or with custom options\ngo-to-wheel ./mytool --name my-python-tool --version 1.0.0\n```\n\n资料来源：[README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n\n## Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| `go-to-wheel: command not found` | Ensure pip's Scripts directory is in PATH, or use `python -m go_to_wheel` |\n| Go not found | Install Go from [go.dev](https://go.dev) and ensure it's in PATH |\n| Python version error | Upgrade to Python 3.10 or higher |\n| Permission denied | Use `pip install --user` or `pipx install` instead of system-wide install |\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[CLI Options Reference](#page-cli-options), [Usage Examples](#page-examples)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n- [go_to_wheel/__init__.py](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n- [spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n \n\n# Quick Start Guide\n\n## Overview\n\nThe **Quick Start Guide** provides the fastest path for developers to begin using go-to-wheel to compile Go CLI programs into installable Python wheels. This tool addresses a gap in the Go/Python ecosystem—there is no equivalent to Rust's `maturin --bindings bin` for Go. Go-to-wheel takes a Go module directory, cross-compiles it for multiple platforms, and produces properly-tagged Python wheels installable via `pip` or `pipx`. 资料来源：[README.md:1-10]()\n\n## Prerequisites\n\nBefore using go-to-wheel, ensure your environment meets the following requirements:\n\n| Requirement | Version | Notes |\n|-------------|---------|-------|\n| Python | >= 3.10 | Required for installation and running the tool |\n| Go | >= 1.16 | Required for building Go modules 资料来源：[spec.md:145-150]() |\n| Go Module | Valid `go.mod` | The source Go project must be a Go module |\n\nGo must be installed and available in your system PATH. No external Python dependencies are required—go-to-wheel uses only the Python standard library. 资料来源：[go_to_wheel/__init__.py:1-15]()\n\n## Installation\n\nInstall go-to-wheel using pip or pipx:\n\n```bash\npip install go-to-wheel\n# or\npipx install go-to-wheel\n```\n\nVerify the installation:\n\n```bash\ngo-to-wheel --version\n```\n\n## Basic Usage\n\n### Minimal Command\n\nBuild wheels for all supported platforms using the simplest invocation:\n\n```bash\ngo-to-wheel path/to/go-module\n```\n\nThis command will:\n\n1. Cross-compile the Go binary for all default platforms\n2. Create a Python package with a thin wrapper\n3. Package everything into wheels in `./dist` directory\n4. Use the directory name as the package name with version `0.1.0` 资料来源：[README.md:35-50]()\n\n### Build Flow\n\n```mermaid\ngraph TD\n A[Go Module Directory] --> B[Validate go.mod exists]\n B --> C[Cross-compile Go binary for each platform]\n C --> D[Create Python package structure]\n D --> E[Generate wheel metadata]\n E --> F[Package into .whl file]\n F --> G[Move to output directory]\n```\n\n## Command Options\n\nThe following table documents all available command-line options:\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--name NAME` | Python package name | Directory basename |\n| `--version VERSION` | Package version | `0.1.0` |\n| `--output-dir DIR` | Directory for built wheels | `./dist` |\n| `--entry-point NAME` | CLI command name | Same as package name |\n| `--platforms PLATFORMS` | Comma-separated list of targets | All supported platforms |\n| `--go-binary PATH` | Path to Go binary | `go` |\n| `--description TEXT` | Package description | `\"Go binary packaged as Python wheel\"` |\n| `--license LICENSE` | License identifier (e.g., MIT) | None |\n| `--author AUTHOR` | Author name | None |\n| `--author-email EMAIL` | Author email | None |\n| `--url URL` | Project URL | None |\n| `--requires-python VERSION` | Python version requirement | `>=3.10` |\n| `--readme PATH` | Path to README markdown file for PyPI | None |\n| `--set-version-var VAR` | Go variable to set via `-X` ldflag | None |\n| `--ldflags FLAGS` | Additional Go linker flags | None | 资料来源：[README.md:20-35]()\n\n## Supported Platforms\n\nGo-to-wheel supports cross-compilation to the following target platforms:\n\n| Platform Identifier | GOOS | GOARCH | Wheel Tag |\n|---------------------|------|--------|-----------|\n| `linux-amd64` | linux | amd64 | `manylinux_2_17_x86_64` |\n| `linux-arm64` | linux | arm64 | `manylinux_2_17_aarch64` |\n| `linux-amd64-musl` | linux | amd64 | `musllinux_1_2_x86_64` |\n| `linux-arm64-musl` | linux | arm64 | `musllinux_1_2_aarch64` |\n| `darwin-amd64` | darwin | amd64 | `macosx_10_9_x86_64` |\n| `darwin-arm64` | darwin | arm64 | `macosx_11_0_arm64` |\n| `windows-amd64` | windows | amd64 | `win_amd64` |\n| `windows-arm64` | windows | arm64 | `win_arm64` | 资料来源：[go_to_wheel/__init__.py:20-30]()\n\n## Common Use Cases\n\n### Custom Package Name\n\nBuild wheels with a custom Python package name:\n\n```bash\ngo-to-wheel ./mytool --name my-python-tool\n```\n\n### Build for Specific Platforms Only\n\nReduce build time by targeting only required platforms:\n\n```bash\ngo-to-wheel ./mytool --platforms linux-amd64,darwin-arm64\n```\n\n### Embed Version into Go Binary\n\nPass the version to the Go binary at compile time using linker flags. First, add a version variable to your Go source:\n\n```go\nvar version = \"dev\"\n\nfunc main() {\n if os.Args[1] == \"--version\" {\n fmt.Println(version)\n }\n}\n```\n\nThen build with:\n\n```bash\ngo-to-wheel ./mytool --version 2.0.0 --set-version-var main.version\n```\n\nThis passes `-X main.version=2.0.0` to the Go linker. The flags are appended to the default `-s -w`, resulting in `-ldflags=\"-s -w -X main.version=2.0.0\"`. 资料来源：[README.md:55-75]()\n\n### Full Metadata for PyPI\n\nPublish to PyPI with complete metadata:\n\n```bash\ngo-to-wheel ./mytool \\\n --name mytool-bin \\\n --version 2.0.0 \\\n --description \"My awesome tool\" \\\n --license MIT \\\n --author \"Jane Doe\" \\\n --author-email \"jane@example.com\" \\\n --url \"https://github.com/jane/mytool\" \\\n --readme README.md\n```\n\n### Custom Linker Flags\n\nPass arbitrary Go linker flags for additional build-time configuration:\n\n```bash\ngo-to-wheel ./mytool --version 2.0.0 \\\n --ldflags \"-X main.version=2.0.0 -X main.commit=abc123\"\n```\n\n## How It Works\n\nThe build process consists of four main steps:\n\n```mermaid\ngraph LR\n A[Cross-compile Go Binary] --> B[Create Python Package]\n B --> C[Generate Metadata Files]\n C --> D[Package into Wheel]\n```\n\n### Step 1: Cross-Compilation\n\nFor each target platform, go-to-wheel executes:\n\n```bash\nGOOS={goos} GOARCH={goarch} CGO_ENABLED=0 go build \\\n -ldflags=\"-s -w\" \\\n -o {output_path} \\\n {go_module_path}\n```\n\nKey points:\n- `CGO_ENABLED=0` ensures static binaries with no libc dependency issues\n- `-ldflags=\"-s -w\"` strips debug information to reduce binary size\n- Windows builds automatically receive `.exe` extension 资料来源：[spec.md:100-115]()\n\n### Step 2: Python Package Structure\n\nEach wheel contains a Python wrapper that executes the bundled binary:\n\n```\n{package_name}-{version}-py3-none-{platform_tag}.whl\n├── {package_name}/\n│ ├── __init__.py\n│ ├── __main__.py\n│ └── bin/\n│ └── {binary_name}[.exe]\n├── {package_name}-{version}.dist-info/\n│ ├── METADATA\n│ ├── WHEEL\n│ ├── RECORD\n│ └── entry_points.txt\n```\n\nThe `__init__.py` file contains a `main()` function that:\n- On Windows: uses `subprocess.call()` for proper signal handling\n- On Unix: uses `os.execvp()` to replace the Python process 资料来源：[spec.md:60-95]()\n\n### Step 3: Metadata Generation\n\nGenerated METADATA follows PEP 566:\n\n```\nMetadata-Version: 2.1\nName: {package_name}\nVersion: {version}\nSummary: {description}\nLicense: {license}\nAuthor: {author}\nAuthor-email: {author_email}\nHome-page: {url}\nRequires-Python: {requires_python}\n```\n\nThe WHEEL file follows PEP 427:\n\n```\nWheel-Version: 1.0\nGenerator: go-to-wheel {version}\nRoot-Is-Purelib: false\nTag: py3-none-{platform_tag}\n```\n\n### Step 4: Entry Points\n\nConsole script entry points are defined in `entry_points.txt`:\n\n```\n[console_scripts]\n{entry_point} = {package_name}:main\n```\n\nThe tool uses Python wrapper entry points rather than `.data/scripts/` because:\n- Consistent behavior across all platforms\n- Better error messages if binary is missing\n- Future flexibility for Python-side features\n- Seamless pipx compatibility 资料来源：[spec.md:95-105]()\n\n## Testing Built Wheels\n\n### Install with pip\n\n```bash\npip install ./dist/mytool-1.0.0-py3-none-manylinux_2_17_x86_64.whl\n```\n\n### Test with uv\n\n```bash\nuv run --with ./dist/mytool-1.0.0-py3-none-manylinux_2_17_x86_64.whl mytool --help\n```\n\n### Run with pipx\n\n```bash\npipx install ./dist/mytool-1.0.0-py3-none-manylinux_2_17_x86_64.whl\n```\n\nAfter installation, the Go binary is available on your PATH through the Python wrapper. 资料来源：[README.md:100-115]()\n\n## Development\n\nTo contribute or customize go-to-wheel:\n\n```bash\n# Clone the repository\ngit clone https://github.com/simonw/go-to-wheel\ncd go-to-wheel\n\n# Run tests\nuv run pytest\n```\n\n## Package Name Validation\n\nPackage names must follow PEP 503 naming rules:\n\n| Rule | Description |\n|------|-------------|\n| Allowed characters | Lowercase letters, digits, hyphens, underscores, periods |\n| Must start with | Letter or digit |\n| Normalization | Hyphens and underscores become hyphens in wheel filename |\n\nThe import name (Python package directory) follows PEP 8:\n- Hyphens are replaced with underscores\n- Example: `my-tool` becomes `my_tool/` directory 资料来源：[spec.md:130-140]()\n\n## Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| \"No go.mod file found\" | Ensure the path points to a valid Go module directory |\n| \"Go compilation failed\" | Verify Go is installed and the module builds correctly standalone |\n| Invalid package name | Follow PEP 503 naming rules (lowercase, alphanumeric with hyphens/underscores) |\n\n## See Also\n\n- [maturin](https://github.com/PyO3/maturin) - The Rust equivalent that inspired this tool\n- [pip-binary-factory](https://github.com/Bing-su/pip-binary-factory) - Template for packaging pre-built binaries\n- [Distributing Go binaries like sqlite-scanner through PyPI using go-to-wheel](https://simonwillison.net/2026/Feb/4/distributing-go-binaries/) - Background article on this project 资料来源：[README.md:120-130]()\n\n---\n\n\n\n## CLI Options Reference\n\n### 相关页面\n\n相关主题：[Quick Start Guide](#page-quick-start), [Configuration and Metadata](#page-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [go_to_wheel/__init__.py](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n- [README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n- [spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n \n\n# CLI Options Reference\n\n## Overview\n\nThe `go-to-wheel` CLI provides comprehensive options for cross-compiling Go binaries into Python wheels. The command follows the structure:\n\n```bash\ngo-to-wheel path/to/go-folder [options]\n```\n\nAll options are passed as space-separated arguments after the path to the Go module directory. 资料来源：[README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n\n## Complete Options Reference\n\n### Core Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `path/to/go-folder` | positional | required | Path to Go module directory containing go.mod |\n| `--name NAME` | string | Directory basename | Python package name for the wheel |\n| `--version VERSION` | string | `0.1.0` | Package version string |\n| `--output-dir DIR` | string | `./dist` | Directory where built wheels are written |\n| `--entry-point NAME` | string | Same as package name | CLI command name exposed after installation |\n| `--go-binary PATH` | string | `go` | Path to Go binary in PATH |\n\n资料来源：[go_to_wheel/__init__.py:52-85](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### Metadata Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--description TEXT` | string | `\"Go binary packaged as Python wheel\"` | Package summary for PyPI |\n| `--license LICENSE` | string | None | SPDX license identifier (e.g., MIT, Apache-2.0) |\n| `--author AUTHOR` | string | None | Author name |\n| `--author-email EMAIL` | string | None | Author email address |\n| `--url URL` | string | None | Project homepage URL |\n| `--requires-python VERSION` | string | `>=3.10` | Python version requirement |\n| `--readme PATH` | string | None | Path to README.md for PyPI long description |\n\n资料来源：[go_to_wheel/__init__.py:86-115](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### Build Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--platforms PLATFORMS` | string | All 8 platforms | Comma-separated list of target platforms |\n| `--ldflags FLAGS` | string | None | Additional Go linker flags appended to `-s -w` |\n| `--set-version-var VAR` | string | None | Go variable name for version embedding via `-X` |\n\n资料来源：[go_to_wheel/__init__.py:116-128](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Supported Platforms\n\nThe following platform targets are available for cross-compilation:\n\n| Platform Identifier | GOOS | GOARCH | Wheel Tag |\n|-------------------|------|--------|-----------|\n| `linux-amd64` | linux | amd64 | manylinux_2_17_x86_64 |\n| `linux-arm64` | linux | arm64 | manylinux_2_17_aarch64 |\n| `linux-amd64-musl` | linux | amd64 | musllinux_1_2_x86_64 |\n| `linux-arm64-musl` | linux | arm64 | musllinux_1_2_aarch64 |\n| `darwin-amd64` | darwin | amd64 | macosx_10_9_x86_64 |\n| `darwin-arm64` | darwin | arm64 | macosx_11_0_arm64 |\n| `windows-amd64` | windows | amd64 | win_amd64 |\n| `windows-arm64` | windows | arm64 | win_arm64 |\n\n资料来源：[go_to_wheel/__init__.py:25-35](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### Platform Selection Syntax\n\nSpecify multiple platforms using comma-separated values:\n\n```bash\ngo-to-wheel ./mytool --platforms linux-amd64,darwin-arm64,windows-amd64\n```\n\n## Version Embedding\n\nThe `--set-version-var` option enables embedding the package version into the Go binary at compile time. This requires a matching variable in the Go source:\n\n```go\nvar version = \"dev\"\n\nfunc main() {\n if len(os.Args) > 1 && os.Args[1] == \"--version\" {\n fmt.Println(version)\n }\n}\n```\n\nBuild command with version embedding:\n\n```bash\ngo-to-wheel ./mytool --version 2.0.0 --set-version-var main.version\n```\n\nThis passes `-X main.version=2.0.0` to the Go linker. 资料来源：[README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n\n## Advanced Ldflags\n\nThe `--ldflags` option appends custom linker flags to the default `-s -w` flags (which strip debug info):\n\n```bash\ngo-to-wheel ./mytool --ldflags \"-X main.commit=abc123 -X main.date=2024-01-15\"\n```\n\nThe combined ldflags become: `-s -w -X main.commit=abc123 -X main.date=2024-01-15`\n\n## Usage Examples\n\n### Minimal Build\n\n```bash\ngo-to-wheel ./mytool\n```\n\nProduces wheels for all 8 platforms using default settings. 资料来源：[README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n\n### Custom Package Name\n\n```bash\ngo-to-wheel ./mytool --name my-python-tool\n```\n\nCreates `my-python-tool-0.1.0-py3-none-*.whl` files.\n\n### PyPI-Ready Build\n\n```bash\ngo-to-wheel ./mytool \\\n --name mytool-bin \\\n --version 2.0.0 \\\n --description \"My awesome CLI tool\" \\\n --license MIT \\\n --author \"Jane Doe\" \\\n --author-email \"jane@example.com\" \\\n --url \"https://github.com/jane/mytool\" \\\n --readme README.md\n```\n\n### Platform-Specific Build\n\n```bash\ngo-to-wheel ./mytool --platforms linux-amd64,darwin-arm64\n```\n\n### With Version Embedding\n\n```bash\ngo-to-wheel ./mytool --version 1.2.3 --set-version-var main.version\n```\n\n## Option Processing Flow\n\n```mermaid\ngraph TD\n A[Parse CLI Arguments] --> B[Validate go_dir exists]\n B --> C{Check go.mod}\n C -->|Valid| D[Set defaults]\n C -->|Invalid| E[Exit with error]\n D --> F[Parse platforms list]\n F --> G[Build ldflags]\n G --> H[Cross-compile for each platform]\n H --> I[Generate Python wheel]\n I --> J[Move to output-dir]\n J --> K[Print summary]\n```\n\n## Default Values Behavior\n\n| Option | Default Source | Override Mechanism |\n|--------|---------------|-------------------|\n| Package name | `go_path.name` (directory basename) | `--name` |\n| Version | `\"0.1.0\"` | `--version` |\n| Entry point | Same as package name | `--entry-point` |\n| Platforms | `DEFAULT_PLATFORMS` list (all 8) | `--platforms` |\n| Go binary | `\"go\"` from PATH | `--go-binary` |\n| Description | `\"Go binary packaged as Python wheel\"` | `--description` |\n| Requires Python | `\">=3.10\"` | `--requires-python` |\n\n资料来源：[go_to_wheel/__init__.py:175-190](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Error Handling\n\nThe CLI validates inputs and exits with descriptive errors:\n\n| Error Condition | Exit Behavior |\n|-----------------|---------------|\n| Go directory not found | `FileNotFoundError: Go directory not found: ` |\n| No go.mod file | `ValueError: Not a Go module: ` |\n| Go binary not found | `FileNotFoundError` from subprocess |\n| Compilation failure | `RuntimeError: Go compilation failed for /` |\n| No wheels built | `Error: No wheels were built` |\n\n## Return Codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | Success - wheels built and written to output directory |\n| 1 | Error occurred (invalid input, compilation failure, etc.) |\n\n资料来源：[go_to_wheel/__init__.py:130-155](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n---\n\n\n\n## Usage Examples\n\n### 相关页面\n\n相关主题：[Quick Start Guide](#page-quick-start), [Wheel Generation Process](#page-wheel-generation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n- [go_to_wheel/__init__.py](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n- [spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n \n\n# Usage Examples\n\nThis page provides comprehensive usage examples for `go-to-wheel`, demonstrating how to compile Go CLI programs into distributable Python wheels. The examples progress from basic usage to advanced configurations, covering all available command-line options and common use cases.\n\n## Overview\n\n`go-to-wheel` transforms Go binaries into Python packages that can be installed via `pip` or `pipx`. The tool handles cross-compilation for multiple platforms, generates proper Python wheel metadata, and creates installable packages with executable entry points. All examples assume Go is installed and available in the system PATH.\n\n## Basic Usage\n\nThe simplest way to build wheels from a Go module is to pass the module directory path:\n\n```bash\ngo-to-wheel ./mytool\n```\n\nThis command:\n\n1. Locates the Go module in `./mytool` (requires `go.mod` file)\n2. Cross-compiles the binary for all supported platforms\n3. Creates wheels in `./dist` directory\n4. Uses the directory name as the package name\n5. Defaults to version `0.1.0`\n\nThe resulting wheels follow the naming convention `{name}-{version}-py3-none-{platform_tag}.whl`.\n\n## Command Line Options\n\n### Option Reference Table\n\n| Option | Description | Default Value |\n|--------|-------------|---------------|\n| `--name NAME` | Python package name | Directory basename |\n| `--version VERSION` | Package version | `0.1.0` |\n| `--output-dir DIR` | Directory for built wheels | `./dist` |\n| `--entry-point NAME` | CLI command name | Same as package name |\n| `--platforms PLATFORMS` | Comma-separated list of targets | All supported platforms |\n| `--go-binary PATH` | Path to Go binary | `go` |\n| `--description TEXT` | Package description | `\"Go binary packaged as Python wheel\"` |\n| `--license LICENSE` | License identifier | None |\n| `--author AUTHOR` | Author name | None |\n| `--author-email EMAIL` | Author email | None |\n| `--url URL` | Project URL | None |\n| `--requires-python VERSION` | Python version requirement | `>=3.10` |\n| `--readme PATH` | Path to README markdown file | None |\n| `--set-version-var VAR` | Go variable for `--version` value | None |\n| `--ldflags FLAGS` | Additional Go linker flags | None |\n\n资料来源：[go_to_wheel/__init__.py:1-100]()\n\n## Platform Selection\n\n### Build for All Platforms\n\nBy default, `go-to-wheel` builds wheels for all supported platforms:\n\n| Platform | Wheel Tag |\n|----------|-----------|\n| `linux-amd64` | `manylinux_2_17_x86_64` |\n| `linux-arm64` | `manylinux_2_17_aarch64` |\n| `linux-amd64-musl` | `musllinux_1_2_x86_64` |\n| `linux-arm64-musl` | `musllinux_1_2_aarch64` |\n| `darwin-amd64` | `macosx_10_9_x86_64` |\n| `darwin-arm64` | `macosx_11_0_arm64` |\n| `windows-amd64` | `win_amd64` |\n| `windows-arm64` | `win_arm64` |\n\n资料来源：[README.md:1-50]()\n\n### Build for Specific Platforms\n\nTo build only for specific platforms, use the `--platforms` option with a comma-separated list:\n\n```bash\ngo-to-wheel ./mytool --platforms linux-amd64,darwin-arm64\n```\n\nThis produces wheels for only Linux amd64 and macOS ARM64, reducing build time when you don't need all platform variants.\n\n### Using a Custom Go Binary\n\nIf Go is not in your PATH or you need a specific version:\n\n```bash\ngo-to-wheel ./mytool --go-binary /usr/local/go/bin/go\n```\n\n## Package Naming\n\n### Custom Package Name\n\nOverride the default package name derived from the directory:\n\n```bash\ngo-to-wheel ./mytool --name my-python-tool\n```\n\nThis creates wheels named `my-python-tool-{version}-py3-none-{platform_tag}.whl`.\n\n### Custom Entry Point\n\nThe CLI command name can differ from the package name:\n\n```bash\ngo-to-wheel ./mytool --name my-tool-bin --entry-point mytool\n```\n\nThis creates a package named `my-tool-bin` but installs the command as `mytool`.\n\n## Version Management\n\n### Setting Package Version\n\n```bash\ngo-to-wheel ./mytool --version 2.0.0\n```\n\n### Embedding Version in Go Binary\n\nTo embed the version into the Go binary at compile time, define a version variable in your Go source:\n\n```go\nvar version = \"dev\"\n\nfunc main() {\n if os.Args[1] == \"--version\" {\n fmt.Println(version)\n }\n}\n```\n\nThen use `--set-version-var` to pass the version via linker flags:\n\n```bash\ngo-to-wheel ./mytool --version 2.0.0 --set-version-var main.version\n```\n\nThis passes `-X main.version=2.0.0` to the Go linker. The combined linker flags become `-s -w -X main.version=2.0.0`.\n\n资料来源：[README.md:50-80]()\n\n## Custom Linker Flags\n\n### Using ldflags\n\nPass arbitrary Go linker flags with `--ldflags`:\n\n```bash\ngo-to-wheel ./mytool --version 2.0.0 \\\n --ldflags \"-X main.version=2.0.0 -X main.commit=abc123\"\n```\n\nFlags are appended to the default `-s -w`, so the full linker invocation becomes:\n\n```\n-ldflags=\"-s -w -X main.version=2.0.0 -X main.commit=abc123\"\n```\n\nThe `-s` flag strips symbol table, and `-w` removes DWARF debugging information, reducing binary size.\n\n资料来源：[spec.md:50-80]()\n\n## Output Management\n\n### Custom Output Directory\n\n```bash\ngo-to-wheel ./mytool --output-dir ./wheels\n```\n\n### Installing Built Wheels\n\nAfter building, install wheels with pip:\n\n```bash\npip install ./dist/mytool-1.0.0-py3-none-manylinux_2_17_x86_64.whl\n```\n\nOr test directly with uv:\n\n```bash\nuv run --with ./dist/mytool-1.0.0-py3-none-manylinux_2_17_x86_64.whl mytool --help\n```\n\n## Complete Examples\n\n### Basic Distribution\n\nFor internal distribution without PyPI publishing:\n\n```bash\ngo-to-wheel ./mytool\n```\n\n### PyPI-Ready Distribution\n\nFull metadata configuration for PyPI publishing:\n\n```bash\ngo-to-wheel ./mytool \\\n --name mytool-bin \\\n --version 2.0.0 \\\n --description \"My awesome tool\" \\\n --license MIT \\\n --author \"Jane Doe\" \\\n --author-email \"jane@example.com\" \\\n --url \"https://github.com/jane/mytool\" \\\n --readme README.md\n```\n\nThis generates wheels with complete metadata suitable for publishing to PyPI. The `--readme` option sets the long description from your README file.\n\n资料来源：[README.md:80-120]()\n\n### Development Workflow\n\nTypical development workflow:\n\n```bash\n# Build all wheels\ngo-to-wheel ./mytool --output-dir ./dist\n\n# Test specific wheel\nuv run --with ./dist/mytool-0.1.0-py3-none-manylinux_2_17_x86_64.whl mytool --help\n\n# Install locally for testing\npip install ./dist/mytool-0.1.0-py3-none-manylinux_2_17_x86_64.whl\n\n# Uninstall after testing\npip uninstall mytool\n```\n\n## Build Process Flow\n\n```mermaid\ngraph TD\n A[go-to-wheel command] --> B[Validate Go directory]\n B --> C[Check go.mod exists]\n C --> D{For each platform}\n D --> E[Cross-compile with GOOS/GOARCH]\n E --> F[Create Python package structure]\n F --> G[Generate __init__.py and __main__.py]\n G --> H[Generate METADATA and WHEEL files]\n H --> I[Calculate RECORD with SHA256]\n I --> J[Zip into wheel file]\n J --> K{More platforms?}\n K -->|Yes| D\n K -->|No| L[Move wheels to output dir]\n L --> M[Print summary]\n```\n\nThe build process uses `CGO_ENABLED=0` for static binaries, ensuring compatibility across different Linux distributions without libc dependencies.\n\n资料来源：[spec.md:30-60]()\n\n## Error Handling\n\nCommon errors and solutions:\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| `Go directory not found` | Invalid path | Verify the directory exists |\n| `Not a Go module` | Missing `go.mod` | Ensure directory contains `go.mod` |\n| `Go compilation failed` | Build error in Go code | Check Go source for errors |\n| `No wheels were built` | Platform validation failed | Verify platform names are correct |\n\n资料来源：[go_to_wheel/__init__.py:150-200]()\n\n## Quick Reference\n\n| Task | Command |\n|------|---------|\n| Build all wheels | `go-to-wheel ./mytool` |\n| Custom name | `go-to-wheel ./mytool --name my-package` |\n| Specific version | `go-to-wheel ./mytool --version 1.2.3` |\n| Specific platforms | `go-to-wheel ./mytool --platforms linux-amd64,darwin-arm64` |\n| With metadata | `go-to-wheel ./mytool --author \"Name\" --license MIT --readme README.md` |\n| Embed version | `go-to-wheel ./mytool --version 1.0 --set-version-var main.version` |\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Wheel Generation Process](#page-wheel-generation), [Supported Platforms](#page-platforms)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [go_to_wheel/__init__.py](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n- [spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n- [README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n \n\n# System Architecture\n\n## Overview\n\ngo-to-wheel is a Python CLI tool that bridges the Go and Python packaging ecosystems. It takes a Go module directory, cross-compiles it for multiple target platforms, and packages each binary as a PEP 427-compliant Python wheel with executable entry points. This enables Go binaries to be distributed and installed via `pip` or `pipx`.\n\n资料来源：[spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n## Architecture Components\n\nThe system consists of four primary components working in sequence:\n\n```mermaid\ngraph TD\n A[Go Module Input] --> B[Input Validation]\n B --> C[Cross-Compilation Engine]\n C --> D[Wheel Builder]\n D --> E[Output Wheels]\n \n B --> B1[Verify go.mod exists]\n B --> B2[Validate package name]\n C --> C1[GOOS/GOARCH env vars]\n C --> C2[CGO_ENABLED=0]\n D --> D1[Generate METADATA]\n D --> D2[Generate WHEEL]\n D --> D3[Generate RECORD]\n D --> D4[Create zip archive]\n```\n\n### Component Responsibilities\n\n| Component | Purpose | Key Functions |\n|-----------|---------|---------------|\n| **CLI Parser** | Parse command-line arguments | `argparse`, argument validation |\n| **Input Validator** | Verify Go module structure | Path existence, `go.mod` detection |\n| **Cross-Compiler** | Build binaries for target platforms | `subprocess.run()`, env var management |\n| **Wheel Builder** | Create PEP 427 compliant wheels | `zipfile`, metadata generation |\n\n资料来源：[go_to_wheel/__init__.py:1-50](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Platform Mapping System\n\nThe platform mapping system translates human-readable platform names into Go build environment variables and Python wheel tags.\n\n```mermaid\ngraph LR\n P1[\"linux-amd64\"] --> PM1[\"PLATFORM_MAPPINGS\"]\n P2[\"darwin-arm64\"] --> PM1\n P3[\"windows-amd64\"] --> PM1\n \n PM1 --> G[\"GOOS/GOARCH\"]\n PM1 --> W[\"Wheel Tag\"]\n \n G --> G1[\"linux/amd64\"]\n W --> W1[\"manylinux_2_17_x86_64\"]\n```\n\n### Platform Mapping Table\n\n| Platform Name | GOOS | GOARCH | Wheel Tag |\n|---------------|------|--------|-----------|\n| `linux-amd64` | `linux` | `amd64` | `manylinux_2_17_x86_64` |\n| `linux-arm64` | `linux` | `arm64` | `manylinux_2_17_aarch64` |\n| `linux-amd64-musl` | `linux` | `amd64` | `musllinux_1_2_x86_64` |\n| `linux-arm64-musl` | `linux` | `arm64` | `musllinux_1_2_aarch64` |\n| `darwin-amd64` | `darwin` | `amd64` | `macosx_10_9_x86_64` |\n| `darwin-arm64` | `darwin` | `arm64` | `macosx_11_0_arm64` |\n| `windows-amd64` | `windows` | `amd64` | `win_amd64` |\n| `windows-arm64` | `windows` | `arm64` | `win_arm64` |\n\n资料来源：[go_to_wheel/__init__.py:23-32](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Build Process Workflow\n\n```mermaid\nflowchart TD\n START[Start build_wheels] --> V1{Go directory exists?}\n V1 -->|No| ERROR1[FileNotFoundError]\n V1 -->|Yes| V2{go.mod exists?}\n V2 -->|No| ERROR2[ValueError]\n V2 -->|Yes| PARSE[Parse arguments]\n \n PARSE --> SETUP[Set defaults
name, entry_point,
platforms]\n \n SETUP --> FOR_LOOP[For each platform]\n FOR_LOOP --> CROSS[cross_compile_go]\n \n CROSS --> BUILD[Build wheel structure]\n BUILD --> GEN_INIT[Generate __init__.py]\n BUILD --> GEN_MAIN[Generate __main__.py]\n BUILD --> GEN_META[Generate METADATA]\n BUILD --> GEN_WHEEL[Generate WHEEL]\n BUILD --> GEN_RECORD[Generate RECORD]\n BUILD --> GEN_ENTRY[Generate entry_points.txt]\n \n GEN_INIT --> ZIP[Create wheel.zip]\n GEN_MAIN --> ZIP\n GEN_META --> ZIP\n GEN_WHEEL --> ZIP\n GEN_RECORD --> ZIP\n GEN_ENTRY --> ZIP\n \n ZIP --> NEXT{More platforms?}\n NEXT -->|Yes| FOR_LOOP\n NEXT -->|No| OUTPUT[Move wheels to output_dir]\n OUTPUT --> DONE[Return wheel paths]\n```\n\n### Cross-Compilation Details\n\nThe cross-compilation step uses Go's built-in cross-compilation support:\n\n```bash\nGOOS={goos} GOARCH={goarch} CGO_ENABLED=0 go build \\\n -ldflags=\"-s -w\" \\\n -o {output_path} \\\n {go_module_path}\n```\n\nKey compilation flags:\n- `CGO_ENABLED=0`: Disables C bindings for static binaries\n- `-ldflags=\"-s -w\"`: Strips debug info and symbol tables\n- `.exe` extension added automatically on Windows\n\n资料来源：[spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n## Wheel Structure\n\nEach generated wheel follows the PEP 427 standard structure:\n\n```\n{package_name}-{version}-py3-none-{platform_tag}.whl\n├── {package_name}/\n│ ├── __init__.py\n│ ├── __main__.py\n│ └── bin/\n│ └── {binary_name}[.exe]\n├── {package_name}-{version}.dist-info/\n│ ├── METADATA\n│ ├── WHEEL\n│ ├── RECORD\n│ └── entry_points.txt\n```\n\n资料来源：[spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n### Generated File Contents\n\n#### `__init__.py`\n\nThe wrapper module that locates and executes the bundled binary:\n\n```python\n\"\"\"Go binary packaged as Python wheel.\"\"\"\n\nimport os\nimport stat\nimport subprocess\nimport sys\n\n__version__ = \"{version}\"\n\ndef get_binary_path():\n \"\"\"Return the path to the bundled binary.\"\"\"\n binary = os.path.join(os.path.dirname(__file__), \"bin\", \"{binary_name}\")\n\n # Ensure binary is executable on Unix\n if sys.platform != \"win32\":\n current_mode = os.stat(binary).st_mode\n if not (current_mode & stat.S_IXUSR):\n os.chmod(binary, current_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)\n return binary\n\ndef main():\n \"\"\"Execute the bundled binary.\"\"\"\n binary = get_binary_path()\n if sys.platform == \"win32\":\n sys.exit(subprocess.call([binary] + sys.argv[1:]))\n else:\n os.execvp(binary, [binary] + sys.argv[1:])\n```\n\n资料来源：[go_to_wheel/__init__.py:75-100](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n#### METADATA (PEP 566)\n\n```\nMetadata-Version: 2.1\nName: {package_name}\nVersion: {version}\nSummary: {description}\nLicense: {license}\nAuthor: {author}\nAuthor-email: {author_email}\nHome-page: {url}\nRequires-Python: {requires_python}\n```\n\n#### WHEEL (PEP 427)\n\n```\nWheel-Version: 1.0\nGenerator: go-to-wheel {go_to_wheel_version}\nRoot-Is-Purelib: false\nTag: py3-none-{platform_tag}\n```\n\n#### RECORD\n\nCSV format with columns: `path,hash,size`\n\n#### entry_points.txt\n\n```\n[console_scripts]\n{entry_point} = {package_name}:main\n```\n\n资料来源：[spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n## Command-Line Interface\n\n### Options Table\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--name NAME` | Python package name | Directory basename |\n| `--version VERSION` | Package version | `0.1.0` |\n| `--output-dir DIR` | Directory for built wheels | `./dist` |\n| `--entry-point NAME` | CLI command name | Same as package name |\n| `--platforms PLATFORMS` | Comma-separated list of targets | All 8 platforms |\n| `--go-binary PATH` | Path to Go binary | `go` |\n| `--description TEXT` | Package description | `\"Go binary packaged as Python wheel\"` |\n| `--license LICENSE` | License identifier | None |\n| `--author AUTHOR` | Author name | None |\n| `--author-email EMAIL` | Author email | None |\n| `--url URL` | Project URL | None |\n| `--requires-python VERSION` | Python version requirement | `>=3.10` |\n| `--readme PATH` | Path to README markdown file | None |\n| `--set-version-var VAR` | Go variable for version via `-X` | None |\n| `--ldflags FLAGS` | Additional Go linker flags | None |\n\n资料来源：[go_to_wheel/__init__.py:50-130](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Data Flow Diagram\n\n```mermaid\nflowchart LR\n subgraph Input\n A[Go Module Directory]\n B[CLI Arguments]\n end\n \n subgraph Processing\n C[Input Validation]\n D[Cross-Compilation]\n E[Metadata Generation]\n F[Zip Packaging]\n end\n \n subgraph Output\n G[Python Wheel Files]\n H[dist/ Directory]\n end\n \n A --> C\n B --> C\n C --> D\n D --> E\n E --> F\n F --> G\n G --> H\n```\n\n## Key Function Signatures\n\n### `build_wheels()`\n\n```python\ndef build_wheels(\n go_dir: str,\n *,\n name: str | None = None,\n version: str = \"0.1.0\",\n output_dir: str = \"./dist\",\n entry_point: str | None = None,\n platforms: list[str] | None = None,\n go_binary: str = \"go\",\n description: str = \"Go binary packaged as Python wheel\",\n requires_python: str = \">=3.10\",\n author: str | None = None,\n author_email: str | None = None,\n license_: str | None = None,\n url: str | None = None,\n readme: str | None = None,\n ldflags: str | None = None,\n set_version_var: str | None = None,\n) -> list[str]:\n \"\"\"Build Python wheels from a Go module.\"\"\"\n```\n\n资料来源：[go_to_wheel/__init__.py:150-200](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### `cross_compile_go()`\n\n```python\ndef cross_compile_go(\n go_dir: Path,\n output_path: Path,\n goos: str,\n goarch: str,\n go_binary: str = \"go\",\n ldflags: str | None = None,\n) -> None:\n \"\"\"Cross-compile Go binary for target platform.\"\"\"\n```\n\n资料来源：[go_to_wheel/__init__.py:65-92](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Dependency Architecture\n\n```mermaid\ngraph TD\n A[go-to-wheel] --> B[Python Standard Library]\n \n B --> B1[argparse]\n B --> B2[zipfile]\n B --> B3[subprocess]\n B --> B4[pathlib]\n B --> B5[hashlib]\n B --> B6[csv]\n \n A --> C[External Dependency]\n C --> C1[Go Toolchain]\n```\n\n### Python Dependencies\n\nThe tool uses only Python standard library modules, requiring no external Python dependencies:\n\n- `argparse`: CLI argument parsing\n- `zipfile`: Wheel archive creation\n- `subprocess`: Go compilation invocation\n- `pathlib`: Path manipulation\n- `hashlib`: SHA256 hashing for RECORD\n- `csv`: RECORD file generation\n- `tempfile`: Temporary build directory\n- `shutil`: File operations\n\n### External Dependencies\n\n- **Go >= 1.16**: Required for `go build` and cross-compilation\n\n资料来源：[spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n## Version Information\n\n| Item | Value |\n|------|-------|\n| Project Version | `0.1.0` |\n| Python Requirement | `>=3.10` |\n| Go Requirement | `>=1.16` |\n| License | Apache 2.0 |\n\n资料来源：[go_to_wheel/__init__.py:10](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Installation Methods\n\n```mermaid\ngraph TD\n A[User] --> B{Installation Method}\n \n B --> C[pip install]\n B --> D[pipx install]\n \n C --> E[System Python]\n D --> F[Isolated environment
with PATH access]\n \n E --> G[Requires Go in PATH]\n F --> G\n```\n\n资料来源：[README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n\n---\n\n\n\n## Supported Platforms\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Wheel Generation Process](#page-wheel-generation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [go_to_wheel/__init__.py](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n- [README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n- [spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n \n\n# Supported Platforms\n\n`go-to-wheel` provides comprehensive cross-platform support for distributing Go CLI binaries as Python wheels. The tool automatically generates wheels for all supported platforms with correct PEP 427 tags, enabling seamless installation via `pip` or `pipx`.\n\n## Platform Architecture\n\n`go-to-wheel` maps Go's `GOOS`/`GOARCH` environment variables to Python wheel platform tags. The mapping system allows for precise targeting of specific architectures while maintaining compatibility with the Python packaging ecosystem.\n\n```mermaid\ngraph TD\n A[Go Source Code] --> B[go-to-wheel build]\n B --> C{Platform Selection}\n C -->|Default| D[All 8 Platforms]\n C -->|Custom| E[User-specified subset]\n \n D --> F[Cross-compile with GOOS/GOARCH]\n E --> F\n \n F --> G[Generate wheel with platform tag]\n G --> H[Installable via pip/pipx]\n```\n\n资料来源：[go_to_wheel/__init__.py:9-27](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Default Supported Platforms\n\nThe following 8 platform targets are built by default when no `--platforms` flag is specified:\n\n| Platform Identifier | GOOS | GOARCH | Wheel Tag |\n|---------------------|------|--------|-----------|\n| `linux-amd64` | `linux` | `amd64` | `manylinux_2_17_x86_64` |\n| `linux-arm64` | `linux` | `arm64` | `manylinux_2_17_aarch64` |\n| `linux-amd64-musl` | `linux` | `amd64` | `musllinux_1_2_x86_64` |\n| `linux-arm64-musl` | `linux` | `arm64` | `musllinux_1_2_aarch64` |\n| `darwin-amd64` | `darwin` | `amd64` | `macosx_10_9_x86_64` |\n| `darwin-arm64` | `darwin` | `arm64` | `macosx_11_0_arm64` |\n| `windows-amd64` | `windows` | `amd64` | `win_amd64` |\n| `windows-arm64` | `windows` | `arm64` | `win_arm64` |\n\n资料来源：[go_to_wheel/__init__.py:9-27](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Platform Selection Options\n\n### Building All Platforms (Default)\n\nWithout specifying platforms, all 8 targets are built:\n\n```bash\ngo-to-wheel ./mytool\n```\n\n### Building Specific Platforms\n\nUse the `--platforms` flag with a comma-separated list:\n\n```bash\ngo-to-wheel ./mytool --platforms linux-amd64,darwin-arm64\n```\n\nOnly Linux amd64 and macOS ARM64 wheels will be generated.\n\n资料来源：[README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n\n## Linux Variants\n\n### glibc-based (manylinux)\n\nThe `linux-amd64` and `linux-arm64` targets produce binaries linked against glibc, using the `manylinux_2_17` container tag. These wheels are compatible with most modern Linux distributions including:\n\n- Ubuntu 18.04+\n- Debian 10+\n- Fedora 30+\n- RHEL/CentOS 8+\n- Amazon Linux 2\n\n### musl-based (musllinux)\n\nThe `linux-amd64-musl` and `linux-arm64-musl` targets produce static binaries linked against musl libc. These wheels target:\n\n- Alpine Linux (all versions)\n- OpenWrt\n- Other musl-based distributions\n\nMusl builds are compiled with `CGO_ENABLED=0` to ensure fully static linking, eliminating any libc dependency issues.\n\n资料来源：[spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n## macOS Support\n\n### Universal2 Consideration\n\nWhile `go-to-wheel` does not natively generate `darwin-universal2` wheels that combine both architectures, the tool can build both `darwin-amd64` and `darwin-arm64` separately. Users can combine them using Apple's `lipo` tool if a single universal binary is required:\n\n```bash\nlipo -create mytool-darwin-amd64 mytool-darwin-arm64 -output mytool-darwin-universal\n```\n\n资料来源：[spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n### macOS Version Compatibility\n\n| Wheel Tag | Minimum macOS Version | Architecture |\n|-----------|----------------------|--------------|\n| `macosx_10_9_x86_64` | macOS 10.9 (Mavericks) | Intel |\n| `macosx_11_0_arm64` | macOS 11.0 (Big Sur) | Apple Silicon |\n\nThe x86_64 tag maintains backwards compatibility to macOS 10.9, while the ARM64 tag starts from macOS 11.0 due to Apple Silicon hardware requirements.\n\n## Windows Support\n\nWindows builds are cross-compiled from Linux/macOS hosts using `CGO_ENABLED=0`. The tool automatically appends the `.exe` extension to the binary within the wheel.\n\n| Wheel Tag | Architecture | Notes |\n|-----------|-------------|-------|\n| `win_amd64` | x86_64 | 64-bit Windows |\n| `win_arm64` | ARM64 | Windows on ARM devices |\n\n## Build Process\n\nThe platform-specific build workflow demonstrates how `go-to-wheel` handles cross-compilation:\n\n```mermaid\ngraph LR\n A[Source Host] -->|GOOS=linux GOARCH=amd64| B[Linux amd64 binary]\n A -->|GOOS=linux GOARCH=arm64| C[Linux arm64 binary]\n A -->|GOOS=darwin GOARCH=amd64| D[macOS amd64 binary]\n A -->|GOOS=darwin GOARCH=arm64| E[macOS arm64 binary]\n A -->|GOOS=windows GOARCH=amd64| F[Windows amd64 binary]\n \n B --> G[Wheel: manylinux_2_17_x86_64]\n C --> H[Wheel: manylinux_2_17_aarch64]\n D --> I[Wheel: macosx_10_9_x86_64]\n E --> J[Wheel: macosx_11_0_arm64]\n F --> K[Wheel: win_amd64]\n \n style A fill:#f9f,color:#000\n style G fill:#9f9,color:#000\n style H fill:#9f9,color:#000\n style I fill:#9f9,color:#000\n style J fill:#9f9,color:#000\n style K fill:#9f9,color:#000\n```\n\nEach build uses the following environment configuration:\n\n```python\nenv[\"GOOS\"] = goos\nenv[\"GOARCH\"] = goarch\nenv[\"CGO_ENABLED\"] = \"0\"\n```\n\n资料来源：[go_to_wheel/__init__.py:129-136](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Wheel Installation Compatibility\n\nThe wheel filename format ensures pip automatically selects the correct wheel for the target platform:\n\n```\n{package_name}-{version}-py3-none-{platform_tag}.whl\n```\n\nExample wheel names:\n\n| Wheel Filename | Platform |\n|----------------|----------|\n| `mytool-1.0.0-py3-none-manylinux_2_17_x86_64.whl` | Linux x86_64 (glibc) |\n| `mytool-1.0.0-py3-none-musllinux_1_2_aarch64.whl` | Linux ARM64 (musl) |\n| `mytool-1.0.0-py3-none-macosx_11_0_arm64.whl` | macOS Apple Silicon |\n| `mytool-1.0.0-py3-none-win_amd64.whl` | Windows x86_64 |\n\n资料来源：[spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n## Requirements\n\nBuilding wheels requires:\n\n| Component | Requirement |\n|-----------|-------------|\n| Go | >= 1.16 (for `go mod` support) |\n| Python | >= 3.10 |\n| Python dependencies | None (stdlib only) |\n\nThe build host does not need to match the target platform due to Go's native cross-compilation support.\n\n## Platform Detection for Binary Execution\n\nThe generated `__init__.py` wrapper uses `sys.platform` to handle platform-specific behavior:\n\n```python\ndef main():\n \"\"\"Execute the bundled binary.\"\"\"\n binary = get_binary_path()\n if sys.platform == \"win32\":\n # On Windows, use subprocess to properly handle signals\n sys.exit(subprocess.call([binary] + sys.argv[1:]))\n else:\n # On Unix, exec replaces the process\n os.execvp(binary, [binary] + sys.argv[1:])\n```\n\nThis ensures consistent behavior across all supported platforms while respecting OS-specific process management conventions.\n\n资料来源：[go_to_wheel/__init__.py:158-170](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n---\n\n\n\n## Wheel Generation Process\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Supported Platforms](#page-platforms)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [go_to_wheel/__init__.py](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n- [spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n- [README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n \n\n# Wheel Generation Process\n\n## Overview\n\nThe Wheel Generation Process is the core mechanism of `go-to-wheel` that transforms a Go CLI program into a distributable Python wheel package. This process handles cross-compilation, binary packaging, and wheel metadata generation for multiple target platforms in a single operation.\n\nThe wheel generation workflow accepts a Go module directory, validates the input, compiles static binaries for each target platform, creates a Python package wrapper, and packages everything into properly tagged wheel files following PEP 427 and PEP 376 standards.\n\n资料来源：[spec.md:1-25]()\n\n## Platform Configuration\n\n### Supported Platforms\n\nThe tool supports eight target platforms by default, covering major operating systems and architectures:\n\n| Platform Key | GOOS | GOARCH | Wheel Tag |\n|-------------|------|--------|-----------|\n| `linux-amd64` | `linux` | `amd64` | `manylinux_2_17_x86_64` |\n| `linux-arm64` | `linux` | `arm64` | `manylinux_2_17_aarch64` |\n| `linux-amd64-musl` | `linux` | `amd64` | `musllinux_1_2_x86_64` |\n| `linux-arm64-musl` | `linux` | `arm64` | `musllinux_1_2_aarch64` |\n| `darwin-amd64` | `darwin` | `amd64` | `macosx_10_9_x86_64` |\n| `darwin-arm64` | `darwin` | `arm64` | `macosx_11_0_arm64` |\n| `windows-amd64` | `windows` | `amd64` | `win_amd64` |\n| `windows-arm64` | `windows` | `arm64` | `win_arm64` |\n\n资料来源：[go_to_wheel/__init__.py:15-29]()\n\n### Platform Mapping Structure\n\nThe `PLATFORM_MAPPINGS` dictionary maps platform keys to a tuple containing the Go operating system, Go architecture, and the corresponding Python wheel platform tag:\n\n```python\nPLATFORM_MAPPINGS: dict[str, tuple[str, str, str]] = {\n \"linux-amd64\": (\"linux\", \"amd64\", \"manylinux_2_17_x86_64\"),\n # ... additional platforms\n}\n```\n\nThe `DEFAULT_PLATFORMS` list defines which platforms are built when no specific platform is specified:\n\n```python\nDEFAULT_PLATFORMS = [\n \"linux-amd64\",\n \"linux-arm64\",\n \"linux-amd64-musl\",\n \"linux-arm64-musl\",\n \"darwin-amd64\",\n \"darwin-arm64\",\n \"windows-amd64\",\n \"windows-arm64\",\n]\n```\n\n资料来源：[go_to_wheel/__init__.py:31-37]()\n\n## Build Process Architecture\n\n### High-Level Workflow\n\n```mermaid\ngraph TD\n A[Start: go-to-wheel Command] --> B[Validate Go Directory]\n B --> C{Valid?}\n C -->|No| D[Error: Directory not found or no go.mod]\n C -->|Yes| E[Parse Options and Set Defaults]\n E --> F{Platforms specified?}\n F -->|Yes| G[Use Specified Platforms]\n F -->|No| H[Use DEFAULT_PLATFORMS]\n G --> I[For Each Platform]\n H --> I\n I --> J[Cross-Compile Go Binary]\n J --> K[Create Package Directory Structure]\n K --> L[Generate Python Wrapper Files]\n L --> M[Generate Metadata Files]\n M --> N[Create Wheel ZIP Archive]\n N --> O{More Platforms?}\n O -->|Yes| I\n O -->|No| P[Move Wheels to Output Directory]\n P --> Q[Print Summary]\n```\n\n### Main Entry Point\n\nThe `build_wheels()` function serves as the primary entry point for the wheel generation process. It accepts the following parameters:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `go_dir` | `str` | Required | Path to Go module directory |\n| `name` | `str \\| None` | `None` | Python package name (defaults to directory basename) |\n| `version` | `str` | `\"0.1.0\"` | Package version |\n| `output_dir` | `str` | `\"./dist\"` | Directory for built wheels |\n| `entry_point` | `str \\| None` | `None` | CLI command name (defaults to package name) |\n| `platforms` | `list[str] \\| None` | `None` | Target platforms (defaults to all) |\n| `go_binary` | `str` | `\"go\"` | Path to Go binary |\n| `description` | `str` | `\"Go binary packaged as Python wheel\"` | Package description |\n| `requires_python` | `str` | `\">=3.10\"` | Python version requirement |\n| `author` | `str \\| None` | `None` | Author name |\n| `author_email` | `str \\| None` | `None` | Author email |\n| `license_` | `str \\| None` | `None` | License identifier |\n| `url` | `str \\| None` | `None` | Project URL |\n| `readme` | `str \\| None` | `None` | Path to README markdown file |\n| `ldflags` | `str \\| None` | `None` | Additional Go linker flags |\n| `set_version_var` | `str \\| None` | `None` | Go variable to set via -X ldflag |\n\n资料来源：[go_to_wheel/__init__.py:136-168]()\n\n## Step-by-Step Generation Process\n\n### Step 1: Input Validation\n\nThe process begins with comprehensive validation of the input parameters:\n\n1. **Directory Existence**: Verify the Go directory exists using `Path.resolve()`\n2. **Go Module Verification**: Check for `go.mod` file to confirm valid Go module\n3. **README File Check**: If `--readme` is provided, verify the file exists and read its content\n4. **Default Value Assignment**: Set defaults for `name` and `entry_point` from directory name\n\n```python\ngo_path = Path(go_dir).resolve()\n\nif not go_path.exists():\n raise FileNotFoundError(f\"Go directory not found: {go_dir}\")\n\nif not (go_path / \"go.mod\").exists():\n raise ValueError(f\"Not a Go module: {go_dir} (no go.mod file found)\")\n```\n\n资料来源：[go_to_wheel/__init__.py:179-186]()\n\n### Step 2: Cross-Compilation\n\nEach Go binary is compiled for its target platform using environment variables:\n\n```mermaid\ngraph LR\n A[Platform: linux-amd64] --> B[\"GOOS=linux
GOARCH=amd64
CGO_ENABLED=0\"]\n B --> C[\"go build
-ldflags='-s -w'
-o output\"]\n C --> D[Static Binary]\n \n E[Platform: windows-amd64] --> F[\"GOOS=windows
GOARCH=amd64
CGO_ENABLED=0\"]\n F --> G[\"go build
-ldflags='-s -w'
-o output.exe\"]\n G --> H[Static Binary .exe]\n```\n\n**Compilation Environment Variables:**\n\n| Variable | Value | Purpose |\n|----------|-------|---------|\n| `GOOS` | Platform's OS | Target operating system |\n| `GOARCH` | Platform's architecture | Target CPU architecture |\n| `CGO_ENABLED` | `0` | Disable CGO for static binaries |\n\n**Linker Flags:**\n\nThe default linker flags `-s -w` strip debug information and symbol tables to reduce binary size. Additional flags can be appended via the `--ldflags` option:\n\n```python\nGOOS={goos} GOARCH={goarch} CGO_ENABLED=0 go build \\\n -ldflags=\"-s -w {additional_flags}\" \\\n -o {output_path} \\\n {go_module_path}\n```\n\n资料来源：[spec.md:145-156]()\n\n### Step 3: Wheel Package Structure Creation\n\nThe wheel contains a specific directory structure following PEP 427:\n\n```\n{package_name}-{version}-py3-none-{platform_tag}.whl\n├── {package_name}/\n│ ├── __init__.py\n│ ├── __main__.py\n│ └── bin/\n│ └── {binary_name}[.exe]\n├── {package_name}-{version}.dist-info/\n│ ├── METADATA\n│ ├── WHEEL\n│ ├── RECORD\n│ └── entry_points.txt\n```\n\n资料来源：[spec.md:40-57]()\n\n### Step 4: Python Wrapper Generation\n\nThe generated `__init__.py` provides a thin wrapper that executes the bundled binary:\n\n```python\n\"\"\"Go binary packaged as Python wheel.\"\"\"\n\nimport os\nimport sys\nimport subprocess\n\n__version__ = \"{version}\"\n\ndef get_binary_path():\n \"\"\"Return the path to the bundled binary.\"\"\"\n return os.path.join(os.path.dirname(__file__), \"bin\", \"{binary_name}\")\n\ndef main():\n \"\"\"Execute the bundled binary.\"\"\"\n binary = get_binary_path()\n if sys.platform == \"win32\":\n # On Windows, use subprocess to properly handle signals\n sys.exit(subprocess.call([binary] + sys.argv[1:]))\n else:\n # On Unix, exec replaces the process\n os.execvp(binary, [binary] + sys.argv[1:])\n```\n\nThe `__main__.py` serves as the entry point bridge:\n\n```python\nfrom . import main\nmain()\n```\n\n资料来源：[spec.md:63-87]()\n\n### Step 5: Metadata File Generation\n\n#### METADATA (PEP 566)\n\nGenerated dynamically with package metadata:\n\n```\nMetadata-Version: 2.1\nName: {normalized_name}\nVersion: {version}\nSummary: {description}\nLicense: {license}\nAuthor: {author}\nAuthor-email: {author_email}\nHome-page: {url}\nRequires-Python: {requires_python}\n```\n\n#### WHEEL (PEP 427)\n\n```python\nWheel-Version: 1.0\nGenerator: go-to-wheel {version}\nRoot-Is-Purelib: false\nTag: py3-none-{platform_tag}\n```\n\n#### entry_points.txt\n\n```ini\n[console_scripts]\n{entry_point} = {package_name}:main\n```\n\n#### RECORD (PEP 376)\n\nCSV format tracking all files with SHA256 hashes:\n\n```csv\n{package_name}/__init__.py,sha256={hash},{size}\n{package_name}/__main__.py,sha256={hash},{size}\n{package_name}/bin/{binary_name},sha256={hash},{size}\n{package_name}-{version}.dist-info/METADATA,sha256={hash},{size}\n{package_name}-{version}.dist-info/WHEEL,sha256={hash},{size}\n{package_name}-{version}.dist-info/entry_points.txt,sha256={hash},{size}\n{package_name}-{version}.dist-info/RECORD,,\n```\n\n资料来源：[spec.md:162-183]()\n\n### Step 6: Wheel Archive Creation\n\nThe wheel is created as a ZIP archive with specific handling:\n\n```python\nwith zipfile.ZipFile(wheel_path, \"w\", zipfile.ZIP_DEFLATED) as whl:\n for file_path, content in files.items():\n # Set executable permission for binary\n if \"/bin/\" in file_path:\n info = zipfile.ZipInfo(file_path)\n # Set Unix permissions: rwxr-xr-x (0755)\n info.external_attr = (\n stat.S_IRWXU | stat.S_IRGRP | stat.S_IXGRP | \n stat.S_IROTH | stat.S_IXOTH\n ) << 16\n whl.writestr(info, content)\n else:\n whl.writestr(file_path, content)\n```\n\nBinary files receive executable permissions (0755) via the ZIP external attributes, ensuring they can be executed after installation.\n\n资料来源：[go_to_wheel/__init__.py:110-123]()\n\n## Wheel Naming Convention\n\nWheels follow PEP 427 naming with format:\n\n```\n{name}-{version}-py3-none-{platform_tag}.whl\n```\n\n**Examples:**\n\n| Package | Version | Platform | Full Wheel Name |\n|---------|---------|----------|-----------------|\n| `myapp` | `1.0.0` | linux-amd64 | `myapp-1.0.0-py3-none-manylinux_2_17_x86_64.whl` |\n| `myapp` | `1.0.0` | darwin-arm64 | `myapp-1.0.0-py3-none-macosx_11_0_arm64.whl` |\n| `myapp` | `1.0.0` | windows-amd64 | `myapp-1.0.0-py3-none-win_amd64.whl` |\n\nPackage names are normalized per PEP 503: hyphens are used in wheel filenames, while the import name (directory) uses underscores.\n\n资料来源：[spec.md:207-216]()\n\n## Linker Flags Integration\n\n### Version Variable Setting\n\nThe `--set-version-var` option embeds the package version into a Go variable at compile time:\n\n```bash\ngo-to-wheel ./mytool --version 2.0.0 --set-version-var main.version\n```\n\nThis passes `-X main.version=2.0.0` to the Go linker. The combined ldflags are constructed as:\n\n```python\ncombined_ldflags_parts: list[str] = []\nif set_version_var:\n combined_ldflags_parts.append(f\"-X {set_version_var}={version}\")\nif ldflags:\n combined_ldflags_parts.append(ldflags)\n\ncombined_ldflags = \" \".join(combined_ldflags_parts)\n```\n\nThe final linker invocation becomes: `-ldflags=\"-s -w -X main.version=2.0.0\"`\n\n资料来源：[go_to_wheel/__init__.py:196-203]()\n\n### Custom ldflags\n\nAdditional arbitrary linker flags can be passed with `--ldflags`:\n\n```bash\ngo-to-wheel ./mytool --ldflags \"-X main.version=2.0.0 -X main.commit=abc123\"\n```\n\nThese flags are appended to the default `-s -w`, so the full invocation becomes `-ldflags=\"-s -w -X main.version=2.0.0 -X main.commit=abc123\"`.\n\n资料来源：[README.md:48-51]()\n\n## Error Handling\n\n| Error Condition | Handling |\n|-----------------|----------|\n| Directory not found | `FileNotFoundError` with message |\n| No `go.mod` file | `ValueError` indicating invalid Go module |\n| README file not found | `FileNotFoundError` for README path |\n| Go binary not found | `FileNotFoundError` from subprocess |\n| Build failure | Exception propagates with Go error output |\n| No wheels built | Prints error and returns exit code 1 |\n\nThe CLI entry point catches `FileNotFoundError` and `ValueError` exceptions, printing them to stderr and returning exit code 1:\n\n```python\ntry:\n wheels = build_wheels(...)\nexcept (FileNotFoundError, ValueError) as e:\n print(f\"Error: {e}\", file=sys.stderr)\n return 1\n```\n\n资料来源：[go_to_wheel/__init__.py:92-95]()\n\n## Output Example\n\nSuccessful wheel generation produces output like:\n\n```\ngo-to-wheel v0.1.0\nBuilding from ./myapp\n\n ✓ myapp-1.0.0-py3-none-manylinux_2_17_x86_64.whl\n ✓ myapp-1.0.0-py3-none-manylinux_2_17_aarch64.whl\n ✓ myapp-1.0.0-py3-none-musllinux_1_2_x86_64.whl\n ✓ myapp-1.0.0-py3-none-musllinux_1_2_aarch64.whl\n ✓ myapp-1.0.0-py3-none-macosx_10_9_x86_64.whl\n ✓ myapp-1.0.0-py3-none-macosx_11_0_arm64.whl\n ✓ myapp-1.0.0-py3-none-win_amd64.whl\n ✓ myapp-1.0.0-py3-none-win_arm64.whl\n\nDone! Built 8 wheels in ./dist\n```\n\n资料来源：[spec.md:225-240]()\n\n## Related Components\n\n| Component | Purpose |\n|-----------|---------|\n| `build_wheels()` | Main orchestrator function |\n| `build_single_wheel()` | Creates wheel for one platform |\n| `compile_go_binary()` | Executes Go cross-compilation |\n| `generate_metadata()` | Creates METADATA content |\n| `generate_wheel_file()` | Creates WHEEL file content |\n| `generate_record()` | Creates RECORD with hashes |\n| `generate_entry_points()` | Creates entry_points.txt |\n\nThese functions work together to transform a Go module into a distributable Python wheel package that can be installed via `pip` or `pipx`.\n\n资料来源：[go_to_wheel/__init__.py:96-135]()\n\n## See Also\n\n- [go-to-wheel GitHub Repository](https://github.com/simonw/go-to-wheel)\n- [maturin](https://github.com/PyO3/maturin) - Rust equivalent tool\n- [PEP 427 - Wheel Binary Package Format](https://peps.python.org/pep-0427/)\n- [PEP 376 - Wheel Metadata and RECORD](https://peps.python.org/pep-0376/)\n\n---\n\n\n\n## Development Guide\n\n### 相关页面\n\n相关主题：[Installation](#page-installation), [Configuration and Metadata](#page-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [go_to_wheel/__init__.py](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n- [README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n- [spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n- [pyproject.toml](https://github.com/simonw/go-to-wheel/blob/main/pyproject.toml)\n \n\n# Development Guide\n\n## Overview\n\nThis guide covers everything you need to know to develop, test, and contribute to `go-to-wheel`. The project is a Python CLI tool that compiles Go programs into Python wheels, enabling distribution of Go binaries via PyPI and pipx. 资料来源：[README.md:1-15]()\n\nThe tool requires no external Python dependencies—only Python's standard library is used—making it lightweight and easy to maintain. 资料来源：[spec.md:95-97]()\n\n## Prerequisites\n\nBefore setting up a development environment, ensure you have the following installed:\n\n| Requirement | Minimum Version | Purpose |\n|-------------|-----------------|---------|\n| Python | >= 3.10 | Runtime for the tool |\n| Go | >= 1.16 | Required for `go build` commands |\n| uv | Latest | Package manager and test runner |\n| Git | Any recent | Version control |\n\n资料来源：[spec.md:95-100]()\n\n## Repository Structure\n\n```\ngo-to-wheel/\n├── go_to_wheel/\n│ └── __init__.py # Main module with all logic\n├── tests/\n│ └── test_*.py # Test files\n├── pyproject.toml # Project configuration\n├── README.md # User documentation\n├── spec.md # Technical specification\n└── LICENSE # Apache 2.0 license\n```\n\nThe main implementation resides in `go_to_wheel/__init__.py`, which contains:\n\n- Platform mapping definitions\n- CLI argument parsing\n- Go cross-compilation logic\n- Wheel building functions\n- Metadata generation\n\n资料来源：[go_to_wheel/__init__.py:1-50]()\n\n## Setting Up the Development Environment\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/simonw/go-to-wheel\ncd go-to-wheel\n```\n\n资料来源：[README.md:55-58]()\n\n### 2. Install Dependencies\n\nThe project uses `uv` for dependency management. Install all development dependencies:\n\n```bash\nuv sync\n```\n\nThis automatically installs the project and its test dependencies based on `pyproject.toml`.\n\n### 3. Verify Installation\n\nConfirm the tool is accessible:\n\n```bash\nuv run go-to-wheel --version\n```\n\n## Running Tests\n\nThe project uses `pytest` for testing. Execute the full test suite with:\n\n```bash\nuv run pytest\n```\n\n资料来源：[README.md:59-60]()\n\n### Test Structure\n\nTests are located in the `tests/` directory and follow the naming pattern `test_*.py`. Each test file typically corresponds to a major component:\n\n| Test File | Coverage Area |\n|-----------|---------------|\n| `test_platforms.py` | Platform mapping and validation |\n| `test_build.py` | Wheel building logic |\n| `test_cli.py` | Command-line argument parsing |\n\n### Running Specific Tests\n\nRun tests matching a pattern:\n\n```bash\nuv run pytest -k \"test_name_pattern\"\n```\n\nRun with verbose output:\n\n```bash\nuv run pytest -v\n```\n\n## Code Architecture\n\n### Core Components\n\n```mermaid\ngraph TD\n A[CLI Entry Point] --> B[Argument Parser]\n B --> C[build_wheels Function]\n C --> D[Platform Validation]\n C --> E[Go Cross-Compilation]\n E --> F[Wheel Assembly]\n F --> G[Metadata Generation]\n F --> H[ZIP Creation]\n G --> H\n H --> I[Output Wheels]\n```\n\n### Platform Mapping System\n\nThe tool defines platform mappings that translate human-readable platform names to Go environment variables and wheel tags:\n\n```python\nPLATFORM_MAPPINGS: dict[str, tuple[str, str, str]] = {\n \"linux-amd64\": (\"linux\", \"amd64\", \"manylinux_2_17_x86_64\"),\n \"linux-arm64\": (\"linux\", \"arm64\", \"manylinux_2_17_aarch64\"),\n \"linux-amd64-musl\": (\"linux\", \"amd64\", \"musllinux_1_2_x86_64\"),\n \"linux-arm64-musl\": (\"linux\", \"arm64\", \"musllinux_1_2_aarch64\"),\n \"darwin-amd64\": (\"darwin\", \"amd64\", \"macosx_10_9_x86_64\"),\n \"darwin-arm64\": (\"darwin\", \"arm64\", \"macosx_11_0_arm64\"),\n \"windows-amd64\": (\"windows\", \"amd64\", \"win_amd64\"),\n \"windows-arm64\": (\"windows\", \"arm64\", \"win_arm64\"),\n}\n```\n\n资料来源：[go_to_wheel/__init__.py:19-27]()\n\n### Default Platforms\n\n```mermaid\ngraph LR\n A[Default Platforms] --> B[Linux amd64]\n A --> C[Linux arm64]\n A --> D[Linux amd64-musl]\n A --> E[Linux arm64-musl]\n A --> F[macOS amd64]\n A --> G[macOS arm64]\n A --> H[Windows amd64]\n A --> I[Windows arm64]\n```\n\nThe `DEFAULT_PLATFORMS` list defines which platforms are built when none are specified:\n\n```python\nDEFAULT_PLATFORMS = [\n \"linux-amd64\",\n \"linux-arm64\",\n \"linux-amd64-musl\",\n \"linux-arm64-musl\",\n \"darwin-amd64\",\n \"darwin-arm64\",\n \"windows-amd64\",\n \"windows-arm64\",\n]\n```\n\n资料来源：[go_to_wheel/__init__.py:29-37]()\n\n### Build Workflow\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI\n participant Builder\n participant Go\n participant WheelBuilder\n \n User->>CLI: go-to-wheel ./myapp\n CLI->>Builder: build_wheels(go_dir)\n Builder->>Go: GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build\n Go-->>Builder: Binary for linux/amd64\n Builder->>Go: (repeat for each platform)\n Go-->>Builder: Binaries for all platforms\n Builder->>WheelBuilder: Create wheel structure\n WheelBuilder->>WheelBuilder: Generate __init__.py\n WheelBuilder->>WheelBuilder: Generate METADATA\n WheelBuilder->>WheelBuilder: Create RECORD with hashes\n WheelBuilder->>Builder: Wheel file\n Builder->>User: List of wheel paths\n```\n\n## Building Wheels Locally\n\n### Local Installation\n\nInstall the package in development mode:\n\n```bash\nuv pip install -e .\n```\n\n### Building Wheels for Testing\n\nCreate test wheels for a sample Go module:\n\n```bash\ngo-to-wheel ./path/to/go-module --name my-test-package\n```\n\nThis creates wheels in `./dist` for all default platforms. 资料来源：[README.md:31-37]()\n\n### Custom Platform Selection\n\nBuild only specific platforms to speed up iteration:\n\n```bash\ngo-to-wheel ./myapp --platforms linux-amd64,darwin-arm64\n```\n\n## CLI Argument Reference\n\nThe tool accepts the following arguments for development and testing:\n\n| Argument | Type | Default | Purpose |\n|----------|------|---------|---------|\n| `--name` | string | Directory name | Python package name |\n| `--version` | string | `0.1.0` | Package version |\n| `--output-dir` | string | `./dist` | Output directory |\n| `--platforms` | string | All platforms | Target platforms |\n| `--go-binary` | string | `go` | Go binary path |\n| `--ldflags` | string | None | Additional linker flags |\n\n资料来源：[go_to_wheel/__init__.py:75-100]()\n\n## Cross-Compilation Process\n\nThe build process uses Go's cross-compilation with specific environment settings:\n\n```python\ndef compile_go_binary(\n go_dir: str,\n goos: str,\n goarch: str,\n output_path: str,\n go_binary: str,\n ldflags: str | None = None,\n) -> None:\n env = os.environ.copy()\n env[\"GOOS\"] = goos\n env[\"GOARCH\"] = goarch\n env[\"CGO_ENABLED\"] = \"0\" # Static binaries\n \n ldflags_value = \"-s -w\" # Strip debug info\n if ldflags:\n ldflags_value += \" \" + ldflags\n \n cmd = [go_binary, \"build\", f\"-ldflags={ldflags_value}\", \"-o\", output_path, \".\"]\n```\n\nKey points:\n- `CGO_ENABLED=0` ensures static binaries with no libc dependency\n- `-ldflags=\"-s -w\"` strips debug information to reduce binary size\n- Windows builds automatically receive `.exe` extension\n\n资料来源：[go_to_wheel/__init__.py:120-140]()\n\n## Wheel Structure Generation\n\nEach wheel contains a Python wrapper that executes the bundled binary:\n\n```mermaid\ngraph TD\n subgraph Wheel Contents\n A[Package Directory] --> B[__init__.py]\n A --> C[__main__.py]\n A --> D[bin/]\n D --> E[Go Binary]\n A --> F[.dist-info/]\n F --> G[METADATA]\n F --> H[WHEEL]\n F --> I[RECORD]\n F --> J[entry_points.txt]\n end\n```\n\nThe `__init__.py` includes:\n\n```python\ndef get_binary_path():\n \"\"\"Return the path to the bundled binary.\"\"\"\n return os.path.join(os.path.dirname(__file__), \"bin\", \"{binary_name}\")\n\ndef main():\n \"\"\"Execute the bundled binary.\"\"\"\n binary = get_binary_path()\n if sys.platform == \"win32\":\n sys.exit(subprocess.call([binary] + sys.argv[1:]))\n else:\n os.execvp(binary, [binary] + sys.argv[1:])\n```\n\n资料来源：[spec.md:58-75]()\n\n## Version Information\n\nThe project version is defined in the main module:\n\n```python\n__version__ = \"0.1.0\"\n```\n\n资料来源：[go_to_wheel/__init__.py:12]()\n\nTo check the installed version during development:\n\n```bash\nuv run python -c \"import go_to_wheel; print(go_to_wheel.__version__)\"\n```\n\n## Debugging\n\n### Enable Verbose Output\n\nThe CLI outputs progress during builds:\n\n```\ngo-to-wheel v0.1.0\nBuilding from ./myapp\n\nlinux-amd64... done\ndarwin-arm64... done\n```\n\n### Common Build Failures\n\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| `go.mod not found` | Directory is not a Go module | Run `go mod init` first |\n| `Go not found` | Go not in PATH | Install Go or use `--go-binary` |\n| Build timeout | Complex Go project | Increase timeout or skip platforms |\n\n### Inspecting Generated Wheels\n\nList contents of a wheel:\n\n```bash\nunzip -l myapp-1.0.0-py3-none-manylinux_2_17_x86_64.whl\n```\n\n## Contributing\n\n### Development Workflow\n\n1. Fork the repository on GitHub\n2. Clone your fork locally\n3. Create a feature branch: `git checkout -b feature/my-feature`\n4. Make changes and add tests\n5. Run the test suite: `uv run pytest`\n6. Commit your changes with clear messages\n7. Push to your fork and submit a pull request\n\n### Code Style\n\n- Follow PEP 8 for Python code\n- Use type hints for function parameters and return values\n- Add docstrings to public functions\n- Keep functions focused and small\n\n### Testing Guidelines\n\n- All new features should include tests\n- Ensure existing tests pass before submitting\n- Use descriptive test names: `test_platform_mapping_linux_amd64`\n\n## Future Development Considerations\n\nThe specification outlines potential future features not yet implemented:\n\n| Feature | Status | Description |\n|---------|--------|-------------|\n| Configuration file | Not started | Support `pyproject.toml` or `go-to-wheel.toml` |\n| Auto version detection | Not started | Parse from VERSION file or git tags |\n| Multiple entry points | Not started | Support Go modules with multiple binaries |\n| Universal2 macOS | Not started | Combine arm64 and x86_64 with `lipo` |\n| Build caching | Not started | Skip unchanged platforms |\n| PyPI publishing | Not started | Add `go-to-wheel publish` command |\n\n资料来源：[spec.md:80-93]()\n\n## Related Documentation\n\n- [User README](README.md) - Installation and usage instructions\n- [Technical Specification](spec.md) - Detailed system design\n- [maturin](https://github.com/PyO3/maturin) - Rust equivalent that inspired this project\n- [pip-binary-factory](https://github.com/Bing-su/pip-binary-factory) - Template for pre-built binaries\n\n---\n\n\n\n## Configuration and Metadata\n\n### 相关页面\n\n相关主题：[CLI Options Reference](#page-cli-options), [Development Guide](#page-development-guide)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [go_to_wheel/__init__.py](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n- [README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n- [spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n \n\n# Configuration and Metadata\n\nThis page documents the configuration system and metadata handling in go-to-wheel, a tool that compiles Go CLI programs into Python wheels.\n\n## Overview\n\ngo-to-wheel provides extensive configuration options for customizing wheel builds. Configuration is passed through command-line arguments and is used to generate proper Python wheel metadata according to PEP 427 and PEP 566 standards.\n\nThe tool supports two layers of configuration:\n1. **Build Configuration** - Controls how the Go binary is compiled (platforms, Go binary path, ldflags)\n2. **Package Metadata** - Defines Python package metadata (name, version, author, license, etc.)\n\n资料来源：[go_to_wheel/__init__.py:1-50](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Platform Configuration\n\n### Supported Platforms\n\ngo-to-wheel supports cross-compilation for 8 different platform configurations:\n\n| Platform Identifier | GOOS | GOARCH | Wheel Tag |\n|---------------------|------|--------|-----------|\n| `linux-amd64` | linux | amd64 | `manylinux_2_17_x86_64` |\n| `linux-arm64` | linux | arm64 | `manylinux_2_17_aarch64` |\n| `linux-amd64-musl` | linux | amd64 | `musllinux_1_2_x86_64` |\n| `linux-arm64-musl` | linux | arm64 | `musllinux_1_2_aarch64` |\n| `darwin-amd64` | darwin | amd64 | `macosx_10_9_x86_64` |\n| `darwin-arm64` | darwin | arm64 | `macosx_11_0_arm64` |\n| `windows-amd64` | windows | amd64 | `win_amd64` |\n| `windows-arm64` | windows | arm64 | `win_arm64` |\n\n资料来源：[go_to_wheel/__init__.py:22-30](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### Platform Selection\n\nBy default, all 8 platforms are built. Users can specify a subset using the `--platforms` option:\n\n```bash\ngo-to-wheel ./mytool --platforms linux-amd64,darwin-arm64\n```\n\nPlatform identifiers are defined in the `PLATFORM_MAPPINGS` dictionary and can be parsed from comma-separated input.\n\n资料来源：[go_to_wheel/__init__.py:86-90](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### Build Workflow\n\n```mermaid\ngraph TD\n A[Parse --platforms argument] --> B{Platforms specified?}\n B -->|No| C[Use DEFAULT_PLATFORMS]\n B -->|Yes| D[Split by comma]\n D --> E[Validate each platform]\n E --> F[For each platform]\n F --> G[Set GOOS/GOARCH env]\n G --> H[Run go build with CGO_ENABLED=0]\n H --> I[Create wheel structure]\n I --> J[Generate METADATA, WHEEL, RECORD]\n J --> K[Zip into .whl file]\n K --> F\n```\n\n## Command-Line Options\n\n### Full Option Reference\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--name` | string | Directory basename | Python package name |\n| `--version` | string | `0.1.0` | Package version |\n| `--output-dir` | string | `./dist` | Directory for built wheels |\n| `--entry-point` | string | Same as `--name` | CLI command name |\n| `--platforms` | string | All 8 platforms | Comma-separated platform list |\n| `--go-binary` | string | `go` | Path to Go binary |\n| `--description` | string | `\"Go binary packaged as Python wheel\"` | Package description |\n| `--license` | string | None | SPDX license identifier |\n| `--author` | string | None | Author name |\n| `--author-email` | string | None | Author email |\n| `--url` | string | None | Project URL |\n| `--requires-python` | string | `>=3.10` | Python version requirement |\n| `--readme` | string | None | Path to README markdown file |\n| `--ldflags` | string | None | Additional Go linker flags |\n| `--set-version-var` | string | None | Go variable for version embedding |\n\n资料来源：[go_to_wheel/__init__.py:52-115](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### Build Configuration Options\n\nThese options control the Go compilation process:\n\n```python\ndef build_wheels(\n go_dir: str,\n *,\n name: str | None = None,\n version: str = \"0.1.0\",\n output_dir: str = \"./dist\",\n entry_point: str | None = None,\n platforms: list[str] | None = None,\n go_binary: str = \"go\",\n description: str = \"Go binary packaged as Python wheel\",\n # ... metadata options ...\n ldflags: str | None = None,\n set_version_var: str | None = None,\n) -> list[str]:\n```\n\n资料来源：[go_to_wheel/__init__.py:178-220](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### Linker Flags Configuration\n\nThe `--ldflags` and `--set-version-var` options control Go linker flags:\n\n**Default flags:** `-s -w` (strips debug info and symbol tables)\n\n**Additional flags** can be appended using `--ldflags`:\n\n```bash\ngo-to-wheel ./mytool --ldflags \"-X main.commit=abc123\"\n```\n\n**Version embedding** via `--set-version-var`:\n\n```bash\ngo-to-wheel ./mytool --version 2.0.0 --set-version-var main.version\n```\n\nThis passes `-X main.version=2.0.0` to the Go linker.\n\n资料来源：[README.md:30-50](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n\nThe linker flags are combined in this order:\n1. `-s -w` (default strip flags)\n2. `-X {set_version_var}={version}` (if `--set-version-var` is set)\n3. User-provided `--ldflags` (appended last)\n\n资料来源：[go_to_wheel/__init__.py:255-265](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Metadata Generation\n\n### METADATA File (PEP 566)\n\nGenerated by `generate_metadata()`:\n\n```python\ndef generate_metadata(\n name: str,\n version: str,\n description: str,\n *,\n author: str | None = None,\n author_email: str | None = None,\n license_: str | None = None,\n url: str | None = None,\n requires_python: str = \">=3.10\",\n readme_content: str | None = None,\n) -> str:\n \"\"\"Generate METADATA file content.\"\"\"\n lines = [\n \"Metadata-Version: 2.1\",\n f\"Name: {name}\",\n f\"Version: {version}\",\n f\"Summary: {description}\",\n ]\n\n if author:\n lines.append(f\"Author: {author}\")\n if author_email:\n lines.append(f\"Author-email: {author_email}\")\n if license_:\n lines.append(f\"License: {license_}\")\n if url:\n lines.append(f\"Home-page: {url}\")\n\n lines.append(f\"Requires-Python: {requires_python}\")\n\n if readme_content:\n lines.append(\"Description-Content-Type: text/markdown\")\n lines.append(\"\")\n lines.append(readme_content)\n\n return \"\\n\".join(lines) + \"\\n\"\n```\n\n资料来源：[go_to_wheel/__init__.py:280-315](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### WHEEL File (PEP 427)\n\nGenerated by `generate_wheel_metadata()`:\n\n```\nWheel-Version: 1.0\nGenerator: go-to-wheel {version}\nRoot-Is-Purelib: false\nTag: py3-none-{platform_tag}\n```\n\nKey points:\n- `Root-Is-Purelib: false` indicates platform-specific binary\n- `py3-none` indicates Python 3+ requirement\n- `{platform_tag}` varies by target (e.g., `manylinux_2_17_x86_64`)\n\n资料来源：[go_to_wheel/__init__.py:317-325](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### entry_points.txt\n\nGenerated for console script entry points:\n\n```\n[console_scripts]\n{entry_point} = {import_name}:main\n```\n\nThe `import_name` is derived from the package name by replacing hyphens with underscores.\n\n资料来源：[go_to_wheel/__init__.py:327-332](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### RECORD File\n\nGenerated by `generate_record()` using SHA256 hashes:\n\n```python\ndef generate_record(files: dict[str, bytes]) -> str:\n \"\"\"Generate RECORD file content.\"\"\"\n output = io.StringIO()\n writer = csv.writer(output)\n\n for path, content in files.items():\n if path.endswith(\"RECORD\"):\n writer.writerow([path, \"\", \"\"])\n else:\n hash_value = base64.urlsafe_b64encode(\n hashlib.sha256(content).digest()\n ).rstrip(b\"=\").decode(\"ascii\")\n writer.writerow([path, f\"sha256={hash_value}\", len(content)])\n\n return output.getvalue()\n```\n\n资料来源：[go_to_wheel/__init__.py:334-348](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Package Structure\n\nThe generated wheel follows this structure:\n\n```\n{package_name}-{version}-py3-none-{platform_tag}.whl\n├── {import_name}/\n│ ├── __init__.py\n│ ├── __main__.py\n│ └── bin/\n│ └── {binary_name}[.exe]\n├── {import_name}-{version}.dist-info/\n│ ├── METADATA\n│ ├── WHEEL\n│ ├── RECORD\n│ └── entry_points.txt\n```\n\n资料来源：[spec.md:60-80](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n### __init__.py Template\n\n```python\n\"\"\"Go binary packaged as Python wheel.\"\"\"\n\nimport os\nimport sys\nimport subprocess\n\n__version__ = \"{version}\"\n\ndef get_binary_path():\n \"\"\"Return the path to the bundled binary.\"\"\"\n return os.path.join(os.path.dirname(__file__), \"bin\", \"{binary_name}\")\n\ndef main():\n \"\"\"Execute the bundled binary.\"\"\"\n binary = get_binary_path()\n if sys.platform == \"win32\":\n sys.exit(subprocess.call([binary] + sys.argv[1:]))\n else:\n os.execvp(binary, [binary] + sys.argv[1:])\n```\n\n资料来源：[spec.md:82-100](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n## Metadata Flow\n\n```mermaid\ngraph LR\n A[CLI Arguments] --> B[ArgumentParser]\n B --> C[build_wheels function]\n C --> D[Input Validation]\n D --> E[README Processing]\n E --> F[Platform Loop]\n F --> G[Go Compilation]\n G --> H[Wheel Assembly]\n H --> I[Metadata Generation]\n I --> J[ZIP Creation]\n J --> K[Output Directory]\n \n C -->|name, version| L[METADATA]\n C -->|platform_tag| M[WHEEL]\n C -->|entry_point| N[entry_points.txt]\n H --> O[RECORD with hashes]\n```\n\n## Input Validation\n\nThe `build_wheels()` function validates inputs:\n\n| Check | Behavior on Failure |\n|-------|---------------------|\n| Go directory exists | Raises `FileNotFoundError` |\n| `go.mod` file present | Raises `ValueError` |\n| README file exists (if provided) | Raises `FileNotFoundError` |\n| Package name valid (PEP 503) | Raises `ValueError` |\n\n资料来源：[go_to_wheel/__init__.py:225-235](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Configuration Precedence\n\nWhen multiple configuration sources conflict, the following precedence applies:\n\n1. **Command-line arguments** (highest priority)\n2. **Default values** (lowest priority)\n\nFor `--ldflags`, user-provided flags are appended after default flags, allowing overrides.\n\n## Environment Variables Used\n\nDuring build, these environment variables are set:\n\n| Variable | Value | Purpose |\n|----------|-------|---------|\n| `GOOS` | Platform GOOS | Cross-compilation target |\n| `GOARCH` | Platform GOARCH | Cross-compilation target |\n| `CGO_ENABLED` | `0` | Static binary compilation |\n\n资料来源：[go_to_wheel/__init__.py:270-280](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Example: Full Metadata Configuration\n\n```bash\ngo-to-wheel ./mytool \\\n --name mytool-bin \\\n --version 2.0.0 \\\n --description \"My awesome tool\" \\\n --license MIT \\\n --author \"Jane Doe\" \\\n --author-email \"jane@example.com\" \\\n --url \"https://github.com/jane/mytool\" \\\n --readme README.md\n```\n\nThis produces a wheel with complete PyPI-compatible metadata.\n\n资料来源：[README.md:55-65](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：simonw/go-to-wheel\n\n摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | no_demo; severity=medium\n\n## 5. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | issue_or_pr_quality=unknown\n\n## 6. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | release_recency=unknown\n\n\n",
"markdown_key": "go-to-wheel",
"pages": "draft",
"source_refs": [
{
"evidence_id": "hn_item:48109677",
"kind": "hn",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://news.ycombinator.com/item?id=48109677"
},
{
"evidence_id": "art_0ebc1ca4318444e4a3baf98f272af635",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/simonw/go-to-wheel#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "go-to-wheel 说明书",
"toc": [
"https://github.com/simonw/go-to-wheel 项目说明书",
"目录",
"Introduction",
"Overview",
"Core Functionality",
"Supported Platforms",
"Installation and Requirements",
"or",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "eb9c343a6bd3c4da4c7bcb4a6106c8fd67cc10a8",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md"
],
"repo_inspection_verified": true,
"review_reasons": [
"community_discussion_evidence_below_public_threshold"
],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# go-to-wheel - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 go-to-wheel 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **想在安装前理解开源项目价值和边界的用户**：当前证据主要来自项目文档。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install go-to-wheel` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `pipx install go-to-wheel` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `pip install ./dist/mytool-1.0.0-py3-none-manylinux_2_17_x86_64.whl` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `git clone https://github.com/simonw/go-to-wheel` 证据：`README.md` Claim：`clm_0006` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：仅建议沙盒试装\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：仅建议沙盒试装\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、本地环境或项目文件、宿主 AI 上下文\n\n### 现在可以相信\n\n- **适合人群线索：想在安装前理解开源项目价值和边界的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0007` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0008` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：14\n- 重要文件覆盖：7/14\n- 证据索引条目：6\n- 角色 / Skill 条目：2\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 go-to-wheel 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 go-to-wheel 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 go-to-wheel 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 2 个角色 / Skill / 项目文档条目。\n\n- **go-to-wheel**（project_doc）：! PyPI https://img.shields.io/pypi/v/go-to-wheel.svg https://pypi.org/project/go-to-wheel/ ! Changelog https://img.shields.io/github/v/release/simonw/go-to-wheel?include prereleases&label=changelog https://github.com/simonw/go-to-wheel/releases ! Tests https://github.com/simonw/go-to-wheel/workflows/Test/badge.svg https://github.com/simonw/go-to-wheel/actions?query=workflow%3ATest ! License https://img.shields.io/ba… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **go-to-wheel Specification**（project_doc）：A Python tool that compiles Go CLI programs for multiple architectures and bundles each as a Python wheel with executable entry points. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`spec.md`\n\n## 证据索引\n\n- 共索引 6 条证据。\n\n- **go-to-wheel**（documentation）：! PyPI https://img.shields.io/pypi/v/go-to-wheel.svg https://pypi.org/project/go-to-wheel/ ! Changelog https://img.shields.io/github/v/release/simonw/go-to-wheel?include prereleases&label=changelog https://github.com/simonw/go-to-wheel/releases ! Tests https://github.com/simonw/go-to-wheel/workflows/Test/badge.svg https://github.com/simonw/go-to-wheel/actions?query=workflow%3ATest ! License https://img.shields.io/badge/license-Apache%202.0-blue.svg https://github.com/simonw/go-to-wheel/blob/main/LICENSE 证据：`README.md`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **go-to-wheel Specification**（documentation）：A Python tool that compiles Go CLI programs for multiple architectures and bundles each as a Python wheel with executable entry points. 证据：`spec.md`\n- **.gitignore**（source_file）：.python-version uv.lock pycache / .pyc .pytest cache/ .venv/ dist/ .egg-info/ 证据：`.gitignore`\n- **Platform mappings: goos, goarch - wheel platform tag**（source_file）：\"\"\"go-to-wheel: Compile Go CLI programs into Python wheels.\"\"\" 证据：`go_to_wheel/__init__.py`\n- **Pyproject**（source_file）：project name = \"go-to-wheel\" version = \"0.2\" description = \"Compile Go CLI programs into Python wheels\" readme = \"README.md\" requires-python = \" =3.10\" license = \"Apache-2.0\" authors = { name = \"Simon Willison\" } dependencies = 证据：`pyproject.toml`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `LICENSE`, `spec.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `LICENSE`, `spec.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Introduction**：importance `high`\n - source_paths: README.md, spec.md\n- **Installation**：importance `high`\n - source_paths: pyproject.toml, README.md\n- **Quick Start Guide**：importance `high`\n - source_paths: README.md, go_to_wheel/__init__.py\n- **CLI Options Reference**：importance `high`\n - source_paths: go_to_wheel/__init__.py, README.md\n- **Usage Examples**：importance `high`\n - source_paths: README.md, go_to_wheel/__init__.py\n- **System Architecture**：importance `high`\n - source_paths: go_to_wheel/__init__.py, spec.md\n- **Supported Platforms**：importance `medium`\n - source_paths: go_to_wheel/__init__.py, README.md\n- **Wheel Generation Process**：importance `medium`\n - source_paths: go_to_wheel/__init__.py, spec.md\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `eb9c343a6bd3c4da4c7bcb4a6106c8fd67cc10a8`\n- inspected_files: `pyproject.toml`, `README.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：simonw/go-to-wheel\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- issue/PR 响应质量未知（low）：用户无法判断遇到问题后是否有人维护。 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/simonw/go-to-wheel 项目说明书\n\n生成时间：2026-05-15 08:31:09 UTC\n\n## 目录\n\n- [Introduction](#page-introduction)\n- [Installation](#page-installation)\n- [Quick Start Guide](#page-quick-start)\n- [CLI Options Reference](#page-cli-options)\n- [Usage Examples](#page-examples)\n- [System Architecture](#page-architecture)\n- [Supported Platforms](#page-platforms)\n- [Wheel Generation Process](#page-wheel-generation)\n- [Development Guide](#page-development-guide)\n- [Configuration and Metadata](#page-configuration)\n\n\n\n## Introduction\n\n### 相关页面\n\n相关主题：[Installation](#page-installation), [Quick Start Guide](#page-quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n- [spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n- [go_to_wheel/__init__.py](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n \n\n# Introduction\n\n## Overview\n\n`go-to-wheel` is a Python command-line tool that compiles Go CLI programs into Python wheels, enabling Go binaries to be distributed and installed through the Python packaging ecosystem via `pip` or `pipx`. This tool bridges the Go and Python communities by providing a seamless way to package and distribute Go applications to Python developers who are accustomed to installing tools through Python package managers. The project was created to address the gap in the ecosystem—there was no equivalent to Rust's `maturin --bindings bin` for Go, and `go-to-wheel` fills that void by providing a straightforward solution for bundling Go binaries into standard Python wheel packages.\n\n资料来源：[README.md:1-10]()\n\nThe tool takes a Go module directory as input, cross-compiles the Go binary for multiple target platforms, and produces properly-tagged Python wheels that can be installed via standard Python package management tools. This approach allows Go developers to leverage the extensive Python packaging infrastructure for distribution, including PyPI hosting, pipx for isolated installations, and standard Python dependency resolution.\n\n资料来源：[spec.md:1-15]()\n\n## Core Functionality\n\n### What go-to-wheel Does\n\nAt its core, `go-to-wheel` performs three main operations to transform a Go module into a distributable Python wheel. First, it validates that the input directory is a valid Go module containing a `go.mod` file. Second, it cross-compiles the Go binary for each requested target platform using environment variables `GOOS` and `GOARCH` with `CGO_ENABLED=0` to produce static binaries. Third, it creates a Python package structure with a thin wrapper that executes the bundled binary, then packages everything into a wheel file following PEP 427 conventions.\n\n资料来源：[spec.md:80-95]()\n\nThe resulting wheel can be installed with pip, which extracts the bundled Go binary and creates console entry points that make the tool available on the system PATH. This means users can install and run Go-compiled tools exactly as they would any other Python package, without needing to understand that the underlying implementation is written in Go.\n\n资料来源：[README.md:55-65]()\n\n### How It Works\n\nThe build process follows a precise sequence of operations to ensure compatibility across all supported platforms. The tool begins by validating the input Go module directory and verifying that Go is installed and accessible. It then iterates through each requested platform, setting the appropriate environment variables and running the Go compiler with flags optimized for static binary production.\n\n```mermaid\ngraph TD\n A[Start: go-to-wheel] --> B{Validate Go Module}\n B -->|go.mod exists| C[Parse Package Metadata]\n B -->|No go.mod| E[Error: Not a Go module]\n C --> D{For each target platform}\n D --> F[Cross-compile with GOOS/GOARCH]\n F --> G[CGO_ENABLED=0 for static binary]\n G --> H[Generate Python wrapper]\n H --> I[Create wheel structure]\n I --> J[Zip into .whl file]\n J --> D\n D -->|All platforms done| K[Output wheels to ./dist]\n K --> L[Success]\n```\n\n资料来源：[spec.md:85-100]()\n\nThe cross-compilation step uses `CGO_ENABLED=0` to ensure that the resulting binaries are fully static and have no libc dependencies, which is essential for compatibility across different Linux distributions and container environments. The `-ldflags=\"-s -w\"` flags strip debug information and reduce binary size for more efficient distribution.\n\n资料来源：[README.md:45-50]()\n\n## Supported Platforms\n\n`go-to-wheel` supports a comprehensive range of target platforms across Linux, macOS, and Windows operating systems, covering both x86_64 and ARM architectures. The tool provides different wheel tags depending on whether the target uses glibc (standard Linux) or musl (Alpine Linux and similar distributions).\n\n### Platform Mapping\n\n| Target Platform | GOOS | GOARCH | Wheel Tag |\n|-----------------|------|--------|-----------|\n| linux-amd64 | linux | amd64 | manylinux_2_17_x86_64 |\n| linux-arm64 | linux | arm64 | manylinux_2_17_aarch64 |\n| linux-amd64-musl | linux | amd64 | musllinux_1_2_x86_64 |\n| linux-arm64-musl | linux | arm64 | musllinux_1_2_aarch64 |\n| darwin-amd64 | darwin | amd64 | macosx_10_9_x86_64 |\n| darwin-arm64 | darwin | arm64 | macosx_11_0_arm64 |\n| windows-amd64 | windows | amd64 | win_amd64 |\n| windows-arm64 | windows | arm64 | win_arm64 |\n\n资料来源：[README.md:35-45]()\n\n### Default Platform Behavior\n\nBy default, `go-to-wheel` builds wheels for all eight supported platforms, ensuring maximum compatibility for distribution. Users can optionally specify a subset of platforms using the `--platforms` flag with a comma-separated list of target platforms, which is useful when building for specific deployment environments or when cross-compilation toolchains are not available for all targets.\n\n资料来源：[spec.md:40-45]()\n\n## Installation and Requirements\n\n### Prerequisites\n\nThe tool itself requires Python 3.10 or later and has no external Python dependencies—it uses only the Python standard library. For building Go binaries, Go 1.16 or later is required due to the use of `go mod` commands.\n\n资料来源：[spec.md:115-120]()\n\n### Installation Methods\n\n`go-to-wheel` can be installed using standard Python package installation tools:\n\n```bash\npip install go-to-wheel\n# or\npipx install go-to-wheel\n```\n\n资料来源：[README.md:20-25]()\n\nAfter installation, Go must be available in the system PATH. The tool will automatically detect the Go binary or can be configured to use a specific path via the `--go-binary` option.\n\n## Command Line Interface\n\n### Basic Usage\n\nThe simplest usage of `go-to-wheel` requires only a path to the Go module directory:\n\n```bash\ngo-to-wheel path/to/go-module\n```\n\n资料来源：[README.md:30-35]()\n\nThis command creates wheels in the `./dist` directory for all supported platforms using default metadata values.\n\n### Command Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--name NAME` | Python package name | Directory basename |\n| `--version VERSION` | Package version | `0.1.0` |\n| `--output-dir DIR` | Directory for built wheels | `./dist` |\n| `--entry-point NAME` | CLI command name | Same as package name |\n| `--platforms PLATFORMS` | Comma-separated list of targets | All supported platforms |\n| `--go-binary PATH` | Path to Go binary | `go` |\n| `--description TEXT` | Package description | `\"Go binary packaged as Python wheel\"` |\n| `--license LICENSE` | License identifier | None |\n| `--author AUTHOR` | Author name | None |\n| `--author-email EMAIL` | Author email | None |\n| `--url URL` | Project URL | None |\n| `--requires-python VERSION` | Python version requirement | `>=3.10` |\n| `--readme PATH` | Path to README markdown file | None |\n| `--set-version-var VAR` | Go variable for version via `-X` ldflag | None |\n| `--ldflags FLAGS` | Additional Go linker flags | None |\n\n资料来源：[spec.md:25-45]()\n\n## Wheel Structure\n\nEach generated wheel follows PEP 427 format with a specific internal structure that enables proper execution of the bundled Go binary.\n\n### File Structure\n\n```\n{package_name}-{version}-py3-none-{platform_tag}.whl\n├── {package_name}/\n│ ├── __init__.py\n│ ├── __main__.py\n│ └── bin/\n│ └── {binary_name}[.exe]\n├── {package_name}-{version}.dist-info/\n│ ├── METADATA\n│ ├── WHEEL\n│ ├── RECORD\n│ └── entry_points.txt\n```\n\n资料来源：[spec.md:60-70]()\n\n### Python Wrapper Mechanism\n\nThe Python wrapper in `__init__.py` provides the execution mechanism for the bundled binary. It uses `os.execvp()` on Unix systems to replace the Python process with the Go binary, ensuring proper signal handling and exit code propagation. On Windows, it uses `subprocess.call()` to achieve similar behavior with proper signal handling.\n\n资料来源：[spec.md:60-90]()\n\n```python\ndef main():\n \"\"\"Execute the bundled binary.\"\"\"\n binary = get_binary_path()\n if sys.platform == \"win32\":\n # On Windows, use subprocess to properly handle signals\n sys.exit(subprocess.call([binary] + sys.argv[1:]))\n else:\n # On Unix, exec replaces the process\n os.execvp(binary, [binary] + sys.argv[1:])\n```\n\n资料来源：[spec.md:75-85]()\n\n### Why Python Wrapper vs .data/scripts\n\nThe specification uses a Python wrapper with `console_scripts` entry point rather than placing the binary directly in `.data/scripts/` for several important reasons. First, it provides consistent behavior across all platforms without platform-specific edge cases. Second, it enables better error messages if the binary is missing or incompatible with the system. Third, it offers future flexibility for adding Python-side features such as version checking or update notifications. Fourth, it works seamlessly with `pipx install` for isolated application installations.\n\n资料来源：[spec.md:90-100]()\n\n## Use Cases\n\n### Distributing Go Tools to Python Users\n\nThe primary use case for `go-to-wheel` is distributing Go CLI tools to Python developers who prefer to use `pip` or `pipx` for managing command-line tools. This is particularly valuable for tools that have natural appeal to the Python community or tools that need to be installed alongside Python packages as dependencies.\n\n资料来源：[README.md:8-12]()\n\n### PyPI Distribution\n\nGo binaries packaged as wheels can be uploaded to PyPI, making them available through the standard Python package index. This enables distribution to millions of Python developers who can install the tool with a single `pip install` command, without needing to understand Go compilation or maintain separate release artifacts.\n\n### pipx Isolation\n\nWheels built with `go-to-wheel` work seamlessly with `pipx`, which provides isolated Python environments for command-line tools. Users can install Go-compiled tools in isolation to avoid dependency conflicts:\n\n```bash\npipx install ./dist/mytool-1.0.0-py3-none-manylinux_2_17_x86_64.whl\n```\n\n资料来源：[README.md:60-65]()\n\n## Advanced Features\n\n### Version Embedding\n\nGo-to-wheel supports embedding the package version into the Go binary at compile time using Go linker flags. This requires a `var version` declaration in the Go source code. When the `--set-version-var` option is used, the tool automatically passes the value from `--version` to the Go linker via the `-X` flag.\n\n资料来源：[README.md:50-55]()\n\nA typical Go pattern for version embedding:\n\n```go\nvar version = \"dev\"\n\nfunc main() {\n if os.Args[1] == \"--version\" {\n fmt.Println(version) // prints \"2.0.0\" when built with --set-version-var\n }\n}\n```\n\n资料来源：[README.md:50-60]()\n\n### Custom Linker Flags\n\nAdditional Go linker flags can be passed using the `--ldflags` option, which are appended to the default `-s -w` flags. This allows for custom version strings, commit hashes, or other build-time information:\n\n```bash\ngo-to-wheel ./mytool --version 2.0.0 \\\n --ldflags \"-X main.version=2.0.0 -X main.commit=abc123\"\n```\n\n资料来源：[README.md:60-65]()\n\n### README Integration\n\nThe `--readme` option allows embedding a README markdown file into the wheel's METADATA, which is displayed on the PyPI package page:\n\n```bash\ngo-to-wheel ./mytool --readme README.md\n```\n\n资料来源：[spec.md:42]()\n\n## Development\n\n### Running Tests\n\nThe project uses pytest for testing. After cloning the repository, tests can be run with:\n\n```bash\ngit clone https://github.com/simonw/go-to-wheel\ncd go-to-wheel\nuv run pytest\n```\n\n资料来源：[README.md:70-75]()\n\n### Project Architecture\n\nThe tool is implemented as a single Python module (`go_to_wheel/__init__.py`) with no external dependencies. The main components include argument parsing, cross-compilation orchestration, wheel file generation, and metadata file creation. This simple architecture makes the tool easy to understand, maintain, and extend.\n\n## Related Tools\n\n`go-to-wheel` was inspired by similar tools in the Rust ecosystem. The primary inspiration is `maturin`, which provides the same functionality for Rust programs with Python bindings. Additionally, `pip-binary-factory` serves as a template for packaging pre-built binaries.\n\n资料来源：[README.md:75-80]()\n\n| Tool | Language | Repository |\n|------|----------|------------|\n| go-to-wheel | Go | simonw/go-to-wheel |\n| maturin | Rust | PyO3/maturin |\n| pip-binary-factory | Template | Bing-su/pip-binary-factory |\n\n## License\n\n`go-to-wheel` is released under the Apache 2.0 license, allowing for both personal and commercial use with minimal restrictions.\n\n资料来源：[README.md:12]()\n\n## Summary\n\n`go-to-wheel` provides a valuable bridge between the Go and Python ecosystems by enabling Go CLI programs to be packaged and distributed as standard Python wheels. With support for eight target platforms, flexible metadata configuration, and seamless integration with pip and pipx, it offers Go developers a straightforward path to reaching Python's extensive user base. The tool's single-file implementation with no external dependencies ensures reliability and ease of installation, making it a practical choice for distributing Go tools to the Python community.\n\n---\n\n\n\n## Installation\n\n### 相关页面\n\n相关主题：[Introduction](#page-introduction), [Development Guide](#page-development-guide)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n- [spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n- [go_to_wheel/__init__.py](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n \n\n# Installation\n\n`go-to-wheel` is a Python tool that compiles Go CLI programs into Python wheels. Installing this tool correctly is the first step to packaging Go binaries for PyPI distribution.\n\n## Prerequisites\n\nBefore installing `go-to-wheel`, ensure your environment meets the following requirements:\n\n| Requirement | Version | Description |\n|-------------|---------|-------------|\n| Python | >= 3.10 | The tool is implemented in Python and requires this version or higher |\n| Go | >= 1.16 | Required for building Go modules with `go mod` support |\n\n资料来源：[spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n### Python Dependencies\n\n`go-to-wheel` has **no external Python dependencies**. The tool uses only Python's standard library for all operations:\n\n- `argparse` - Command-line argument parsing\n- `zipfile` - Wheel creation\n- `subprocess` - Go compilation execution\n- `hashlib` / `base64` - RECORD file hash generation\n- `tempfile` / `shutil` - Temporary directory management\n\n资料来源：[go_to_wheel/__init__.py:1-20](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### Go Installation Verification\n\nTo verify Go is installed and accessible:\n\n```bash\ngo version\n```\n\nEnsure `go` is in your system's `PATH` environment variable.\n\n## Installation Methods\n\n### Via pip (Recommended for Users)\n\n```bash\npip install go-to-wheel\n```\n\n资料来源：[README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n\nThis method installs `go-to-wheel` globally in your Python environment.\n\n### Via pipx (Recommended for CLI Tools)\n\n```bash\npipx install go-to-wheel\n```\n\n资料来源：[README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n\n`pipx` is preferred for CLI applications because it:\n\n- Creates an isolated virtual environment for the tool\n- Automatically manages PATH shims for the installed command\n- Avoids dependency conflicts with other Python packages\n\n## Installation Workflow\n\n```mermaid\ngraph TD\n A[Choose Installation Method] --> B{pip or pipx?}\n B -->|pip| C[Run pip install go-to-wheel]\n B -->|pipx| D[Run pipx install go-to-wheel]\n C --> E[Download from PyPI]\n D --> E\n E --> F[Install to Python environment]\n F --> G[Create executable entry point]\n G --> H[go-to-wheel ready to use]\n```\n\n## Post-Installation Verification\n\nAfter installation, verify the tool is working:\n\n```bash\ngo-to-wheel --version\n```\n\nExpected output:\n```\ngo-to-wheel v0.1.0\n```\n\n资料来源：[go_to_wheel/__init__.py](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Usage Requirements\n\nOnce installed, you need a Go module to package:\n\n```bash\n# Verify you have a Go module\ncd path/to/your-go-module\nls go.mod\n```\n\nThe tool will:\n1. Cross-compile the Go binary for multiple platforms\n2. Create Python wheels with proper metadata\n3. Bundle everything into installable packages\n\n资料来源：[spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n## Quick Start After Installation\n\n```bash\n# Build wheels for all platforms\ngo-to-wheel path/to/go-module\n\n# Or with custom options\ngo-to-wheel ./mytool --name my-python-tool --version 1.0.0\n```\n\n资料来源：[README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n\n## Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| `go-to-wheel: command not found` | Ensure pip's Scripts directory is in PATH, or use `python -m go_to_wheel` |\n| Go not found | Install Go from [go.dev](https://go.dev) and ensure it's in PATH |\n| Python version error | Upgrade to Python 3.10 or higher |\n| Permission denied | Use `pip install --user` or `pipx install` instead of system-wide install |\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[CLI Options Reference](#page-cli-options), [Usage Examples](#page-examples)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n- [go_to_wheel/__init__.py](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n- [spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n \n\n# Quick Start Guide\n\n## Overview\n\nThe **Quick Start Guide** provides the fastest path for developers to begin using go-to-wheel to compile Go CLI programs into installable Python wheels. This tool addresses a gap in the Go/Python ecosystem—there is no equivalent to Rust's `maturin --bindings bin` for Go. Go-to-wheel takes a Go module directory, cross-compiles it for multiple platforms, and produces properly-tagged Python wheels installable via `pip` or `pipx`. 资料来源：[README.md:1-10]()\n\n## Prerequisites\n\nBefore using go-to-wheel, ensure your environment meets the following requirements:\n\n| Requirement | Version | Notes |\n|-------------|---------|-------|\n| Python | >= 3.10 | Required for installation and running the tool |\n| Go | >= 1.16 | Required for building Go modules 资料来源：[spec.md:145-150]() |\n| Go Module | Valid `go.mod` | The source Go project must be a Go module |\n\nGo must be installed and available in your system PATH. No external Python dependencies are required—go-to-wheel uses only the Python standard library. 资料来源：[go_to_wheel/__init__.py:1-15]()\n\n## Installation\n\nInstall go-to-wheel using pip or pipx:\n\n```bash\npip install go-to-wheel\n# or\npipx install go-to-wheel\n```\n\nVerify the installation:\n\n```bash\ngo-to-wheel --version\n```\n\n## Basic Usage\n\n### Minimal Command\n\nBuild wheels for all supported platforms using the simplest invocation:\n\n```bash\ngo-to-wheel path/to/go-module\n```\n\nThis command will:\n\n1. Cross-compile the Go binary for all default platforms\n2. Create a Python package with a thin wrapper\n3. Package everything into wheels in `./dist` directory\n4. Use the directory name as the package name with version `0.1.0` 资料来源：[README.md:35-50]()\n\n### Build Flow\n\n```mermaid\ngraph TD\n A[Go Module Directory] --> B[Validate go.mod exists]\n B --> C[Cross-compile Go binary for each platform]\n C --> D[Create Python package structure]\n D --> E[Generate wheel metadata]\n E --> F[Package into .whl file]\n F --> G[Move to output directory]\n```\n\n## Command Options\n\nThe following table documents all available command-line options:\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--name NAME` | Python package name | Directory basename |\n| `--version VERSION` | Package version | `0.1.0` |\n| `--output-dir DIR` | Directory for built wheels | `./dist` |\n| `--entry-point NAME` | CLI command name | Same as package name |\n| `--platforms PLATFORMS` | Comma-separated list of targets | All supported platforms |\n| `--go-binary PATH` | Path to Go binary | `go` |\n| `--description TEXT` | Package description | `\"Go binary packaged as Python wheel\"` |\n| `--license LICENSE` | License identifier (e.g., MIT) | None |\n| `--author AUTHOR` | Author name | None |\n| `--author-email EMAIL` | Author email | None |\n| `--url URL` | Project URL | None |\n| `--requires-python VERSION` | Python version requirement | `>=3.10` |\n| `--readme PATH` | Path to README markdown file for PyPI | None |\n| `--set-version-var VAR` | Go variable to set via `-X` ldflag | None |\n| `--ldflags FLAGS` | Additional Go linker flags | None | 资料来源：[README.md:20-35]()\n\n## Supported Platforms\n\nGo-to-wheel supports cross-compilation to the following target platforms:\n\n| Platform Identifier | GOOS | GOARCH | Wheel Tag |\n|---------------------|------|--------|-----------|\n| `linux-amd64` | linux | amd64 | `manylinux_2_17_x86_64` |\n| `linux-arm64` | linux | arm64 | `manylinux_2_17_aarch64` |\n| `linux-amd64-musl` | linux | amd64 | `musllinux_1_2_x86_64` |\n| `linux-arm64-musl` | linux | arm64 | `musllinux_1_2_aarch64` |\n| `darwin-amd64` | darwin | amd64 | `macosx_10_9_x86_64` |\n| `darwin-arm64` | darwin | arm64 | `macosx_11_0_arm64` |\n| `windows-amd64` | windows | amd64 | `win_amd64` |\n| `windows-arm64` | windows | arm64 | `win_arm64` | 资料来源：[go_to_wheel/__init__.py:20-30]()\n\n## Common Use Cases\n\n### Custom Package Name\n\nBuild wheels with a custom Python package name:\n\n```bash\ngo-to-wheel ./mytool --name my-python-tool\n```\n\n### Build for Specific Platforms Only\n\nReduce build time by targeting only required platforms:\n\n```bash\ngo-to-wheel ./mytool --platforms linux-amd64,darwin-arm64\n```\n\n### Embed Version into Go Binary\n\nPass the version to the Go binary at compile time using linker flags. First, add a version variable to your Go source:\n\n```go\nvar version = \"dev\"\n\nfunc main() {\n if os.Args[1] == \"--version\" {\n fmt.Println(version)\n }\n}\n```\n\nThen build with:\n\n```bash\ngo-to-wheel ./mytool --version 2.0.0 --set-version-var main.version\n```\n\nThis passes `-X main.version=2.0.0` to the Go linker. The flags are appended to the default `-s -w`, resulting in `-ldflags=\"-s -w -X main.version=2.0.0\"`. 资料来源：[README.md:55-75]()\n\n### Full Metadata for PyPI\n\nPublish to PyPI with complete metadata:\n\n```bash\ngo-to-wheel ./mytool \\\n --name mytool-bin \\\n --version 2.0.0 \\\n --description \"My awesome tool\" \\\n --license MIT \\\n --author \"Jane Doe\" \\\n --author-email \"jane@example.com\" \\\n --url \"https://github.com/jane/mytool\" \\\n --readme README.md\n```\n\n### Custom Linker Flags\n\nPass arbitrary Go linker flags for additional build-time configuration:\n\n```bash\ngo-to-wheel ./mytool --version 2.0.0 \\\n --ldflags \"-X main.version=2.0.0 -X main.commit=abc123\"\n```\n\n## How It Works\n\nThe build process consists of four main steps:\n\n```mermaid\ngraph LR\n A[Cross-compile Go Binary] --> B[Create Python Package]\n B --> C[Generate Metadata Files]\n C --> D[Package into Wheel]\n```\n\n### Step 1: Cross-Compilation\n\nFor each target platform, go-to-wheel executes:\n\n```bash\nGOOS={goos} GOARCH={goarch} CGO_ENABLED=0 go build \\\n -ldflags=\"-s -w\" \\\n -o {output_path} \\\n {go_module_path}\n```\n\nKey points:\n- `CGO_ENABLED=0` ensures static binaries with no libc dependency issues\n- `-ldflags=\"-s -w\"` strips debug information to reduce binary size\n- Windows builds automatically receive `.exe` extension 资料来源：[spec.md:100-115]()\n\n### Step 2: Python Package Structure\n\nEach wheel contains a Python wrapper that executes the bundled binary:\n\n```\n{package_name}-{version}-py3-none-{platform_tag}.whl\n├── {package_name}/\n│ ├── __init__.py\n│ ├── __main__.py\n│ └── bin/\n│ └── {binary_name}[.exe]\n├── {package_name}-{version}.dist-info/\n│ ├── METADATA\n│ ├── WHEEL\n│ ├── RECORD\n│ └── entry_points.txt\n```\n\nThe `__init__.py` file contains a `main()` function that:\n- On Windows: uses `subprocess.call()` for proper signal handling\n- On Unix: uses `os.execvp()` to replace the Python process 资料来源：[spec.md:60-95]()\n\n### Step 3: Metadata Generation\n\nGenerated METADATA follows PEP 566:\n\n```\nMetadata-Version: 2.1\nName: {package_name}\nVersion: {version}\nSummary: {description}\nLicense: {license}\nAuthor: {author}\nAuthor-email: {author_email}\nHome-page: {url}\nRequires-Python: {requires_python}\n```\n\nThe WHEEL file follows PEP 427:\n\n```\nWheel-Version: 1.0\nGenerator: go-to-wheel {version}\nRoot-Is-Purelib: false\nTag: py3-none-{platform_tag}\n```\n\n### Step 4: Entry Points\n\nConsole script entry points are defined in `entry_points.txt`:\n\n```\n[console_scripts]\n{entry_point} = {package_name}:main\n```\n\nThe tool uses Python wrapper entry points rather than `.data/scripts/` because:\n- Consistent behavior across all platforms\n- Better error messages if binary is missing\n- Future flexibility for Python-side features\n- Seamless pipx compatibility 资料来源：[spec.md:95-105]()\n\n## Testing Built Wheels\n\n### Install with pip\n\n```bash\npip install ./dist/mytool-1.0.0-py3-none-manylinux_2_17_x86_64.whl\n```\n\n### Test with uv\n\n```bash\nuv run --with ./dist/mytool-1.0.0-py3-none-manylinux_2_17_x86_64.whl mytool --help\n```\n\n### Run with pipx\n\n```bash\npipx install ./dist/mytool-1.0.0-py3-none-manylinux_2_17_x86_64.whl\n```\n\nAfter installation, the Go binary is available on your PATH through the Python wrapper. 资料来源：[README.md:100-115]()\n\n## Development\n\nTo contribute or customize go-to-wheel:\n\n```bash\n# Clone the repository\ngit clone https://github.com/simonw/go-to-wheel\ncd go-to-wheel\n\n# Run tests\nuv run pytest\n```\n\n## Package Name Validation\n\nPackage names must follow PEP 503 naming rules:\n\n| Rule | Description |\n|------|-------------|\n| Allowed characters | Lowercase letters, digits, hyphens, underscores, periods |\n| Must start with | Letter or digit |\n| Normalization | Hyphens and underscores become hyphens in wheel filename |\n\nThe import name (Python package directory) follows PEP 8:\n- Hyphens are replaced with underscores\n- Example: `my-tool` becomes `my_tool/` directory 资料来源：[spec.md:130-140]()\n\n## Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| \"No go.mod file found\" | Ensure the path points to a valid Go module directory |\n| \"Go compilation failed\" | Verify Go is installed and the module builds correctly standalone |\n| Invalid package name | Follow PEP 503 naming rules (lowercase, alphanumeric with hyphens/underscores) |\n\n## See Also\n\n- [maturin](https://github.com/PyO3/maturin) - The Rust equivalent that inspired this tool\n- [pip-binary-factory](https://github.com/Bing-su/pip-binary-factory) - Template for packaging pre-built binaries\n- [Distributing Go binaries like sqlite-scanner through PyPI using go-to-wheel](https://simonwillison.net/2026/Feb/4/distributing-go-binaries/) - Background article on this project 资料来源：[README.md:120-130]()\n\n---\n\n\n\n## CLI Options Reference\n\n### 相关页面\n\n相关主题：[Quick Start Guide](#page-quick-start), [Configuration and Metadata](#page-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [go_to_wheel/__init__.py](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n- [README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n- [spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n \n\n# CLI Options Reference\n\n## Overview\n\nThe `go-to-wheel` CLI provides comprehensive options for cross-compiling Go binaries into Python wheels. The command follows the structure:\n\n```bash\ngo-to-wheel path/to/go-folder [options]\n```\n\nAll options are passed as space-separated arguments after the path to the Go module directory. 资料来源：[README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n\n## Complete Options Reference\n\n### Core Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `path/to/go-folder` | positional | required | Path to Go module directory containing go.mod |\n| `--name NAME` | string | Directory basename | Python package name for the wheel |\n| `--version VERSION` | string | `0.1.0` | Package version string |\n| `--output-dir DIR` | string | `./dist` | Directory where built wheels are written |\n| `--entry-point NAME` | string | Same as package name | CLI command name exposed after installation |\n| `--go-binary PATH` | string | `go` | Path to Go binary in PATH |\n\n资料来源：[go_to_wheel/__init__.py:52-85](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### Metadata Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--description TEXT` | string | `\"Go binary packaged as Python wheel\"` | Package summary for PyPI |\n| `--license LICENSE` | string | None | SPDX license identifier (e.g., MIT, Apache-2.0) |\n| `--author AUTHOR` | string | None | Author name |\n| `--author-email EMAIL` | string | None | Author email address |\n| `--url URL` | string | None | Project homepage URL |\n| `--requires-python VERSION` | string | `>=3.10` | Python version requirement |\n| `--readme PATH` | string | None | Path to README.md for PyPI long description |\n\n资料来源：[go_to_wheel/__init__.py:86-115](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### Build Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--platforms PLATFORMS` | string | All 8 platforms | Comma-separated list of target platforms |\n| `--ldflags FLAGS` | string | None | Additional Go linker flags appended to `-s -w` |\n| `--set-version-var VAR` | string | None | Go variable name for version embedding via `-X` |\n\n资料来源：[go_to_wheel/__init__.py:116-128](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Supported Platforms\n\nThe following platform targets are available for cross-compilation:\n\n| Platform Identifier | GOOS | GOARCH | Wheel Tag |\n|-------------------|------|--------|-----------|\n| `linux-amd64` | linux | amd64 | manylinux_2_17_x86_64 |\n| `linux-arm64` | linux | arm64 | manylinux_2_17_aarch64 |\n| `linux-amd64-musl` | linux | amd64 | musllinux_1_2_x86_64 |\n| `linux-arm64-musl` | linux | arm64 | musllinux_1_2_aarch64 |\n| `darwin-amd64` | darwin | amd64 | macosx_10_9_x86_64 |\n| `darwin-arm64` | darwin | arm64 | macosx_11_0_arm64 |\n| `windows-amd64` | windows | amd64 | win_amd64 |\n| `windows-arm64` | windows | arm64 | win_arm64 |\n\n资料来源：[go_to_wheel/__init__.py:25-35](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### Platform Selection Syntax\n\nSpecify multiple platforms using comma-separated values:\n\n```bash\ngo-to-wheel ./mytool --platforms linux-amd64,darwin-arm64,windows-amd64\n```\n\n## Version Embedding\n\nThe `--set-version-var` option enables embedding the package version into the Go binary at compile time. This requires a matching variable in the Go source:\n\n```go\nvar version = \"dev\"\n\nfunc main() {\n if len(os.Args) > 1 && os.Args[1] == \"--version\" {\n fmt.Println(version)\n }\n}\n```\n\nBuild command with version embedding:\n\n```bash\ngo-to-wheel ./mytool --version 2.0.0 --set-version-var main.version\n```\n\nThis passes `-X main.version=2.0.0` to the Go linker. 资料来源：[README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n\n## Advanced Ldflags\n\nThe `--ldflags` option appends custom linker flags to the default `-s -w` flags (which strip debug info):\n\n```bash\ngo-to-wheel ./mytool --ldflags \"-X main.commit=abc123 -X main.date=2024-01-15\"\n```\n\nThe combined ldflags become: `-s -w -X main.commit=abc123 -X main.date=2024-01-15`\n\n## Usage Examples\n\n### Minimal Build\n\n```bash\ngo-to-wheel ./mytool\n```\n\nProduces wheels for all 8 platforms using default settings. 资料来源：[README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n\n### Custom Package Name\n\n```bash\ngo-to-wheel ./mytool --name my-python-tool\n```\n\nCreates `my-python-tool-0.1.0-py3-none-*.whl` files.\n\n### PyPI-Ready Build\n\n```bash\ngo-to-wheel ./mytool \\\n --name mytool-bin \\\n --version 2.0.0 \\\n --description \"My awesome CLI tool\" \\\n --license MIT \\\n --author \"Jane Doe\" \\\n --author-email \"jane@example.com\" \\\n --url \"https://github.com/jane/mytool\" \\\n --readme README.md\n```\n\n### Platform-Specific Build\n\n```bash\ngo-to-wheel ./mytool --platforms linux-amd64,darwin-arm64\n```\n\n### With Version Embedding\n\n```bash\ngo-to-wheel ./mytool --version 1.2.3 --set-version-var main.version\n```\n\n## Option Processing Flow\n\n```mermaid\ngraph TD\n A[Parse CLI Arguments] --> B[Validate go_dir exists]\n B --> C{Check go.mod}\n C -->|Valid| D[Set defaults]\n C -->|Invalid| E[Exit with error]\n D --> F[Parse platforms list]\n F --> G[Build ldflags]\n G --> H[Cross-compile for each platform]\n H --> I[Generate Python wheel]\n I --> J[Move to output-dir]\n J --> K[Print summary]\n```\n\n## Default Values Behavior\n\n| Option | Default Source | Override Mechanism |\n|--------|---------------|-------------------|\n| Package name | `go_path.name` (directory basename) | `--name` |\n| Version | `\"0.1.0\"` | `--version` |\n| Entry point | Same as package name | `--entry-point` |\n| Platforms | `DEFAULT_PLATFORMS` list (all 8) | `--platforms` |\n| Go binary | `\"go\"` from PATH | `--go-binary` |\n| Description | `\"Go binary packaged as Python wheel\"` | `--description` |\n| Requires Python | `\">=3.10\"` | `--requires-python` |\n\n资料来源：[go_to_wheel/__init__.py:175-190](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Error Handling\n\nThe CLI validates inputs and exits with descriptive errors:\n\n| Error Condition | Exit Behavior |\n|-----------------|---------------|\n| Go directory not found | `FileNotFoundError: Go directory not found: ` |\n| No go.mod file | `ValueError: Not a Go module: ` |\n| Go binary not found | `FileNotFoundError` from subprocess |\n| Compilation failure | `RuntimeError: Go compilation failed for /` |\n| No wheels built | `Error: No wheels were built` |\n\n## Return Codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | Success - wheels built and written to output directory |\n| 1 | Error occurred (invalid input, compilation failure, etc.) |\n\n资料来源：[go_to_wheel/__init__.py:130-155](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n---\n\n\n\n## Usage Examples\n\n### 相关页面\n\n相关主题：[Quick Start Guide](#page-quick-start), [Wheel Generation Process](#page-wheel-generation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n- [go_to_wheel/__init__.py](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n- [spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n \n\n# Usage Examples\n\nThis page provides comprehensive usage examples for `go-to-wheel`, demonstrating how to compile Go CLI programs into distributable Python wheels. The examples progress from basic usage to advanced configurations, covering all available command-line options and common use cases.\n\n## Overview\n\n`go-to-wheel` transforms Go binaries into Python packages that can be installed via `pip` or `pipx`. The tool handles cross-compilation for multiple platforms, generates proper Python wheel metadata, and creates installable packages with executable entry points. All examples assume Go is installed and available in the system PATH.\n\n## Basic Usage\n\nThe simplest way to build wheels from a Go module is to pass the module directory path:\n\n```bash\ngo-to-wheel ./mytool\n```\n\nThis command:\n\n1. Locates the Go module in `./mytool` (requires `go.mod` file)\n2. Cross-compiles the binary for all supported platforms\n3. Creates wheels in `./dist` directory\n4. Uses the directory name as the package name\n5. Defaults to version `0.1.0`\n\nThe resulting wheels follow the naming convention `{name}-{version}-py3-none-{platform_tag}.whl`.\n\n## Command Line Options\n\n### Option Reference Table\n\n| Option | Description | Default Value |\n|--------|-------------|---------------|\n| `--name NAME` | Python package name | Directory basename |\n| `--version VERSION` | Package version | `0.1.0` |\n| `--output-dir DIR` | Directory for built wheels | `./dist` |\n| `--entry-point NAME` | CLI command name | Same as package name |\n| `--platforms PLATFORMS` | Comma-separated list of targets | All supported platforms |\n| `--go-binary PATH` | Path to Go binary | `go` |\n| `--description TEXT` | Package description | `\"Go binary packaged as Python wheel\"` |\n| `--license LICENSE` | License identifier | None |\n| `--author AUTHOR` | Author name | None |\n| `--author-email EMAIL` | Author email | None |\n| `--url URL` | Project URL | None |\n| `--requires-python VERSION` | Python version requirement | `>=3.10` |\n| `--readme PATH` | Path to README markdown file | None |\n| `--set-version-var VAR` | Go variable for `--version` value | None |\n| `--ldflags FLAGS` | Additional Go linker flags | None |\n\n资料来源：[go_to_wheel/__init__.py:1-100]()\n\n## Platform Selection\n\n### Build for All Platforms\n\nBy default, `go-to-wheel` builds wheels for all supported platforms:\n\n| Platform | Wheel Tag |\n|----------|-----------|\n| `linux-amd64` | `manylinux_2_17_x86_64` |\n| `linux-arm64` | `manylinux_2_17_aarch64` |\n| `linux-amd64-musl` | `musllinux_1_2_x86_64` |\n| `linux-arm64-musl` | `musllinux_1_2_aarch64` |\n| `darwin-amd64` | `macosx_10_9_x86_64` |\n| `darwin-arm64` | `macosx_11_0_arm64` |\n| `windows-amd64` | `win_amd64` |\n| `windows-arm64` | `win_arm64` |\n\n资料来源：[README.md:1-50]()\n\n### Build for Specific Platforms\n\nTo build only for specific platforms, use the `--platforms` option with a comma-separated list:\n\n```bash\ngo-to-wheel ./mytool --platforms linux-amd64,darwin-arm64\n```\n\nThis produces wheels for only Linux amd64 and macOS ARM64, reducing build time when you don't need all platform variants.\n\n### Using a Custom Go Binary\n\nIf Go is not in your PATH or you need a specific version:\n\n```bash\ngo-to-wheel ./mytool --go-binary /usr/local/go/bin/go\n```\n\n## Package Naming\n\n### Custom Package Name\n\nOverride the default package name derived from the directory:\n\n```bash\ngo-to-wheel ./mytool --name my-python-tool\n```\n\nThis creates wheels named `my-python-tool-{version}-py3-none-{platform_tag}.whl`.\n\n### Custom Entry Point\n\nThe CLI command name can differ from the package name:\n\n```bash\ngo-to-wheel ./mytool --name my-tool-bin --entry-point mytool\n```\n\nThis creates a package named `my-tool-bin` but installs the command as `mytool`.\n\n## Version Management\n\n### Setting Package Version\n\n```bash\ngo-to-wheel ./mytool --version 2.0.0\n```\n\n### Embedding Version in Go Binary\n\nTo embed the version into the Go binary at compile time, define a version variable in your Go source:\n\n```go\nvar version = \"dev\"\n\nfunc main() {\n if os.Args[1] == \"--version\" {\n fmt.Println(version)\n }\n}\n```\n\nThen use `--set-version-var` to pass the version via linker flags:\n\n```bash\ngo-to-wheel ./mytool --version 2.0.0 --set-version-var main.version\n```\n\nThis passes `-X main.version=2.0.0` to the Go linker. The combined linker flags become `-s -w -X main.version=2.0.0`.\n\n资料来源：[README.md:50-80]()\n\n## Custom Linker Flags\n\n### Using ldflags\n\nPass arbitrary Go linker flags with `--ldflags`:\n\n```bash\ngo-to-wheel ./mytool --version 2.0.0 \\\n --ldflags \"-X main.version=2.0.0 -X main.commit=abc123\"\n```\n\nFlags are appended to the default `-s -w`, so the full linker invocation becomes:\n\n```\n-ldflags=\"-s -w -X main.version=2.0.0 -X main.commit=abc123\"\n```\n\nThe `-s` flag strips symbol table, and `-w` removes DWARF debugging information, reducing binary size.\n\n资料来源：[spec.md:50-80]()\n\n## Output Management\n\n### Custom Output Directory\n\n```bash\ngo-to-wheel ./mytool --output-dir ./wheels\n```\n\n### Installing Built Wheels\n\nAfter building, install wheels with pip:\n\n```bash\npip install ./dist/mytool-1.0.0-py3-none-manylinux_2_17_x86_64.whl\n```\n\nOr test directly with uv:\n\n```bash\nuv run --with ./dist/mytool-1.0.0-py3-none-manylinux_2_17_x86_64.whl mytool --help\n```\n\n## Complete Examples\n\n### Basic Distribution\n\nFor internal distribution without PyPI publishing:\n\n```bash\ngo-to-wheel ./mytool\n```\n\n### PyPI-Ready Distribution\n\nFull metadata configuration for PyPI publishing:\n\n```bash\ngo-to-wheel ./mytool \\\n --name mytool-bin \\\n --version 2.0.0 \\\n --description \"My awesome tool\" \\\n --license MIT \\\n --author \"Jane Doe\" \\\n --author-email \"jane@example.com\" \\\n --url \"https://github.com/jane/mytool\" \\\n --readme README.md\n```\n\nThis generates wheels with complete metadata suitable for publishing to PyPI. The `--readme` option sets the long description from your README file.\n\n资料来源：[README.md:80-120]()\n\n### Development Workflow\n\nTypical development workflow:\n\n```bash\n# Build all wheels\ngo-to-wheel ./mytool --output-dir ./dist\n\n# Test specific wheel\nuv run --with ./dist/mytool-0.1.0-py3-none-manylinux_2_17_x86_64.whl mytool --help\n\n# Install locally for testing\npip install ./dist/mytool-0.1.0-py3-none-manylinux_2_17_x86_64.whl\n\n# Uninstall after testing\npip uninstall mytool\n```\n\n## Build Process Flow\n\n```mermaid\ngraph TD\n A[go-to-wheel command] --> B[Validate Go directory]\n B --> C[Check go.mod exists]\n C --> D{For each platform}\n D --> E[Cross-compile with GOOS/GOARCH]\n E --> F[Create Python package structure]\n F --> G[Generate __init__.py and __main__.py]\n G --> H[Generate METADATA and WHEEL files]\n H --> I[Calculate RECORD with SHA256]\n I --> J[Zip into wheel file]\n J --> K{More platforms?}\n K -->|Yes| D\n K -->|No| L[Move wheels to output dir]\n L --> M[Print summary]\n```\n\nThe build process uses `CGO_ENABLED=0` for static binaries, ensuring compatibility across different Linux distributions without libc dependencies.\n\n资料来源：[spec.md:30-60]()\n\n## Error Handling\n\nCommon errors and solutions:\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| `Go directory not found` | Invalid path | Verify the directory exists |\n| `Not a Go module` | Missing `go.mod` | Ensure directory contains `go.mod` |\n| `Go compilation failed` | Build error in Go code | Check Go source for errors |\n| `No wheels were built` | Platform validation failed | Verify platform names are correct |\n\n资料来源：[go_to_wheel/__init__.py:150-200]()\n\n## Quick Reference\n\n| Task | Command |\n|------|---------|\n| Build all wheels | `go-to-wheel ./mytool` |\n| Custom name | `go-to-wheel ./mytool --name my-package` |\n| Specific version | `go-to-wheel ./mytool --version 1.2.3` |\n| Specific platforms | `go-to-wheel ./mytool --platforms linux-amd64,darwin-arm64` |\n| With metadata | `go-to-wheel ./mytool --author \"Name\" --license MIT --readme README.md` |\n| Embed version | `go-to-wheel ./mytool --version 1.0 --set-version-var main.version` |\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Wheel Generation Process](#page-wheel-generation), [Supported Platforms](#page-platforms)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [go_to_wheel/__init__.py](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n- [spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n- [README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n \n\n# System Architecture\n\n## Overview\n\ngo-to-wheel is a Python CLI tool that bridges the Go and Python packaging ecosystems. It takes a Go module directory, cross-compiles it for multiple target platforms, and packages each binary as a PEP 427-compliant Python wheel with executable entry points. This enables Go binaries to be distributed and installed via `pip` or `pipx`.\n\n资料来源：[spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n## Architecture Components\n\nThe system consists of four primary components working in sequence:\n\n```mermaid\ngraph TD\n A[Go Module Input] --> B[Input Validation]\n B --> C[Cross-Compilation Engine]\n C --> D[Wheel Builder]\n D --> E[Output Wheels]\n \n B --> B1[Verify go.mod exists]\n B --> B2[Validate package name]\n C --> C1[GOOS/GOARCH env vars]\n C --> C2[CGO_ENABLED=0]\n D --> D1[Generate METADATA]\n D --> D2[Generate WHEEL]\n D --> D3[Generate RECORD]\n D --> D4[Create zip archive]\n```\n\n### Component Responsibilities\n\n| Component | Purpose | Key Functions |\n|-----------|---------|---------------|\n| **CLI Parser** | Parse command-line arguments | `argparse`, argument validation |\n| **Input Validator** | Verify Go module structure | Path existence, `go.mod` detection |\n| **Cross-Compiler** | Build binaries for target platforms | `subprocess.run()`, env var management |\n| **Wheel Builder** | Create PEP 427 compliant wheels | `zipfile`, metadata generation |\n\n资料来源：[go_to_wheel/__init__.py:1-50](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Platform Mapping System\n\nThe platform mapping system translates human-readable platform names into Go build environment variables and Python wheel tags.\n\n```mermaid\ngraph LR\n P1[\"linux-amd64\"] --> PM1[\"PLATFORM_MAPPINGS\"]\n P2[\"darwin-arm64\"] --> PM1\n P3[\"windows-amd64\"] --> PM1\n \n PM1 --> G[\"GOOS/GOARCH\"]\n PM1 --> W[\"Wheel Tag\"]\n \n G --> G1[\"linux/amd64\"]\n W --> W1[\"manylinux_2_17_x86_64\"]\n```\n\n### Platform Mapping Table\n\n| Platform Name | GOOS | GOARCH | Wheel Tag |\n|---------------|------|--------|-----------|\n| `linux-amd64` | `linux` | `amd64` | `manylinux_2_17_x86_64` |\n| `linux-arm64` | `linux` | `arm64` | `manylinux_2_17_aarch64` |\n| `linux-amd64-musl` | `linux` | `amd64` | `musllinux_1_2_x86_64` |\n| `linux-arm64-musl` | `linux` | `arm64` | `musllinux_1_2_aarch64` |\n| `darwin-amd64` | `darwin` | `amd64` | `macosx_10_9_x86_64` |\n| `darwin-arm64` | `darwin` | `arm64` | `macosx_11_0_arm64` |\n| `windows-amd64` | `windows` | `amd64` | `win_amd64` |\n| `windows-arm64` | `windows` | `arm64` | `win_arm64` |\n\n资料来源：[go_to_wheel/__init__.py:23-32](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Build Process Workflow\n\n```mermaid\nflowchart TD\n START[Start build_wheels] --> V1{Go directory exists?}\n V1 -->|No| ERROR1[FileNotFoundError]\n V1 -->|Yes| V2{go.mod exists?}\n V2 -->|No| ERROR2[ValueError]\n V2 -->|Yes| PARSE[Parse arguments]\n \n PARSE --> SETUP[Set defaults
name, entry_point,
platforms]\n \n SETUP --> FOR_LOOP[For each platform]\n FOR_LOOP --> CROSS[cross_compile_go]\n \n CROSS --> BUILD[Build wheel structure]\n BUILD --> GEN_INIT[Generate __init__.py]\n BUILD --> GEN_MAIN[Generate __main__.py]\n BUILD --> GEN_META[Generate METADATA]\n BUILD --> GEN_WHEEL[Generate WHEEL]\n BUILD --> GEN_RECORD[Generate RECORD]\n BUILD --> GEN_ENTRY[Generate entry_points.txt]\n \n GEN_INIT --> ZIP[Create wheel.zip]\n GEN_MAIN --> ZIP\n GEN_META --> ZIP\n GEN_WHEEL --> ZIP\n GEN_RECORD --> ZIP\n GEN_ENTRY --> ZIP\n \n ZIP --> NEXT{More platforms?}\n NEXT -->|Yes| FOR_LOOP\n NEXT -->|No| OUTPUT[Move wheels to output_dir]\n OUTPUT --> DONE[Return wheel paths]\n```\n\n### Cross-Compilation Details\n\nThe cross-compilation step uses Go's built-in cross-compilation support:\n\n```bash\nGOOS={goos} GOARCH={goarch} CGO_ENABLED=0 go build \\\n -ldflags=\"-s -w\" \\\n -o {output_path} \\\n {go_module_path}\n```\n\nKey compilation flags:\n- `CGO_ENABLED=0`: Disables C bindings for static binaries\n- `-ldflags=\"-s -w\"`: Strips debug info and symbol tables\n- `.exe` extension added automatically on Windows\n\n资料来源：[spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n## Wheel Structure\n\nEach generated wheel follows the PEP 427 standard structure:\n\n```\n{package_name}-{version}-py3-none-{platform_tag}.whl\n├── {package_name}/\n│ ├── __init__.py\n│ ├── __main__.py\n│ └── bin/\n│ └── {binary_name}[.exe]\n├── {package_name}-{version}.dist-info/\n│ ├── METADATA\n│ ├── WHEEL\n│ ├── RECORD\n│ └── entry_points.txt\n```\n\n资料来源：[spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n### Generated File Contents\n\n#### `__init__.py`\n\nThe wrapper module that locates and executes the bundled binary:\n\n```python\n\"\"\"Go binary packaged as Python wheel.\"\"\"\n\nimport os\nimport stat\nimport subprocess\nimport sys\n\n__version__ = \"{version}\"\n\ndef get_binary_path():\n \"\"\"Return the path to the bundled binary.\"\"\"\n binary = os.path.join(os.path.dirname(__file__), \"bin\", \"{binary_name}\")\n\n # Ensure binary is executable on Unix\n if sys.platform != \"win32\":\n current_mode = os.stat(binary).st_mode\n if not (current_mode & stat.S_IXUSR):\n os.chmod(binary, current_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)\n return binary\n\ndef main():\n \"\"\"Execute the bundled binary.\"\"\"\n binary = get_binary_path()\n if sys.platform == \"win32\":\n sys.exit(subprocess.call([binary] + sys.argv[1:]))\n else:\n os.execvp(binary, [binary] + sys.argv[1:])\n```\n\n资料来源：[go_to_wheel/__init__.py:75-100](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n#### METADATA (PEP 566)\n\n```\nMetadata-Version: 2.1\nName: {package_name}\nVersion: {version}\nSummary: {description}\nLicense: {license}\nAuthor: {author}\nAuthor-email: {author_email}\nHome-page: {url}\nRequires-Python: {requires_python}\n```\n\n#### WHEEL (PEP 427)\n\n```\nWheel-Version: 1.0\nGenerator: go-to-wheel {go_to_wheel_version}\nRoot-Is-Purelib: false\nTag: py3-none-{platform_tag}\n```\n\n#### RECORD\n\nCSV format with columns: `path,hash,size`\n\n#### entry_points.txt\n\n```\n[console_scripts]\n{entry_point} = {package_name}:main\n```\n\n资料来源：[spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n## Command-Line Interface\n\n### Options Table\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--name NAME` | Python package name | Directory basename |\n| `--version VERSION` | Package version | `0.1.0` |\n| `--output-dir DIR` | Directory for built wheels | `./dist` |\n| `--entry-point NAME` | CLI command name | Same as package name |\n| `--platforms PLATFORMS` | Comma-separated list of targets | All 8 platforms |\n| `--go-binary PATH` | Path to Go binary | `go` |\n| `--description TEXT` | Package description | `\"Go binary packaged as Python wheel\"` |\n| `--license LICENSE` | License identifier | None |\n| `--author AUTHOR` | Author name | None |\n| `--author-email EMAIL` | Author email | None |\n| `--url URL` | Project URL | None |\n| `--requires-python VERSION` | Python version requirement | `>=3.10` |\n| `--readme PATH` | Path to README markdown file | None |\n| `--set-version-var VAR` | Go variable for version via `-X` | None |\n| `--ldflags FLAGS` | Additional Go linker flags | None |\n\n资料来源：[go_to_wheel/__init__.py:50-130](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Data Flow Diagram\n\n```mermaid\nflowchart LR\n subgraph Input\n A[Go Module Directory]\n B[CLI Arguments]\n end\n \n subgraph Processing\n C[Input Validation]\n D[Cross-Compilation]\n E[Metadata Generation]\n F[Zip Packaging]\n end\n \n subgraph Output\n G[Python Wheel Files]\n H[dist/ Directory]\n end\n \n A --> C\n B --> C\n C --> D\n D --> E\n E --> F\n F --> G\n G --> H\n```\n\n## Key Function Signatures\n\n### `build_wheels()`\n\n```python\ndef build_wheels(\n go_dir: str,\n *,\n name: str | None = None,\n version: str = \"0.1.0\",\n output_dir: str = \"./dist\",\n entry_point: str | None = None,\n platforms: list[str] | None = None,\n go_binary: str = \"go\",\n description: str = \"Go binary packaged as Python wheel\",\n requires_python: str = \">=3.10\",\n author: str | None = None,\n author_email: str | None = None,\n license_: str | None = None,\n url: str | None = None,\n readme: str | None = None,\n ldflags: str | None = None,\n set_version_var: str | None = None,\n) -> list[str]:\n \"\"\"Build Python wheels from a Go module.\"\"\"\n```\n\n资料来源：[go_to_wheel/__init__.py:150-200](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### `cross_compile_go()`\n\n```python\ndef cross_compile_go(\n go_dir: Path,\n output_path: Path,\n goos: str,\n goarch: str,\n go_binary: str = \"go\",\n ldflags: str | None = None,\n) -> None:\n \"\"\"Cross-compile Go binary for target platform.\"\"\"\n```\n\n资料来源：[go_to_wheel/__init__.py:65-92](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Dependency Architecture\n\n```mermaid\ngraph TD\n A[go-to-wheel] --> B[Python Standard Library]\n \n B --> B1[argparse]\n B --> B2[zipfile]\n B --> B3[subprocess]\n B --> B4[pathlib]\n B --> B5[hashlib]\n B --> B6[csv]\n \n A --> C[External Dependency]\n C --> C1[Go Toolchain]\n```\n\n### Python Dependencies\n\nThe tool uses only Python standard library modules, requiring no external Python dependencies:\n\n- `argparse`: CLI argument parsing\n- `zipfile`: Wheel archive creation\n- `subprocess`: Go compilation invocation\n- `pathlib`: Path manipulation\n- `hashlib`: SHA256 hashing for RECORD\n- `csv`: RECORD file generation\n- `tempfile`: Temporary build directory\n- `shutil`: File operations\n\n### External Dependencies\n\n- **Go >= 1.16**: Required for `go build` and cross-compilation\n\n资料来源：[spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n## Version Information\n\n| Item | Value |\n|------|-------|\n| Project Version | `0.1.0` |\n| Python Requirement | `>=3.10` |\n| Go Requirement | `>=1.16` |\n| License | Apache 2.0 |\n\n资料来源：[go_to_wheel/__init__.py:10](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Installation Methods\n\n```mermaid\ngraph TD\n A[User] --> B{Installation Method}\n \n B --> C[pip install]\n B --> D[pipx install]\n \n C --> E[System Python]\n D --> F[Isolated environment
with PATH access]\n \n E --> G[Requires Go in PATH]\n F --> G\n```\n\n资料来源：[README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n\n---\n\n\n\n## Supported Platforms\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Wheel Generation Process](#page-wheel-generation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [go_to_wheel/__init__.py](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n- [README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n- [spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n \n\n# Supported Platforms\n\n`go-to-wheel` provides comprehensive cross-platform support for distributing Go CLI binaries as Python wheels. The tool automatically generates wheels for all supported platforms with correct PEP 427 tags, enabling seamless installation via `pip` or `pipx`.\n\n## Platform Architecture\n\n`go-to-wheel` maps Go's `GOOS`/`GOARCH` environment variables to Python wheel platform tags. The mapping system allows for precise targeting of specific architectures while maintaining compatibility with the Python packaging ecosystem.\n\n```mermaid\ngraph TD\n A[Go Source Code] --> B[go-to-wheel build]\n B --> C{Platform Selection}\n C -->|Default| D[All 8 Platforms]\n C -->|Custom| E[User-specified subset]\n \n D --> F[Cross-compile with GOOS/GOARCH]\n E --> F\n \n F --> G[Generate wheel with platform tag]\n G --> H[Installable via pip/pipx]\n```\n\n资料来源：[go_to_wheel/__init__.py:9-27](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Default Supported Platforms\n\nThe following 8 platform targets are built by default when no `--platforms` flag is specified:\n\n| Platform Identifier | GOOS | GOARCH | Wheel Tag |\n|---------------------|------|--------|-----------|\n| `linux-amd64` | `linux` | `amd64` | `manylinux_2_17_x86_64` |\n| `linux-arm64` | `linux` | `arm64` | `manylinux_2_17_aarch64` |\n| `linux-amd64-musl` | `linux` | `amd64` | `musllinux_1_2_x86_64` |\n| `linux-arm64-musl` | `linux` | `arm64` | `musllinux_1_2_aarch64` |\n| `darwin-amd64` | `darwin` | `amd64` | `macosx_10_9_x86_64` |\n| `darwin-arm64` | `darwin` | `arm64` | `macosx_11_0_arm64` |\n| `windows-amd64` | `windows` | `amd64` | `win_amd64` |\n| `windows-arm64` | `windows` | `arm64` | `win_arm64` |\n\n资料来源：[go_to_wheel/__init__.py:9-27](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Platform Selection Options\n\n### Building All Platforms (Default)\n\nWithout specifying platforms, all 8 targets are built:\n\n```bash\ngo-to-wheel ./mytool\n```\n\n### Building Specific Platforms\n\nUse the `--platforms` flag with a comma-separated list:\n\n```bash\ngo-to-wheel ./mytool --platforms linux-amd64,darwin-arm64\n```\n\nOnly Linux amd64 and macOS ARM64 wheels will be generated.\n\n资料来源：[README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n\n## Linux Variants\n\n### glibc-based (manylinux)\n\nThe `linux-amd64` and `linux-arm64` targets produce binaries linked against glibc, using the `manylinux_2_17` container tag. These wheels are compatible with most modern Linux distributions including:\n\n- Ubuntu 18.04+\n- Debian 10+\n- Fedora 30+\n- RHEL/CentOS 8+\n- Amazon Linux 2\n\n### musl-based (musllinux)\n\nThe `linux-amd64-musl` and `linux-arm64-musl` targets produce static binaries linked against musl libc. These wheels target:\n\n- Alpine Linux (all versions)\n- OpenWrt\n- Other musl-based distributions\n\nMusl builds are compiled with `CGO_ENABLED=0` to ensure fully static linking, eliminating any libc dependency issues.\n\n资料来源：[spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n## macOS Support\n\n### Universal2 Consideration\n\nWhile `go-to-wheel` does not natively generate `darwin-universal2` wheels that combine both architectures, the tool can build both `darwin-amd64` and `darwin-arm64` separately. Users can combine them using Apple's `lipo` tool if a single universal binary is required:\n\n```bash\nlipo -create mytool-darwin-amd64 mytool-darwin-arm64 -output mytool-darwin-universal\n```\n\n资料来源：[spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n### macOS Version Compatibility\n\n| Wheel Tag | Minimum macOS Version | Architecture |\n|-----------|----------------------|--------------|\n| `macosx_10_9_x86_64` | macOS 10.9 (Mavericks) | Intel |\n| `macosx_11_0_arm64` | macOS 11.0 (Big Sur) | Apple Silicon |\n\nThe x86_64 tag maintains backwards compatibility to macOS 10.9, while the ARM64 tag starts from macOS 11.0 due to Apple Silicon hardware requirements.\n\n## Windows Support\n\nWindows builds are cross-compiled from Linux/macOS hosts using `CGO_ENABLED=0`. The tool automatically appends the `.exe` extension to the binary within the wheel.\n\n| Wheel Tag | Architecture | Notes |\n|-----------|-------------|-------|\n| `win_amd64` | x86_64 | 64-bit Windows |\n| `win_arm64` | ARM64 | Windows on ARM devices |\n\n## Build Process\n\nThe platform-specific build workflow demonstrates how `go-to-wheel` handles cross-compilation:\n\n```mermaid\ngraph LR\n A[Source Host] -->|GOOS=linux GOARCH=amd64| B[Linux amd64 binary]\n A -->|GOOS=linux GOARCH=arm64| C[Linux arm64 binary]\n A -->|GOOS=darwin GOARCH=amd64| D[macOS amd64 binary]\n A -->|GOOS=darwin GOARCH=arm64| E[macOS arm64 binary]\n A -->|GOOS=windows GOARCH=amd64| F[Windows amd64 binary]\n \n B --> G[Wheel: manylinux_2_17_x86_64]\n C --> H[Wheel: manylinux_2_17_aarch64]\n D --> I[Wheel: macosx_10_9_x86_64]\n E --> J[Wheel: macosx_11_0_arm64]\n F --> K[Wheel: win_amd64]\n \n style A fill:#f9f,color:#000\n style G fill:#9f9,color:#000\n style H fill:#9f9,color:#000\n style I fill:#9f9,color:#000\n style J fill:#9f9,color:#000\n style K fill:#9f9,color:#000\n```\n\nEach build uses the following environment configuration:\n\n```python\nenv[\"GOOS\"] = goos\nenv[\"GOARCH\"] = goarch\nenv[\"CGO_ENABLED\"] = \"0\"\n```\n\n资料来源：[go_to_wheel/__init__.py:129-136](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Wheel Installation Compatibility\n\nThe wheel filename format ensures pip automatically selects the correct wheel for the target platform:\n\n```\n{package_name}-{version}-py3-none-{platform_tag}.whl\n```\n\nExample wheel names:\n\n| Wheel Filename | Platform |\n|----------------|----------|\n| `mytool-1.0.0-py3-none-manylinux_2_17_x86_64.whl` | Linux x86_64 (glibc) |\n| `mytool-1.0.0-py3-none-musllinux_1_2_aarch64.whl` | Linux ARM64 (musl) |\n| `mytool-1.0.0-py3-none-macosx_11_0_arm64.whl` | macOS Apple Silicon |\n| `mytool-1.0.0-py3-none-win_amd64.whl` | Windows x86_64 |\n\n资料来源：[spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n## Requirements\n\nBuilding wheels requires:\n\n| Component | Requirement |\n|-----------|-------------|\n| Go | >= 1.16 (for `go mod` support) |\n| Python | >= 3.10 |\n| Python dependencies | None (stdlib only) |\n\nThe build host does not need to match the target platform due to Go's native cross-compilation support.\n\n## Platform Detection for Binary Execution\n\nThe generated `__init__.py` wrapper uses `sys.platform` to handle platform-specific behavior:\n\n```python\ndef main():\n \"\"\"Execute the bundled binary.\"\"\"\n binary = get_binary_path()\n if sys.platform == \"win32\":\n # On Windows, use subprocess to properly handle signals\n sys.exit(subprocess.call([binary] + sys.argv[1:]))\n else:\n # On Unix, exec replaces the process\n os.execvp(binary, [binary] + sys.argv[1:])\n```\n\nThis ensures consistent behavior across all supported platforms while respecting OS-specific process management conventions.\n\n资料来源：[go_to_wheel/__init__.py:158-170](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n---\n\n\n\n## Wheel Generation Process\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Supported Platforms](#page-platforms)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [go_to_wheel/__init__.py](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n- [spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n- [README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n \n\n# Wheel Generation Process\n\n## Overview\n\nThe Wheel Generation Process is the core mechanism of `go-to-wheel` that transforms a Go CLI program into a distributable Python wheel package. This process handles cross-compilation, binary packaging, and wheel metadata generation for multiple target platforms in a single operation.\n\nThe wheel generation workflow accepts a Go module directory, validates the input, compiles static binaries for each target platform, creates a Python package wrapper, and packages everything into properly tagged wheel files following PEP 427 and PEP 376 standards.\n\n资料来源：[spec.md:1-25]()\n\n## Platform Configuration\n\n### Supported Platforms\n\nThe tool supports eight target platforms by default, covering major operating systems and architectures:\n\n| Platform Key | GOOS | GOARCH | Wheel Tag |\n|-------------|------|--------|-----------|\n| `linux-amd64` | `linux` | `amd64` | `manylinux_2_17_x86_64` |\n| `linux-arm64` | `linux` | `arm64` | `manylinux_2_17_aarch64` |\n| `linux-amd64-musl` | `linux` | `amd64` | `musllinux_1_2_x86_64` |\n| `linux-arm64-musl` | `linux` | `arm64` | `musllinux_1_2_aarch64` |\n| `darwin-amd64` | `darwin` | `amd64` | `macosx_10_9_x86_64` |\n| `darwin-arm64` | `darwin` | `arm64` | `macosx_11_0_arm64` |\n| `windows-amd64` | `windows` | `amd64` | `win_amd64` |\n| `windows-arm64` | `windows` | `arm64` | `win_arm64` |\n\n资料来源：[go_to_wheel/__init__.py:15-29]()\n\n### Platform Mapping Structure\n\nThe `PLATFORM_MAPPINGS` dictionary maps platform keys to a tuple containing the Go operating system, Go architecture, and the corresponding Python wheel platform tag:\n\n```python\nPLATFORM_MAPPINGS: dict[str, tuple[str, str, str]] = {\n \"linux-amd64\": (\"linux\", \"amd64\", \"manylinux_2_17_x86_64\"),\n # ... additional platforms\n}\n```\n\nThe `DEFAULT_PLATFORMS` list defines which platforms are built when no specific platform is specified:\n\n```python\nDEFAULT_PLATFORMS = [\n \"linux-amd64\",\n \"linux-arm64\",\n \"linux-amd64-musl\",\n \"linux-arm64-musl\",\n \"darwin-amd64\",\n \"darwin-arm64\",\n \"windows-amd64\",\n \"windows-arm64\",\n]\n```\n\n资料来源：[go_to_wheel/__init__.py:31-37]()\n\n## Build Process Architecture\n\n### High-Level Workflow\n\n```mermaid\ngraph TD\n A[Start: go-to-wheel Command] --> B[Validate Go Directory]\n B --> C{Valid?}\n C -->|No| D[Error: Directory not found or no go.mod]\n C -->|Yes| E[Parse Options and Set Defaults]\n E --> F{Platforms specified?}\n F -->|Yes| G[Use Specified Platforms]\n F -->|No| H[Use DEFAULT_PLATFORMS]\n G --> I[For Each Platform]\n H --> I\n I --> J[Cross-Compile Go Binary]\n J --> K[Create Package Directory Structure]\n K --> L[Generate Python Wrapper Files]\n L --> M[Generate Metadata Files]\n M --> N[Create Wheel ZIP Archive]\n N --> O{More Platforms?}\n O -->|Yes| I\n O -->|No| P[Move Wheels to Output Directory]\n P --> Q[Print Summary]\n```\n\n### Main Entry Point\n\nThe `build_wheels()` function serves as the primary entry point for the wheel generation process. It accepts the following parameters:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `go_dir` | `str` | Required | Path to Go module directory |\n| `name` | `str \\| None` | `None` | Python package name (defaults to directory basename) |\n| `version` | `str` | `\"0.1.0\"` | Package version |\n| `output_dir` | `str` | `\"./dist\"` | Directory for built wheels |\n| `entry_point` | `str \\| None` | `None` | CLI command name (defaults to package name) |\n| `platforms` | `list[str] \\| None` | `None` | Target platforms (defaults to all) |\n| `go_binary` | `str` | `\"go\"` | Path to Go binary |\n| `description` | `str` | `\"Go binary packaged as Python wheel\"` | Package description |\n| `requires_python` | `str` | `\">=3.10\"` | Python version requirement |\n| `author` | `str \\| None` | `None` | Author name |\n| `author_email` | `str \\| None` | `None` | Author email |\n| `license_` | `str \\| None` | `None` | License identifier |\n| `url` | `str \\| None` | `None` | Project URL |\n| `readme` | `str \\| None` | `None` | Path to README markdown file |\n| `ldflags` | `str \\| None` | `None` | Additional Go linker flags |\n| `set_version_var` | `str \\| None` | `None` | Go variable to set via -X ldflag |\n\n资料来源：[go_to_wheel/__init__.py:136-168]()\n\n## Step-by-Step Generation Process\n\n### Step 1: Input Validation\n\nThe process begins with comprehensive validation of the input parameters:\n\n1. **Directory Existence**: Verify the Go directory exists using `Path.resolve()`\n2. **Go Module Verification**: Check for `go.mod` file to confirm valid Go module\n3. **README File Check**: If `--readme` is provided, verify the file exists and read its content\n4. **Default Value Assignment**: Set defaults for `name` and `entry_point` from directory name\n\n```python\ngo_path = Path(go_dir).resolve()\n\nif not go_path.exists():\n raise FileNotFoundError(f\"Go directory not found: {go_dir}\")\n\nif not (go_path / \"go.mod\").exists():\n raise ValueError(f\"Not a Go module: {go_dir} (no go.mod file found)\")\n```\n\n资料来源：[go_to_wheel/__init__.py:179-186]()\n\n### Step 2: Cross-Compilation\n\nEach Go binary is compiled for its target platform using environment variables:\n\n```mermaid\ngraph LR\n A[Platform: linux-amd64] --> B[\"GOOS=linux
GOARCH=amd64
CGO_ENABLED=0\"]\n B --> C[\"go build
-ldflags='-s -w'
-o output\"]\n C --> D[Static Binary]\n \n E[Platform: windows-amd64] --> F[\"GOOS=windows
GOARCH=amd64
CGO_ENABLED=0\"]\n F --> G[\"go build
-ldflags='-s -w'
-o output.exe\"]\n G --> H[Static Binary .exe]\n```\n\n**Compilation Environment Variables:**\n\n| Variable | Value | Purpose |\n|----------|-------|---------|\n| `GOOS` | Platform's OS | Target operating system |\n| `GOARCH` | Platform's architecture | Target CPU architecture |\n| `CGO_ENABLED` | `0` | Disable CGO for static binaries |\n\n**Linker Flags:**\n\nThe default linker flags `-s -w` strip debug information and symbol tables to reduce binary size. Additional flags can be appended via the `--ldflags` option:\n\n```python\nGOOS={goos} GOARCH={goarch} CGO_ENABLED=0 go build \\\n -ldflags=\"-s -w {additional_flags}\" \\\n -o {output_path} \\\n {go_module_path}\n```\n\n资料来源：[spec.md:145-156]()\n\n### Step 3: Wheel Package Structure Creation\n\nThe wheel contains a specific directory structure following PEP 427:\n\n```\n{package_name}-{version}-py3-none-{platform_tag}.whl\n├── {package_name}/\n│ ├── __init__.py\n│ ├── __main__.py\n│ └── bin/\n│ └── {binary_name}[.exe]\n├── {package_name}-{version}.dist-info/\n│ ├── METADATA\n│ ├── WHEEL\n│ ├── RECORD\n│ └── entry_points.txt\n```\n\n资料来源：[spec.md:40-57]()\n\n### Step 4: Python Wrapper Generation\n\nThe generated `__init__.py` provides a thin wrapper that executes the bundled binary:\n\n```python\n\"\"\"Go binary packaged as Python wheel.\"\"\"\n\nimport os\nimport sys\nimport subprocess\n\n__version__ = \"{version}\"\n\ndef get_binary_path():\n \"\"\"Return the path to the bundled binary.\"\"\"\n return os.path.join(os.path.dirname(__file__), \"bin\", \"{binary_name}\")\n\ndef main():\n \"\"\"Execute the bundled binary.\"\"\"\n binary = get_binary_path()\n if sys.platform == \"win32\":\n # On Windows, use subprocess to properly handle signals\n sys.exit(subprocess.call([binary] + sys.argv[1:]))\n else:\n # On Unix, exec replaces the process\n os.execvp(binary, [binary] + sys.argv[1:])\n```\n\nThe `__main__.py` serves as the entry point bridge:\n\n```python\nfrom . import main\nmain()\n```\n\n资料来源：[spec.md:63-87]()\n\n### Step 5: Metadata File Generation\n\n#### METADATA (PEP 566)\n\nGenerated dynamically with package metadata:\n\n```\nMetadata-Version: 2.1\nName: {normalized_name}\nVersion: {version}\nSummary: {description}\nLicense: {license}\nAuthor: {author}\nAuthor-email: {author_email}\nHome-page: {url}\nRequires-Python: {requires_python}\n```\n\n#### WHEEL (PEP 427)\n\n```python\nWheel-Version: 1.0\nGenerator: go-to-wheel {version}\nRoot-Is-Purelib: false\nTag: py3-none-{platform_tag}\n```\n\n#### entry_points.txt\n\n```ini\n[console_scripts]\n{entry_point} = {package_name}:main\n```\n\n#### RECORD (PEP 376)\n\nCSV format tracking all files with SHA256 hashes:\n\n```csv\n{package_name}/__init__.py,sha256={hash},{size}\n{package_name}/__main__.py,sha256={hash},{size}\n{package_name}/bin/{binary_name},sha256={hash},{size}\n{package_name}-{version}.dist-info/METADATA,sha256={hash},{size}\n{package_name}-{version}.dist-info/WHEEL,sha256={hash},{size}\n{package_name}-{version}.dist-info/entry_points.txt,sha256={hash},{size}\n{package_name}-{version}.dist-info/RECORD,,\n```\n\n资料来源：[spec.md:162-183]()\n\n### Step 6: Wheel Archive Creation\n\nThe wheel is created as a ZIP archive with specific handling:\n\n```python\nwith zipfile.ZipFile(wheel_path, \"w\", zipfile.ZIP_DEFLATED) as whl:\n for file_path, content in files.items():\n # Set executable permission for binary\n if \"/bin/\" in file_path:\n info = zipfile.ZipInfo(file_path)\n # Set Unix permissions: rwxr-xr-x (0755)\n info.external_attr = (\n stat.S_IRWXU | stat.S_IRGRP | stat.S_IXGRP | \n stat.S_IROTH | stat.S_IXOTH\n ) << 16\n whl.writestr(info, content)\n else:\n whl.writestr(file_path, content)\n```\n\nBinary files receive executable permissions (0755) via the ZIP external attributes, ensuring they can be executed after installation.\n\n资料来源：[go_to_wheel/__init__.py:110-123]()\n\n## Wheel Naming Convention\n\nWheels follow PEP 427 naming with format:\n\n```\n{name}-{version}-py3-none-{platform_tag}.whl\n```\n\n**Examples:**\n\n| Package | Version | Platform | Full Wheel Name |\n|---------|---------|----------|-----------------|\n| `myapp` | `1.0.0` | linux-amd64 | `myapp-1.0.0-py3-none-manylinux_2_17_x86_64.whl` |\n| `myapp` | `1.0.0` | darwin-arm64 | `myapp-1.0.0-py3-none-macosx_11_0_arm64.whl` |\n| `myapp` | `1.0.0` | windows-amd64 | `myapp-1.0.0-py3-none-win_amd64.whl` |\n\nPackage names are normalized per PEP 503: hyphens are used in wheel filenames, while the import name (directory) uses underscores.\n\n资料来源：[spec.md:207-216]()\n\n## Linker Flags Integration\n\n### Version Variable Setting\n\nThe `--set-version-var` option embeds the package version into a Go variable at compile time:\n\n```bash\ngo-to-wheel ./mytool --version 2.0.0 --set-version-var main.version\n```\n\nThis passes `-X main.version=2.0.0` to the Go linker. The combined ldflags are constructed as:\n\n```python\ncombined_ldflags_parts: list[str] = []\nif set_version_var:\n combined_ldflags_parts.append(f\"-X {set_version_var}={version}\")\nif ldflags:\n combined_ldflags_parts.append(ldflags)\n\ncombined_ldflags = \" \".join(combined_ldflags_parts)\n```\n\nThe final linker invocation becomes: `-ldflags=\"-s -w -X main.version=2.0.0\"`\n\n资料来源：[go_to_wheel/__init__.py:196-203]()\n\n### Custom ldflags\n\nAdditional arbitrary linker flags can be passed with `--ldflags`:\n\n```bash\ngo-to-wheel ./mytool --ldflags \"-X main.version=2.0.0 -X main.commit=abc123\"\n```\n\nThese flags are appended to the default `-s -w`, so the full invocation becomes `-ldflags=\"-s -w -X main.version=2.0.0 -X main.commit=abc123\"`.\n\n资料来源：[README.md:48-51]()\n\n## Error Handling\n\n| Error Condition | Handling |\n|-----------------|----------|\n| Directory not found | `FileNotFoundError` with message |\n| No `go.mod` file | `ValueError` indicating invalid Go module |\n| README file not found | `FileNotFoundError` for README path |\n| Go binary not found | `FileNotFoundError` from subprocess |\n| Build failure | Exception propagates with Go error output |\n| No wheels built | Prints error and returns exit code 1 |\n\nThe CLI entry point catches `FileNotFoundError` and `ValueError` exceptions, printing them to stderr and returning exit code 1:\n\n```python\ntry:\n wheels = build_wheels(...)\nexcept (FileNotFoundError, ValueError) as e:\n print(f\"Error: {e}\", file=sys.stderr)\n return 1\n```\n\n资料来源：[go_to_wheel/__init__.py:92-95]()\n\n## Output Example\n\nSuccessful wheel generation produces output like:\n\n```\ngo-to-wheel v0.1.0\nBuilding from ./myapp\n\n ✓ myapp-1.0.0-py3-none-manylinux_2_17_x86_64.whl\n ✓ myapp-1.0.0-py3-none-manylinux_2_17_aarch64.whl\n ✓ myapp-1.0.0-py3-none-musllinux_1_2_x86_64.whl\n ✓ myapp-1.0.0-py3-none-musllinux_1_2_aarch64.whl\n ✓ myapp-1.0.0-py3-none-macosx_10_9_x86_64.whl\n ✓ myapp-1.0.0-py3-none-macosx_11_0_arm64.whl\n ✓ myapp-1.0.0-py3-none-win_amd64.whl\n ✓ myapp-1.0.0-py3-none-win_arm64.whl\n\nDone! Built 8 wheels in ./dist\n```\n\n资料来源：[spec.md:225-240]()\n\n## Related Components\n\n| Component | Purpose |\n|-----------|---------|\n| `build_wheels()` | Main orchestrator function |\n| `build_single_wheel()` | Creates wheel for one platform |\n| `compile_go_binary()` | Executes Go cross-compilation |\n| `generate_metadata()` | Creates METADATA content |\n| `generate_wheel_file()` | Creates WHEEL file content |\n| `generate_record()` | Creates RECORD with hashes |\n| `generate_entry_points()` | Creates entry_points.txt |\n\nThese functions work together to transform a Go module into a distributable Python wheel package that can be installed via `pip` or `pipx`.\n\n资料来源：[go_to_wheel/__init__.py:96-135]()\n\n## See Also\n\n- [go-to-wheel GitHub Repository](https://github.com/simonw/go-to-wheel)\n- [maturin](https://github.com/PyO3/maturin) - Rust equivalent tool\n- [PEP 427 - Wheel Binary Package Format](https://peps.python.org/pep-0427/)\n- [PEP 376 - Wheel Metadata and RECORD](https://peps.python.org/pep-0376/)\n\n---\n\n\n\n## Development Guide\n\n### 相关页面\n\n相关主题：[Installation](#page-installation), [Configuration and Metadata](#page-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [go_to_wheel/__init__.py](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n- [README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n- [spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n- [pyproject.toml](https://github.com/simonw/go-to-wheel/blob/main/pyproject.toml)\n \n\n# Development Guide\n\n## Overview\n\nThis guide covers everything you need to know to develop, test, and contribute to `go-to-wheel`. The project is a Python CLI tool that compiles Go programs into Python wheels, enabling distribution of Go binaries via PyPI and pipx. 资料来源：[README.md:1-15]()\n\nThe tool requires no external Python dependencies—only Python's standard library is used—making it lightweight and easy to maintain. 资料来源：[spec.md:95-97]()\n\n## Prerequisites\n\nBefore setting up a development environment, ensure you have the following installed:\n\n| Requirement | Minimum Version | Purpose |\n|-------------|-----------------|---------|\n| Python | >= 3.10 | Runtime for the tool |\n| Go | >= 1.16 | Required for `go build` commands |\n| uv | Latest | Package manager and test runner |\n| Git | Any recent | Version control |\n\n资料来源：[spec.md:95-100]()\n\n## Repository Structure\n\n```\ngo-to-wheel/\n├── go_to_wheel/\n│ └── __init__.py # Main module with all logic\n├── tests/\n│ └── test_*.py # Test files\n├── pyproject.toml # Project configuration\n├── README.md # User documentation\n├── spec.md # Technical specification\n└── LICENSE # Apache 2.0 license\n```\n\nThe main implementation resides in `go_to_wheel/__init__.py`, which contains:\n\n- Platform mapping definitions\n- CLI argument parsing\n- Go cross-compilation logic\n- Wheel building functions\n- Metadata generation\n\n资料来源：[go_to_wheel/__init__.py:1-50]()\n\n## Setting Up the Development Environment\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/simonw/go-to-wheel\ncd go-to-wheel\n```\n\n资料来源：[README.md:55-58]()\n\n### 2. Install Dependencies\n\nThe project uses `uv` for dependency management. Install all development dependencies:\n\n```bash\nuv sync\n```\n\nThis automatically installs the project and its test dependencies based on `pyproject.toml`.\n\n### 3. Verify Installation\n\nConfirm the tool is accessible:\n\n```bash\nuv run go-to-wheel --version\n```\n\n## Running Tests\n\nThe project uses `pytest` for testing. Execute the full test suite with:\n\n```bash\nuv run pytest\n```\n\n资料来源：[README.md:59-60]()\n\n### Test Structure\n\nTests are located in the `tests/` directory and follow the naming pattern `test_*.py`. Each test file typically corresponds to a major component:\n\n| Test File | Coverage Area |\n|-----------|---------------|\n| `test_platforms.py` | Platform mapping and validation |\n| `test_build.py` | Wheel building logic |\n| `test_cli.py` | Command-line argument parsing |\n\n### Running Specific Tests\n\nRun tests matching a pattern:\n\n```bash\nuv run pytest -k \"test_name_pattern\"\n```\n\nRun with verbose output:\n\n```bash\nuv run pytest -v\n```\n\n## Code Architecture\n\n### Core Components\n\n```mermaid\ngraph TD\n A[CLI Entry Point] --> B[Argument Parser]\n B --> C[build_wheels Function]\n C --> D[Platform Validation]\n C --> E[Go Cross-Compilation]\n E --> F[Wheel Assembly]\n F --> G[Metadata Generation]\n F --> H[ZIP Creation]\n G --> H\n H --> I[Output Wheels]\n```\n\n### Platform Mapping System\n\nThe tool defines platform mappings that translate human-readable platform names to Go environment variables and wheel tags:\n\n```python\nPLATFORM_MAPPINGS: dict[str, tuple[str, str, str]] = {\n \"linux-amd64\": (\"linux\", \"amd64\", \"manylinux_2_17_x86_64\"),\n \"linux-arm64\": (\"linux\", \"arm64\", \"manylinux_2_17_aarch64\"),\n \"linux-amd64-musl\": (\"linux\", \"amd64\", \"musllinux_1_2_x86_64\"),\n \"linux-arm64-musl\": (\"linux\", \"arm64\", \"musllinux_1_2_aarch64\"),\n \"darwin-amd64\": (\"darwin\", \"amd64\", \"macosx_10_9_x86_64\"),\n \"darwin-arm64\": (\"darwin\", \"arm64\", \"macosx_11_0_arm64\"),\n \"windows-amd64\": (\"windows\", \"amd64\", \"win_amd64\"),\n \"windows-arm64\": (\"windows\", \"arm64\", \"win_arm64\"),\n}\n```\n\n资料来源：[go_to_wheel/__init__.py:19-27]()\n\n### Default Platforms\n\n```mermaid\ngraph LR\n A[Default Platforms] --> B[Linux amd64]\n A --> C[Linux arm64]\n A --> D[Linux amd64-musl]\n A --> E[Linux arm64-musl]\n A --> F[macOS amd64]\n A --> G[macOS arm64]\n A --> H[Windows amd64]\n A --> I[Windows arm64]\n```\n\nThe `DEFAULT_PLATFORMS` list defines which platforms are built when none are specified:\n\n```python\nDEFAULT_PLATFORMS = [\n \"linux-amd64\",\n \"linux-arm64\",\n \"linux-amd64-musl\",\n \"linux-arm64-musl\",\n \"darwin-amd64\",\n \"darwin-arm64\",\n \"windows-amd64\",\n \"windows-arm64\",\n]\n```\n\n资料来源：[go_to_wheel/__init__.py:29-37]()\n\n### Build Workflow\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI\n participant Builder\n participant Go\n participant WheelBuilder\n \n User->>CLI: go-to-wheel ./myapp\n CLI->>Builder: build_wheels(go_dir)\n Builder->>Go: GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build\n Go-->>Builder: Binary for linux/amd64\n Builder->>Go: (repeat for each platform)\n Go-->>Builder: Binaries for all platforms\n Builder->>WheelBuilder: Create wheel structure\n WheelBuilder->>WheelBuilder: Generate __init__.py\n WheelBuilder->>WheelBuilder: Generate METADATA\n WheelBuilder->>WheelBuilder: Create RECORD with hashes\n WheelBuilder->>Builder: Wheel file\n Builder->>User: List of wheel paths\n```\n\n## Building Wheels Locally\n\n### Local Installation\n\nInstall the package in development mode:\n\n```bash\nuv pip install -e .\n```\n\n### Building Wheels for Testing\n\nCreate test wheels for a sample Go module:\n\n```bash\ngo-to-wheel ./path/to/go-module --name my-test-package\n```\n\nThis creates wheels in `./dist` for all default platforms. 资料来源：[README.md:31-37]()\n\n### Custom Platform Selection\n\nBuild only specific platforms to speed up iteration:\n\n```bash\ngo-to-wheel ./myapp --platforms linux-amd64,darwin-arm64\n```\n\n## CLI Argument Reference\n\nThe tool accepts the following arguments for development and testing:\n\n| Argument | Type | Default | Purpose |\n|----------|------|---------|---------|\n| `--name` | string | Directory name | Python package name |\n| `--version` | string | `0.1.0` | Package version |\n| `--output-dir` | string | `./dist` | Output directory |\n| `--platforms` | string | All platforms | Target platforms |\n| `--go-binary` | string | `go` | Go binary path |\n| `--ldflags` | string | None | Additional linker flags |\n\n资料来源：[go_to_wheel/__init__.py:75-100]()\n\n## Cross-Compilation Process\n\nThe build process uses Go's cross-compilation with specific environment settings:\n\n```python\ndef compile_go_binary(\n go_dir: str,\n goos: str,\n goarch: str,\n output_path: str,\n go_binary: str,\n ldflags: str | None = None,\n) -> None:\n env = os.environ.copy()\n env[\"GOOS\"] = goos\n env[\"GOARCH\"] = goarch\n env[\"CGO_ENABLED\"] = \"0\" # Static binaries\n \n ldflags_value = \"-s -w\" # Strip debug info\n if ldflags:\n ldflags_value += \" \" + ldflags\n \n cmd = [go_binary, \"build\", f\"-ldflags={ldflags_value}\", \"-o\", output_path, \".\"]\n```\n\nKey points:\n- `CGO_ENABLED=0` ensures static binaries with no libc dependency\n- `-ldflags=\"-s -w\"` strips debug information to reduce binary size\n- Windows builds automatically receive `.exe` extension\n\n资料来源：[go_to_wheel/__init__.py:120-140]()\n\n## Wheel Structure Generation\n\nEach wheel contains a Python wrapper that executes the bundled binary:\n\n```mermaid\ngraph TD\n subgraph Wheel Contents\n A[Package Directory] --> B[__init__.py]\n A --> C[__main__.py]\n A --> D[bin/]\n D --> E[Go Binary]\n A --> F[.dist-info/]\n F --> G[METADATA]\n F --> H[WHEEL]\n F --> I[RECORD]\n F --> J[entry_points.txt]\n end\n```\n\nThe `__init__.py` includes:\n\n```python\ndef get_binary_path():\n \"\"\"Return the path to the bundled binary.\"\"\"\n return os.path.join(os.path.dirname(__file__), \"bin\", \"{binary_name}\")\n\ndef main():\n \"\"\"Execute the bundled binary.\"\"\"\n binary = get_binary_path()\n if sys.platform == \"win32\":\n sys.exit(subprocess.call([binary] + sys.argv[1:]))\n else:\n os.execvp(binary, [binary] + sys.argv[1:])\n```\n\n资料来源：[spec.md:58-75]()\n\n## Version Information\n\nThe project version is defined in the main module:\n\n```python\n__version__ = \"0.1.0\"\n```\n\n资料来源：[go_to_wheel/__init__.py:12]()\n\nTo check the installed version during development:\n\n```bash\nuv run python -c \"import go_to_wheel; print(go_to_wheel.__version__)\"\n```\n\n## Debugging\n\n### Enable Verbose Output\n\nThe CLI outputs progress during builds:\n\n```\ngo-to-wheel v0.1.0\nBuilding from ./myapp\n\nlinux-amd64... done\ndarwin-arm64... done\n```\n\n### Common Build Failures\n\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| `go.mod not found` | Directory is not a Go module | Run `go mod init` first |\n| `Go not found` | Go not in PATH | Install Go or use `--go-binary` |\n| Build timeout | Complex Go project | Increase timeout or skip platforms |\n\n### Inspecting Generated Wheels\n\nList contents of a wheel:\n\n```bash\nunzip -l myapp-1.0.0-py3-none-manylinux_2_17_x86_64.whl\n```\n\n## Contributing\n\n### Development Workflow\n\n1. Fork the repository on GitHub\n2. Clone your fork locally\n3. Create a feature branch: `git checkout -b feature/my-feature`\n4. Make changes and add tests\n5. Run the test suite: `uv run pytest`\n6. Commit your changes with clear messages\n7. Push to your fork and submit a pull request\n\n### Code Style\n\n- Follow PEP 8 for Python code\n- Use type hints for function parameters and return values\n- Add docstrings to public functions\n- Keep functions focused and small\n\n### Testing Guidelines\n\n- All new features should include tests\n- Ensure existing tests pass before submitting\n- Use descriptive test names: `test_platform_mapping_linux_amd64`\n\n## Future Development Considerations\n\nThe specification outlines potential future features not yet implemented:\n\n| Feature | Status | Description |\n|---------|--------|-------------|\n| Configuration file | Not started | Support `pyproject.toml` or `go-to-wheel.toml` |\n| Auto version detection | Not started | Parse from VERSION file or git tags |\n| Multiple entry points | Not started | Support Go modules with multiple binaries |\n| Universal2 macOS | Not started | Combine arm64 and x86_64 with `lipo` |\n| Build caching | Not started | Skip unchanged platforms |\n| PyPI publishing | Not started | Add `go-to-wheel publish` command |\n\n资料来源：[spec.md:80-93]()\n\n## Related Documentation\n\n- [User README](README.md) - Installation and usage instructions\n- [Technical Specification](spec.md) - Detailed system design\n- [maturin](https://github.com/PyO3/maturin) - Rust equivalent that inspired this project\n- [pip-binary-factory](https://github.com/Bing-su/pip-binary-factory) - Template for pre-built binaries\n\n---\n\n\n\n## Configuration and Metadata\n\n### 相关页面\n\n相关主题：[CLI Options Reference](#page-cli-options), [Development Guide](#page-development-guide)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [go_to_wheel/__init__.py](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n- [README.md](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n- [spec.md](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n \n\n# Configuration and Metadata\n\nThis page documents the configuration system and metadata handling in go-to-wheel, a tool that compiles Go CLI programs into Python wheels.\n\n## Overview\n\ngo-to-wheel provides extensive configuration options for customizing wheel builds. Configuration is passed through command-line arguments and is used to generate proper Python wheel metadata according to PEP 427 and PEP 566 standards.\n\nThe tool supports two layers of configuration:\n1. **Build Configuration** - Controls how the Go binary is compiled (platforms, Go binary path, ldflags)\n2. **Package Metadata** - Defines Python package metadata (name, version, author, license, etc.)\n\n资料来源：[go_to_wheel/__init__.py:1-50](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Platform Configuration\n\n### Supported Platforms\n\ngo-to-wheel supports cross-compilation for 8 different platform configurations:\n\n| Platform Identifier | GOOS | GOARCH | Wheel Tag |\n|---------------------|------|--------|-----------|\n| `linux-amd64` | linux | amd64 | `manylinux_2_17_x86_64` |\n| `linux-arm64` | linux | arm64 | `manylinux_2_17_aarch64` |\n| `linux-amd64-musl` | linux | amd64 | `musllinux_1_2_x86_64` |\n| `linux-arm64-musl` | linux | arm64 | `musllinux_1_2_aarch64` |\n| `darwin-amd64` | darwin | amd64 | `macosx_10_9_x86_64` |\n| `darwin-arm64` | darwin | arm64 | `macosx_11_0_arm64` |\n| `windows-amd64` | windows | amd64 | `win_amd64` |\n| `windows-arm64` | windows | arm64 | `win_arm64` |\n\n资料来源：[go_to_wheel/__init__.py:22-30](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### Platform Selection\n\nBy default, all 8 platforms are built. Users can specify a subset using the `--platforms` option:\n\n```bash\ngo-to-wheel ./mytool --platforms linux-amd64,darwin-arm64\n```\n\nPlatform identifiers are defined in the `PLATFORM_MAPPINGS` dictionary and can be parsed from comma-separated input.\n\n资料来源：[go_to_wheel/__init__.py:86-90](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### Build Workflow\n\n```mermaid\ngraph TD\n A[Parse --platforms argument] --> B{Platforms specified?}\n B -->|No| C[Use DEFAULT_PLATFORMS]\n B -->|Yes| D[Split by comma]\n D --> E[Validate each platform]\n E --> F[For each platform]\n F --> G[Set GOOS/GOARCH env]\n G --> H[Run go build with CGO_ENABLED=0]\n H --> I[Create wheel structure]\n I --> J[Generate METADATA, WHEEL, RECORD]\n J --> K[Zip into .whl file]\n K --> F\n```\n\n## Command-Line Options\n\n### Full Option Reference\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--name` | string | Directory basename | Python package name |\n| `--version` | string | `0.1.0` | Package version |\n| `--output-dir` | string | `./dist` | Directory for built wheels |\n| `--entry-point` | string | Same as `--name` | CLI command name |\n| `--platforms` | string | All 8 platforms | Comma-separated platform list |\n| `--go-binary` | string | `go` | Path to Go binary |\n| `--description` | string | `\"Go binary packaged as Python wheel\"` | Package description |\n| `--license` | string | None | SPDX license identifier |\n| `--author` | string | None | Author name |\n| `--author-email` | string | None | Author email |\n| `--url` | string | None | Project URL |\n| `--requires-python` | string | `>=3.10` | Python version requirement |\n| `--readme` | string | None | Path to README markdown file |\n| `--ldflags` | string | None | Additional Go linker flags |\n| `--set-version-var` | string | None | Go variable for version embedding |\n\n资料来源：[go_to_wheel/__init__.py:52-115](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### Build Configuration Options\n\nThese options control the Go compilation process:\n\n```python\ndef build_wheels(\n go_dir: str,\n *,\n name: str | None = None,\n version: str = \"0.1.0\",\n output_dir: str = \"./dist\",\n entry_point: str | None = None,\n platforms: list[str] | None = None,\n go_binary: str = \"go\",\n description: str = \"Go binary packaged as Python wheel\",\n # ... metadata options ...\n ldflags: str | None = None,\n set_version_var: str | None = None,\n) -> list[str]:\n```\n\n资料来源：[go_to_wheel/__init__.py:178-220](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### Linker Flags Configuration\n\nThe `--ldflags` and `--set-version-var` options control Go linker flags:\n\n**Default flags:** `-s -w` (strips debug info and symbol tables)\n\n**Additional flags** can be appended using `--ldflags`:\n\n```bash\ngo-to-wheel ./mytool --ldflags \"-X main.commit=abc123\"\n```\n\n**Version embedding** via `--set-version-var`:\n\n```bash\ngo-to-wheel ./mytool --version 2.0.0 --set-version-var main.version\n```\n\nThis passes `-X main.version=2.0.0` to the Go linker.\n\n资料来源：[README.md:30-50](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n\nThe linker flags are combined in this order:\n1. `-s -w` (default strip flags)\n2. `-X {set_version_var}={version}` (if `--set-version-var` is set)\n3. User-provided `--ldflags` (appended last)\n\n资料来源：[go_to_wheel/__init__.py:255-265](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Metadata Generation\n\n### METADATA File (PEP 566)\n\nGenerated by `generate_metadata()`:\n\n```python\ndef generate_metadata(\n name: str,\n version: str,\n description: str,\n *,\n author: str | None = None,\n author_email: str | None = None,\n license_: str | None = None,\n url: str | None = None,\n requires_python: str = \">=3.10\",\n readme_content: str | None = None,\n) -> str:\n \"\"\"Generate METADATA file content.\"\"\"\n lines = [\n \"Metadata-Version: 2.1\",\n f\"Name: {name}\",\n f\"Version: {version}\",\n f\"Summary: {description}\",\n ]\n\n if author:\n lines.append(f\"Author: {author}\")\n if author_email:\n lines.append(f\"Author-email: {author_email}\")\n if license_:\n lines.append(f\"License: {license_}\")\n if url:\n lines.append(f\"Home-page: {url}\")\n\n lines.append(f\"Requires-Python: {requires_python}\")\n\n if readme_content:\n lines.append(\"Description-Content-Type: text/markdown\")\n lines.append(\"\")\n lines.append(readme_content)\n\n return \"\\n\".join(lines) + \"\\n\"\n```\n\n资料来源：[go_to_wheel/__init__.py:280-315](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### WHEEL File (PEP 427)\n\nGenerated by `generate_wheel_metadata()`:\n\n```\nWheel-Version: 1.0\nGenerator: go-to-wheel {version}\nRoot-Is-Purelib: false\nTag: py3-none-{platform_tag}\n```\n\nKey points:\n- `Root-Is-Purelib: false` indicates platform-specific binary\n- `py3-none` indicates Python 3+ requirement\n- `{platform_tag}` varies by target (e.g., `manylinux_2_17_x86_64`)\n\n资料来源：[go_to_wheel/__init__.py:317-325](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### entry_points.txt\n\nGenerated for console script entry points:\n\n```\n[console_scripts]\n{entry_point} = {import_name}:main\n```\n\nThe `import_name` is derived from the package name by replacing hyphens with underscores.\n\n资料来源：[go_to_wheel/__init__.py:327-332](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n### RECORD File\n\nGenerated by `generate_record()` using SHA256 hashes:\n\n```python\ndef generate_record(files: dict[str, bytes]) -> str:\n \"\"\"Generate RECORD file content.\"\"\"\n output = io.StringIO()\n writer = csv.writer(output)\n\n for path, content in files.items():\n if path.endswith(\"RECORD\"):\n writer.writerow([path, \"\", \"\"])\n else:\n hash_value = base64.urlsafe_b64encode(\n hashlib.sha256(content).digest()\n ).rstrip(b\"=\").decode(\"ascii\")\n writer.writerow([path, f\"sha256={hash_value}\", len(content)])\n\n return output.getvalue()\n```\n\n资料来源：[go_to_wheel/__init__.py:334-348](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Package Structure\n\nThe generated wheel follows this structure:\n\n```\n{package_name}-{version}-py3-none-{platform_tag}.whl\n├── {import_name}/\n│ ├── __init__.py\n│ ├── __main__.py\n│ └── bin/\n│ └── {binary_name}[.exe]\n├── {import_name}-{version}.dist-info/\n│ ├── METADATA\n│ ├── WHEEL\n│ ├── RECORD\n│ └── entry_points.txt\n```\n\n资料来源：[spec.md:60-80](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n### __init__.py Template\n\n```python\n\"\"\"Go binary packaged as Python wheel.\"\"\"\n\nimport os\nimport sys\nimport subprocess\n\n__version__ = \"{version}\"\n\ndef get_binary_path():\n \"\"\"Return the path to the bundled binary.\"\"\"\n return os.path.join(os.path.dirname(__file__), \"bin\", \"{binary_name}\")\n\ndef main():\n \"\"\"Execute the bundled binary.\"\"\"\n binary = get_binary_path()\n if sys.platform == \"win32\":\n sys.exit(subprocess.call([binary] + sys.argv[1:]))\n else:\n os.execvp(binary, [binary] + sys.argv[1:])\n```\n\n资料来源：[spec.md:82-100](https://github.com/simonw/go-to-wheel/blob/main/spec.md)\n\n## Metadata Flow\n\n```mermaid\ngraph LR\n A[CLI Arguments] --> B[ArgumentParser]\n B --> C[build_wheels function]\n C --> D[Input Validation]\n D --> E[README Processing]\n E --> F[Platform Loop]\n F --> G[Go Compilation]\n G --> H[Wheel Assembly]\n H --> I[Metadata Generation]\n I --> J[ZIP Creation]\n J --> K[Output Directory]\n \n C -->|name, version| L[METADATA]\n C -->|platform_tag| M[WHEEL]\n C -->|entry_point| N[entry_points.txt]\n H --> O[RECORD with hashes]\n```\n\n## Input Validation\n\nThe `build_wheels()` function validates inputs:\n\n| Check | Behavior on Failure |\n|-------|---------------------|\n| Go directory exists | Raises `FileNotFoundError` |\n| `go.mod` file present | Raises `ValueError` |\n| README file exists (if provided) | Raises `FileNotFoundError` |\n| Package name valid (PEP 503) | Raises `ValueError` |\n\n资料来源：[go_to_wheel/__init__.py:225-235](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Configuration Precedence\n\nWhen multiple configuration sources conflict, the following precedence applies:\n\n1. **Command-line arguments** (highest priority)\n2. **Default values** (lowest priority)\n\nFor `--ldflags`, user-provided flags are appended after default flags, allowing overrides.\n\n## Environment Variables Used\n\nDuring build, these environment variables are set:\n\n| Variable | Value | Purpose |\n|----------|-------|---------|\n| `GOOS` | Platform GOOS | Cross-compilation target |\n| `GOARCH` | Platform GOARCH | Cross-compilation target |\n| `CGO_ENABLED` | `0` | Static binary compilation |\n\n资料来源：[go_to_wheel/__init__.py:270-280](https://github.com/simonw/go-to-wheel/blob/main/go_to_wheel/__init__.py)\n\n## Example: Full Metadata Configuration\n\n```bash\ngo-to-wheel ./mytool \\\n --name mytool-bin \\\n --version 2.0.0 \\\n --description \"My awesome tool\" \\\n --license MIT \\\n --author \"Jane Doe\" \\\n --author-email \"jane@example.com\" \\\n --url \"https://github.com/jane/mytool\" \\\n --readme README.md\n```\n\nThis produces a wheel with complete PyPI-compatible metadata.\n\n资料来源：[README.md:55-65](https://github.com/simonw/go-to-wheel/blob/main/README.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：simonw/go-to-wheel\n\n摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | no_demo; severity=medium\n\n## 5. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | issue_or_pr_quality=unknown\n\n## 6. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：simonw/go-to-wheel\n\n摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | no_demo; severity=medium\n\n## 5. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | issue_or_pr_quality=unknown\n\n## 6. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | hn_item:48109677 | https://news.ycombinator.com/item?id=48109677 | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# go-to-wheel - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 go-to-wheel 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: [](https://pypi.org/project/go-to-wheel/) 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：Introduction。围绕“Introduction”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：Installation。围绕“Installation”模拟一次用户任务，不展示安装或运行结果。\n3. page-quick-start：Quick Start Guide。围绕“Quick Start Guide”模拟一次用户任务，不展示安装或运行结果。\n4. page-cli-options：CLI Options Reference。围绕“CLI Options Reference”模拟一次用户任务，不展示安装或运行结果。\n5. page-examples：Usage Examples。围绕“Usage Examples”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“Introduction”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“Installation”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-quick-start\n输入：用户提供的“Quick Start Guide”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-cli-options\n输入：用户提供的“CLI Options Reference”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-examples\n输入：用户提供的“Usage Examples”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“Introduction”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“Installation”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-quick-start：Step 3 必须围绕“Quick Start Guide”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-cli-options：Step 4 必须围绕“CLI Options Reference”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-examples：Step 5 必须围绕“Usage Examples”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://news.ycombinator.com/item?id=48109677\n- https://github.com/simonw/go-to-wheel#readme\n- README.md\n- spec.md\n- pyproject.toml\n- go_to_wheel/__init__.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 go-to-wheel 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：simonw/go-to-wheel\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install go-to-wheel\n```\n\n来源：https://github.com/simonw/go-to-wheel#readme\n\n## 来源\n\n- hn: https://news.ycombinator.com/item?id=48109677\n- docs: https://github.com/simonw/go-to-wheel#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_b7241181c1994477a8167e0e79e3c2a9"
}