FreeBSD Porter's Handbook

The FreeBSD Documentation Project

Copyright © 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 The FreeBSD Documentation Project

[ Split HTML / Single HTML ]
Table of Contents
1 Introduction
2 Making a New Port Yourself
3 Quick Porting
3.1 Writing the Makefile
3.2 Writing the Description Files
3.2.1 pkg-descr
3.2.2 pkg-plist
3.3 Creating the Checksum File
3.4 Testing the Port
3.5 Checking Your Port with portlint
3.6 Submitting the New Port
4 Slow Porting
4.1 How Things Work
4.2 Getting the Original Sources
4.3 Modifying the Port
4.4 Patching
4.5 Configuring
4.6 Handling User Input
5 Configuring the Makefile
5.1 The Original Source
5.2 Naming
5.2.1 PORTNAME and PORTVERSION
5.2.2 PORTREVISION and PORTEPOCH
5.2.3 PKGNAMEPREFIX and PKGNAMESUFFIX
5.2.4 LATEST_LINK
5.2.5 Package Naming Conventions
5.3 Categorization
5.3.1 CATEGORIES
5.3.2 Current List of Categories
5.3.3 Choosing the Right Category
5.3.4 Proposing a New Category
5.3.5 Proposing Reorganizing All the Categories
5.4 The Distribution Files
5.4.1 DISTVERSION/DISTNAME
5.4.2 MASTER_SITES
5.4.3 EXTRACT_SUFX
5.4.4 DISTFILES
5.4.5 EXTRACT_ONLY
5.4.6 PATCHFILES
5.4.7 Multiple Distribution Files or Patches from Different Sites and Subdirectories (MASTER_SITES:n)
5.4.8 DIST_SUBDIR
5.4.9 ALWAYS_KEEP_DISTFILES
5.5 MAINTAINER
5.6 COMMENT
5.7 PORTSCOUT
5.8 Dependencies
5.8.1 LIB_DEPENDS
5.8.2 RUN_DEPENDS
5.8.3 BUILD_DEPENDS
5.8.4 FETCH_DEPENDS
5.8.5 EXTRACT_DEPENDS
5.8.6 PATCH_DEPENDS
5.8.7 USE_*
5.8.8 Minimal Version of a Dependency
5.8.9 Notes on Dependencies
5.8.10 Circular Dependencies Are Fatal
5.8.11 Problems Caused by Automatic Dependencies
5.8.12 USE_ and WANT_
5.9 MASTERDIR
5.10 Man Pages
5.11 Info Files
5.12 Makefile Options
5.12.1 Knobs
5.12.2 OPTIONS
5.12.3 Feature Auto-Activation
5.13 Specifying the Working Directory
5.13.1 WRKSRC
5.13.2 NO_WRKSUBDIR
5.14 Conflict Handling
5.14.1 CONFLICTS_INSTALL
5.14.2 CONFLICTS_BUILD
5.14.3 CONFLICTS
5.15 Installing Files
5.15.1 INSTALL_* Macros
5.15.2 Stripping Binaries and Shared Libraries
5.15.3 Installing a Whole Tree of Files
5.15.4 Install Additional Documentation
5.15.5 Subdirectories Under PREFIX
6 Special Considerations
6.1 Shared Libraries
6.2 Ports with Distribution Restrictions
6.2.1 NO_PACKAGE
6.2.2 NO_CDROM
6.2.3 NOFETCHFILES
6.2.4 RESTRICTED
6.2.5 RESTRICTED_FILES
6.2.6 Examples
6.3 Building Mechanisms
6.3.1 Building Ports in Parallel
6.3.2 make, gmake, and imake
6.3.3 configure Script
6.3.4 Using scons
6.4 Using GNU Autotools
6.4.1 Introduction
6.4.2 libtool
6.4.3 libltdl
6.4.4 autoconf and autoheader
6.4.5 automake and aclocal
6.5 Using pkg-config
6.6 Using GNU gettext
6.6.1 Basic Usage
6.6.2 Optional Usage
6.6.3 Handling Message Catalog Directories
6.7 Using Perl
6.8 Using X11
6.8.1 X.Org Components
6.8.2 Ports That Require Motif
6.8.3 X11 Fonts
6.8.4 Getting a Fake DISPLAY with Xvfb
6.8.5 Desktop Entries
6.9 Using GNOME
6.10 Using Qt
6.10.1 Ports That Require Qt
6.10.2 Component Selection (Qt 4.x Only)
6.10.3 Additional Considerations
6.11 Using KDE
6.11.1 Variable Definitions (KDE 3.x Only)
6.11.2 KDE 4 Variable Definitions
6.12 Using Java
6.12.1 Variable Definitions
6.12.2 Building with Ant
6.12.3 Best Practices
6.13 Web Applications, Apache and PHP
6.13.1 Apache
6.13.2 Web Applications
6.13.3 PHP
6.13.4 PEAR Modules
6.14 Using Python
6.15 Using Tcl/Tk
6.16 Using Emacs
6.17 Using Ruby
6.18 Using SDL
6.19 Using wxWidgets
6.19.1 Introduction
6.19.2 Version Selection
6.19.3 Component Selection
6.19.4 Unicode
6.19.5 Detecting Installed Versions
6.19.6 Defined Variables
6.19.7 Processing in bsd.port.pre.mk
6.19.8 Additional configure Arguments
6.20 Using Lua
6.20.1 Introduction
6.20.2 Version Selection
6.20.3 Component Selection
6.20.4 Detecting Installed Versions
6.20.5 Defined Variables
6.20.6 Processing in bsd.port.pre.mk
6.21 Using Xfce
6.22 Using Mozilla
6.23 Using Databases
6.24 Starting and Stopping Services (rc Scripts)
6.24.1 Stopping Services at Deinstall
6.24.2 Pre-Commit Checklist
6.25 Adding Users and Groups
6.26 Ports That Rely on Kernel Sources
7 Advanced pkg-plist Practices
7.1 Changing pkg-plist Based on Make Variables
7.2 Empty Directories
7.2.1 Cleaning Up Empty Directories
7.2.2 Creating Empty Directories
7.3 Configuration Files
7.4 Dynamic Versus Static Package List
7.5 Automated Package List Creation
8 The pkg-* Files
8.1 pkg-message
8.2 pkg-install
8.3 pkg-deinstall
8.4 pkg-req
8.5 Changing the Names of pkg-* Files
8.6 Making Use of SUB_FILES and SUB_LIST
9 Testing Your Port
9.1 Running make describe
9.2 Portlint
9.3 Port Tools
9.4 PREFIX and DESTDIR
9.5 Tinderbox
10 Upgrading an Individual Port
10.1 Using SVN to Make Patches
10.2 The Files UPDATING and MOVED
11 Ports Security
11.1 Why Security is So Important
11.2 Fixing Security Vulnerabilities
11.3 Keeping the Community Informed
11.3.1 The VuXML Database
11.3.2 A Short Introduction to VuXML
11.3.3 Testing Your Changes to the VuXML Database
12 Dos and Don'ts
12.1 Introduction
12.2 WRKDIR
12.3 WRKDIRPREFIX
12.4 Differentiating Operating Systems and OS Versions
12.5 __FreeBSD_version Values
12.6 Writing Something After bsd.port.mk
12.7 Use the exec Statement in Wrapper Scripts
12.8 Do Things Rationally
12.9 Respect Both CC and CXX
12.10 Respect CFLAGS
12.11 Threading Libraries
12.12 Feedback
12.13 README.html
12.14 Marking a Port Not Installable with BROKEN, FORBIDDEN, or IGNORE
12.14.1 Variables
12.14.2 Implementation Notes
12.15 Marking a Port for Removal with DEPRECATED or EXPIRATION_DATE
12.16 Avoid Use of the .error Construct
12.17 Usage of sysctl
12.18 Rerolling Distfiles
12.19 Avoiding Linuxisms
12.20 Miscellanea
13 A Sample Makefile
14 Keeping Up
14.1 FreshPorts
14.2 The Web Interface to the Source Repository
14.3 The FreeBSD Ports Mailing List
14.4 The FreeBSD Port Building Cluster on pointyhat.FreeBSD.org
14.5 Portscout: the FreeBSD Ports Distfile Scanner
14.6 The FreeBSD Ports Monitoring System
List of Tables
5-1. Popular Magic MASTER_SITES Macros
5-2. The USE_* Variables
5-3. Common WITH_* and WITHOUT_* Variables
6-1. Variables for Ports Related to gmake
6-2. Variables for Ports That Use configure
6-3. Variables for Ports That Use scons
6-4. Values for USE_PKGCONFIG
6-5. Variables for Ports That Use Perl
6-6. Variables for Ports That Use X
6-7. Variables for Depending on Individual Parts of X11
6-8. Variables for Ports That Use Qt
6-9. Additional Variables for Ports That Use Qt 4.x
6-10. Available Qt 4 Library Components
6-11. Available Qt 4 Tool Components
6-12. Available Qt 4 Plugin Components
6-13. Variables for Ports That Use KDE 3.x
6-14. Available KDE 4 Components
6-15. Variables Which May be Set by Ports That Use Java
6-16. Variables Provided to Ports That Use Java
6-17. Constants Defined for Ports That Use Java
6-18. Variables for Ports That Use Apache
6-19. Useful Variables for Porting Apache Modules
6-20. Variables for Ports That Use PHP
6-21. Most Useful Variables for Ports That Use Python
6-22. The Most Useful Variables for Ports That Use Tcl/Tk
6-23. Useful Variables for Ports That Use Ruby
6-24. Selected Read-Only Variables for Ports That Use Ruby
6-25. Variables to Select wxWidgets Versions
6-26. Available wxWidgets Versions
6-27. wxWidgets Version Specifications
6-28. Variables to Select Preferred wxWidgets Versions
6-29. Available wxWidgets Components
6-30. Available wxWidgets Dependency Types
6-31. Default wxWidgets Dependency Types
6-32. Variables to Select Unicode in wxWidgets Versions
6-33. Variables Defined for Ports That Use wxWidgets
6-34. Legal Values for WX_CONF_ARGS
6-35. Variables to Select Lua Versions
6-36. Available Lua Versions
6-37. Lua Version Specifications
6-38. Variables to Select Preferred Lua Versions
6-39. Available Lua Components
6-40. Available Lua Dependency Types
6-41. Default Lua Dependency Types
6-42. Variables Defined for Ports That Use Lua
6-43. Variables for Ports That Use Mozilla
6-44. Variables for Ports Using Databases
10-1. SVN Update File Prefixes
12-1. __FreeBSD_version Values
List of Examples
5-1. Simplified Use of MASTER_SITES:n with One File Per Site
5-2. Simplified Use of MASTER_SITES:n with More Than One File Per Site
5-3. Detailed Use of MASTER_SITES:n in MASTER_SITE_SUBDIR
5-4. Detailed Use of MASTER_SITES:n with Comma Operator, Multiple Files, Multiple Sites and Multiple Subdirectories
5-5. Detailed Use of MASTER_SITES:n with MASTER_SITE_SOURCEFORGE
5-6. Simplified Use of MASTER_SITES:n with PATCH_SITES
5-7. Use of ALWAYS_KEEP_DISTFILES
5-8. Wrong Declaration of an Optional Dependency
5-9. Correct Declaration of an Optional Dependency
5-10. Simple Use of OPTIONS
5-11. Check for Unset Port OPTIONS
5-12. Practical Use of OPTIONS
5-13. Old-Style Use of OPTIONS
5-14. Wrong Handling of an Option
5-15. Correct Handling of an Option
6-1. Perl Dependency Example
6-2. USE_XORG Example
6-3. Using X11-Related Variables
6-4. Selecting Qt 4 Components
6-5. USE_KDE4 Example
6-6. Example Makefile for PEAR Class
6-7. Selecting wxWidgets Components
6-8. Detecting Installed wxWidgets Versions and Components
6-9. Using wxWidgets Variables in Commands
6-10. Selecting the Lua Version
6-11. Selecting Lua Components
6-12. Detecting Installed Lua Versions and Components
6-13. Telling the Port Where to Find Lua
6-14. Using Lua Variables in Commands
12-1. How to Avoid Using .error
    Next
    Introduction
For questions about the FreeBSD ports system, e-mail <ports@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.