Chapter 8 The Website

Table of Contents
8.1 Preparation
8.2 Build the Web Pages from Scratch
8.3 Install the Web Pages into Your Web Server
8.4 Environment Variables

8.1 Preparation

Use a disk with sufficient free space. You may need anything from 200 MB to over 500 MB, depending on the method you choose. This space will hold the SGML tools, a subset of the CVS tree, temporary build space and the installed web pages.

Note: Make sure your documentation ports are up to date! When in doubt, remove the old ports using pkg_delete(1) command before installing the port. For example, we currently depend on jade-1.2 and if you have installed jade-1.1, please do:

# pkg_delete jade-1.1

There are two methods to get the files required for the website build:

8.1.1 Simple Method: Using csup

The csup command is part of the base system and already used extensively by most people for updating the Ports Collection. The following sample supfile can be used to obtain a checkout of the files required for the website build:

#
# This file checks out all collections required to rebuild
# the FreeBSD website
#
# Use the nearest CVSup mirror
# listed at http://www.freebsd.org/doc/handbook/mirrors.html.

*default host=cvsup10.FreeBSD.org
*default base=/var/db
*default prefix=/usr/build
*default release=cvs tag=.
*default delete use-rel-suffix
*default compress

# This will retrieve the entire doc branch of the FreeBSD repository.

doc-all

# This will retrieve the files required for the website

www

# This will retrieve some basic ports info required for the build

ports-base

You should, of course, change the default host entry to a CVSup mirror near your location, and the default prefix entry to the location where you intend to store the checked out files. Save this file as e.g. doc-www-supfile, and then execute the following command:

# csup -g -L2 doc-www-supfile

When this command finishes, you will find the directories doc/, www/ and ports/ under the directory you specified in default prefix (/usr/build in our example). We will use this same directory for the build process itself, so it would be better to use a filesystem with sufficient free space.

That's it! You can now proceed with the website build.

8.1.2 Advanced Method: Maintaining a Local CVS doc/www Repository

This method will give you more advanced options, but will require you to install the net/cvsup-without-gui port or package.

Note: The net/cvsup-without-gui port has a build dependency on lang/ezm3, a Modula 3 compiler. This compiler takes quite some time to build, and since most people will not need it for anything else, it is perhaps best to use a package to install CVSup.

The CVSup utility has a special “cvs” mode that allows the retrieval of the “,v” files that make up a CVS repository. This function is not currently available in csup. For detailed information on CVSup, please read the CVSup introduction in the FreeBSD Handbook.

The supfile shown below will fetch the cvs collections required for the website build, and create a local CVS repository:

#
# This file will create a local CVS repository
# with the collections required for a complete
# FreeBSD website rebuild. It should be used with
# cvsup *only* (csup will not work)

*default host=cvsup10.FreeBSD.org
*default base=/var/db
*default prefix=/usr/dcvs
*default release=cvs
*default delete use-rel-suffix
*default compress

# The following collections are needed
# for the website build

ports-base
doc-all
www

# These collections are needed
# for CVS functionality

cvsroot-common
cvsroot-ports
cvsroot-doc

You should, of course, change the default host entry to a CVSup mirror near your location, and the default prefix entry to the location where you intend to store the repository files. Save this file as e.g. doc-www-cvsfile, and then execute the following command:

# cvsup -g -L2 doc-www-cvsfile

It is also advisable to set the CVSROOT environment variable in your shell's startup files. For example, use the following entry in your ~/.cshrc file:

setenv CVSROOT /usr/dcvs

If you set this variable, you may omit the -d argument (shown below) when performing repository operations using the cvs command.

Currently, you will need more than 400 MB of free space to host the repository files. An additional 200 MB will be needed for the temporary build space. Once the cvsup command completes, you are ready to check out the files to your build directory:

# mkdir /usr/build
# cd /usr/build
# cvs -d /usr/dcvs -R co -AP doc www ports

The above command is consistent with the way csup checks out the files from the CVSup servers. When it completes, you will have a build directory with similar contents to the one used in the simple csup method.

You can continue to use the cvsup command shown above, to update your local CVS repository on a regular basis. After the initial somewhat lengthy download, regular updates will only take a few minutes.