share/man/man7/ports.7

   1 .\"
   2 .\" Copyright (c) 1997 David E. O'Brien
   3 .\"
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD: src/share/man/man7/ports.7,v 1.17.2.9 2002/08/07 10:54:39 blackend Exp $
  27 .\" $DragonFly: src/share/man/man7/Attic/ports.7,v 1.3 2004/02/25 20:44:30 eirikn Exp $
  28 .\"
  29 .Dd January 25, 1998
  30 .Dt PORTS 7
  31 .Os
  32 .Sh NAME
  33 .Nm ports
  34 .Nd contributed applications
  35 .Sh DESCRIPTION
  36 The
  37 .Fx
  38 Ports Collection
  39 offers a simple way for users and
  40 administrators to install applications.
  41 Each
  42 .Em port
  43 contains any patches necessary to make the original
  44 application source code compile and run on
  45 .Bx .
  46 Compiling an
  47 application is as simple as typing
  48 .Nm make Cm build
  49 in the port directory!
  50 The
  51 .Pa Makefile
  52 automatically fetches the
  53 application source code, either from a local disk or via FTP, unpacks it
  54 on your system, applies the patches, and compiles it.
  55 If all goes well,
  56 simply type
  57 .Nm make Cm install
  58 to install the application.
  59 .Pp
  60 It is possible to download and use ports from the
  61 .Fx
  62 repository
  63 that are newer than the installed system; however it is important to
  64 install the appropriate
  65 .Dq "Upgrade Kit"
  66 from
  67 .Pa http://www.FreeBSD.org/ports/
  68 first!
  69 The
  70 .Xr portcheckout 1
  71 script (also a port, of course!) will help to download new ports.
  72 .Pp
  73 For more information about using ports, see
  74 .Dq "Packages and Ports"
  75 in
  76 .%B "The FreeBSD Handbook" ,
  77 .Pa ( file:/usr/share/doc/handbook/ports.html
  78 or
  79 .Pa http://www.FreeBSD.org/doc/handbook/ports.html ) .
  80 For information about creating new ports, see
  81 .%B "The Porter's Handbook"
  82 .Pa ( file:/usr/share/doc/porters-handbook/index.html
  83 or
  84 .Pa http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/porters-handbook/ ) .
  85 .Sh TARGETS
  86 Some of the targets work recursively through subdirectories.
  87 This lets you, for example, install all of the
  88 .Dq Li biology
  89 ports.
  90 The targets that do this are
  91 .Cm build , checksum , clean , configure ,
  92 .Cm depends , extract , fetch , install ,
  93 and
  94 .Cm package .
  95 .Pp
  96 The following targets will be run automatically by each proceeding
  97 target in order.
  98 That is,
  99 .Cm build
 100 will be run
 101 (if necessary)
 102 by
 103 .Cm install ,
 104 and so on all the way to
 105 .Cm fetch .
 106 Usually, you will only use the
 107 .Cm install
 108 target.
 109 .Bl -tag -width ".Cm configure"
 110 .It Cm fetch
 111 Fetch all of the files needed to build this port from the sites
 112 listed in
 113 .Va MASTER_SITES
 114 and
 115 .Va PATCH_SITES .
 116 See
 117 .Va FETCH_CMD
 118 and
 119 .Va MASTER_SITE_OVERRIDE .
 120 .It Cm checksum
 121 Verify that the fetched distfile's checksum matches the one the port was
 122 tested against.
 123 Defining
 124 .Va NO_CHECKSUM
 125 will skip this step.
 126 .It Cm depends
 127 Install
 128 (or compile if only compilation is necessary)
 129 any dependencies of the current port.
 130 When called by the
 131 .Cm extract
 132 or
 133 .Cm fetch
 134 targets, this is run in piecemeal as
 135 .Cm fetch-depends , build-depends ,
 136 etc.
 137 Defining
 138 .Va NO_DEPENDS
 139 will skip this step.
 140 .It Cm extract
 141 Expand the distfile into a work directory.
 142 .It Cm patch
 143 Apply any patches that are necessary for the port.
 144 .It Cm configure
 145 Configure the port.
 146 Some ports will ask you questions during this stage.
 147 See
 148 .Va INTERACTIVE
 149 and
 150 .Va BATCH .
 151 .It Cm build
 152 Build the port.
 153 This is the same as calling the
 154 .Cm all
 155 target.
 156 .It Cm install
 157 Install the port and register it with the package system.
 158 This is all you really need to do.
 159 .El
 160 .Pp
 161 The following targets are not run during the normal install process.
 162 .Bl -tag -width ".Cm fetch-list"
 163 .It Cm fetch-list
 164 Show list of files needed to be fetched in order to build the port.
 165 .It Cm pretty-print-run-depends-list , pretty-print-build-depends-list
 166 Print a list of all the compile and run dependencies, and dependencies
 167 of those dependencies.
 168 .It Cm clean
 169 Remove the expanded source code.
 170 This recurses to dependencies unless
 171 .Va NOCLEANDEPENDS
 172 is defined.
 173 .It Cm distclean
 174 Remove the port's distfiles and perform the
 175 .Cm clean
 176 target.
 177 The
 178 .Cm clean
 179 portion recurses to dependencies unless
 180 .Va NOCLEANDEPENDS
 181 is defined, but the
 182 .Cm distclean
 183 portion never recurses
 184 (this is perhaps a bug).
 185 .It Cm reinstall
 186 Use this to restore a port after using
 187 .Xr pkg_delete 1
 188 when you should have used
 189 .Cm deinstall .
 190 .It Cm deinstall
 191 Remove an installed port from the system, similar to
 192 .Xr pkg_delete 1 .
 193 .It Cm package
 194 Make a binary package for the port.
 195 The port will be installed if it has not already been.
 196 The package is a
 197 .Pa .tgz
 198 file that you can use to
 199 install the port on other machines with
 200 .Xr pkg_add 1 .
 201 If the directory specified by
 202 .Va PACKAGES
 203 does not exist, the package will be put into the current directory.
 204 See
 205 .Va PKGREPOSITORY
 206 and
 207 .Va PKGFILE .
 208 .It Cm readmes
 209 Create a port's
 210 .Pa README.html .
 211 This can be used from
 212 .Pa /usr/ports
 213 to create a browsable web of all ports on your system!
 214 .It Cm search
 215 Search the
 216 .Pa INDEX
 217 file for the pattern specified by either the
 218 .Va key
 219 (searches the port name, comment, and dependencies) or
 220 .Va name
 221 (searches the port name only)
 222 .Xr make 1
 223 variable.
 224 For example, one would type:
 225 .Pp
 226 .Dl "cd /usr/ports && make search name=query"
 227 .Pp
 228 to find all ports whose
 229 name matches
 230 .Dq Li query .
 231 Results include the matching ports' path, comment, maintainer,
 232 build dependencies, and run dependencies.
 233 .It Cm index
 234 Create
 235 .Pa /usr/ports/INDEX ,
 236 which is used by the
 237 .Cm pretty-print-*
 238 and
 239 .Cm search
 240 targets.
 241 While the master
 242 .Pa INDEX
 243 file in the CVS repository is periodically
 244 updated, running the
 245 .Cm index
 246 target will ensure your
 247 .Pa INDEX
 248 file is up to date with your ports tree.
 249 .El
 250 .Sh ENVIRONMENT
 251 You can change all of these.
 252 .Bl -tag -width ".Va MASTER_SITES"
 253 .It Va PORTSDIR
 254 Location of the ports tree.
 255 This is
 256 .Pa /usr/ports
 257 on
 258 .Fx
 259 and
 260 .Ox ,
 261 and
 262 .Pa /usr/pkgsrc
 263 on
 264 .Nx .
 265 .It Va WRKDIRPREFIX
 266 Where to create any temporary files.
 267 Useful if
 268 .Va PORTSDIR
 269 is read-only (perhaps mounted from a CD-ROM).
 270 .It Va DISTDIR
 271 Where to find/put distfiles, normally
 272 .Pa distfiles/
 273 in
 274 .Va PORTSDIR .
 275 .It Va PACKAGES
 276 Used only for the
 277 .Cm package
 278 target; the base directory for the packages tree, normally
 279 .Pa packages/
 280 in
 281 .Va PORTSDIR .
 282 If this directory exists, the package tree will be (partially) constructed.
 283 This directory does not have to exist; if it does not, packages will be
 284 placed into the current directory, or you can define one of
 285 .Bl -tag -width ".Va PKGREPOSITORY"
 286 .It Va PKGREPOSITORY
 287 Directory to put the package in.
 288 .It Va PKGFILE
 289 The full path to the package.
 290 .El
 291 .It Va PREFIX
 292 Where to install things in general
 293 (usually
 294 .Pa /usr/local
 295 or
 296 .Pa /usr/X11R6 ) .
 297 .It Va MASTER_SITES
 298 Primary sites for distribution files if not found locally.
 299 .It Va PATCH_SITES
 300 Primary locations for distribution patch files if not found
 301 locally.
 302 .It Va MASTER_SITE_FREEBSD
 303 If set, go to the master
 304 .Fx
 305 site for all files.
 306 .It Va MASTER_SITE_OVERRIDE
 307 Try going to this site for all files and patches, first.
 308 .It Va NOCLEANDEPENDS
 309 If defined, do not let
 310 .Cm clean
 311 recurse to dependencies.
 312 .It Va FETCH_CMD
 313 Command to use to fetch files.
 314 Normally
 315 .Xr fetch 1 .
 316 .It Va FORCE_PKG_REGISTER
 317 If set, overwrite any existing package registration on the system.
 318 .It Va MOTIFLIB
 319 Location of
 320 .Pa libXm. Ns Brq Pa a , Ns Pa so .
 321 .It Va INTERACTIVE
 322 If defined, only operate on a port if it requires interaction.
 323 .It Va BATCH
 324 If defined, only operate on a port if it can be installed 100% automatically.
 325 .El
 326 .Sh FILES
 327 .Bl -tag -width ".Pa /usr/ports/Mk/bsd.port.mk" -compact
 328 .It Pa /usr/ports
 329 The default ports directory
 330 .No ( Fx
 331 , FreeBSD
 332 and
 333 .Ox ) .
 334 .It Pa /usr/pkgsrc
 335 The default ports directory
 336 .Pq Nx .
 337 .It Pa /usr/dfports
 338 DragonFly override ports
 339 .It Pa /usr/ports/Mk/bsd.port.mk
 340 The big Kahuna.
 341 .El
 342 .Sh SEE ALSO
 343 .Xr make 1 ,
 344 .Xr pkg_add 1 ,
 345 .Xr pkg_create 1 ,
 346 .Xr pkg_delete 1 ,
 347 .Xr pkg_info 1 ,
 348 .Xr pkg_version 1
 349 .Pp
 350 The following are part of the ports collection:
 351 .Pp
 352 .Xr pib 1 ,
 353 .Xr portcheckout 1 ,
 354 .Xr portlint 1
 355 .Rs
 356 .%B "The FreeBSD Handbook"
 357 .Re
 358 .Pp
 359 .Pa http://www.FreeBSD.org/ports
 360 (searchable index of all ports)
 361 .Sh AUTHORS
 362 .An -nosplit
 363 This man page was originated by
 364 .An David O'Brien .
 365 The ports collection is maintained by
 366 .An Satoshi Asami
 367 and the Awesome Ports Team.
 368 .Sh HISTORY
 369 The Ports Collection
 370 appeared in
 371 .Fx 1.0 .
 372 It has since spread to
 373 .Nx
 374 and
 375 .Ox .
 376 .Sh BUGS
 377 Ports documentation is split over four places \(em
 378 .Pa /usr/ports/Mk/bsd.port.mk ,
 379 .%B "The Porter's Handbook" ,
 380 the
 381 .Dq "Packages and Ports"
 382 chapter of
 383 .%B "The FreeBSD Handbook" ,
 384 and
 385 .Xr ports 7 .
 386 .Pp
 387 This man page is too long.