Annotation of ports/README, Revision 1.15
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.10 espie 9: ======================================================================
10:
1.12 pvalchev 11: This file is mostly obsolete. You should refer to the corresponding
1.11 espie 12: man-pages: ports(7), packages(7), mirroring-ports(7), packages-specs (7),
13: and bsd.port.mk(5) instead.
1.10 espie 14:
15: ======================================================================
16:
1.7 espie 17: Contacts
18: ========
1.11 espie 19: * individual ports have a MAINTAINER.
20: Go to the port directory and use make show=MAINTAINER to see it.
1.5 espie 21: * ports without explicit maintainers, and other general issues should
22: go to ports@openbsd.org
23:
1.7 espie 24: Considering the size of the ports tree, and even though we strive to
1.9 avsm 25: eradicate all bugs, things may go wrong on individual ports.
1.7 espie 26: In such a case, as a general rule, try to contact the MAINTAINER first.
27: If nothing happens after a reasonable delay, start plaguing him,
28: or go to the next step.
1.5 espie 29:
1.9 avsm 30: Developers with a major investment in the ports tree include
1.14 david 31: Brad Smith <brad@openbsd.org>, Christian Weisgerber <naddy@openbsd.org>,
1.11 espie 32: Marc Espie <espie@openbsd.org>.
1.5 espie 33:
34: Those people can be contacted to put some pressure on a lazy maintainer.
35: But we do read ports@openbsd.org, so...
36:
37: The ports tree
38: ==============
39: The ports tree usually live under /usr/ports. It's a hierarchical
40: list of recipes to build various pieces of software.
41: We'll call that PORTSDIR in the following discussion.
1.9 avsm 42: Stuff that doesn't constitute a port proper, but rather paraphernalia,
1.5 espie 43: is stored under /usr/ports/infrastructure, INFRA in the following
44: discussion.
45:
46: The main Makefile, PORTSDIR/Makefile, can be used to obtain various
47: information.
48:
1.13 fgsch 49: * make search key=<keyword>
50: will locate ports that match the given keyword in the INDEX and print
1.5 espie 51: information about them.
52:
53: * make index
54: can be used to rebuild that INDEX, normally useful after you update your
55: ports dir through cvs.
56:
57: * make readmes
1.11 espie 58: will populate the ports tree with a set of html indices (currently somewhat
59: broken).
1.5 espie 60:
61: The script INFRA/build/out-of-date will find
62: discrepancies between your installed packages and the INDEX. This might
63: give you an hint as to what you would need to rebuild to update a machine.
64:
65: Some useful `make' trivia
66: =========================
67: * if you always use some make variables, e.g., DISTDIR, CLEANDEPENDS, or
68: MASTER_SITE_OVERRIDE you can put this in your local make configuration
69: file instead: /etc/mk.conf.
70: * starting with 2.6, make can deal with case issues, so CLEANDEPENDS=Yes
71: or CLEANDEPENDS=YES or even CLEANDEPENDS=yEs should be equivalent.
72: * the make process uses some subroutines out of /usr/share/mk. Starting
73: with 2.6, the `port' subroutines live in INFRA/mk.
74: The bsd.port.mk and bsd.port.subdir.mk in /usr/share/mk are only stubs
75: that redirect to those files.
76:
77: Building a port
78: ===============
79: It's usually as simple as
80: cd category/portname && make && make install
81:
82: That specific `make' will normally
83: * resolve dependencies and go out to install required ports recursively
84: * fetch the software source (`distfiles' and `distribution patches')
85: from the available media into your repository
86: * extract the source
87: * apply distribution patches and OpenBSD patches
88: * build the program
89:
90: `make install' will
1.11 espie 91: * install the software in a special playpen directory (the fake area)
92: * create a binary package out of that fake-install
93: * install the package on your system
1.5 espie 94:
1.11 espie 95: Some ports can have some options (flavors), or demand that you make some choice
1.5 espie 96: before building, e.g.,
1.11 espie 97: cd /usr/ports/editors/vim/stable
98: env FLAVOR=no_x11 make all install
1.5 espie 99:
1.11 espie 100: Some ports may give you some information about ways to build them.
101: Likewise, installing or uninstalling
102: a package may give you useful information. READ IT.
1.5 espie 103:
104: You can also use
1.11 espie 105: * `make clean=install' to remove the installed software (calls pkg_delete)
106: * `make package' to create a binary package without necessarily installing
107: it. Packages normally end up in /usr/ports/packages/${MACHINE_ARCH},
108: overridable with PACKAGES.
109: * `make clean=package' to remove a previously built package.
1.5 espie 110: * `make clean' to remove all scaffolding after the port is built and
111: installed.
1.11 espie 112: * `make clean=dist' to also remove distfiles and distribution patches
1.5 espie 113: from the repository
1.11 espie 114: * `make clean=depends' will also remove sub ports that have been
1.5 espie 115: recursively built.
1.11 espie 116: * `make clean="depends dist"', guess what this does.
1.5 espie 117:
118: Please note that, in normal use, the OpenBSD ports tree will grow quite
1.11 espie 119: a lot. Starting with OpenBSD 3.0, working directories for packaged ports
120: can be cleaned out. See the bulk-packages target.
121: However, the distfiles and built
122: packages still can take a lot of space (over 1 Gb).
123: You can redirect ports activity elsewhere by making use of WRKOBJDIR,
124: DISTDIR and PACKAGES. `find /usr/ports -type d -name w-\* -print'
1.8 espie 125: can be useful to find out ports you forgot to clean out.
1.5 espie 126:
127: Where do the distfiles come from
128: ================================
129: Retrieving distfiles is a subpart of `make' that can be invoked separately
130: as `make fetch'.
131:
132: Starting with 2.6, the fetch process is configurable by editing
133: INFRA/db/network.conf.
134:
135: The ports tree does store files it retrieves in a repository area,
136: normally /usr/ports/distfiles (defined as DISTDIR=${PORTSDIR}/distfiles;
137: you can override this if you need; e.g., assuming you've got a cdrom
138: full of distfiles mounted under /cdrom, you can make stuff with
139: DISTDIR=/cdrom/distfiles, provided all the distfiles are available on
140: the CD-Rom).
141:
142: If the file is found in the repository, the build process continues.
143: In some rare cases, vendors change their archive contents without changing
144: the archive name, so the file in the repository may end up having a wrong
145: checksum. Or, if you aborted a network transfer, the file in the repository
146: may be truncated, and end up having a wrong checksum again. In such a case,
147: manual intervention is required (it was deemed that such problems may need
148: human expertise and that blindly removing distfiles was not a good idea).
149: It's usually as simple as deleting the offending file, or doing a
150: make distclean.
151:
152: To avoid building from corrupted archives, the ports tree holds checksums
153: for almost all files it retrieves from other media (a few ports ignore
154: checksums from the files listed in IGNOREFILES).
155: Those are strong cryptographic checksums: sha1, rmd160, and md5,
156: in that order. See CIPHERS and PREFERRED_CIPHERS in
157: INFRA/mk/bsd.port.mk for details.
158:
159: If the directory /cdrom/distfiles exist, available distfiles are copied
160: off that directory to your repository. You can avoid the copy overhead
161: by defining FETCH_SYMLINK_DISTFILES. You can give another location for
162: the distfiles as CDROM_SITE.
163:
164: OpenBSD `ftp' command is normally used to fetch distfiles off the net,
165: so all file addresses are given in URL format.
166: Each port uses its own set of sites, and there should also be backups of
167: the distribution files on ftp.openbsd.org. MASTER_SITE_BACKUP holds an
168: overridable list of backup sites, normally
169: ftp://ftp.openbsd.org/pub/OpenBSD/distfiles/${DIST_SUBDIR}/
170: ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/
171:
172: You can ask the fetch process to try to retrieve files from those sites first
173: by setting MASTER_SITE_OVERRIDE, e.g.,
174: make MASTER_SITE_OVERRIDE='${MASTER_SITE_BACKUP}'
175:
176: You can retrieve file from the OpenBSD site only with
177: make MASTER_SITE_OPENBSD=Yes
178:
179: Continuing our CD-Rom example, you could also fetch files off a CD-Rom into
180: your repository for safe-keeping by using the following incantation:
1.8 espie 181: make fetch MASTER_SITE_OVERRIDE='file:/cdrom/${DIST_SUBDIR}/'
1.5 espie 182: This is equivalent to using CDROM_SITE.
183:
184: Some common sites have their own variables. It is strongly recommended
185: that you edit the INFRA/db/network.conf file for
186: your site.
187:
188: Please refer to that file for a complete list, and address lists
189: (those are not exhaustive). Those include:
190: MASTER_SITE_GNU FSF and other GPL programs
191: MASTER_SITE_XCONTRIB X11 contributed software
192: MASTER_SITE_SUNSITE Sunsite site and mirror, major linux archive
193: MASTER_SITE_GNOME Gnome
194: MASTER_SITE_PERL_CPAN Comprehensive perl archive network
195: MASTER_SITE_TEX_CTAN Comprehensive TeX archive network
196: MASTER_SITE_KDE KDE
197: MASTER_SITE_TCLTK Tcl/Tk
198: MASTER_SITE_AFTERSTEP AfterStep
199: MASTER_SITE_WINDOWMAKER WindowMaker
200:
201: There is a backup copy of that file in
202: INFRA/templates/network.conf.template.
203:
1.12 pvalchev 204: In case you don't have a permanent network connection, you should read
1.11 espie 205: mirroring-ports(7).
1.5 espie 206:
207: Building several ports
208: ======================
209: Each category directory holds a Makefile that propagates commands to
1.11 espie 210: its sub ports, e.g., if you cd /usr/ports/audio && make package, this should
211: build packages for all ports under /usr/ports/audio.
1.5 espie 212:
213: A more useful command is the
1.11 espie 214: INFRA/package/check-plist script.
1.5 espie 215: You normally prepare a list of the ports you want to build, in the same
1.11 espie 216: format as INFRA/db/essentials, and pass it to that script.
1.5 espie 217: This yields a sorted list of the required ports.
218:
219: You can filter ports that require interaction out with
220: make BATCH=yes
221:
222: Files Summary
223: =============
224: /usr/ports (PORTSDIR):
225: the whole port collection
226: /usr/ports/<category>/<portname>:
227: where to find a given port
228: /usr/ports/INDEX:
229: all distfiles, rebuilt with make index
230: /usr/ports/distfiles (DISTFILES):
231: repository for distribution files and distribution patches
232: /cdrom/distfiles (CDROM_SITE):
233: standard location for distfiles off a CD
1.11 espie 234: /usr/ports/packages/${MACHINE_ARCH} (PACKAGES):
1.5 espie 235: where binary packages are built (by category. Normally everything
236: ends up under All, with symlinks for each category)
1.11 espie 237: /usr/ports/<category>/<portname>/w-${PKGNAME}:
1.5 espie 238: where the ports mechanism does the building. This is normally a
239: real directory, but you can set WRKOBJDIR to point to another
240: base which is not /usr/ports, and work/ will be a link to
241: ${WRKOBJDIR}/category/portname/work. This can be useful to
242: mount a master /usr/ports directory by NFS on several
243: architectures. Normally, you first
244: cd /usr/ports && make WRKOBJDIR=path obj
245: on the master machine, which creates the symbolic links, so that
246: you can mount your master /usr/ports read-only.
247: /usr/ports/<category>/<portname>/pkg/SECURITY:
248: information relative to a security audit of the port. Usually
249: missing.
250: /usr/ports/infrastructure:
251: paraphernalia around the ports tree
1.15 ! avsm 252: /usr/ports/infrastructure/db/network.conf:
1.5 espie 253: your local network configuration (ftp sites)
254: /var/db/pkg:
255: installed ports, see pkg_add(1).
256: /usr/local (LOCALBASE):
257: where normal ports install themselves.
258:
259: Other tweaks
260: ============
261: NO_IGNORE: coerce fetch, build, install... into doing their job even though
262: there might be a good reason not to. Good reasons include BROKEN,
1.11 espie 263: ONLY_FOR_ARCH, IS_INTERACTIVE in BATCH mode. This is a dangerous option.
1.5 espie 264:
265: Keeping up with the Jones, ports as a moving target
266: ===================================================
267: The OpenBSD ports tree is growing from release to release. It needs
268: people to write and test new ports.
269: Like for src, you can choose to live on the bleeding edge by updating
1.11 espie 270: your ports dir thru cvs or ftp, and contribute bug-reports. You must
271: update both ports and src in synch.
1.5 espie 272:
273: If you prefer to stay with a stable release, we try to make sure
274: the distfiles for a given release stay on the OpenBSD site between
275: releases.
1.1 joey 276:
1.3 marc 277: No matter how fast we update the tree it seems that we are always
1.12 pvalchev 278: behind. There are always new versions of software out there, without
279: an existing port. Very often, no one had time to update the port yet,
1.11 espie 280: or it is very likely that the new version has not been tested enough
281: yet to deem it reasonable to upgrade the port.
282:
283: You may wish to contribute, by updating ports or creating new ports.
1.3 marc 284: please visit
285:
1.1 joey 286: http://www.openbsd.org/porting.html
1.3 marc 287:
1.11 espie 288: and always remember to communicate with OpenBSD project members on
289: ports@openbsd.org. Why create a brand new shiny port to discover that
290: someone was already working on it, and they committed their new version
291: ten minutes before you announced yours ?
292:
1.15 ! avsm 293: $OpenBSD: README,v 1.14 2003/03/01 09:09:16 david 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