FreeBSD Ports Collection

What is the Ports Collection?

The Ports Collection is FreeBSD's system for building software from source code. Unlike pkg (binary packages), ports let you:

• Customize compile-time options
• Apply patches
• Use non-default configurations
• Get the latest versions

Installing the Ports Tree

# Using portsnap (traditional method)
portsnap fetch extract
portsnap update  # For subsequent updates

# Using Git (recommended for FreeBSD 14+)
pkg install git
git clone https://git.FreeBSD.org/ports.git /usr/ports

# Update via git
cd /usr/ports && git pull

Ports Structure

/usr/ports/
├── Mk/              # Build framework
├── Templates/       # Port templates
├── Tools/           # Build tools
├── www/             # Category: Web
│   ├── nginx/       # Port: nginx
│   │   ├── Makefile
│   │   ├── distinfo
│   │   ├── pkg-descr
│   │   └── files/
│   └── apache24/
├── databases/       # Category: Databases
├── editors/         # Category: Editors
└── ...

Building a Port

# Navigate to port directory
cd /usr/ports/www/nginx

# Configure options
make config

# Build the port
make

# Install
make install

# Clean build files
make clean

# All in one
make install clean

Configuration Options

# Interactive configuration dialog
make config

# Show current options
make showconfig

# Reset to defaults
make rmconfig

# Set options non-interactively
make OPTIONS_SET="HTTP2 THREADS" OPTIONS_UNSET="DEBUG"

# Save options system-wide
mkdir -p /var/db/ports/www_nginx
make config  # Then save

Searching Ports

# Search by name
cd /usr/ports
make search name=nginx

# Search by keyword
make search key=webserver

# Search with psearch (faster)
pkg install psearch
psearch nginx

# Locate port
whereis nginx
# Output: nginx: /usr/ports/www/nginx

Updating Ports

# Update ports tree
portsnap update
# or
cd /usr/ports && git pull

# Rebuild specific port
cd /usr/ports/www/nginx
make deinstall
make reinstall clean

# Using portupgrade
pkg install portupgrade
portupgrade -a  # Upgrade all
portupgrade nginx

Using poudriere (Port Build System)

# Install poudriere
pkg install poudriere

# Create jail for building
poudriere jail -c -j 14amd64 -v 14.0-RELEASE

# Create ports tree
poudriere ports -c -p default

# Build packages
poudriere bulk -j 14amd64 -p default www/nginx databases/mysql80-server

Useful Make Targets

make config        # Configure options
make fetch         # Download source
make extract       # Extract source
make patch         # Apply patches
make configure     # Run configure
make build         # Compile
make install       # Install
make deinstall     # Uninstall
make reinstall     # Reinstall
make clean         # Clean build files
make distclean     # Clean + remove downloaded files
make package       # Create binary package

Best Practices

1. Use pkg when possible - Binary packages are faster
2. Document custom options - Track why you built from ports
3. Keep ports tree updated - Security fixes
4. Use poudriere for multiple systems - Build once, deploy everywhere
5. Check UPDATING file - Important upgrade notes in /usr/ports/UPDATING