FreeBSD Documentation Project Primer for New Contributors
Prev |  | Next

# Chapter 8 The Website

# 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:

- Use `csup` to get a local copy of the files from a CVSup server. This is the easiest method, and does not require installation of additional software. The supfile presented in the next section will always checkout the latest version of the required files. This is sufficient if you are simply rebuilding the website and do not intend to commit any changes.

  > Note: csup(1) became part of the base system in FreeBSD 6.2-RELEASE. If you are using an earlier version of FreeBSD you will need to install `net/csup` from the Ports Collection.

- Use `cvsup` in “cvs” mode to create and maintain a local CVS repository with the required files. This will require you to install a program like `net/cvsup-without-gui`, but it is a more flexible method if you need to have quick access to different revisions of the doc/www files, revision histories, or if you intend to commit changes to the central FreeBSD CVS repository.

## 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.

Prev | Home | Next
FreeBSD Documentation Project make includes |  | Build the Web Pages from Scratch