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