12.06-Using the ports collection
Description: FreeBSD Installer Guide
Keywords: FreeBSD, freebsd, FBSD, fbsd, Installer Guide, how-to, book, manual, guide, installing, configuring, aide step by step, instructions, from scratch, Unix

# FreeBSD Stable Release 6.0 Installer Guide

______________________________________________________________________

# Using the Ports Collection

Installer Note:

The cvsup command uses the tcp port 5999. It’s a mandatory requirement that your firewall rules allow the tcp port 5999 bi-directional access to the public Internet. Otherwise you will never be able to use the ports collection.

Before you can do anything with the ports collection you have to install the cvsup program on your FBSD system. The cvsup program handles accessing the ports cvsup server and the in mass downloading of the config files for all the applications in a category of the port collection you selected. It's also used to download the current source code that comprises the FBSD operating system when you want to do an operating system upgrade in place. For some unknown reason the basic FBSD install does not come with this very important program bundled in.

You can download and install the package version of cvsup with this command. Be sure your firewall allows passive FTP access to the public Internet.

pkg_add -rv cvsup-without-gui

rehash

Configure the cvsup control file. There are examples of different cvsup control files you can use. To see them:

cd /usr/share/examples/cvsup/

ls

Now copy this one to customize and use

cp ports-supfile /etc/

ee /etc/ports-supfile

This file has loads of comments at the beginning. You can delete all those comments until you come to this line:

*default host=CHANGE_THIS.FreeBSD.org

Replace the 'CHANGE_THIS.FreeBSD.org' with a real mirror site name.

See

http://www.freebsd.org/doc/handbook/mirrors.html for a complete listing of mirror sites. The statement should look something like this:

*default host=cvsup1.us.FreeBSD.org

Leave the rest of the *default statements as is and look for this statement:

ports-all

This statement means you want to download the complete ports collection. Just look a little further down into the file and you will see all the categories this statement will download. You really don't want to do this!

Comment out the ports-all statement and uncomment the ports-base statement, because it contains all the behind-the-scene makefiles and the ports index file, all of which are mandatory for the cvsup ports collection to function on your FBSD system.

Execute the cvsup program to download the ports-base category config files:

cvsup -g -L 2 /etc/ports-supfile

The -g option means no GUI interface, the -L 2 means list verbose level 2 and /etc/ports-supfile points to the cvsup config file to use.

If you get a message 'Connection Refused' hit ctrl and 'c' keyboard keys at same time to terminate cvsup, because the server is busy right then. Re-edit the ports-supfile file and change the number in the server name to try a different server until you find one that is available, or use this format of the command:

cvsup -g -L 2 -h 'cvsup7.us.FreeBSD.org' /etc/ports-supfile

After this completes, issue the 'rehash' command to enable all the functions downloaded as part of ports-base.

# Downloading Makefiles for Single Port

There is no mandatory requirement to populate your system's hard drive with config files for the whole complete 10,200 ports collection, or even to populate your system's hard drive with config files for a complete category. All you really need is the port config files for the single port you want to install and any ports it depends on to function, if any. Some ports have a whole lot of dependencies.

You should have already created your list of port download names and their categories as instructed in Finding the Application Download Name Section.

So following our example we have www/apache13 and its dependents textproc/expat2 and devel/libtool13.

Edit your /etc/ports-supfile file:

Be sure all the ports-whatever statements are commented out except for the port-www, port-textproc, and port-devel statements which should be uncommented.

Use this format of the cvsup command to download only config files for the selected ports:

cvsup -g -L 2 -i ports/www/apache13 /etc/ports-supfile
cvsup -g -L 2 -i ports/textproc/expat2 /etc/ports-supfile
cvsup -g -L 2 -i ports/devel/libtool13 /etc/ports-supfile

or this format which does the same thing with one execution of the cvsup program:

cvsup -g -L 2 –i ports/www/apache13 \
-i ports/textproc/expat2 \
-i ports/devel/libtool13 \
/etc/ports-supfile

At the completion:

cd /usr/ports # change into directory

ls -l # long list of directory contents

cd www/apache13 # change into directory

make install clean # Install the port

This last command will read the apache port config files; determine it has dependecies to install first: download the expat2 dependent libtool13 distribution source file, compile and install it; then download the expat2 distribution source file, compile and install it; and then download the apache13 distribution source file, compile and install it; and finish up by posting them as installed into the ports/package install history database. During this process you will see massive messages roll off your screen. There is no log to review later if there is a problem installing.

What I do to create a log of the install process; is start the script program to capture everything displayed to the console screen to a file for later review before issuing the ‘make install’ command. You do that like this:

script /root/apache.install.list # you can name the file anything you want
exit # exit to stop script recording.

I also like to run the 'make install clean' command on each of the dependent ports manually, starting with the lowest dependency, so I have individual install logs for each one instead of letting the primary port do it all for me automatically. This helps greatly in limiting the scope of debugging install problems.

Installer Note:

Using the cvsup process presented above only positions you for the initial install of your selected ports. After a time you may be interested in checking if your installed collection has updated versions available. To do that you have to download the ports-base category to get a current INDEX file, followed by the use of the pkg_version command. If you find installed ports that have an updated version available that you want to make your system use, you will have to download that ports config files again to get the current port config file's content. Then delete the installed port binary execution files using the pkg_delete command and run the make install clean command on the selected port. For convenience you may want to save the cvsup commands you used during the creation of your initial port config file inventory in a file /etc/cvsup.cmds so you can use it to update all your port config files in mass some time in the future. You will have to do some manual editing of the file’s contents to create a command stream that will execute correctly, but at least you will have all the –i statements for all your ports so you will not have to do all that research work again. An alternative is to use the following script as a template, making the appropriate changes for each port application you want, naming the script with a name that identifies its purpose and saving it to /root/bin, so you can use it in the future to update the ports config file contents.

# Fetch Port Config Files Script

The following script is an example of a method to further simplify the port config downloading process. It packages the whole process into a script which you can name and save in /root/bin.

ee /root/bin/port.apache13.cvsup
#! /bin/sh
# This script downloads the port config files for Apache13
# and all its dependencies.
echo ' '
echo 'port.apache13.cvsup script processing starting '
echo ' '
# Load script symbolic field with path & file name
cvsupfile=/root/temp.cvsupwork.file
# Check to see if file exists & delete it if it does
[ -e "$cvsupfile" ] && rm -f "$cvsupfile"
# Load instream data to file until EOD line.
cat >> "$cvsupfile" <<EOD
*default base=/usr
*default release=cvs
*default delete use-rel-suffix
*default host=cvsup11.FreeBSD.org
*default tag=.
ports-www
ports-textproc
ports-devel
EOD
# Display contents of loaded file to screen for testing
#cat $cvsupfile
# DO the cvsup to download just the selected port config files
cd /usr/ports/
cvsup -g -L 2 –i ports/www/apache13 \
-i ports/textproc/expat2 \
-i ports/devel/libtool13 \
"$cvsupfile"
# Delete file we are done with it
rm -f "$cvsupfile"
echo ' '
echo 'port.apache13.cvsup script processing completed '
echo ' '

You will have to issue the chmod command to make the script executable.

chmod 700 /root/bin/port.apache13.cvsup

# Ports/Package Install History Database Commands

There are five package commands; two are specific to the package applications and the remaining apply to both the installed ports and installed packages. I am not going into details about the commands, because the man pages are pretty clear and easy to understand. Where xx is the port/package name.

pkg_add xx # Fetch package from server and install it,
# or install package you created from port.
pkg_create xx # Create package out of port you have installed
pkg_info xx # Create list of installed ports and packaged on your
# system from the installed software history database.
pkg_delete xx # Delete installed port or package. Uses the name
# from the pkg_info list display.
pkg_version xx # List version info about installed software from
# installed software database. This command compares
# packages version and port versions to the
# /usr/ports/index file to determine if they are out
# of date. For an installed package only environment
# the index file has never been downloaded, so
# this command has no relevance. For installed ports
# environment the ports-base category has to be
# recently downloaded to get a current /usr/ports/index
# before this command has relevance.

pkg_info xx\* # To find out which packages/ports are dependent on it.

# Port Make Commands

The 'man make' info is not the correct place to look for the 'make sub-commands' for installing ports. Instead use the 'man ports' page instead. It's very important that you understand that for the make command to be successful, all the config files for all the dependencies and all their dependencies have to be on your system’s hard drive in the correct directory tree layout. If you missed downloading one of the sub-dependency's config files then the parent port does not know it's missing and you will get compile errors for something missing.
You must cd into the directory of the port you want to install before executing any of the following commands.
make install # Normal way to install port
make install clean # Remove the expanded source code,
# including the dependencies at completion
make install distclean # Remove expanded source code &
# distribution files, including the
# dependencies at completion
make all-depends-list # List all dependent ports
make fetch # This will fetch the distribution file
make fetch-recursive # This will fetch all the distribution
# files of the port and for all its
# dependencies.
make checksum-recursive # This will fetch all the distribution
# files of the port and for all its
# dependencies and checksums them.

You must cd into the /usr/ports directory before executing the search commands.

The make search command reads the /usr/ports/INDEX file for the search argument. It’s imperative that the INDEX file is current and up to date with the INDEX file on the FBSD cvsup server. You have to cvsup the ports-base category to download the current INDEX file. The INDEX file does not contain the download port names. It contains the port names with the version suffixes. The search option displays all the port's dependencies. You will have to search on the named dependencies to find if it has dependencies or not. This is a good way to acquire the info needed to verify you have all of the primary port's interdependences coded in cvsup commands before trying to download all the ports config files.

make search name= # Search the INDEX file port names.
make search key= # Search the INDEX file port name,
# comments, and dependencies

______________________________________________________________________

This FreeBSD Installer Guide is an public domain HOW-TO. This content may be reproduced, in any form or by any means, and used by all without permission in writing from the author.