Skip to content

Commit 2abd4a5

Browse files
SupananWCSupananWC
committed
docs: update copilot instructions (concise merged version)
Signed-off-by: SupananWC <[email protected]>
1 parent 0b7d982 commit 2abd4a5

File tree

2 files changed

+177
-0
lines changed

2 files changed

+177
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
<!-- GitHub Copilot / AI agent instructions for wireguard-tools -->
2+
3+
# Purpose
4+
5+
Concise, action-first guidance for AI coding agents to be productive in
6+
`wireguard-tools`. Focus: where to change code, how to build/test, and
7+
project conventions that differ from typical C projects.
8+
9+
# Big picture
10+
11+
- Repo provides userspace tooling for WireGuard: the `wg(8)` CLI and
12+
`wg-quick(8)` helper scripts. Primary code: `src/`. Platform specifics live
13+
under `uapi/` (kernel headers) and `wincompat/` (Windows portability).
14+
- Major areas: `src/` (C CLI tools), `wg-quick/` (shell helpers), `uapi/`,
15+
`completion/`, `systemd/`, `man/`, and `contrib/` + `external-tests/`.
16+
17+
# Quick start (commands you'll use most)
18+
19+
- Build: `cd src && make`
20+
- Verbose build/debug: `cd src && make V=1 DEBUG=yes`
21+
- Install for packaging tests: `make install PREFIX=/usr DESTDIR=<dest> WITH_WGQUICK=yes WITH_BASHCOMPLETION=yes`
22+
- Static analysis: `cd src && make check` (runs `scan-build` if available)
23+
- Cross-build for Windows: set `PLATFORM=windows` (Makefile will use `wincompat/`).
24+
25+
# Code change conventions (important)
26+
27+
- Adding a C source: place under `src/` — the `src/Makefile` builds `*.c`
28+
by default. Keep flags consistent with `CFLAGS` in `src/Makefile`.
29+
- Platform-specific headers go in `uapi/<platform>/` and are added with
30+
`-isystem uapi/$(PLATFORM)`; do not diverge from kernel WireGuard headers
31+
without coordinating upstream kernel changes.
32+
- When adding runtime files (scripts, manpages, completion, systemd units),
33+
update the `install` target in `src/Makefile` so packaging includes them.
34+
- Prefer existing helpers (`ipc-*.h`, `netlink.h`) for IPC and netlink logic.
35+
36+
# Files to read first (high value)
37+
38+
- `src/Makefile` — build, platform detection, install flags (`WITH_WGQUICK`,
39+
`WITH_BASHCOMPLETION`, `WITH_SYSTEMDUNITS`).
40+
- `src/wg.c`, `src/setconf.c`, `src/show.c` — core CLI behavior and parsing.
41+
- `wg-quick/` scripts — show how configs are consumed and expected runtime
42+
behavior for `wg-quick`.
43+
- `uapi/` — kernel/user API headers (keeps user tooling in sync with kernel).
44+
45+
# Testing / validation checklist before PR
46+
47+
- Run `cd src && make V=1` to reproduce compile issues.
48+
- Run `cd src && make check` if changing parsing, memory-handling, or IPC.
49+
- If adding files that affect packaging, run `make install DESTDIR=<tmp>` and
50+
verify installed layout.
51+
52+
# Notes on portability & packaging
53+
54+
- Minimal dependencies: project targets portability and a plain libc.
55+
- Keep changes small and portable. Avoid introducing new heavy deps.
56+
57+
# PR tips for reviewers
58+
59+
- Include the minimal build and install commands you used to verify the
60+
change. Show `make V=1` output if build flags or toolchain changes were
61+
required.
62+
- If you changed `uapi/`, state why it must differ from upstream kernel
63+
headers and include references.
64+
65+
# If you're stuck
66+
67+
- Read `README.md` and `src/Makefile` first. If build errors persist, paste
68+
`make V=1` output and relevant `gcc/clang` errors into the PR description.
69+
70+
---
71+
If you'd like, I can (a) shorten or expand any section, (b) add a short
72+
walkthrough for adding a CLI flag in `wg.c`, or (c) include a sample PR
73+
checklist. Which would you prefer?

‎.github/copilot-instructions.original.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
<!-- GitHub Copilot / AI agent instructions for wireguard-tools -->
2+
3+
# Purpose
4+
5+
Short, actionable guidance for AI coding agents to be immediately productive in
6+
this repository. Focus on how the project is structured, build/test/debug
7+
workflows, and concrete file examples you should read before changing code.
8+
9+
# Big picture
10+
11+
- **What this repo is**: userspace tooling for WireGuard: the `wg(8)` CLI and
12+
`wg-quick(8)` helper scripts. Primary code lives in `src/` and platform
13+
specifics under `uapi/` and `wincompat/`.
14+
- **Major components**:
15+
- `src/` — main C sources (`wg.c`, `setconf.c`, `show.c`, etc.) and `src/Makefile`.
16+
- `wg-quick/` — platform-specific shell scripts (bash) used by install.
17+
- `uapi/` — platform-specific kernel/user API headers included at build time.
18+
- `contrib/` and `external-tests/` — sample integrations and language bindings.
19+
- `wincompat/` — compatibility layer and resources for Windows builds.
20+
21+
# What to read first (examples)
22+
23+
- `README.md` — project overview and canonical build/install commands.
24+
- `src/Makefile` — most important: how compilation, platform detection, and
25+
installation variables work (`PREFIX`, `WITH_WGQUICK`, `WITH_BASHCOMPLETION`).
26+
- `src/wg.c`, `src/setconf.c`, `src/show.c` — core CLI behavior and parsing.
27+
- `wg-quick/` — how the quick helper expects configuration files.
28+
- `uapi/linux/` — shows kernel-compatible headers used when compiling.
29+
30+
# Build, test and debug (concrete commands)
31+
32+
- Build the tools (recommended):
33+
34+
`cd src && make`
35+
36+
- Install (honors packaging env vars):
37+
38+
`make install PREFIX=/usr DESTDIR=... WITH_WGQUICK=yes WITH_BASHCOMPLETION=yes`
39+
40+
- Useful Makefile knobs:
41+
- `V=1` — disable pretty short messages and print full compiler/linker commands.
42+
- `DEBUG=yes` — compile with `-g` for debugging symbols.
43+
- `PLATFORM=$(uname -s | tr '[:upper:]' '[:lower:]')` is auto-detected.
44+
45+
- Static analysis:
46+
47+
`cd src && make check` # runs `scan-build` if available
48+
49+
- Windows cross-build: `wincompat/` files are used when `PLATFORM=windows`.
50+
The Makefile sets `CC` for mingw (`x86_64-w64-mingw32-clang`) when building
51+
for Windows; inspect `wincompat/` for resource and manifest handling.
52+
53+
# Project-specific conventions & patterns
54+
55+
- Minimal dependencies: the top-level `README.md` states "no dependencies other
56+
than a good C compiler and a sane libc." Expect simple, portable C patterns.
57+
- Platform headers: `src/Makefile` adds `-isystem uapi/$(PLATFORM)` when that
58+
directory exists. Prefer adding platform-specific headers under `uapi/`.
59+
- Packaging variables and conditional installs are controlled in `src/Makefile`.
60+
When adding files that should be packaged, update `install` target there.
61+
- Shell helpers: `wg-quick` is intentionally a small, opinionated bash script;
62+
changes to interface/flags must remain compatible with it.
63+
64+
# Integration points & external interfaces
65+
66+
- Kernel/user API: code relies on headers in `uapi/` to match kernel wireguard
67+
definitions — don't diverge without coordinating kernel changes.
68+
- System integration: systemd unit templates are in `systemd/`; `install`
69+
target will optionally install them if `WITH_SYSTEMDUNITS` is enabled.
70+
- Completion scripts are under `completion/` and are installed when
71+
`WITH_BASHCOMPLETION=yes`.
72+
- `contrib/embeddable-wg-library/` contains an example of embedding wireguard
73+
logic into other languages; use it as a reference for integrations.
74+
75+
# Testing & external test harnesses
76+
77+
- Look at `external-tests/` for example consumers in Go, Rust, Python and
78+
Haskell. These show how others interact with the CLI or wireguard APIs.
79+
- Fuzzing harness is in `fuzz/` with its own `Makefile` — follow that
80+
directory's README before changing the fuzz targets.
81+
82+
# Helpful patterns and examples for edits
83+
84+
- When adding a new source file to `src/`, add it to the wildcard `*.c` pattern
85+
in `src/Makefile` (it already builds all `*.c`). Keep compilation flags
86+
consistent with the existing `CFLAGS` defined there.
87+
- To preserve portable behavior, prefer using existing helpers in `ipc-*.h`
88+
and `netlink.h` rather than adding custom platform IPC code.
89+
90+
# What an AI agent should do when making a change
91+
92+
1. Read `src/Makefile` and the relevant `uapi/<platform>/` headers.
93+
2. Run `cd src && make V=1` locally to verify build commands and locate
94+
compile-time failures.
95+
3. Update `install` target only if adding runtime files (scripts, manpages,
96+
completions, systemd units) and test installation locally using `DESTDIR`.
97+
4. Run `make check` if the change touches memory/undefined behavior sensitive
98+
code and static analysis is available.
99+
100+
# Questions / feedback
101+
102+
If any of these sections are unclear or you'd like more examples (e.g. a
103+
short walkthrough of adding a new CLI flag in `wg.c`), tell me which area to
104+
expand and I'll update this file.

0 commit comments

Comments
 (0)