6.8. Using Perl

If MASTER_SITES is set to CPAN, the correct subdirectory is usually selected automatically. If the default subdirectory is wrong, CPAN/Module can be used to change it. MASTER_SITES can also be set to the old MASTER_SITE_PERL_CPAN, then the preferred value of MASTER_SITE_SUBDIR is the top-level hierarchy name. For example, the recommended value for p5-Module-Name is Module. The top-level hierarchy can be examined at cpan.org. This keeps the port working when the author of the module changes.

The exception to this rule is when the relevant directory does not exist or the distfile does not exist in that directory. In such case, using author's id as MASTER_SITE_SUBDIR is allowed. The CPAN:AUTHOR macro can be used, which will be translated to the hashed author directory. For example, CPAN:AUTHOR will be converted to authors/id/A/AU/AUTHOR.

When a port needs Perl support, it must set USES=perl5 with the optional USE_PERL5 described in the perl5 USES description.

Table 6.4. Read-Only Variables for Ports That Use Perl
Read only variablesMeans
PERLThe full path of the Perl 5 interpreter, either in the system or installed from a port, but without the version number. Use this when the software needs the path to the Perl interpreter. To replace #!lines in scripts, use USES=shebangfix.
PERL_VERSIONThe full version of Perl installed (for example, 5.8.9).
PERL_LEVELThe installed Perl version as an integer of the form MNNNPP (for example, 500809).
PERL_ARCHWhere Perl stores architecture dependent libraries. Defaults to ${ARCH}-freebsd.
PERL_PORTName of the Perl port that is installed (for example, perl5).
SITE_PERLDirectory name where site specific Perl packages go. This value is added to PLIST_SUB.


Ports of Perl modules which do not have an official website must link to cpan.org in the WWW line of pkg-descr. The preferred URL form is http://search.cpan.org/dist/Module-Name/ (including the trailing slash).


Do not use ${SITE_PERL} in dependency declarations. Doing so assumes that perl5.mk has been included, which is not always true. Ports depending on this port will have incorrect dependencies if this port's files move later in an upgrade. The right way to declare Perl module dependencies is shown in the example below.

Example 6.5. Perl Dependency Example

For Perl ports that install manual pages, the macro PERL5_MAN3 and PERL5_MAN1 can be used inside pkg-plist. For example,


can be replaced with



There are no PERL5_MANx macros for the other sections (x in 2 and 4 to 9) because those get installed in the regular directories.

Example 6.6. A Port Which Only Requires Perl to Build

As the default USE_PERL5 value is build and run, set it to:

USES=		perl5
USE_PERL5=	build

Example 6.7. A Port Which Also Requires Perl to Patch

From time to time, using sed(1) for patching is not enough. When using perl(1) is easier, use:

USES=		perl5
USE_PERL5=	patch build run

Example 6.8. A Perl Module Which Needs ExtUtils::MakeMaker to Build

Most Perl modules come with a Makefile.PL configure script. In this case, set:

USES=		perl5
USE_PERL5=	configure

Example 6.9. A Perl Module Which Needs Module::Build to Build

When a Perl module comes with a Build.PL configure script, it can require Module::Build, in which case, set

USES=		perl5
USE_PERL5=	modbuild

If it instead requires Module::Build::Tiny, set

USES=		perl5
USE_PERL5=	modbuildtiny

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.