FreeBSD Porter's Handbook

The FreeBSD Documentation Project

Revision: 54728
Copyright
Legal Notice
Last modified on 2020-12-03 22:05:38 by ygy.

Table of Contents
1. Introduction
2. Making a New Port
3. Quick Porting
3.1. Writing the Makefile
3.2. Writing the Description Files
3.3. Creating the Checksum File
3.4. Testing the Port
3.5. Checking the 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.3. Categorization
5.4. The Distribution Files
5.5. MAINTAINER
5.6. COMMENT
5.7. Licenses
5.8. PORTSCOUT
5.9. Dependencies
5.10. Slave Ports and MASTERDIR
5.11. Man Pages
5.12. Info Files
5.13. Makefile Options
5.14. Specifying the Working Directory
5.15. Conflict Handling
5.16. Installing Files
5.17. Use BINARY_ALIAS to Rename Commands Instead of Patching the Build
6. Special Considerations
6.1. Staging
6.2. Bundled Libraries
6.3. Shared Libraries
6.4. Ports with Distribution Restrictions or Legal Concerns
6.5. Building Mechanisms
6.6. Using GNU Autotools
6.7. Using GNU gettext
6.8. Using Perl
6.9. Using X11
6.10. Using GNOME
6.11. GNOME Components
6.12. Using Qt
6.13. Using KDE
6.14. Using LXQt
6.15. Using Java
6.16. Web Applications, Apache and PHP
6.17. Using Python
6.18. Using Tcl/Tk
6.19. Using Ruby
6.20. Using SDL
6.21. Using wxWidgets
6.22. Using Lua
6.23. Using iconv
6.24. Using Xfce
6.25. Using Databases
6.26. Starting and Stopping Services (rc Scripts)
6.27. Adding Users and Groups
6.28. Ports That Rely on Kernel Sources
6.29. Go Libraries
6.30. Haskell Libraries
6.31. Shell Completion Files
7. Flavors
7.1. An Introduction to Flavors
7.2. Using FLAVORS
7.3. USES=php and Flavors
7.4. USES=python and Flavors
7.5. USES=lua and Flavors
8. Advanced pkg-plist Practices
8.1. Changing pkg-plist Based on Make Variables
8.2. Empty Directories
8.3. Configuration Files
8.4. Dynamic Versus Static Package List
8.5. Automated Package List Creation
8.6. Expanding Package List with Keywords
9. pkg-*
9.1. pkg-message
9.2. pkg-install
9.3. pkg-deinstall
9.4. Changing the Names of pkg-*
9.5. Making Use of SUB_FILES and SUB_LIST
10. Testing the Port
10.1. Running make describe
10.2. Portlint
10.3. Port Tools
10.4. PREFIX and DESTDIR
10.5. Poudriere
11. Upgrading a Port
11.1. Using Subversion to Make Patches
11.2. UPDATING and MOVED
12. Security
12.1. Why Security is So Important
12.2. Fixing Security Vulnerabilities
12.3. Keeping the Community Informed
13. Dos and Don'ts
13.1. Introduction
13.2. WRKDIR
13.3. WRKDIRPREFIX
13.4. Differentiating Operating Systems and OS Versions
13.5. Writing Something After bsd.port.mk
13.6. Use the exec Statement in Wrapper Scripts
13.7. Do Things Rationally
13.8. Respect Both CC and CXX
13.9. Respect CFLAGS
13.10. Verbose Build Logs
13.11. Feedback
13.12. README.html
13.13. Marking a Port Not Installable with BROKEN, FORBIDDEN, or IGNORE
13.14. Architectural Considerations
13.15. Marking a Port for Removal with DEPRECATED or EXPIRATION_DATE
13.16. Avoid Use of the .error Construct
13.17. Usage of sysctl
13.18. Rerolling Distfiles
13.19. Use POSIX Standards
13.20. Miscellanea
14. A Sample Makefile
15. Order of Variables in Port Makefiles
15.1. PORTNAME Block
15.2. PATCHFILES Block
15.3. MAINTAINER Block
15.4. LICENSE Block
15.5. Generic BROKEN/IGNORE/DEPRECATED Messages
15.6. The Dependencies Block
15.7. Flavors
15.8. USES and USE_x
15.9. Standard bsd.port.mk Variables
15.10. Options and Helpers
15.11. The Rest of the Variables
15.12. The Targets
16. Keeping Up
16.1. FreshPorts
16.2. The Web Interface to the Source Repository
16.3. The FreeBSD Ports Mailing List
16.4. The FreeBSD Port Building Cluster
16.5. Portscout: the FreeBSD Ports Distfile Scanner
16.6. The FreeBSD Ports Monitoring System
17. Using USES Macros
17.1. An Introduction to USES
17.2. 7z
17.3. ada
17.4. autoreconf
17.5. blaslapack
17.6. bdb
17.7. bison
17.8. cabal
17.9. cargo
17.10. charsetfix
17.11. cmake
17.12. compiler
17.13. cpe
17.14. cran
17.15. desktop-file-utils
17.16. desthack
17.17. display
17.18. dos2unix
17.19. drupal
17.20. eigen
17.21. fakeroot
17.22. fam
17.23. firebird
17.24. fonts
17.25. fortran
17.26. fuse
17.27. gem
17.28. gettext
17.29. gettext-runtime
17.30. gettext-tools
17.31. ghostscript
17.32. gl
17.33. gmake
17.34. gnome
17.35. go
17.36. gperf
17.37. grantlee
17.38. groff
17.39. gssapi
17.40. horde
17.41. iconv
17.42. imake
17.43. kde
17.44. kmod
17.45. lha
17.46. libarchive
17.47. libedit
17.48. libtool
17.49. linux
17.50. localbase
17.51. lua
17.52. lxqt
17.53. makeinfo
17.54. makeself
17.55. mate
17.56. meson
17.57. metaport
17.58. mysql
17.59. mono
17.60. motif
17.61. ncurses
17.62. ninja
17.63. objc
17.64. openal
17.65. pathfix
17.66. pear
17.67. perl5
17.68. pgsql
17.69. php
17.70. pkgconfig
17.71. pure
17.72. pyqt
17.73. python
17.74. qmail
17.75. qmake
17.76. qt
17.77. qt-dist
17.78. readline
17.79. samba
17.80. scons
17.81. shared-mime-info
17.82. shebangfix
17.83. sqlite
17.84. ssl
17.85. tar
17.86. tcl
17.87. terminfo
17.88. tk
17.89. uidfix
17.90. uniquefiles
17.91. varnish
17.92. webplugin
17.93. xfce
17.94. xorg
17.95. xorg-cat
17.96. zip
18. __FreeBSD_version Values
18.1. FreeBSD 13 Versions
18.2. FreeBSD 12 Versions
18.3. FreeBSD 11 Versions
18.4. FreeBSD 10 Versions
18.5. FreeBSD 9 Versions
18.6. FreeBSD 8 Versions
18.7. FreeBSD 7 Versions
18.8. FreeBSD 6 Versions
18.9. FreeBSD 5 Versions
18.10. FreeBSD 4 Versions
18.11. FreeBSD 3 Versions
18.12. FreeBSD 2.2 Versions
18.13. FreeBSD 2 Before 2.2-RELEASE Versions
List of Tables
5.1. Examples of DISTVERSION and the Derived PORTVERSION
5.2. Package Naming Examples
5.3. Shortcuts for MASTER_SITE_* Macros
5.4. Magic MASTER_SITES Macros
5.5. USE_GITHUB Description
5.6. USE_GITLAB Description
5.7. Predefined License List
5.8. USE_*
6.1. Variables for Ports That Use configure
6.2. Variables for Ports That Use cmake
6.3. Variables the Users Can Define for cmake Builds
6.4. Variables the Users Can Define for cargo Builds
6.5. Variables for Ports That Use meson
6.6. Read-Only Variables for Ports That Use Perl
6.7. Variables for Ports That Use X
6.8. GNOME Components
6.9. GNOME Macro Components
6.10. GNOME Legacy Components
6.11. Deprecated Components: Do Not Use
6.12. Variables Provided to Ports That Use Qt
6.13. Available Qt Library Components
6.14. Available Qt Tool Components
6.15. Available Qt Plugin Components
6.16. Possible Arguments for USES= qmake
6.17. Variables for Ports That Use qmake
6.18. Available KDE Components
6.19. Available LXQt Components
6.20. Variables Which May be Set by Ports That Use Java
6.21. Variables Provided to Ports That Use Java
6.22. Constants Defined for Ports That Use Java
6.23. Variables for Ports That Use Apache
6.24. Useful Variables for Porting Apache Modules
6.25. Most Useful Variables for Ports That Use Python
6.26. Python Module Dependency Helpers
6.27. The Most Useful Read-Only Variables for Ports That Use Tcl/Tk
6.28. Useful Variables for Ports That Use Ruby
6.29. Selected Read-Only Variables for Ports That Use Ruby
6.30. Variables to Select wxWidgets Versions
6.31. Available wxWidgets Versions
6.32. wxWidgets Version Specifications
6.33. Variables to Select Preferred wxWidgets Versions
6.34. Available wxWidgets Components
6.35. Available wxWidgets Dependency Types
6.36. Default wxWidgets Dependency Types
6.37. Variables Defined for Ports That Use wxWidgets
6.38. Legal Values for WX_CONF_ARGS
6.39. Variables Defined for Ports That Use Lua
6.40. Variables Defined for Lua Module Ports
6.41. Database USES Macros
6.42. Shell completion file paths
11.1. Subversion Update File Prefixes
17.1. Available X.Org Components
18.1. FreeBSD 13 __FreeBSD_version Values
18.2. FreeBSD 12 __FreeBSD_version Values
18.3. FreeBSD 11 __FreeBSD_version Values
18.4. FreeBSD 10 __FreeBSD_version Values
18.5. FreeBSD 9 __FreeBSD_version Values
18.6. FreeBSD 8 __FreeBSD_version Values
18.7. FreeBSD 7 __FreeBSD_version Values
18.8. FreeBSD 6 __FreeBSD_version Values
18.9. FreeBSD 5 __FreeBSD_version Values
18.10. FreeBSD 4 __FreeBSD_version Values
18.11. FreeBSD 3 __FreeBSD_version Values
18.12. FreeBSD 2.2 __FreeBSD_version Values
18.13. FreeBSD 2 Before 2.2-RELEASE __FreeBSD_version Values
List of Examples
3.1. Creating a .diff for a New Port
3.2. Creating a .shar for a New Port
4.1. Applying a Patch for a Specific FreeBSD Version
4.2. Optionally Applying a Patch
4.3. Using EXTRA_PATCHES With a Directory
5.1. Using pkg-version(8) to Compare Versions.
5.2. Using DISTVERSION
5.3. Using DISTVERSION When the Version Starts with a Letter or a Prefix
5.4. Using DISTVERSION When the Version Contains Letters Meaning alpha, beta, or pre-release
5.5. Not Using DISTVERSION When the Version Contains Letters Meaning "Patch Level"
5.6. Deriving PORTVERSION Manually
5.7. Derive DISTNAME from PORTVERSION
5.8. Exotic Case 1
5.9. Exotic Case 2
5.10. Simple Use of USE_GITHUB
5.11. More Complete Use of USE_GITHUB
5.12. Use of USE_GITHUB with DISTVERSIONPREFIX
5.13. Using USE_GITHUB When Upstream Does Not Use Versions
5.14. Using USE_GITHUB to Access a Commit Between Two Versions
5.15. Use of USE_GITHUB with Multiple Distribution Files
5.16. Use of USE_GITHUB with Multiple Distribution Files Using GH_TUPLE
5.17. How to Use USE_GITHUB with Git Submodules?
5.18. Simple Use of USE_GITLAB
5.19. More Complete Use of USE_GITLAB
5.20. Use of USE_GITLAB with Multiple Distribution Files
5.21. Use of USE_GITLAB with Multiple Distribution Files Using GL_TUPLE
5.22. Simplified Use of MASTER_SITES:n with One File Per Site
5.23. Simplified Use of MASTER_SITES:n with More Than One File Per Site
5.24. Detailed Use of MASTER_SITES:n in MASTER_SITE_SUBDIR
5.25. Detailed Use of MASTER_SITES:n with Comma Operator, Multiple Files, Multiple Sites and Multiple Subdirectories
5.26. Detailed Use of MASTER_SITES:n with SourceForge (SF)
5.27. Simplified Use of MASTER_SITES:n with PATCH_SITES
5.28. Simplest Usage, Predefined Licenses
5.29. Nonstandard License
5.30. Standard and Nonstandard Licenses
5.31. LICENSE_NAME
5.32. LICENSE_FILE
5.33. LICENSE_TEXT
5.34. LICENSE_DISTFILES
5.35. Dual Licenses
5.36. Multiple Licenses
5.37. Wrong Declaration of an Optional Dependency
5.38. Correct Declaration of an Optional Dependency
5.39. Simple Use of OPTIONS
5.40. Check for Unset Port OPTIONS
5.41. Practical Use of OPTIONS
5.42. Wrong Handling of an Option
5.43. Correct Handling of an Option
5.44. Simple Use of OPT_IMPLIES
5.45. Simple Use of OPT_PREVENTS
5.46. Basic usage of CONFLICTS*
5.47. Using CONFLICTS* With Globs.
5.48. Using BINARY_ALIAS to Make gsed Available as sed
5.49. Using BINARY_ALIAS to Provide Aliases for Hardcoded python3 Commands
6.1. Create Relative Symbolic Links Automatically
6.2. USES= cmake Example
6.3. CMAKE_ON and CMAKE_OFF
6.4. Creating a Port for a Simple Rust Application
6.5. Enabling Additional Application Features
6.6. Encoding Application Features As Port Options
6.7. Listing Crate Licenses
6.8. USES=meson Example
6.9. Creating a Port for a Go Modules Based Application
6.10. Setting Output Binary Name or Installation Path
6.11. Creating a Port for a Hackage-hosted Haskell Application
6.12. Perl Dependency Example
6.13. A Port Which Only Requires Perl to Build
6.14. A Port Which Also Requires Perl to Patch
6.15. A Perl Module Which Needs ExtUtils::MakeMaker to Build
6.16. A Perl Module Which Needs Module::Build to Build
6.17. USE_XORG Example
6.18. Using X11-Related Variables
6.19. Selecting Qt 5 Components
6.20. USES= qmake Example
6.21. USE_KDE Example
6.22. USE_LXQT Example
6.23. Example Makefile for PEAR Class
6.24. Example Makefile for Horde Module
6.25. Makefile for a Simple Python Module
6.26. Selecting wxWidgets Components
6.27. Detecting Installed wxWidgets Versions and Components
6.28. Using wxWidgets Variables in Commands
6.29. Makefile for an application using Lua
6.30. Makefile for a simple Lua module
6.31. Simple iconv Usage
6.32. iconv Usage with configure
6.33. Fixing Hardcoded -liconv
6.34. Checking for Native iconv Availability
6.35. USES=xfce Example
6.36. Using Xfce's Own GTK2 Widgets
6.37. Using Berkeley DB 6
6.38. Using MySQL
6.39. Using PostgreSQL
6.40. Using SQLite 3
7.1. Basic Flavors Usage
7.2. Another Basic Flavors Usage
7.3. More Complex Flavors Usage
7.4. Flavor Specific PKGNAME
7.5. Simple USES=php Extension
7.6. Flavorizing a PHP Application
7.7. Simple USES=python
7.8. USES=python with Version Requirements
7.9. For a Port Not Using distutils
8.1. Using PLIST_SUB with Regular Expressions
8.2. Example of a @dirrmtryecho Keyword
8.3. Real Life Example, How @sample is Implemented
9.1. UCL Short Strings
9.2. UCL Multiline Strings
9.3. Display a Message on Install/Deinstall
9.4. Display a Message on Upgrade
10.1. Using make.conf to Change Default Perl
13.1. How to Avoid Using .error
15.1. Options Variables Order Example
17.1. Using Multiple Values
17.2. Adding an Argument
17.3. Adding Multiple Arguments
17.4. Mixing it All Together
17.5. Typical Use
17.6. Building Qt 5 Components
17.7. Building Qt 5 Components with Different Names
17.8. Adding Another Interpreter to USES=shebangfix
17.9. Specifying all the Paths When Adding an Interpreter to USES=shebangfix
17.10. Adding a Strange Location for an Interpreter
17.11. USES=shebangfix with SHEBANG_REGEX
17.12. USES=shebangfix with SHEBANG_GLOB
17.13. USES=shebangfix with SHEBANG_FILES

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.