openbsd-porting

name: openbsd-porting description: 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. license: LICENSE

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