[BACK]Return to README CVS log [TXT][DIR] Up to [local] / ports

Diff for /ports/README between version 1.11 and 1.18

version 1.11, 2001/11/01 22:59:37 version 1.18, 2009/03/13 10:03:29
Line 1 
Line 1 
   Documentation for the ports tree: ports(7), packages(7), mirroring-ports(7),
   library-specs(7), bsd.port.mk(5), port-modules(5).
   
                 Welcome to the OpenBSD ports collection.  See also http://www.openbsd.org/porting.html
         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 Weisberger <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 key=<keyword> describe  
 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/db/essentials, 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/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 version 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$  $OpenBSD$
Legend:
Removed from v.1.11  
changed lines
  Added in v.1.18