===================================================================
RCS file: /cvsrepo/anoncvs/cvs/ports/README,v
retrieving revision 1.16
retrieving revision 1.17
diff -c -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 ****
  
! 		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
  
! 
! ======================================================================
! 
! 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 <brad@openbsd.org>, Christian Weisgerber <naddy@openbsd.org>, 
! Marc Espie <espie@openbsd.org>.
! 
! 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=<keyword>
! 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/<category>/<portname>:
! 	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/<category>/<portname>/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/<category>/<portname>/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 $
--- 1,6 ----
+ Documentation for the ports tree: ports(7), packages(7), mirroring-ports(7),
+ bsd.port.mk(5).
  
! See also http://www.openbsd.org/
  
! $OpenBSD: README,v 1.17 2004/07/25 00:15:32 espie Exp $