=================================================================== RCS file: /cvsrepo/anoncvs/cvs/ports/README,v retrieving revision 1.16 retrieving revision 1.17 diff -u -r1.16 -r1.17 --- ports/README 2003/09/23 01:40:26 1.16 +++ ports/README 2004/07/25 00:15:32 1.17 @@ -1,293 +1,6 @@ +Documentation for the ports tree: ports(7), packages(7), mirroring-ports(7), +bsd.port.mk(5). - Welcome to the OpenBSD ports collection. - For more information on the OpenBSD ports tree please visit - http://www.openbsd.org/ports.html - For general information on the OpenBSD tree please visit - http://www.openbsd.org +See also http://www.openbsd.org/ - -====================================================================== - -This file is mostly obsolete. You should refer to the corresponding -man-pages: ports(7), packages(7), mirroring-ports(7), packages-specs (7), -and bsd.port.mk(5) instead. - -====================================================================== - -Contacts -======== -* individual ports have a MAINTAINER. -Go to the port directory and use make show=MAINTAINER to see it. -* ports without explicit maintainers, and other general issues should -go to ports@openbsd.org - -Considering the size of the ports tree, and even though we strive to -eradicate all bugs, things may go wrong on individual ports. -In such a case, as a general rule, try to contact the MAINTAINER first. -If nothing happens after a reasonable delay, start plaguing him, -or go to the next step. - -Developers with a major investment in the ports tree include -Brad Smith , Christian Weisgerber , -Marc Espie . - -Those people can be contacted to put some pressure on a lazy maintainer. -But we do read ports@openbsd.org, so... - -The ports tree -============== -The ports tree usually live under /usr/ports. It's a hierarchical -list of recipes to build various pieces of software. -We'll call that PORTSDIR in the following discussion. -Stuff that doesn't constitute a port proper, but rather paraphernalia, -is stored under /usr/ports/infrastructure, INFRA in the following -discussion. - -The main Makefile, PORTSDIR/Makefile, can be used to obtain various -information. - -* make search key= -will locate ports that match the given keyword in the INDEX and print -information about them. - -* make index -can be used to rebuild that INDEX, normally useful after you update your -ports dir through cvs. - -* make readmes -will populate the ports tree with a set of html indices (currently somewhat -broken). - -The script INFRA/build/out-of-date will find -discrepancies between your installed packages and the INDEX. This might -give you an hint as to what you would need to rebuild to update a machine. - -Some useful `make' trivia -========================= -* if you always use some make variables, e.g., DISTDIR, CLEANDEPENDS, or -MASTER_SITE_OVERRIDE you can put this in your local make configuration -file instead: /etc/mk.conf. -* starting with 2.6, make can deal with case issues, so CLEANDEPENDS=Yes -or CLEANDEPENDS=YES or even CLEANDEPENDS=yEs should be equivalent. -* the make process uses some subroutines out of /usr/share/mk. Starting -with 2.6, the `port' subroutines live in INFRA/mk. -The bsd.port.mk and bsd.port.subdir.mk in /usr/share/mk are only stubs -that redirect to those files. - -Building a port -=============== -It's usually as simple as -cd category/portname && make && make install - -That specific `make' will normally -* resolve dependencies and go out to install required ports recursively -* fetch the software source (`distfiles' and `distribution patches') -from the available media into your repository -* extract the source -* apply distribution patches and OpenBSD patches -* build the program - -`make install' will -* install the software in a special playpen directory (the fake area) -* create a binary package out of that fake-install -* install the package on your system - -Some ports can have some options (flavors), or demand that you make some choice -before building, e.g., -cd /usr/ports/editors/vim/stable -env FLAVOR=no_x11 make all install - -Some ports may give you some information about ways to build them. -Likewise, installing or uninstalling -a package may give you useful information. READ IT. - -You can also use -* `make clean=install' to remove the installed software (calls pkg_delete) -* `make package' to create a binary package without necessarily installing -it. Packages normally end up in /usr/ports/packages/${MACHINE_ARCH}, -overridable with PACKAGES. -* `make clean=package' to remove a previously built package. -* `make clean' to remove all scaffolding after the port is built and -installed. -* `make clean=dist' to also remove distfiles and distribution patches -from the repository -* `make clean=depends' will also remove sub ports that have been -recursively built. -* `make clean="depends dist"', guess what this does. - -Please note that, in normal use, the OpenBSD ports tree will grow quite -a lot. Starting with OpenBSD 3.0, working directories for packaged ports -can be cleaned out. See the bulk-packages target. -However, the distfiles and built -packages still can take a lot of space (over 1 Gb). -You can redirect ports activity elsewhere by making use of WRKOBJDIR, -DISTDIR and PACKAGES. `find /usr/ports -type d -name w-\* -print' -can be useful to find out ports you forgot to clean out. - -Where do the distfiles come from -================================ -Retrieving distfiles is a subpart of `make' that can be invoked separately -as `make fetch'. - -Starting with 2.6, the fetch process is configurable by editing -INFRA/db/network.conf. - -The ports tree does store files it retrieves in a repository area, -normally /usr/ports/distfiles (defined as DISTDIR=${PORTSDIR}/distfiles; -you can override this if you need; e.g., assuming you've got a cdrom -full of distfiles mounted under /cdrom, you can make stuff with -DISTDIR=/cdrom/distfiles, provided all the distfiles are available on -the CD-Rom). - -If the file is found in the repository, the build process continues. -In some rare cases, vendors change their archive contents without changing -the archive name, so the file in the repository may end up having a wrong -checksum. Or, if you aborted a network transfer, the file in the repository -may be truncated, and end up having a wrong checksum again. In such a case, -manual intervention is required (it was deemed that such problems may need -human expertise and that blindly removing distfiles was not a good idea). -It's usually as simple as deleting the offending file, or doing a -make distclean. - -To avoid building from corrupted archives, the ports tree holds checksums -for almost all files it retrieves from other media (a few ports ignore -checksums from the files listed in IGNOREFILES). -Those are strong cryptographic checksums: sha1, rmd160, and md5, -in that order. See CIPHERS and PREFERRED_CIPHERS in -INFRA/mk/bsd.port.mk for details. - -If the directory /cdrom/distfiles exist, available distfiles are copied -off that directory to your repository. You can avoid the copy overhead -by defining FETCH_SYMLINK_DISTFILES. You can give another location for -the distfiles as CDROM_SITE. - -OpenBSD `ftp' command is normally used to fetch distfiles off the net, -so all file addresses are given in URL format. -Each port uses its own set of sites, and there should also be backups of -the distribution files on ftp.openbsd.org. MASTER_SITE_BACKUP holds an -overridable list of backup sites, normally -ftp://ftp.openbsd.org/pub/OpenBSD/distfiles/${DIST_SUBDIR}/ -ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/ - -You can ask the fetch process to try to retrieve files from those sites first -by setting MASTER_SITE_OVERRIDE, e.g., -make MASTER_SITE_OVERRIDE='${MASTER_SITE_BACKUP}' - -You can retrieve file from the OpenBSD site only with -make MASTER_SITE_OPENBSD=Yes - -Continuing our CD-Rom example, you could also fetch files off a CD-Rom into -your repository for safe-keeping by using the following incantation: -make fetch MASTER_SITE_OVERRIDE='file:/cdrom/${DIST_SUBDIR}/' -This is equivalent to using CDROM_SITE. - -Some common sites have their own variables. It is strongly recommended -that you edit the INFRA/db/network.conf file for -your site. - -Please refer to that file for a complete list, and address lists -(those are not exhaustive). Those include: -MASTER_SITE_GNU FSF and other GPL programs -MASTER_SITE_XCONTRIB X11 contributed software -MASTER_SITE_SUNSITE Sunsite site and mirror, major linux archive -MASTER_SITE_GNOME Gnome -MASTER_SITE_PERL_CPAN Comprehensive perl archive network -MASTER_SITE_TEX_CTAN Comprehensive TeX archive network -MASTER_SITE_KDE KDE -MASTER_SITE_TCLTK Tcl/Tk -MASTER_SITE_AFTERSTEP AfterStep -MASTER_SITE_WINDOWMAKER WindowMaker - -There is a backup copy of that file in -INFRA/templates/network.conf.template. - -In case you don't have a permanent network connection, you should read -mirroring-ports(7). - -Building several ports -====================== -Each category directory holds a Makefile that propagates commands to -its sub ports, e.g., if you cd /usr/ports/audio && make package, this should -build packages for all ports under /usr/ports/audio. - -A more useful command is the -INFRA/package/check-plist script. -You normally prepare a list of the ports you want to build, in the same -format as INFRA/plist/i386, and pass it to that script. -This yields a sorted list of the required ports. - -You can filter ports that require interaction out with -make BATCH=yes - -Files Summary -============= -/usr/ports (PORTSDIR): - the whole port collection -/usr/ports//: - where to find a given port -/usr/ports/INDEX: - all distfiles, rebuilt with make index -/usr/ports/distfiles (DISTFILES): - repository for distribution files and distribution patches -/cdrom/distfiles (CDROM_SITE): - standard location for distfiles off a CD -/usr/ports/packages/${MACHINE_ARCH} (PACKAGES): - where binary packages are built (by category. Normally everything - ends up under All, with symlinks for each category) -/usr/ports///w-${PKGNAME}: - where the ports mechanism does the building. This is normally a - real directory, but you can set WRKOBJDIR to point to another - base which is not /usr/ports, and work/ will be a link to - ${WRKOBJDIR}/category/portname/work. This can be useful to - mount a master /usr/ports directory by NFS on several - architectures. Normally, you first - cd /usr/ports && make WRKOBJDIR=path obj - on the master machine, which creates the symbolic links, so that - you can mount your master /usr/ports read-only. -/usr/ports///pkg/SECURITY: - information relative to a security audit of the port. Usually - missing. -/usr/ports/infrastructure: - paraphernalia around the ports tree -/usr/ports/infrastructure/db/network.conf: - your local network configuration (ftp sites) -/var/db/pkg: - installed ports, see pkg_add(1). -/usr/local (LOCALBASE): - where normal ports install themselves. - -Other tweaks -============ -NO_IGNORE: coerce fetch, build, install... into doing their job even though -there might be a good reason not to. Good reasons include BROKEN, -ONLY_FOR_ARCH, IS_INTERACTIVE in BATCH mode. This is a dangerous option. - -Keeping up with the Jones, ports as a moving target -=================================================== -The OpenBSD ports tree is growing from release to release. It needs -people to write and test new ports. -Like for src, you can choose to live on the bleeding edge by updating -your ports dir thru cvs or ftp, and contribute bug-reports. You must -update both ports and src in synch. - -If you prefer to stay with a stable release, we try to make sure -the distfiles for a given release stay on the OpenBSD site between -releases. - -No matter how fast we update the tree it seems that we are always -behind. There are always new versions of software out there, without -an existing port. Very often, no one had time to update the port yet, -or it is very likely that the new version has not been tested enough -yet to deem it reasonable to upgrade the port. - -You may wish to contribute, by updating ports or creating new ports. -please visit - - http://www.openbsd.org/porting.html - -and always remember to communicate with OpenBSD project members on -ports@openbsd.org. Why create a brand new shiny port to discover that -someone was already working on it, and they committed their new version -ten minutes before you announced yours ? - -$OpenBSD: README,v 1.16 2003/09/23 01:40:26 pvalchev Exp $ +$OpenBSD: README,v 1.17 2004/07/25 00:15:32 espie Exp $