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