How to Write and Submit a FreeBSD Port on the FreeBSD Operating System

Introduction

FreeBSD is a powerful, open-source Unix-like operating system known for its stability, performance, and extensive port collection. The FreeBSD Ports Collection provides an easy way to install, compile, and manage third-party software. If you’ve developed software or found an application that isn’t yet available in the ports tree, you can contribute by creating and submitting a new port.

This guide provides a step-by-step approach to writing and submitting a FreeBSD port. It covers:

1. Understanding FreeBSD Ports
2. Prerequisites for Creating a Port
3. Writing a FreeBSD Port
4. Testing the Port
5. Submitting the Port for Inclusion

By the end of this article, you’ll have a clear understanding of how to contribute to the FreeBSD ecosystem by adding new software to the ports tree.

1. Understanding FreeBSD Ports

What is a FreeBSD Port?

A FreeBSD port is a set of files that define how to:

• Download the software’s source code
• Apply necessary patches
• Configure, build, and install the software
• Handle dependencies

Ports do not include the actual software; instead, they provide instructions (Makefiles, patches, and scripts) to compile and install applications from source.

Ports vs. Packages

• Ports: Compile software from source, allowing customization of build options.
• Packages: Pre-compiled binaries for quick installation.

When you submit a port, the FreeBSD package builders automatically generate packages from it.

2. Prerequisites for Creating a Port

Before writing a port, ensure you have:

A FreeBSD System

• A working FreeBSD installation (latest stable version recommended).
• Administrative (root) access or sudo privileges.

Required Tools

Install essential tools for port development:

pkg install git subversion portlint pkgconf

Knowledge of the Software

• Understand the software’s build system (e.g., CMake, Autotools, Make).
• Identify its dependencies (libraries, tools).
• Check its license (must be compatible with FreeBSD).

Check if the Port Already Exists

Search the FreshPorts or the ports tree:

cd /usr/ports  
make search name=<software-name>

If the port doesn’t exist, proceed with creating it.

3. Writing a FreeBSD Port

A FreeBSD port consists of several key files:

• Makefile – Defines build instructions.
• pkg-descr – A description of the software.
• pkg-plist – Lists files to be installed.
• distinfo – Contains checksums for downloaded files.
• Patches (if needed).

Step 1: Set Up the Port Directory

Ports are organized in categories (e.g., net, devel, sysutils). Choose an appropriate category:

mkdir -p /usr/ports/category/portname  
cd /usr/ports/category/portname  

Step 2: Create the Makefile

The Makefile is the most critical file. A basic template looks like:

PORTNAME=    softwarename  
PORTVERSION= 1.0.0  
CATEGORIES=  category  
MASTER_SITES=  https://example.com/software/  
EXTRACT_SUFX= .tar.gz  

LICENSE=    ISCL  
LICENSE_FILE=  ${WRKSRC}/LICENSE  

USES=       cmake  

.include <bsd.port.mk>

Key Variables:

• PORTNAME: Name of the software.
• PORTVERSION: Version number.
• CATEGORIES: Relevant category (e.g., net, devel).
• MASTER_SITES: Download URL for the source.
• LICENSE: Software license (e.g., GPLv3, BSD2CLAUSE).
• USES: Build system (e.g., cmake, gnome, python).

Refer to the FreeBSD Porter’s Handbook for advanced options.

Step 3: Write pkg-descr

This file contains a brief description (one line) and a longer explanation:

A short one-line description.  

A longer description explaining what the software does,  
its features, and any relevant details.  

Step 4: Generate distinfo

After defining MASTER_SITES, run:

make makesum

This downloads the source and generates distinfo with checksums.

Step 5: Create pkg-plist

The pkg-plist file lists all files installed by the port. Generate it after building:

make install  
make makeplist > pkg-plist

Edit the file to remove unnecessary entries (e.g., @dir directives).

Step 6: Handle Dependencies

If the software requires libraries, specify them in Makefile:

LIB_DEPENDS=   libssl.so:security/openssl
RUN_DEPENDS=   bash:shells/bash

Step 7: Apply Patches (If Needed)

If the software needs modifications, create patches in files/:

mkdir files  
vim files/patch-fix_build_error  

Update Makefile to apply patches:

PATCHFILES=   patch-fix_build_error  

4. Testing the Port

Before submission, thoroughly test the port:

Build the Port

make  

Install and Verify

make install  
pkg info | grep portname  

Check for Errors

• Run portlint to detect issues:

  portlint  
  

• Test package creation:

  make package  
  

5. Submitting the Port for Inclusion

Once the port works correctly, submit it to the FreeBSD project:

Step 1: Create a Bug Report

• Go to FreeBSD Bugzilla.
• Select “Submit a new Port/Update”.
• Provide:
  • Port name and version.
  • Link to the software’s homepage.
  • A brief description.

Step 2: Upload Your Port

• Use git or svn to share your port files.
• Alternatively, attach a .tar.gz of the port directory.

Step 3: Wait for Review

• A FreeBSD committer will review your submission.
• Address any feedback by updating the port.

Once approved, your port will be committed to the official ports tree!

Conclusion

Creating and submitting a FreeBSD port is a rewarding way to contribute to the open-source community. By following this guide, you’ve learned how to:

1. Set up a port directory.
2. Write a Makefile, pkg-descr, and pkg-plist.
3. Test the port for errors.
4. Submit it for inclusion in the FreeBSD ports tree.

The FreeBSD Porter’s Handbook provides additional details for complex scenarios. Happy porting!

Further Reading

• FreeBSD Porter’s Handbook
• FreeBSD Ports Development Guide
• FreshPorts – Track Port Updates

By contributing ports, you help expand FreeBSD’s software ecosystem, benefiting users worldwide. If you encounter issues, the FreeBSD community is always willing to help!