# Openbsd Porting

> OpenBSD ports workflow grounded in OpenBSD docs and man pages. Use when working in /usr/ports or a local ports tree, building packages, or submitting new ports.

- Skill: `decisym/openbsd-porting` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add decisym/openbsd-porting`
- Raw SKILL.md: https://api.skillmd.com/api/skills/decisym/openbsd-porting/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- License: LICENSE
- Author: DeciSym (https://skillmd.com/u/decisym)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/decisym/openbsd-porting

---


# Openbsd Porting

## Overview

Create, test, and prepare OpenBSD ports in a local ports tree,
including Rust ports that need vendoring and patching. Use this skill
for new ports, updates, or preparing review submissions to
ports@openbsd.org. Prefer authoritative sources: OpenBSD Porting Guide
and OpenBSD man pages.  Always follow the Porting Checklist in the
OpenBSD Porting Guide: https://www.openbsd.org/faq/ports/guide.html

## Workflow

1. **Check the environment**

Confirm ports tree and build directories. Prefer a local ports tree
and set: `PORTSDIR_PATH`, `WRKOBJDIR`, `DISTDIR`,
`PACKAGE_REPOSITORY`, `PLIST_REPOSITORY`, `BULK_COOKIES_DIR`.

2. **Prepare the port skeleton**

Create `Makefile`, `distinfo`, `pkg/DESCR`, `pkg/PLIST`, and
`crates.inc` (for Rust).  Avoid `$OpenBSD$` tags in `pkg/PLIST`.
Run `make update-plist` early when packaging large CLI suites to
surface public `bin/` name collisions before finalizing wrappers or
`CONFLICTS`. When only a few command names collide, prefer renamed
OpenBSD wrapper names over package-wide `CONFLICTS`.

3. **Pin dependencies**

Do not use branch-based git deps. Pin `rev` in Cargo.toml and, for
ports, use `DIST_TUPLE` and a patch to replace git deps with local
paths.

4. **Generate checksums**

Run `make makesum` after the source commit is pushed upstream so
distfiles exist.

5. **Build and test**

Run `make test` and fix upstream issues instead of disabling tests
when possible. For a full rebuild verification, run `make clean=all`
and `make package` as separate invocations; the ports framework
rejects mixing `clean=all` with `package`.

6. **Run portcheck**

Use `/usr/ports/infrastructure/bin/portcheck -p /path/to/ports` to
catch structure issues (missing `crates.inc` include, PLIST tags,
etc.).

7. **Prepare for submission**

Bundle the port directory as a tarball for ports@openbsd.org review.
See references for email expectations.

## Rust Ports Notes

- `crates.inc` must be included in `Makefile` with a non-indented
  line: `.include "crates.inc"`.
- `PKGNAME` must not be a stem-only name. Include a version component.
- If a distfile 404s, ensure the commit or tag is pushed upstream.

## Examples

1. **New port**

User: "Create a new port for foo 1.2.3."

Assistant: Follow the workflow steps, run `make makesum`, build/test,
and run `portcheck`, then prepare the tarball for ports@openbsd.org
review.

2. **Update existing port**

User: "Update the port to 2.0 and fix build issues."

Assistant: Update `Makefile`, regenerate `distinfo`, run tests, and
validate with `portcheck`.

## Edge Cases

- Distfile fetch fails (404): confirm upstream tag/commit is public
  before `make makesum`.
- Tests fail: prefer upstream fixes or targeted patches; avoid
  disabling tests unless unavoidable.
- Git dependencies: replace branch-based deps with pinned `rev` and
  `DIST_TUPLE` plus patches.
- Files processed by `SUBST_PROGRAM`: avoid shell variables named
  `${PREFIX}` for runtime path discovery, because `SUBST_VARS`
  rewrites `${PREFIX}` to the fake install prefix during packaging.
  Use a differently named runtime variable instead.

## References

- OpenBSD Porting Guide: https://www.openbsd.org/faq/ports/guide.html
- `ports(7)` overview
- `bsd.port.mk(5)` variables/targets
- `portcheck(8)` for structure checks
- `pkg_create(1)` and `pkg_add(1)` packaging/install