4.4 The distribution files

4.4.1 DISTNAME

DISTNAME is the name of the port as called by the authors of the software. DISTNAME defaults to ${PORTNAME}-${PORTVERSION}, so override it if necessary. DISTNAME is only used in two places. First, the distribution file list (DISTFILES) defaults to ${DISTNAME}${EXTRACT_SUFX}. Second, the distribution file is expected to extract into a subdirectory named WRKSRC, which defaults to work/${DISTNAME}.

4.4.2 MASTER_SITES

Record the directory part of the FTP/HTTP-URL pointing at the original tarball in MASTER_SITES. Do not forget the trailing slash (/)!

The make macros will try to use this specification for grabbing the distribution file with FETCH if they cannot find it already on the system.

It is recommended that you put multiple sites on this list, preferably from different continents. This will safeguard against wide-area network problems, and we are even planning to add support for automatically determining the closest master site and fetching from there!

If the original tarball is part of one of the popular archives such as X-contrib, GNU, or Perl CPAN, you may be able refer to those sites in an easy compact form using MASTER_SITE_* (e.g., MASTER_SITE_XCONTRIB and MASTER_SITE_PERL_GNU). Simply set MASTER_SITES to one of these variables and MASTER_SITE_SUBDIR to the path within the archive. Here is an example:

    MASTER_SITES=         ${MASTER_SITE_XCONTRIB}
    MASTER_SITE_SUBDIR=   applications

These variables are defined in /usr/ports/Mk/bsd.sites.mk. There are new archives added all the time, so make sure to check the latest version of this file before submitting a port.

The user can also set the MASTER_SITE_* variables in /etc/make.conf to override our choices, and use their favorite mirrors of these popular archives instead.

4.4.3 EXTRACT_SUFX

If you have one distribution file, and it uses an odd suffix to indicate the compression mechanism, set EXTRACT_SUFX.

For example, if the distribution file was named foo.tgz instead of the more normal foo.tar.gz, you would write:

    DISTNAME=      foo
    EXTRACT_SUFX=  .tgz

The USE_BZIP2 and USE_ZIP variables automatically set EXTRACT_SUFX to .bz2 or .zip as necessary. If neither of these are set then EXTRACT_SUFX defaults to .tar.gz.

You never need to set both EXTRACT_SUFX and DISTFILES.

4.4.4 DISTFILES

Sometimes the names of the files to be downloaded have no resemblance to the name of the port. For example, it might be called source.tar.gz or similar. In other cases the application's source code might be in several different archives, all of which must be downloaded.

If this is the case, set DISTFILES to be a space separated list of all the files that must be downloaded.

    DISTFILES=     source1.tar.gz source2.tar.gz

If not explicitly set, DISTFILES defaults to ${DISTNAME}${EXTRACT_SUFX}.

4.4.5 EXTRACT_ONLY

If only some of the DISTFILES must be extracted--for example, one of them is the source code, while another is an uncompressed document--list the filenames that must be extracted in EXTRACT_ONLY.

    DISTFILES=     source.tar.gz manual.html
    EXTRACT_ONLY=  source.tar.gz

If none of the DISTFILES should be uncompressed then set EXTRACT_ONLY to the empty string.

    EXTRACT_ONLY=

4.4.6 PATCHFILES

If your port requires some additional patches that are available by FTP or HTTP, set PATCHFILES to the names of the files and PATCH_SITES to the URL of the directory that contains them (the format is the same as MASTER_SITES).

If the patch is not relative to the top of the source tree (i.e., WRKSRC) because it contains some extra pathnames, set PATCH_DIST_STRIP accordingly. For instance, if all the pathnames in the patch have an extra foozolix-1.0/ in front of the filenames, then set PATCH_DIST_STRIP=-p1.

Do not worry if the patches are compressed; they will be decompressed automatically if the filenames end with .gz or .Z.

If the patch is distributed with some other files, such as documentation, in a gzip'd tarball, you cannot just use PATCHFILES. If that is the case, add the name and the location of the patch tarball to DISTFILES and MASTER_SITES. Then, use the EXTRA_PATCHES variable to point to those files and bsd.port.mk will automatically apply them for you. In particular, do not copy patch files into the PATCHDIR directory--that directory may not be writable.

4.4.7 Multiple distribution files from different sites

Some applications consist of multiple distribution files that must be downloaded from a number of different sites. For example, Ghostscript consists of the core of the program, and then a large number of driver files that are used depending on the user's printer. Some of these driver files are supplied with the core, but many others must be downloaded from a variety of different sites.

To support this, each entry in DISTFILES may be followed by a colon and a ``tag name''. Each site listed in MASTER_SITES is then followed by a colon, and the tag that indicates which distribution files should be downloaded from this site.

For example, consider an application with the source split in to source1.tar.gz and source2.tar.gz, which must be downloaded from two different sites. The port's Makefile would include lines like this:

    MASTER_SITES= ftp://ftp.example1.com/:source1 \
                  ftp://ftp.example2.com/:source2
    DISTFILES=    source1.tar.gz:source1 \
                  source2.tar.gz:source2

Multiple distribution files can have the same tag. Continuing the previous example, suppose that there was a third distfile, source3.tar.gz, that should be downloaded from ftp.example2.com. The Makefile would then be written like this.

    MASTER_SITES= ftp://ftp.example1.com/:source1 \
                  ftp://ftp.example2.com/:source2
    DISTFILES=    source1.tar.gz:source1 \
                  source2.tar.gz:source2 \
                  source3.tar.gz:source2

4.4.8 DIST_SUBDIR

Do not let your port clutter /usr/ports/distfiles. If your port requires a lot of files to be fetched, or contains a file that has a name that might conflict with other ports (e.g., Makefile), set DIST_SUBDIR to the name of the port (${PORTNAME} or ${PKGNAMEPREFIX}${PORTNAME} should work fine). This will change DISTDIR from the default /usr/ports/distfiles to /usr/ports/distfiles/DIST_SUBDIR, and in effect puts everything that is required for your port into that subdirectory.

It will also look at the subdirectory with the same name on the backup master site at ftp.FreeBSD.org. (Setting DISTDIR explicitly in your Makefile will not accomplish this, so please use DIST_SUBDIR.)