NetBSD Developer Documentation: Adding a new port

The following is intended to be a brief list of items that need to be addressed when adding a new port to the NetBSD tree.

Note the new files should be added with cvs add, not cvs import. Importing is for vendor branches, whereas this code is to be integrated as part of NetBSD, and it's also one more needless tag on each file.

Steps for those just starting out

Items that need to be addressed when adding new port

Important tasks once port is imported into the tree

Other related documents

Steps for those just starting out

Things to try at first

  • Try to find as much documentation as you can. Then try some more. Contact the original vendor, and the vendors of major chips used on the boards. Frequently the source for another vendor's OS (even Linux) can prove a useful resource.
  • Copy the sys tree of a similar port.
  • Setup a cross compiler on another NetBSD machine (something with the same CPU would be ideal, but usually an i386 should be fine).
  • Work out how to generate a binary understood by the boot loader. If there is an existing OS on the target, you might be better off taking advantage of it.
  • Try to build a standalone binary which can output to the console, possibly using PROM drivers, or serial console. No need for VM.
  • Build a kernel with memorydisk root.
  • Add disk and network device support. It may be easier to start with external cards for which MI drivers already exist in the NetBSD tree.

Items that need to be addressed when adding new port

CVS setting

Setting up cvs checkout-update-commit environment.

  • Read NetBSD CVS HOWTO and setup CVS commitable environment.
  • cvs checkout {htdocs,htutils,doc}

htdocs changes

Edit and commit information about your new port on www.NetBSD.org. Obviously, you need to create a port page under htdocs/ports/${MACHINE}/ first. Please do not commit modifications to other htdocs files until this page has been created and is committed. The DocBook/XML format is useful for FAQ-style information (see the htdocs documentation).

  • Create htdocs/ports/${MACHINE}/, add link from htdocs/index.html, htdocs/ports/index.xml. You may want to include a copy of this checklist and mark off items as completed. If you wish to include a logo or a graphic for your port page, please make sure that you get permission from the copyright owner (if applicable) before adding a new image to the htdocs tree.
  • Add details to htdocs/changes/index.xml and regenerate the HTML file with make(1). See htdocs documentation for details.
  • Add to tables in
    • htdocs/about/query-pr.xml and regenerate the HTML file with make(1)
    • htutils/cgi-src/gnats/netbsd.def
    • htutils/changes/changes2html
    • htutils/changes/code-changes2rss
    • htutils/changes/cvschanges2html
  • Add to htdocs/developers/features/table and regenerate.
  • Add your entry to htdocs/people/port-maintainers.xml.

The list of modified files should be committed in one go. Please contact if you have any questions and remember to announce the new port on other websites once the new html files are online.

GNATS configration

  • Add new category to src/external/gpl2/send-pr/dist/send-pr/categories
  • Send mail to about creating the new category on the GNATS server.

Mail changes (requires special privileges)

  • Create port-${MACHINE} mailing list. Send a request to over it.
  • Add new port-${MACHINE} list to htdocs/mailinglists/index.xml. Regenerate with make(1).
  • Create port-${MACHINE}-maintainer alias for the portmaster.
  • Add portmaster to the port-masters mailing list.
  • Add port-${MACHINE}-maintainer to bug-managers mailing list. e.g. add port-hpcmips-maintainer to bug-managers.
  • If the port uses a shared MACHINE_ARCH, add port-${MACHINE}-maintainer to the port-${MACHINE_ARCH}-maintainer mailing list, e.g. add port-hpcmips-maintainer to port-mips-maintainer.

Create FTP directory for snapshots of new port

  • Update port machinery in distrib/ to build snapshots and releases. Did you create src/distrib/${MACHINE} ?
  • Make snapshot. See NetBSD Developer Documentation: Release Engineering
  • Make source tarballs. The src/distrib/sets/makesrctars script will help you.
  • Create ftp.NetBSD.org:/pub/NetBSD/arch/${MACHINE}/snapshot/YYYYMMDD/ and put the snapshot there.

Other changes

  • Add an entry to src/doc/CHANGES.
  • Add an entry to src/build.sh.
  • Regenerate src/tools/headerlist by running src/tools/mkheaderlist.sh.
  • Add an entry to src/gnu/usr.bin/groff/tmac/mdoc.local.
  • Add an entry to src/distrib/notes/common/main.
  • Add an entry to src/share/man/man7/hier.7.
  • Add an entry to src/sys/arch/README.
  • Add an entry to src/sys/arch/Makefile.
  • Add an entry to src/usr.bin/calendar/calendars/calendar.netbsd.
  • Create sup(1) set for new port (current and release collection for src/sys/arch/${MACHINE}/, and mirror collection for ftp.NetBSD.org:/pub/NetBSD/arch/${MACHINE}/). Consult other developers.
  • Update tarball-building scripts to build tarball for new ${MACHINE}. Consult other developers.
  • Send email to and note the announcement on the WWW news page.

Important tasks once port is imported into the tree

You mean there's more?

  • Keep adding hardware support.
  • Get sysinst running.
  • Produce formal releases.
  • Write a compat_<original_os>.
  • Ongoing maintenance. Make sure your port continues to build and run as the NetBSD source tree evolves.

Other related documents

Valeriy E. Ushakov's papers

Valeriy a related paper on how to get started on a new port.

Frank van der Linden's papers

Frank van der Linden's paper Porting NetBSD to the AMD x86-64: a case study in OS portability from BSDCon 2002.

Back to  NetBSD Developer Documentation