-*- mode: outline -*-
$Id: ports_packages.txt,v 1.2 2009/09/21 19:21:41 acc Exp $

BSD Ports and Packages

Copyright (c) 2004 GUBUG.  All rights reserved.  Redistribution and
use in source and binary forms, with or without modification, are
permitted subject to terms described in the BSD license
(http://gubug.org/license.php).  BSD Daemon Copyright 1988 by
Marshall Kirk McKusick.  Used with permission.  All Rights Reserved.
All trademarks are the property of their respected owners.

* Preliminaries

- originally written by Jordan Hubbard of FreeBSD, later ported to NetBSD (as
  pkgsrc) and OpenBSD

** Ports vs. packages

- ports:
  - typically built from source (but not always!)
  - binaries are tailored to your machine, so they usually run faster
  - highly customizable
  - pay for it in CPU cycles

- packages:
  - pre-built binaries
  - generic: compiled on a designated build machine without optimizations
  - very little customizability
  - quick and easy installation

** Features

- FreeBSD:
  - nearly 12,000 ports
  - mostly stable, well-organized
  - multiple ports needed for multiple versions of the same port
  - architectures:
    - <= 4.x: alpha and i386
    - 5.x: alpha, amd64, i386, ia64, pc98, sparc64

- pkgsrc:
  - over 5,000 packages
  - mostly portable
  - base XFree86 is the responsibility of the platform, not pkgsrc!
  - (experimental) pkgviews needed for multiple versions of the same port
  - platforms: runs best on NetBSD, but (mostly) works under AIX, BSD/OS,
    Darwin (MacOS X), FreeBSD, Interix (Microsoft Services for Unix), IRIX,
    Linux, OpenBSD and Solaris
  - NetBSD architectures (``ports''): 46 stable (1.6.2), 13 experimental
    (-current)

- OpenBSD:
  - nearly 3,000 ports
  - mostly secure: *not* audited for security, but security is a priority for
    inclusion in the tree
  - SUBDIRs needed for multiple versions of the same port
  - architectures: alpha, amd64, arm, hppa, i386, m68k, m88k, powerpc, sparc,
    sparc64 and vax

- Metapkg:
  - DarwinPorts:
    - over 2,000 ports
    - headed by jkh and many others originally from the FreeBSD project
    - reimplementation of the FreeBSD ports tree in Tcl
    - uses port images for installing multiple versions of the same port
    - ports distributed strictly in source form ATM
    - No support for multiple port versions?
    - platforms: Darwin, MacOS X, FreeBSD, Linux
  - Fink:
    - over 4,000 ports
    - apt-get + dpkg + dselect ported from Debian Linux
    - multiple ports needed for multiple versions of the same port
    - platforms: Darwin, MacOS X
  - TigerCow?:
    - over 16,000 ebuilds + nearly 8,000 packages, many of which are masked
    - portage ported from Gentoo Linux
    - very similar to the port trees found in (Free|Open)BSD, but also Linuxish
    - architectures (Gentoo): alpha, amd64, arm, hppa, ia64, macos, mips, ppc,
      ppc64, ppc macos, s390, sparc, x86, x86 obsd, x86 fbsd

- OSXGNU:
  - nearly 2000 ports
  - Unix ports to MacOS X's native package installer system
  - platforms: MacOS X

* Ports

- always remember to READ each port's Makefile (or equivalent) before
  installing!!!

** FreeBSD

- http://www.freebsd.org/handbook/ports-using.html

- the ports tree is rooted in $PORTSDIR (/usr/ports).

- the simplest example of installing a port is simply a matter of:
  # cd $PORTSDIR/$CATEGORY/$PORTNAME
  # make install

- because it relies on make(1), arguments and variables can be specifed as
  usual:
  # make -DOPTION <target>
  or
  # make VARIABLE=foo <target>

- make <target> works almost anywhere (mostly where it makes sense):
  - $PORTSDIR/mail/postfix
  - $PORTSDIR/mail
  - $PORTSDIR

- a port consists of:
  - a Makefile
  - patches (in files/ or in the Makefile)
  - pkg-* files:
    - pkg-descr (verbose description)
    - pkg-plist (the packing list: a complete list of the files and directories
      that the port installs)
    - pkg-message (a message for the installer)
    - pkg-install (run twice by pkg_add)
    - pkg-deinstall (run twice by pkg_delete)
    - pkg-req (``requirements'' script that determines if (de)installation
      should occur)
  - checksums in distinfo
  - some ports include a scripts/ directory, which calls dialog(1)

*** Build targets

- fetch: get the distribution (usually the sources)
- checksum: verify the distribution
- depends: install/compile dependencies
- extract: unpackage the distribution using appropriate tool: tar, unrpm, &c.
- patch: apply patches (above)
- configure: configure port for OS (usually, run ./configure)
- build / all: build (usually, compile) the port
- install: install the executibles and register

*** Utility targets

- informational:
  - (all|build|package|run)-depends-list: list dependencies
  - describe: generate a one line description as used in $PORTSDIR/INDEX
  - fetch-list: list files to be fetched
  - maintainer: who maintains this port?
  - package-links: create symlinks for ports in multiple categories
  - delete-package-links: delete symlinks for ports in multiple categories
  - readmes: create README.html for port
  - search: search $PORTSDIR/INDEX for port by key (name/comment/dependencies)
    or name

- functional:
  - fetch-recursive: fetch this port and dependencies
  - clean: clobber $WRKDIR, recursively
  - deinstall: remove an installed port
  - distclean: clean + clobber $DISTFILES $PATCHFILES, non-recursively
  - package: create binary package from port
  - package-recursive: create binary package for port and depending ports
  - reinstall: reinstall a port
  - repackage: recreate binary package
  - update-patches: create or update patches for a port using diff(1) between
    file and file.orig.

*** Newer targets

- config (prior to extract, patch, configure, build, install and package):
  configure options using $DIALOG (to eliminate the need for scripts/)
- showconfig: display options
- rmconfig: remove options

*** Customizing

- make options:
  - -DNO_CHECKSUM: skip checksum target
  - -DNO_DEPENDS: skip depends target
  - -DNOCLEANDEPENDS: don't clean recursively
  - -DBATCH: skip $DIALOG from scripts/ or config target
  - -DINTERACTIVE: only install ports with $DIALOG
  - -DNO_IGNORE: force build attempt, even if broken
  - -DWITH_* and -DWITHOUT_*: options for individual ports (read port's
    Makefile); globals include:
    - -DWITH_APACHE2: prefer Apache 2.x
    - -DWITH_GHOSTSCRIPT_AFPL: prefer AFPL Ghostscript over GNU
    - -DWITH_GNOME: build with gnome support
    - -DWITH_GNUSTEP_XDPS: use xdps instead of xlib
    - -DWITH_GNUSTEP_LIBART: use libart instead of xlib
    - -DWITH_OPENSSL_BASE: use FreeBSD's OpenSSL
    - -DWITH_OPENSSL_PORT: use OpenSSL from ports (can lead to headaches)
    - -DWITH_OPENSSL_BETA: use OpenSSL beta (for the truly paranoid)

- make variables:
  - directories:
    - $DESTDIR: where installationsshould be rooted
    - $X11BASE ($DESTDIR/usr/X11R6): where X11 ports are installed
    - $LINUXBASE ($DESTDIR/compat/linux): where Linux ports are installed
    - $LOCALBASE ($DESTDIR/usr/local): where non-X11 ports are installed
    - $PREFIX: where *this* port is installed
    - $PORTSDIR (/usr/local): the root of the ports tree
    - $DISTDIR ($PORTSDIR/distfiles): where distributions are stored
    - $PACKAGES ($PORTSDIR/packages): where packages are stored
    - $WRKDIR ($WRKDIRPREFIX${.CURDIR}/work): where distributions are extracted
  - fetch:
    - $FETCH_(BEFORE|AFTER)_ARGS: arguments to $FETCH_CMD
    - $FETCH_ENV: $FETCH_CMD's env
  - depends:
    - $(EXTRACT|PATCH|FETCH|BUILD|RUN|LIB|)_DEPENDS: list of port's
      dependencies
    - $CONFLICTS: ports this port conflicts with
  - extract:
    - $EXTRACT_(BEFORE|AFTER)_ARGS: arguments to $EXTRACT_CMD
  - configure:
    - $CONFIGURE_ARGS: arguments to $CONFIGURE_SCRIPT
    - $CONFIGURE_ENV: $CONFIGURE_SCRIPT's env
  - build / install:
    - $MAKE_ENV: $MAKE's env
    - $MAKE_ARGS: arguments to $MAKE
  - others:
    - $CATEGORIES: list of categories into which this port falls
    - $COMMENT: one line description of port
    - $PKG_DBDIR (/var/db/pkg): package registration directory
    - $PORT_DBDIR (/var/db/ports): where options are recorded
    - $OPTIONS: which WITH_* and WITHOUT_* options the port accepts
    - $SU_CMD (/usr/bin/su root -c): invoke superuser only for those parts that
      need it

- stored in /etc/make.conf (see the make.conf(5) man page and
  /etc/defaults/make.conf)

** pkgsrc

*** Installation

- http://www.netbsd.org/Documentation/pkgsrc/getting.html
- http://www.netbsd.org/Documentation/pkgsrc/platforms.html

*** Usage

- http://www.netbsd.org/Documentation/pkgsrc/using.html
- http://www.netbsd.org/Documentation/pkgsrc/binary.html

** OpenBSD

*** Installation

- http://www.openbsd.org/ports.html#Use

- the ports tree not installed by default---in fact, the install scripts cannot
  do it at all, so it must be done manually

- anoncvs (ports-stable or ports-current):
  - choose a CVSROOT from http://www.openbsd.org/anoncvs.html
  # cd $PORTSDIR/..
  # env CVS_RSH=`which ssh` cvs -d$CVSROOT get -P ports
- CD (ports-release):
  # tar xzf /mnt/ports.tar.gz -C $PORTSDIR/..
- FTP (ports-release):
  - choose an FTP mirror from http://www.openbsd.org/ftp.html
  # wget ${MIRROR_URL}/`uname -r`/ports.tar.gz
  # tar xzf ports.tar.gz -C $PORTSDIR/..

*** Maintenance

- stable branch:
  - http://www.openbsd.org/ports.html#stable
- current branch:
  - http://www.openbsd.org/ports.html#Life

*** Usage

- http://www.openbsd.org/ports.html#Example
- http://www.openbsd.org/ports.html#Advanced

- ``shamelessly stolen from the FreeBSD Ports Collection:''
  - relies on make(1)
  - usually just cd $PORTSDIR/$CATEGORY/$PORTNAME; make install
  - all build targets ported: fetch, checksum, depends, extract, etc.
  - ported utility targets: all-depends-list (as full-build-depends),
    (build|lib|run)-depends-list, deinstall, delete-package-links (as
    unlink-categories), describe, distclean, package, package-links (as
    link-categories), readmes, reinstall, repackage and readmes
  - ported variables: $BATCH, $CATEGORIES, $COMMENT, $CONFIGURE_ARGS,
    $CONFIGURE_ENV, $DESTDIR, $DISTDIR, $(FETCH|BUILD|RUN|LIB)_DEPENDS,
    $LOCALBASE, $MAINTAINER, $MAKE_ENV, $NO_CHECKSUM, $NO_DEPENDS, $NO_IGNORE,
    $NOCLEANDEPENDS (as $CLEANDEPENDS), $PACKAGES (as $PKGREPOSITORYBASE),
    $PKG_DBDIR, $PORTSDIR, $PREFIX, $SU_CMD (as $SUDO), $WRKDIR, $X11BASE

- differences:
  - structure:
    - patches stored in patches/ instead of files/
    - no pkg-{install,deinstall,req} in ports (only packages)
    - pkg-{descr,plist} files moved to pkg/DESCR and pkg/PLIST
    - much in $PORTSDIR/infrastructure: .included Makefiles in
      $PORTSDIR/infrastructure/mk
    - options and variables stored in /etc/mk.conf
  - targets:
    - clean=(work|bulk|depends|flavors|dist|install|package|readmes|sub|
      packages): more ways to clean
    - distpatch: apply distribution patches only
    - rebuild: re-run make build
    - regress: run regression tests for the port
    - search: obsolecent; use locate(1)
    - show='name1 name2 ...': show the contents of the variables $name1,
      $name2, etc., e.g.:
      # make show=MAINTAINER
    - update-plist: update packing lists
  - options:
    - -DBIN_PACKAGES: do not rebuild if $WRKDIR is not present
    - -DBULK: build all targets in $BULK_TARGETS and clean afterward
    - -DNO_DEPENDS: don't build dependencies
    - -DREFETCH: force fetch even if distribution exists
    - -DTRUST_PACKAGES: assume the database of installed packages is correct
      (speed optomization)
    - -DUSE_SYSTRACE: systrace(1) during configure/build/fake
  - variables:
    - $BULK_TARGETS: targets to build in bulk
    - $COPTS / $CXXOPTS: appended to $CFLAGS and $CXXFLAGS
    - $HOMEPAGE: URL of port's homepage
    - $REGRESS_DEPENDS: regression testing dependencies
    - $REPORT_PROBLEM: passed to make with a shell fragment:
      # make REPORT_PROBLEM='qpage -p "Installed!"' install
    - $SKIPDIR: enable exceptions during recursion
  - features:
    - Flavors ($FLAVORS): analogous to OPTIONS:
      # env FLAVOR='mysql ldap' make install
    - MULTI_PACKAGES for componentization (pkg/DESCR-subpackage):
      # env SUBPACKAGE="-server" make install

** Metapkg

* Packages

** FreeBSD

- http://www.freebsd.org/handbook/packages-using.html

- pkg_add(1): install package(s)
- pkg_delete(1): uninstall package(s)
- pkg_update(1): update package

- pkg_info(1): stat package(s)
- pkg_version(1): stat package version(s)

- pkg_create(1): create a package given a packlist
- pkg_sign(1) / pkg_check(1): PGP sign / check package(s)

** pkgsrc

** OpenBSD

*** Maintenance

- http://www.openbsd.org/ports.html#Manage

*** Usage

- http://www.openbsd.org/ports.html#Get

- ported from FreeBSD

- differences:
  - pkg_add and pkg_delete accept the -f option with a keys argument, which is
    a comma-delimited
  - no -x (glob) option available---OTOH, version numbers are not required
  - -A (arch) option added to pkg_add for forcing architecture

- pkg_add(1): install package(s)
- pkg_delete(1): uninstall package(s)

- pkg_info(1): stat package(s)

- pkg_create(1): create a package given a packlist

* User interfaces

- *BSD:
  - command line:
    # ls -d $PORTSDIR/... (globs are useful here)
    # find $PORTSDIR ... (very flexible)
    - whereis(1) / locate(1)
    # make search
    - once installed, which(1)
  - readmes:
    - short description
    - long description
    - homepage
    - maintainer (FreeBSD)
    - dependencies

- FreeBSD:
  - http://www.freebsd.org/ports/ (alphabetical, categorical, searchable)
  - http://www.freshports.org/ (periodic updates, a la http://freshmeat.net/)
  - http://people.freebsd.org/~fenner/portsurvey/ (distfile survey)
  - http://portsmon.firepipe.net/ (statistics)

- pkgsrc:
  - http://www.pkgsrc.org/ (click on "Available Packages"; alphabetical,
    categorical)
  - http://pkgsrc.netbsd.se/ (alphabetical, categorical, chronological,
    searchable)

- OpenBSD:
  - http://www.openbsd.org/ports.html (ports by category, packages by platform)
  - http://uopp.berlios.de/ (categorical, no packages)
  - http://ports.puffy.nu/ (categorical, no packages, searchable, slightly
    outdated)
  - http://www.openbsdports.org/ (categorical, no packages, ads, dead?)

- Metapkg:
  - DarwinPorts:
    - http://darwinports.opendarwin.org/ports/ (alphabetical, categorical,
      searchable)
  - Fink:
    - http://fink.sourceforge.net/pdb/ (alphabetical, categorical, searchable)
    - FinkCommander
  - TigerCow?:
    - http://packages.gentoo.org/archs/macos/ (chronological, searchable)
    - http://packages.gentoo.org/ (by platform, categorical, chronological,
      searchable)

- OSXGNU:
  - OSXPM
    - doubles as a GUI BOM interface for earlier versions of OSX

* Essentials

For each port, the platforms on which it is available preceed as a comma-
separated list inside curlies.  The platforms are abbreviated to the first
letter, i.e., F == FreeBSD, M == Metapkg, O == OpenBSD, and P == pkgsrc.

- informational:
  - {F}misc/portell (easy access to pkg-descr)
  - {F}sysutils/fastest_cvsup (find the fastest CVSup server)
  - {F}sysutils/pkg_tree (display ports tree graphically)

- port developers:
  - {F}devel/portlint (best practices)
  - {F}devel/porttools (for would-be porters)
  - {F}sysutils/port-authoring-tools (meta-port for would-be porters)

- security:
  - {F}security/portaudit (am I secure?)
  - {F}security/portaudit-db (am I securely distributed?)
  - {F}security/vuxml (report insecurities)
  - {F}security/vxquery (query VuXML database)

- management:
  - {F}misc/porteasy (upgrade a branch)
  - {F}sysutils/libchk (check shared libraries)
  - {F}sysutils/pkg_cutleaves (trim unused ports)
  - {F}sysutils/pkg_install (FreeBSD 5.x pkg_* suite for FreeBSD <= 4.6)
  - {F}sysutils/pkg_install-devel (if encountering problems with 5.x pkg_*)
  - {F}sysutils/pkg_remove (a better pkg_delete)
  - {F}sysutils/port-maintenance-tools (meta-package)
  - {F}sysutils/portdowngrade (because the latest isn't always the greatest)
  - {F}sysutils/portmanager (the bleeding edge)
  - {F}sysutils/portsman (for the faint of heart)
  - {F}sysutils/portupgrade (*absolutely* essential)
  - {F}sysutils/qtpkg (for the *really* faint of heart)

- related:
  - {F,O}devel/ccache (speed up compiles dramatically):
    # mkdir -p /usr/staff/bin
    # sh <<HERE
    for i in cc cpp c++; do
      ln -s /usr/local/bin/ccache /usr/staff/bin/$i
    done
    HERE
    # cat >> /etc/make.conf <<HERE
    CC=/usr/staff/bin/cc
    CPP=/usr/staff/bin/cpp
    CXX=/usr/staff/bin/c++
    HERE
    # chgrp -R staff /usr/staff
    # find /usr/staff \( -type d -exec chmod 0775 {} \; \) \
    ? -or \( \! -type d -exec chmod -h 664 {} \; \)
    # chmod -h ug+x /usr/staff/bin/cc /usr/staff/bin/cpp /usr/staff/bin/c++
    # mkdir -p /usr/tmp/ccache
    # chmod 0755 /usr/tmp /usr/tmp/ccache
    # echo 'export CCACHE_DIR=/usr/tmp/ccache' >> /etc/profile
    # echo 'setenv CCACHE_DIR /usr/tmp/ccache' >> /etc/csh.cshrc
    # ccache -M 512M

- the future (?):
  - {F}devel/portmk ($PORTSDIR/Mk/bsd.port.mk replacement)
  - {F}sysutils/portindex ($PORTSDIR/INDEX replacement)

* References

- FreeBSD:
  - ports(7)
  - pkg_*(1)
  - make.conf(1)
  - The FreeBSD Handbook, Chapter 4:
    http://www.freebsd.org/handbook/ports.html
  - $PORTSDIR/Mk/bsd.port.mk
  - The FreeBSD Porter's Handbook:
    http://www.freebsd.org/doc/en/books/porters-handbook/
  - the freebsd-ports@freebsd.org mailing list:
    http://www.freebsd.org/handbook/eresources.html#ERESOURCES-MAIL

- pkgsrc:
  - packages(7)
  - mk.conf(5)
  - the pkgsrc home site:
    http://www.pkgsrc.org/
  - The pkgsrc Guide:
    http://www.netbsd.org/Documentation/pkgsrc/
  - pkgsrc Developers guide:
    http://www.netbsd.org/Documentation/pkgsrc/developers-guide.html

- OpenBSD:
  - ports(7)
  - packages(7)
  - pkg_*(1)
  - bsd.port.mk(5)
  - mk.conf(1)
  - The OpenBSD FAQ, Chapter 8:
    http://www.openbsd.org/faq/faq8.html#Ports
    http://www.openbsd.org/faq/faq8.html#Packages
    http://www.openbsd.org/faq/faq8.html#PortsvsPkgs
  - The OpenBSD Ports & Packages collection:
    http://www.openbsd.org/ports.html
  - $PORTSDIR/infrastructure/mk/bsd.port.mk
  - Building an OpenBSD Port:
    http://www.openbsd.org/porting.html
  - The OpenBSD Port Testing Guide:
    http://www.openbsd.org/porttest.html
  - the ports@openbsd.org mailing list:
    http://www.openbsd.org/mail.html

- Metapkg:
  - The Metapkg Alliance:
    http://www.metapkg.org/
  - DarwinPorts;
    - port(1)
    - porthier(7)
    - portfile(7)
    - portstyle(7)
    - DarwinPorts Guide:
      http://darwinports.opendarwin.org/docs/
    - DarwinPorts Home:
      http://darwinports.opendarwin.org/
    - the darwinports@opendarwin.org mailing list:
      http://www.opendarwin.org/mailman/listinfo/darwinports
  - Fink:
    - fink(8)
    - fink.conf(5)
    - Fink Documentation:
      http://fink.sourceforge.net/doc/
    - The Fink F.A.Q.:
      http://fink.sourceforge.net/faq/
    - Sao's Place:
      http://homepage.mac.com/sao1/fink/
    - APT HOWTO:
      http://www.debian.org/doc/user-manuals#apt-howto
    - dselect Documentation for Beginners:
      http://www.debian.org/doc/user-manuals#dselect
    - Fink home site:
      http://fink.sourceforge.net/
    - the Fink mailing lists:
      http://fink.sourceforge.net/lists/
  - TigerCow?:
    - Gentoo Manual, Chapter 2:
      http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=2
    - Gentoo Portage:
      http://www.gentoo-portage.com/
    - Gentoo for Mac OS X HOWTO:
      http://gentoo-wiki.com/Gentoo_MacOS
    - Portage Manual (obsoleted):
      http://www.gentoo.org/doc/en/portage-manual.xml
    - TigerCow? home site:
      http://www.metadistribution.org/macos/
    - the Gentoo mailing lists:
      http://www.gentoo.org/main/en/lists.xml
    - the Gentoo forums:
      http://forums.gentoo.org/

- OSXGNU:
  http://www.osxgnu.org/