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.
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.
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-L2doc-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.
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-L2doc-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-Rco-APdoc 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.