Annotation of ports/README, Revision 1.5
1.4 marc 1:
1.2 joey 2: Welcome to the OpenBSD ports collection.
3: For more information on the OpenBSD ports tree please visit
4: http://www.openbsd.org/ports.html
5: For general information on the OpenBSD tree please visit
6: http://www.openbsd.org
1.1 joey 7:
8:
1.5 ! espie 9: When things go wrong
! 10: ====================
! 11: There are several contacts for the ports tree.
! 12: * individual ports list a
! 13: MAINTAINER=
! 14: line in their Makefile. Try to contact that person first.
! 15: * specific issues related to the ports framework (e.g., bugs in
! 16: bsd.port.mk) should go to ports-admin@openbsd.org
! 17: * ports without explicit maintainers, and other general issues should
! 18: go to ports@openbsd.org
! 19:
! 20: As a general rule, try to contact the MAINTAINER first. If nothing happens
! 21: after a reasonable delay, start plaguing him, or go to the next step.
! 22:
! 23: Developpers with a major investment in the ports tree include
! 24: brad@cvs.openbsd.org, turan@cvs.openbsd.org, espie@cvs.openbsd.org
! 25:
! 26: Those people can be contacted to put some pressure on a lazy maintainer.
! 27: But we do read ports@openbsd.org, so...
! 28:
! 29: The ports tree
! 30: ==============
! 31: The ports tree usually live under /usr/ports. It's a hierarchical
! 32: list of recipes to build various pieces of software.
! 33: We'll call that PORTSDIR in the following discussion.
! 34: Stuff that doesn't constitue a port proper, but rather paraphernalia,
! 35: is stored under /usr/ports/infrastructure, INFRA in the following
! 36: discussion.
! 37:
! 38: The main Makefile, PORTSDIR/Makefile, can be used to obtain various
! 39: information.
! 40:
! 41: * make search key=<keyword>
! 42: will locate ports that match the given keyword in the Index and print
! 43: information about them.
! 44:
! 45: * make index
! 46: can be used to rebuild that INDEX, normally useful after you update your
! 47: ports dir through cvs.
! 48:
! 49: * make readmes
! 50: will populate the ports tree with a set of html indices.
! 51:
! 52: The script INFRA/build/out-of-date will find
! 53: discrepancies between your installed packages and the INDEX. This might
! 54: give you an hint as to what you would need to rebuild to update a machine.
! 55:
! 56: Some useful `make' trivia
! 57: =========================
! 58: * if you always use some make variables, e.g., DISTDIR, CLEANDEPENDS, or
! 59: MASTER_SITE_OVERRIDE you can put this in your local make configuration
! 60: file instead: /etc/mk.conf.
! 61: * starting with 2.6, make can deal with case issues, so CLEANDEPENDS=Yes
! 62: or CLEANDEPENDS=YES or even CLEANDEPENDS=yEs should be equivalent.
! 63: * the make process uses some subroutines out of /usr/share/mk. Starting
! 64: with 2.6, the `port' subroutines live in INFRA/mk.
! 65: The bsd.port.mk and bsd.port.subdir.mk in /usr/share/mk are only stubs
! 66: that redirect to those files.
! 67:
! 68: Building a port
! 69: ===============
! 70: It's usually as simple as
! 71: cd category/portname && make && make install
! 72:
! 73: That specific `make' will normally
! 74: * resolve dependencies and go out to install required ports recursively
! 75: * fetch the software source (`distfiles' and `distribution patches')
! 76: from the available media into your repository
! 77: * extract the source
! 78: * apply distribution patches and OpenBSD patches
! 79: * build the program
! 80:
! 81: `make install' will
! 82: * install the software on your system
! 83: * log the installation so that later pkg_info or pkg_delete can deal with
! 84: the software.
! 85:
! 86: Some ports can have some options, or demand that you make some choice
! 87: before building, e.g.,
! 88: cd /usr/ports/security/ssh
! 89: make all install USA_RESIDENT=no
! 90:
! 91: Some ports may prompt you for more choice, or give you important
! 92: information about ports building. Likewise, installing or uninstalling
! 93: a port may give you useful information. READ IT.
! 94:
! 95: You can also use
! 96: * `make uninstall' to remove the installed software (same as pkg_delete)
! 97: * `make package' to convert the installed software into a binary `package'
! 98: (a tar ball that you can share with other machines with the same
! 99: configuration, contribute to the ftp project, or that you can backup
! 100: separately). Packages normally end up in /usr/ports/packages, overridable
! 101: with PACKAGE.
! 102: * `make fetch-list' to build a small shell-script that should be able to
! 103: retrieve the missing distfiles and distribution patches for the given port.
! 104: * `make clean' to remove all scaffolding after the port is built and
! 105: installed.
! 106: * `make distclean' to also remove distfiles and distribution patches
! 107: from the repository
! 108: * `make clean CLEANDEPENDS=Yes' will also remove sub ports that have been
! 109: recursively built.
! 110: * `make distclean CLEANDEPENDS=Yes', guess what this does.
! 111:
! 112: Please note that, in normal use, the OpenBSD ports tree will grow quite
! 113: a lot. Careful use of make clean and make distclean will help you.
! 114: `find /usr/ports -type d -name work -print' can be useful to find out
! 115: ports you forgot to clean out.
! 116:
! 117: There are a few kinks in the building of ports with options yet. Namely,
! 118: all such ports should produce distinct package names if built with
! 119: different options. Also, there is no check for consistency between
! 120: make and make install. Taking the ssh example again,
! 121: make USA_RESIDENT=No
! 122: make install USA_RESIDENT=Yes
! 123: won't be flagged as an error...
! 124:
! 125: Where do the distfiles come from
! 126: ================================
! 127: Retrieving distfiles is a subpart of `make' that can be invoked separately
! 128: as `make fetch'.
! 129:
! 130: Starting with 2.6, the fetch process is configurable by editing
! 131: INFRA/db/network.conf.
! 132:
! 133: The ports tree does store files it retrieves in a repository area,
! 134: normally /usr/ports/distfiles (defined as DISTDIR=${PORTSDIR}/distfiles;
! 135: you can override this if you need; e.g., assuming you've got a cdrom
! 136: full of distfiles mounted under /cdrom, you can make stuff with
! 137: DISTDIR=/cdrom/distfiles, provided all the distfiles are available on
! 138: the CD-Rom).
! 139:
! 140: If the file is found in the repository, the build process continues.
! 141: In some rare cases, vendors change their archive contents without changing
! 142: the archive name, so the file in the repository may end up having a wrong
! 143: checksum. Or, if you aborted a network transfer, the file in the repository
! 144: may be truncated, and end up having a wrong checksum again. In such a case,
! 145: manual intervention is required (it was deemed that such problems may need
! 146: human expertise and that blindly removing distfiles was not a good idea).
! 147: It's usually as simple as deleting the offending file, or doing a
! 148: make distclean.
! 149:
! 150: To avoid building from corrupted archives, the ports tree holds checksums
! 151: for almost all files it retrieves from other media (a few ports ignore
! 152: checksums from the files listed in IGNOREFILES).
! 153: Those are strong cryptographic checksums: sha1, rmd160, and md5,
! 154: in that order. See CIPHERS and PREFERRED_CIPHERS in
! 155: INFRA/mk/bsd.port.mk for details.
! 156:
! 157: If the directory /cdrom/distfiles exist, available distfiles are copied
! 158: off that directory to your repository. You can avoid the copy overhead
! 159: by defining FETCH_SYMLINK_DISTFILES. You can give another location for
! 160: the distfiles as CDROM_SITE.
! 161:
! 162: OpenBSD `ftp' command is normally used to fetch distfiles off the net,
! 163: so all file addresses are given in URL format.
! 164: Each port uses its own set of sites, and there should also be backups of
! 165: the distribution files on ftp.openbsd.org. MASTER_SITE_BACKUP holds an
! 166: overridable list of backup sites, normally
! 167: ftp://ftp.openbsd.org/pub/OpenBSD/distfiles/${DIST_SUBDIR}/
! 168: ftp://ftp.openbsd.org/pub/OpenBSD/licensed/${DIST_SUBDIR}/
! 169: ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/
! 170:
! 171: You can ask the fetch process to try to retrieve files from those sites first
! 172: by setting MASTER_SITE_OVERRIDE, e.g.,
! 173: make MASTER_SITE_OVERRIDE='${MASTER_SITE_BACKUP}'
! 174:
! 175: You can retrieve file from the OpenBSD site only with
! 176: make MASTER_SITE_OPENBSD=Yes
! 177:
! 178: Continuing our CD-Rom example, you could also fetch files off a CD-Rom into
! 179: your repository for safe-keeping by using the following incantation:
! 180: make fetch MASTER_SITE_OVERRIDE='file:/cdrom/{$DIST_SUBDIR}/'
! 181: This is equivalent to using CDROM_SITE.
! 182:
! 183: Some common sites have their own variables. It is strongly recommended
! 184: that you edit the INFRA/db/network.conf file for
! 185: your site.
! 186:
! 187: Please refer to that file for a complete list, and address lists
! 188: (those are not exhaustive). Those include:
! 189: MASTER_SITE_GNU FSF and other GPL programs
! 190: MASTER_SITE_XCONTRIB X11 contributed software
! 191: MASTER_SITE_SUNSITE Sunsite site and mirror, major linux archive
! 192: MASTER_SITE_GNOME Gnome
! 193: MASTER_SITE_PERL_CPAN Comprehensive perl archive network
! 194: MASTER_SITE_TEX_CTAN Comprehensive TeX archive network
! 195: MASTER_SITE_KDE KDE
! 196: MASTER_SITE_TCLTK Tcl/Tk
! 197: MASTER_SITE_AFTERSTEP AfterStep
! 198: MASTER_SITE_WINDOWMAKER WindowMaker
! 199:
! 200: There is a backup copy of that file in
! 201: INFRA/templates/network.conf.template.
! 202:
! 203: In case you don't have a permanent network connection,
! 204: `make fetch-list' should provide you with a shell script you can use to
! 205: retrieve distfiles you're missing to build a given port.
! 206:
! 207: (TODO: improve and systematize fetch-all)
! 208:
! 209: Building several ports
! 210: ======================
! 211: Each category directory holds a Makefile that propagates commands to
! 212: its sub ports, e.g., if you cd /usr/ports/audio && make, this should
! 213: build all ports under /usr/ports/audio.
! 214:
! 215: A more useful command is the
! 216: INFRA/build/find-build-order script.
! 217: You normally prepare a list of the ports you want to build, in the same
! 218: format as INFRA/db/essentials, and pass it to find-build-order like
! 219: this:
! 220: cd /usr/ports/infrastructure
! 221: cat db/essentials|build/find-build-order
! 222: This yields a sorted list of the required ports.
! 223:
! 224: (Todo: provide for a script which builds everything we want)
! 225:
! 226: You can filter ports that require interaction out with
! 227: make BATCH=yes
! 228:
! 229: Likewise, make FOR_CDROM=yes, make NO_RESTRICTED=yes
! 230: will yield only the ports with the required level of liberty.
! 231:
! 232: Files Summary
! 233: =============
! 234: /usr/ports (PORTSDIR):
! 235: the whole port collection
! 236: /usr/ports/<category>/<portname>:
! 237: where to find a given port
! 238: /usr/ports/INDEX:
! 239: all distfiles, rebuilt with make index
! 240: /usr/ports/README.html
! 241: /usr/ports/<category>/README.html
! 242: /usr/ports/<category>/<portname>/README.html:
! 243: www indices produced by make readmes
! 244: /usr/ports/distfiles (DISTFILES):
! 245: repository for distribution files and distribution patches
! 246: /cdrom/distfiles (CDROM_SITE):
! 247: standard location for distfiles off a CD
! 248: /usr/ports/packages (PACKAGES):
! 249: where binary packages are built (by category. Normally everything
! 250: ends up under All, with symlinks for each category)
! 251: /usr/ports/<category>/<portname>/work:
! 252: where the ports mechanism does the building. This is normally a
! 253: real directory, but you can set WRKOBJDIR to point to another
! 254: base which is not /usr/ports, and work/ will be a link to
! 255: ${WRKOBJDIR}/category/portname/work. This can be useful to
! 256: mount a master /usr/ports directory by NFS on several
! 257: architectures. Normally, you first
! 258: cd /usr/ports && make WRKOBJDIR=path obj
! 259: on the master machine, which creates the symbolic links, so that
! 260: you can mount your master /usr/ports read-only.
! 261: /usr/ports/<category>/<portname>/pkg/SECURITY:
! 262: information relative to a security audit of the port. Usually
! 263: missing.
! 264: /usr/ports/infrastructure:
! 265: paraphernalia around the ports tree
! 266: /usr/ports/db/network.conf:
! 267: your local network configuration (ftp sites)
! 268: /var/db/pkg:
! 269: installed ports, see pkg_add(1).
! 270: /usr/local (LOCALBASE):
! 271: where normal ports install themselves.
! 272: /usr/X11R6 (X11BASE):
! 273: where ports with a large dependency on X11 install themselves.
! 274:
! 275: Other tweaks
! 276: ============
! 277: FORCE_PACKAGE: force package building. Some ports can't be distributed
! 278: as packages for legal reasons, but you may wish to build a package for
! 279: your private consumption.
! 280: HAVE_MOTIF: set in /etc/mk.conf if we own a copy of the real thing.
! 281: MOTIF_STATIC: set in /etc/mk.conf to use a static version of the Motif
! 282: library only.
! 283: NO_MTREE: don't run mtree before installing a port. This is a dangerous
! 284: option.
! 285: NO_PKG_REGISTER: used for make install, don't register port under
! 286: /var/db/pkg. This is a dangerous option.
! 287: FORCE_PACKAGE_REGISTER: override an existing port (the <pkgname> is already
! 288: installed message). You will end up with several flavors of the same
! 289: package. This is a dangerous option, as this will probably erase the other
! 290: port.
! 291: NO_IGNORE: coerce fetch, build, install... into doing their job even though
! 292: there might be a good reason not to. Good reasons include BROKEN,
! 293: ONLY_FOR_ARCH, IS_INTERACTIVE in BATCH mode, NO_CDROM in FOR_CDROM... This
! 294: is a dangerous option.
! 295:
! 296: Keeping up with the Jones, ports as a moving target
! 297: ===================================================
! 298: The OpenBSD ports tree is growing from release to release. It needs
! 299: people to write and test new ports.
! 300: Like for src, you can choose to live on the bleeding edge by updating
! 301: your ports dir thru cvs or ftp, and contribute bug-reports.
! 302:
! 303: If you prefer to stay with a stable release, we try to make sure
! 304: the distfiles for a given release stay on the OpenBSD site between
! 305: releases.
1.1 joey 306:
1.3 marc 307: No matter how fast we update the tree it seems that we are always
308: behind. For this reason you will sometimes find a port that is
309: marked as BROKEN. If you try to build the port you will see a
310: message something like:
311:
312: ===> xxx-1.0 is marked as broken: newer version available.
313:
314: This means we know there is a newer version of the application but
315: have not yet had time to update the port. If you get this message
316: all may not be lost. If the old sources are still available (and
317: this is often the case) you can force a build using the old sources
318: using the command:
319:
320: make NO_IGNORE=yes
321: sudo make NO_IGNORE=yes install
322:
1.4 marc 323: If you're feeling generous a better solution is to update the port
1.3 marc 324: to use the new sources and feed the changes back to the project.
325: If you are interested in contributing (or creating a new port)
326: please visit
327:
1.1 joey 328: http://www.openbsd.org/porting.html
1.3 marc 329:
1.5 ! espie 330: $OpenBSD: README,v 1.4 1998/10/09 00:15:35 marc Exp $
![[BACK]](/icons/back.gif){kind=icon}
Return to README CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / ports