FreeBSD Porter’s Handbook Owner's manual

FreeBSD Porter's Handbook

The FreeBSD Documentation Project

FreeBSD Porter's Handbook

by

Revision: 54728

2020-12-03 19:05:38 by ygy.

2017, 2018, 2019, 2020 The FreeBSD Documentation Project

Copyright

Redistribution and use in source (XML DocBook) and 'compiled' forms (XML, HTML, PDF, PostScript, RTF and

so forth) with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code (XML DocBook) must retain the above copyright notice, this list of condi-

tions and the following disclaimer as the rst lines of this le unmodified.

2. Redistributions in compiled form (transformed to other DTDs, converted to PDF, PostScript, RTF and other

formats) must reproduce the above copyright notice, this list of conditions and the following disclaimer

in the documentation and/or other materials provided with the distribution.

Important

THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT

"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED

TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICU-

LAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FREEBSD DOCUMENTATION

PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,

OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT

OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS

INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER

IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)

ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED

OF THE POSSIBILITY OF SUCH DAMAGE.

FreeBSD is a registered trademark of the FreeBSD Foundation.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Sun, Sun Microsystems, Java, Java Virtual Machine, JDK, JRE, JSP, JVM, Netra, OpenJDK, Solaris, StarOffice,

SunOS and VirtualBox are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States

and other countries.

Many of the designations used by manufacturers and sellers to distinguish their products are claimed as

trademarks. Where those designations appear in this document, and the FreeBSD Project was aware of the

trademark claim, the designations have been followed by the “™” or the “®” symbol.

ii

Table of Contents

1. Introduction ........................................................................................................................... 1

2. Making a New Port .................................................................................................................. 3

3. Quick Porting .......................................................................................................................... 5

3.1. Writing the Makefile .................................................................................................. 5

3.2. Writing the Description Files ............................................................................................ 6

3.3. Creating the Checksum File .............................................................................................. 8

3.4. Testing the Port ............................................................................................................ 8

3.5. Checking the Port with portlint ..................................................................................... 8

3.6. Submitting the New Port ................................................................................................. 9

4. Slow Porting .......................................................................................................................... 11

4.1. How Things Work ......................................................................................................... 11

4.2. Getting the Original Sources ........................................................................................... 12

4.3. Modifying the Port ....................................................................................................... 12

4.4. Patching ..................................................................................................................... 13

4.5. Configuring ................................................................................................................. 16

4.6. Handling User Input ..................................................................................................... 16

5. Configuring the Makefile .......................................................................................................... 17

5.1. The Original Source ...................................................................................................... 17

5.2. Naming ...................................................................................................................... 17

5.3. Categorization ............................................................................................................. 25

5.4. The Distribution Files .................................................................................................... 31

5.5. MAINTAINER ................................................................................................................. 53

5.6. COMMENT ...................................................................................................................... 54

5.7. Licenses ..................................................................................................................... 54

5.8. PORTSCOUT ................................................................................................................... 63

5.9. Dependencies .............................................................................................................. 63

5.10. Slave Ports and MASTERDIR ............................................................................................ 69

5.11. Man Pages ................................................................................................................. 69

5.12. Info Files ................................................................................................................... 69

5.13. Makefile Options ......................................................................................................... 70

5.14. Specifying the Working Directory ................................................................................... 86

5.15. Conflict Handling ........................................................................................................ 87

5.16. Installing Files ............................................................................................................ 88

5.17. Use BINARY_ALIAS to Rename Commands Instead of Patching the Build ................................... 91

6. Special Considerations ............................................................................................................. 93

6.1. Staging ...................................................................................................................... 93

6.2. Bundled Libraries ......................................................................................................... 94

6.3. Shared Libraries ........................................................................................................... 95

6.4. Ports with Distribution Restrictions or Legal Concerns .......................................................... 96

6.5. Building Mechanisms .................................................................................................... 97

6.6. Using GNU Autotools ................................................................................................... 108

6.7. Using GNU gettext ..................................................................................................... 108

6.8. Using Perl ................................................................................................................. 109

6.9. Using X11 ................................................................................................................. 112

6.10. Using GNOME ........................................................................................................... 113

6.11. GNOME Components .................................................................................................. 115

6.12. Using Qt .................................................................................................................. 119

6.13. Using KDE ................................................................................................................ 123

6.14. Using LXQt .............................................................................................................. 129

6.15. Using Java ............................................................................................................... 129

6.16. Web Applications, Apache and PHP ............................................................................... 132

6.17. Using Python ........................................................................................................... 135

6.18. Using Tcl/Tk ............................................................................................................ 137

6.19. Using Ruby .............................................................................................................. 138

6.20. Using SDL ................................................................................................................ 138

6.21. Using wxWidgets ....................................................................................................... 139

Table of Contents

6.22. Using Lua ................................................................................................................ 143

6.23. Using iconv ............................................................................................................. 146

6.24. Using Xfce ............................................................................................................... 148

6.25. Using Databases ........................................................................................................ 149

6.26. Starting and Stopping Services (rc Scripts) ..................................................................... 150

6.27. Adding Users and Groups ............................................................................................ 152

6.28. Ports That Rely on Kernel Sources ................................................................................ 152

6.29. Go Libraries ............................................................................................................. 153

6.30. Haskell Libraries ....................................................................................................... 153

6.31. Shell Completion Files ................................................................................................ 153

7. Flavors ............................................................................................................................... 155

7.1. An Introduction to Flavors ............................................................................................ 155

7.2. Using FLAVORS .......................................................................................................... 155

7.3. USES=php and Flavors .................................................................................................. 158

7.4. USES=python and Flavors ............................................................................................. 159

7.5. USES=lua and Flavors .................................................................................................. 160

8. Advanced pkg-plist Practices ............................................................................................. 161

8.1. Changing pkg-plist Based on Make Variables ............................................................... 161

8.2. Empty Directories ....................................................................................................... 162

8.3. Configuration Files ...................................................................................................... 162

8.4. Dynamic Versus Static Package List ................................................................................ 163

8.5. Automated Package List Creation ................................................................................... 163

8.6. Expanding Package List with Keywords ............................................................................ 164

9. pkg-* ............................................................................................................................... 171

9.1. pkg-message .......................................................................................................... 171

9.2. pkg-install .......................................................................................................... 173

9.3. pkg-deinstall ...................................................................................................... 174

9.4. Changing the Names of pkg-* ...................................................................................... 174

9.5. Making Use of SUB_FILES and SUB_LIST ......................................................................... 174

10. Testing the Port .................................................................................................................. 177

10.1. Running make describe ............................................................................................. 177

10.2. Portlint ................................................................................................................... 177

10.3. Port Tools ................................................................................................................ 177

10.4. PREFIX and DESTDIR ................................................................................................... 177

10.5. Poudriere ................................................................................................................ 178

11. Upgrading a Port ................................................................................................................. 187

11.1. Using Subversion to Make Patches ................................................................................ 188

11.2. UPDATING and MOVED .............................................................................................. 189

12. Security ............................................................................................................................. 191

12.1. Why Security is So Important ...................................................................................... 191

12.2. Fixing Security Vulnerabilities ..................................................................................... 191

12.3. Keeping the Community Informed ................................................................................ 191

13. Dos and Don'ts .................................................................................................................... 197

13.1. Introduction ............................................................................................................. 197

13.2. WRKDIR .................................................................................................................... 197

13.3. WRKDIRPREFIX ........................................................................................................... 197

13.4. Differentiating Operating Systems and OS Versions ........................................................... 197

13.5. Writing Something After bsd.port.mk ....................................................................... 197

13.6. Use the exec Statement in Wrapper Scripts .................................................................... 198

13.7. Do Things Rationally .................................................................................................. 199

13.8. Respect Both CC and CXX ............................................................................................ 199

13.9. Respect CFLAGS ......................................................................................................... 199

13.10. Verbose Build Logs ................................................................................................... 200

13.11. Feedback ................................................................................................................ 200

13.12. README.html ....................................................................................................... 200

13.13. Marking a Port Not Installable with BROKEN, FORBIDDEN, or IGNORE ...................................... 200

13.14. Architectural Considerations ...................................................................................... 202

13.15. Marking a Port for Removal with DEPRECATED or EXPIRATION_DATE ...................................... 202

iv

Table of Contents

13.16. Avoid Use of the .error Construct .............................................................................. 203

13.17. Usage of sysctl .................................................................................................... 203

13.18. Rerolling Distfiles .................................................................................................... 203

13.19. Use POSIX Standards ................................................................................................ 204

13.20. Miscellanea ............................................................................................................ 204

14. A Sample Makefile ........................................................................................................... 205

15. Order of Variables in Port Makefiles ........................................................................................ 207

15.1. PORTNAME Block ......................................................................................................... 207

15.2. PATCHFILES Block ...................................................................................................... 208

15.3. MAINTAINER Block ...................................................................................................... 208

15.4. LICENSE Block ........................................................................................................... 208

15.5. Generic BROKEN/IGNORE/DEPRECATED Messages ................................................................. 209

15.6. The Dependencies Block ............................................................................................. 209

15.7. Flavors .................................................................................................................... 210

15.8. USES and USE_x ........................................................................................................ 210

15.9. Standard bsd.port.mk Variables ............................................................................... 210

15.10. Options and Helpers ................................................................................................. 210

15.11. The Rest of the Variables .......................................................................................... 211

15.12. The Targets ............................................................................................................ 211

16. Keeping Up ........................................................................................................................ 213

16.1. FreshPorts ............................................................................................................... 213

16.2. The Web Interface to the Source Repository .................................................................... 213

16.3. The FreeBSD Ports Mailing List ..................................................................................... 213

16.4. The FreeBSD Port Building Cluster ................................................................................ 213

16.5. Portscout: the FreeBSD Ports Distfile Scanner .................................................................. 213

16.6. The FreeBSD Ports Monitoring System ........................................................................... 214

17. Using USES Macros .............................................................................................................. 215

17.1. An Introduction to USES ............................................................................................. 215

17.2. 7z .......................................................................................................................... 215

17.3. ada ........................................................................................................................ 215

17.4. autoreconf .............................................................................................................. 216

17.5. blaslapack .............................................................................................................. 216

17.6. bdb ........................................................................................................................ 216

17.7. bison ...................................................................................................................... 217

17.8. cabal ...................................................................................................................... 217

17.9. cargo ...................................................................................................................... 217

17.10. charsetfix ............................................................................................................. 218

17.11. cmake .................................................................................................................... 218

17.12. compiler ................................................................................................................ 218

17.13. cpe ....................................................................................................................... 219

17.14. cran ..................................................................................................................... 219

17.15. desktop-file-utils ................................................................................................ 219

17.16. desthack ............................................................................................................... 219

17.17. display ................................................................................................................. 219

17.18. dos2unix ................................................................................................................ 220

17.19. drupal ................................................................................................................... 220

17.20. eigen .................................................................................................................... 220

17.21. fakeroot ................................................................................................................ 220

17.22. fam ....................................................................................................................... 220

17.23. firebird ................................................................................................................ 220

17.24. fonts .................................................................................................................... 221

17.25. fortran ................................................................................................................. 221

17.26. fuse ..................................................................................................................... 221

17.27. gem ....................................................................................................................... 221

17.28. gettext ................................................................................................................. 221

17.29. gettext-runtime ..................................................................................................... 221

17.30. gettext-tools ........................................................................................................ 221

17.31. ghostscript ........................................................................................................... 221

v

Table of Contents

17.32. gl ........................................................................................................................ 222

17.33. gmake .................................................................................................................... 222

17.34. gnome .................................................................................................................... 222

17.35. go ........................................................................................................................ 225

17.36. gperf .................................................................................................................... 226

17.37. grantlee ............................................................................................................... 226

17.38. groff .................................................................................................................... 226

17.39. gssapi ................................................................................................................... 226

17.40. horde .................................................................................................................... 227

17.41. iconv .................................................................................................................... 227

17.42. imake .................................................................................................................... 228

17.43. kde ....................................................................................................................... 228

17.44. kmod ..................................................................................................................... 228

17.45. lha ....................................................................................................................... 228

17.46. libarchive ............................................................................................................ 228

17.47. libedit ................................................................................................................. 228

17.48. libtool ................................................................................................................ 229

17.49. linux .................................................................................................................... 229

17.50. localbase .............................................................................................................. 231

17.51. lua ....................................................................................................................... 231

17.52. lxqt ...................................................................................................................... 231

17.53. makeinfo ................................................................................................................ 232

17.54. makeself ................................................................................................................ 232

17.55. mate ..................................................................................................................... 232

17.56. meson .................................................................................................................... 233

17.57. metaport ................................................................................................................ 233

17.58. mysql .................................................................................................................... 233

17.59. mono ..................................................................................................................... 233

17.60. motif .................................................................................................................... 233

17.61. ncurses ................................................................................................................. 233

17.62. ninja .................................................................................................................... 234

17.63. objc ...................................................................................................................... 234

17.64. openal ................................................................................................................... 234

17.65. pathfix ................................................................................................................. 234

17.66. pear ..................................................................................................................... 234

17.67. perl5 .................................................................................................................... 234

17.68. pgsql .................................................................................................................... 235

17.69. php ....................................................................................................................... 235

17.70. pkgconfig .............................................................................................................. 237

17.71. pure ..................................................................................................................... 237

17.72. pyqt ..................................................................................................................... 237

17.73. python .................................................................................................................. 238

17.74. qmail .................................................................................................................... 238

17.75. qmake .................................................................................................................... 238

17.76. qt ........................................................................................................................ 239

17.77. qt-dist ................................................................................................................ 239

17.78. readline ................................................................................................................ 239

17.79. samba .................................................................................................................... 239

17.80. scons .................................................................................................................... 240

17.81. shared-mime-info .................................................................................................. 240

17.82. shebangfix ............................................................................................................. 240

17.83. sqlite .................................................................................................................. 243

17.84. ssl ....................................................................................................................... 243

17.85. tar ....................................................................................................................... 243

17.86. tcl ....................................................................................................................... 243

17.87. terminfo ................................................................................................................ 244

17.88. tk ........................................................................................................................ 244

17.89. uidfix ................................................................................................................... 244

vi

Table of Contents

17.90. uniquefiles ........................................................................................................... 244

17.91. varnish ................................................................................................................. 244

17.92. webplugin .............................................................................................................. 245

17.93. xfce ..................................................................................................................... 245

17.94. xorg ..................................................................................................................... 245

17.95. xorg-cat ............................................................................................................... 247

17.96. zip ....................................................................................................................... 247

18. __FreeBSD_version Values .................................................................................................... 249

18.1. FreeBSD 13 Versions .................................................................................................. 249

18.2. FreeBSD 12 Versions .................................................................................................. 259

18.3. FreeBSD 11 Versions .................................................................................................. 269

18.4. FreeBSD 10 Versions .................................................................................................. 283

18.5. FreeBSD 9 Versions .................................................................................................... 293

18.6. FreeBSD 8 Versions .................................................................................................... 300

18.7. FreeBSD 7 Versions .................................................................................................... 311

18.8. FreeBSD 6 Versions .................................................................................................... 318

18.9. FreeBSD 5 Versions .................................................................................................... 322

18.10. FreeBSD 4 Versions .................................................................................................. 330

18.11. FreeBSD 3 Versions .................................................................................................. 334

18.12. FreeBSD 2.2 Versions ................................................................................................ 335

18.13. FreeBSD 2 Before 2.2-RELEASE Versions ........................................................................ 336

vii

List of Tables

5.1. Examples of DISTVERSION and the Derived PORTVERSION .............................................................. 18

5.2. Package Naming Examples ..................................................................................................... 24

5.3. Shortcuts for MASTER_SITE_ * Macros ....................................................................................... 34

5.4. Magic MASTER_SITES Macros .................................................................................................. 34

5.5. USE_GITHUB Description ........................................................................................................ 35

5.6. USE_GITLAB Description ......................................................................................................... 42

5.7. Predefined License List .......................................................................................................... 55

5.8. USE_ * ................................................................................................................................ 67

6.1. Variables for Ports That Use configure .................................................................................... 98

6.2. Variables for Ports That Use cmake .......................................................................................... 98

6.3. Variables the Users Can Define for cmake Builds ......................................................................... 99

6.4. Variables the Users Can Define for cargo Builds ........................................................................ 100

6.5. Variables for Ports That Use meson ......................................................................................... 104

6.6. Read-Only Variables for Ports That Use Perl ............................................................................. 110

6.7. Variables for Ports That Use X ............................................................................................... 112

6.8. GNOME Components ........................................................................................................... 115

6.9. GNOME Macro Components .................................................................................................. 117

6.10. GNOME Legacy Components ................................................................................................ 117

6.11. Deprecated Components: Do Not Use ..................................................................................... 119

6.12. Variables Provided to Ports That Use Qt ................................................................................. 119

6.13. Available Qt Library Components .......................................................................................... 119

6.14. Available Qt Tool Components .............................................................................................. 121

6.15. Available Qt Plugin Components ........................................................................................... 122

6.16. Possible Arguments for USES= qmake .................................................................................... 122

6.17. Variables for Ports That Use qmake ....................................................................................... 122

6.18. Available KDE Components .................................................................................................. 123

6.19. Available LXQt Components ................................................................................................. 129

6.20. Variables Which May be Set by Ports That Use Java .................................................................. 130

6.21. Variables Provided to Ports That Use Java .............................................................................. 130

6.22. Constants Defined for Ports That Use Java .............................................................................. 131

6.23. Variables for Ports That Use Apache ...................................................................................... 132

6.24. Useful Variables for Porting Apache Modules .......................................................................... 133

6.25. Most Useful Variables for Ports That Use Python ...................................................................... 135

6.26. Python Module Dependency Helpers ..................................................................................... 136

6.27. The Most Useful Read-Only Variables for Ports That Use Tcl/Tk ................................................... 137

6.28. Useful Variables for Ports That Use Ruby ............................................................................... 138

6.29. Selected Read-Only Variables for Ports That Use Ruby ............................................................... 138

6.30. Variables to Select wxWidgets Versions ................................................................................. 140

6.31. Available wxWidgets Versions .............................................................................................. 140

6.32. wxWidgets Version Specifications ......................................................................................... 140

6.33. Variables to Select Preferred wxWidgets Versions .................................................................... 140

6.34. Available wxWidgets Components ......................................................................................... 140

6.35. Available wxWidgets Dependency Types ................................................................................. 141

6.36. Default wxWidgets Dependency Types ................................................................................... 141

6.37. Variables Defined for Ports That Use wxWidgets ...................................................................... 142

6.38. Legal Values for WX_CONF_ARGS ............................................................................................. 143

6.39. Variables Defined for Ports That Use Lua ................................................................................ 145

6.40. Variables Defined for Lua Module Ports .................................................................................. 145

6.41. Database USES Macros ........................................................................................................ 149

6.42. Shell completion le paths .................................................................................................. 153

11.1. Subversion Update File Prefixes ........................................................................................... 189

17.1. Available X.Org Components ................................................................................................ 245

18.1. FreeBSD 13 __FreeBSD_version Values .................................................................................. 249

18.2. FreeBSD 12 __FreeBSD_version Values .................................................................................. 259

18.3. FreeBSD 11 __FreeBSD_version Values .................................................................................. 269

18.4. FreeBSD 10 __FreeBSD_version Values .................................................................................. 283

List of Tables

18.5. FreeBSD 9 __FreeBSD_version Values .................................................................................... 293

18.6. FreeBSD 8 __FreeBSD_version Values .................................................................................... 300

18.7. FreeBSD 7 __FreeBSD_version Values .................................................................................... 311

18.8. FreeBSD 6 __FreeBSD_version Values .................................................................................... 318

18.9. FreeBSD 5 __FreeBSD_version Values .................................................................................... 322

18.10. FreeBSD 4 __FreeBSD_version Values .................................................................................. 330

18.11. FreeBSD 3 __FreeBSD_version Values .................................................................................. 334

18.12. FreeBSD 2.2 __FreeBSD_version Values ................................................................................ 335

18.13. FreeBSD 2 Before 2.2-RELEASE __FreeBSD_version Values ........................................................ 336

x

List of Examples

3.1. Creating a .diff for a New Port ............................................................................................. 9

3.2. Creating a .shar for a New Port ............................................................................................ 10

4.1. Applying a Patch for a Specific FreeBSD Version ......................................................................... 15

4.2. Optionally Applying a Patch ................................................................................................... 15

4.3. Using EXTRA_PATCHES With a Directory ..................................................................................... 15

5.1. Using pkg-version(8) to Compare Versions. ................................................................................ 18

5.2. Using DISTVERSION .............................................................................................................. 19

5.3. Using DISTVERSION When the Version Starts with a Letter or a Prefix ............................................. 19

5.4. Using DISTVERSION When the Version Contains Letters Meaning “alpha”, “beta”, or “pre-release” .......... 19

5.5. Not Using DISTVERSION When the Version Contains Letters Meaning "Patch Level" ............................ 20

5.6. Deriving PORTVERSION Manually ............................................................................................. 31

5.7. Derive DISTNAME from PORTVERSION ......................................................................................... 32

5.8. Exotic Case 1 ....................................................................................................................... 32

5.9. Exotic Case 2 ....................................................................................................................... 33

5.10. Simple Use of USE_GITHUB .................................................................................................... 36

5.11. More Complete Use of USE_GITHUB ......................................................................................... 36

5.12. Use of USE_GITHUB with DISTVERSIONPREFIX ............................................................................ 37

5.13. Using USE_GITHUB When Upstream Does Not Use Versions .......................................................... 37

5.14. Using USE_GITHUB to Access a Commit Between Two Versions ...................................................... 37

5.15. Use of USE_GITHUB with Multiple Distribution Files .................................................................... 39

5.16. Use of USE_GITHUB with Multiple Distribution Files Using GH_TUPLE ............................................... 40

5.17. How to Use USE_GITHUB with Git Submodules? ......................................................................... 40

5.18. Simple Use of USE_GITLAB ..................................................................................................... 42

5.19. More Complete Use of USE_GITLAB ......................................................................................... 43

5.20. Use of USE_GITLAB with Multiple Distribution Files ..................................................................... 44

5.21. Use of USE_GITLAB with Multiple Distribution Files Using GL_TUPLE ................................................ 45

5.22. Simplified Use of MASTER_SITES:n with One File Per Site ............................................................ 48

5.23. Simplified Use of MASTER_SITES:n with More Than One File Per Site ............................................. 48

5.24. Detailed Use of MASTER_SITES:n in MASTER_SITE_SUBDIR ............................................................ 49

5.25. Detailed Use of MASTER_SITES:n with Comma Operator, Multiple Files, Multiple Sites and Multiple

Subdirectories ........................................................................................................................... 49

5.26. Detailed Use of MASTER_SITES:n with SourceForge (SF) .............................................................. 52

5.27. Simplified Use of MASTER_SITES:n with PATCH_SITES ................................................................ 52

5.28. Simplest Usage, Predefined Licenses ....................................................................................... 55

5.29. Nonstandard License ........................................................................................................... 60

5.30. Standard and Nonstandard Licenses ........................................................................................ 61

5.31. LICENSE_NAME ..................................................................................................................... 61

5.32. LICENSE_FILE ..................................................................................................................... 62

5.33. LICENSE_TEXT ..................................................................................................................... 62

5.34. LICENSE_DISTFILES ............................................................................................................. 62

5.35. Dual Licenses ..................................................................................................................... 62

5.36. Multiple Licenses ................................................................................................................ 63

5.37. Wrong Declaration of an Optional Dependency .......................................................................... 68

5.38. Correct Declaration of an Optional Dependency ......................................................................... 68

5.39. Simple Use of OPTIONS ......................................................................................................... 71

5.40. Check for Unset Port OPTIONS ................................................................................................ 72

5.41. Practical Use of OPTIONS ....................................................................................................... 72

5.42. Wrong Handling of an Option ................................................................................................ 73

5.43. Correct Handling of an Option ............................................................................................... 73

5.44. Simple Use of OPT_IMPLIES ................................................................................................... 80

5.45. Simple Use of OPT_PREVENTS ................................................................................................. 81

5.46. Basic usage of CONFLICTS* .................................................................................................... 87

5.47. Using CONFLICTS* With Globs. ............................................................................................... 88

5.48. Using BINARY_ALIAS to Make gsed Available as sed .................................................................... 91

5.49. Using BINARY_ALIAS to Provide Aliases for Hardcoded python3 Commands ...................................... 92

6.1. Create Relative Symbolic Links Automatically ............................................................................. 94

6.2. USES= cmake Example .......................................................................................................... 99

6.3. CMAKE_ON and CMAKE_OFF ...................................................................................................... 99

6.4. Creating a Port for a Simple Rust Application ............................................................................ 102

6.5. Enabling Additional Application Features ................................................................................. 103

6.6. Encoding Application Features As Port Options ......................................................................... 103

6.7. Listing Crate Licenses .......................................................................................................... 104

6.8. USES=meson Example ........................................................................................................... 104

6.9. Creating a Port for a Go Modules Based Application .................................................................... 105

6.10. Setting Output Binary Name or Installation Path ...................................................................... 106

6.11. Creating a Port for a Hackage-hosted Haskell Application ........................................................... 107

6.12. Perl Dependency Example ................................................................................................... 110

6.13. A Port Which Only Requires Perl to Build ............................................................................... 111

6.14. A Port Which Also Requires Perl to Patch ............................................................................... 111

6.15. A Perl Module Which Needs ExtUtils::MakeMaker to Build ........................................................ 111

6.16. A Perl Module Which Needs Module::Build to Build ................................................................. 111

6.17. USE_XORG Example ............................................................................................................. 112

6.18. Using X11-Related Variables ................................................................................................ 112

6.19. Selecting Qt 5 Components .................................................................................................. 122

6.20. USES= qmake Example ....................................................................................................... 123

6.21. USE_KDE Example .............................................................................................................. 129

6.22. USE_LXQT Example ............................................................................................................. 129

6.23. Example Makefile for PEAR Class .......................................................................................... 134

6.24. Example Makefile for Horde Module ...................................................................................... 135

6.25. Makefile for a Simple Python Module .................................................................................... 137

6.26. Selecting wxWidgets Components ......................................................................................... 141

6.27. Detecting Installed wxWidgets Versions and Components .......................................................... 141

6.28. Using wxWidgets Variables in Commands ............................................................................... 142

6.29. Makefile for an application using Lua .................................................................................... 145

6.30. Makefile for a simple Lua module ......................................................................................... 146

6.31. Simple iconv Usage ........................................................................................................... 147

6.32. iconv Usage with configure ............................................................................................... 147

6.33. Fixing Hardcoded -liconv .................................................................................................. 147

6.34. Checking for Native iconv Availability ................................................................................... 147

6.35. USES=xfce Example ........................................................................................................... 148

6.36. Using Xfce's Own GTK2 Widgets ........................................................................................... 148

6.37. Using Berkeley DB 6 .......................................................................................................... 149

6.38. Using MySQL .................................................................................................................... 149

6.39. Using PostgreSQL .............................................................................................................. 149

6.40. Using SQLite 3 .................................................................................................................. 150

7.1. Basic Flavors Usage ............................................................................................................. 155

7.2. Another Basic Flavors Usage ................................................................................................. 156

7.3. More Complex Flavors Usage ................................................................................................. 156

7.4. Flavor Specific PKGNAME ........................................................................................................ 157

7.5. Simple USES=php Extension .................................................................................................. 158

7.6. Flavorizing a PHP Application ................................................................................................ 158

7.7. Simple USES=python ........................................................................................................... 159

7.8. USES=python with Version Requirements ................................................................................ 159

7.9. For a Port Not Using distutils ............................................................................................. 160

8.1. Using PLIST_SUB with Regular Expressions ............................................................................... 163

8.2. Example of a @dirrmtryecho Keyword ..................................................................................... 169

8.3. Real Life Example, How @sample is Implemented ....................................................................... 169

9.1. UCL Short Strings ............................................................................................................... 172

9.2. UCL Multiline Strings .......................................................................................................... 172

9.3. Display a Message on Install/Deinstall ..................................................................................... 172

9.4. Display a Message on Upgrade ............................................................................................... 173

10.1. Using make.conf to Change Default Perl ............................................................................. 185

13.1. How to Avoid Using .error ................................................................................................. 203

15.1. Options Variables Order Example .......................................................................................... 210

xii

17.1. Using Multiple Values ........................................................................................................ 215

17.2. Adding an Argument .......................................................................................................... 215

17.3. Adding Multiple Arguments ................................................................................................. 215

17.4. Mixing it All Together ........................................................................................................ 215

17.5. Typical Use ...................................................................................................................... 227

17.6. Building Qt 5 Components ................................................................................................... 239

17.7. Building Qt 5 Components with Different Names ...................................................................... 239

17.8. Adding Another Interpreter to USES=shebangfix ...................................................................... 241

17.9. Specifying all the Paths When Adding an Interpreter to USES=shebangfix ...................................... 241

17.10. Adding a Strange Location for an Interpreter ......................................................................... 242

17.11. USES=shebangfix with SHEBANG_REGEX .................................................................................. 242

17.12. USES=shebangfix with SHEBANG_GLOB ................................................................................... 242

17.13. USES=shebangfix with SHEBANG_FILES .................................................................................. 242

xiii

Chapter1.Introduction

The FreeBSD Ports Collection is the way almost everyone installs applications ("ports") on FreeBSD. Like every-

thing else about FreeBSD, it is primarily a volunteer effort. It is important to keep this in mind when reading this

document.

In FreeBSD, anyone may submit a new port, or volunteer to maintain an existing unmaintained port. No special

commit privilege is needed.

Chapter2.Making a New Port

Interested in making a new port, or upgrading existing ports? Great!

What follows are some guidelines for creating a new port for FreeBSD. To upgrade an existing port, read this, then

read Chapter11, Upgrading a Port.

When this document is not sufficiently detailed, refer to /usr/ports/Mk/bsd.port.mk , which is included by all

port Makefiles. Even those not hacking Makefiles daily can gain much knowledge from it. Additionally, specific

questions can be sent to the FreeBSD ports mailing list.

Note

Only a fraction of the variables (VAR) that can be overridden are mentioned in this document.

Most (if not all) are documented at the start of /usr/ports/Mk/bsd.port.mk ; the others

probably ought to be. Note that this le uses a non-standard tab setting: Emacs and Vim will

recognize the setting on loading the le. Both vi(1) and ex(1) can be set to use the correct

value by typing :set tabstop=4 once the le has been loaded.

Looking for something easy to start with? Take a look at the list of requested ports and see if you can work on

one (or more).

Chapter3.Quick Porting

This section describes how to quickly create a new port. For applications where this quick method is not adequate,

the full “Slow Porting” process is described in Chapter4, Slow Porting.

First, get the original tarball and put it into DISTDIR, which defaults to /usr/ports/distfiles .

Note

These steps assume that the software compiled out-of-the-box. In other words, absolutely

no changes were required for the application to work on a FreeBSD system. If anything had

to be changed, refer to Chapter4, Slow Porting.

Note

It is recommended to set the DEVELOPER make(1) variable in /etc/make.conf before getting

into porting.

# echo DEVELOPER=yes >> /etc/make.conf

This setting enables the “developer mode” that displays deprecation warnings and activates

some further quality checks on calling make.

3.1.Writing the Makefile

The minimal Makefile would look something like this:

# $FreeBSD$

PORTNAME= oneko

DISTVERSION= 1.1b

CATEGORIES= games

MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/

MAINTAINER= [email protected]

COMMENT= Cat chasing a mouse all over the screen

.include <bsd.port.mk>

Note

In some cases, the Makefile of an existing port may contain additional lines in the header,

such as the name of the port and the date it was created. This additional information has

been declared obsolete, and is being phased out.

Try to figure it out. Do not worry about the contents of the $FreeBSD$ line, it will be lled in automatically by

Subversion when the port is imported to our main ports tree. A more detailed example is shown in the sample

Makefile section.

Writing the Description Files

3.2.Writing the Description Files

There are two description les that are required for any port, whether they actually package or not. They are pkg-

descr and pkg-plist . Their pkg- prefix distinguishes them from other les.

3.2.1.pkg-descr

This is a longer description of the port. One to a few paragraphs concisely explaining what the port does is suffi-

cient.

Note

This is not a manual or an in-depth description on how to use or compile the port! Please be

careful when copying from the README or manpage. Too often they are not a concise description

of the port or are in an awkward format. For example, manpages have justified spacing, which

looks particularly bad with monospaced fonts.

On the other hand, the content of pkg-descr must be longer than the COMMENT line from the

Makefile. It must explain in more depth what the port is all about.

A well-written pkg-descr describes the port completely enough that users would not have to consult the docu-

mentation or visit the website to understand what the software does, how it can be useful, or what particularly

nice features it has. Mentioning certain requirements like a graphical toolkit, heavy dependencies, runtime envi-

ronment, or implementation languages help users decide whether this port will work for them.

Include a URL to the official WWW homepage. Prepend one of the websites (pick the most common one) with WWW:

(followed by single space) so that automated tools will work correctly. If the URI is the root of the website or

directory, it must be terminated with a slash.

Note

If the listed webpage for a port is not available, try to search the Internet rst to see if the

official site moved, was renamed, or is hosted elsewhere.

This example shows how pkg-descr looks:

This is a port of oneko, in which a cat chases a poor mouse all over

the screen.

:

(etc.)

WWW: http://www.oneko.org/

3.2.2.pkg-plist

This le lists all the les installed by the port. It is also called the “packing list” because the package is generated

by packing the les listed here. The pathnames are relative to the installation prefix (usually /usr/local ).

Here is a small example:

bin/oneko

man/man1/oneko.1.gz

lib/X11/app-defaults/Oneko

lib/X11/oneko/cat1.xpm

6

Page is loading ...

FreeBSD Porter’s Handbook Owner's manual

FreeBSD Porter’s Handbook Owner's manual

Other documents