===== What is DEFAULT_VERSIONS? =====

The %%FreeBSD%% Ports Framework supports multiple versions of the same software for those packages where such choice is desirable.

DEFAULT_VERSIONS is the mechanism that allows the user to set or override which version of software they want to be used **as the dependency for other ports**.

DEFAULT_VERSIONS support is most often added for those major software packages, where:

  * multiple versions are available, and
  * regularly required by users with different needs, and
  * where no //single// version may reasonably be set by a maintainer.

It is particularly useful for ports that depend on the software, and multiple versions are available, but they either:

  * Don't //require// a specific version, OR
  * Support a //range// of versions, OR
  * //Only// support a //specific// version

In summary, it provides users with extra choice and flexibility.

===== What software or ports supports it? =====

All software that currently support this mechanism are listed in [[https://cgit.freebsd.org/ports/tree/Mk/bsd.default-versions.mk|Mk/bsd.default-versions.mk]]. Among them are:

  * [[/Apache]]
  * BDB (deprecates WITH_BDB_VER make.conf option)
  * GCC
  * LUA
  * %%MySQL%%
  * [[/Perl]]
  * [[/Python]]
  * PHP
  * [[/PostgreSQL]]
  * [[/Ruby]]
  * SSL library selection (deprecates WITH_OPENSSL_PORT and OPENSSL_PORT make.conf options)
  * TCL

===== How do I use it? =====

''%%DEFAULT_VERSIONS%%'' is a make variable that takes one or more space-delimited ''%%name=version%%'' (key=value) pairs.

Supported software //names// are defined in [[https://cgit.freebsd.org/ports/tree/Mk/bsd.default-versions.mk|Mk/bsd.default-versions.mk]]. They are the string before the underscore in variables matching ''%%*_DEFAULT%%''. For example, ''%%PYTHON_DEFAULT%%'', ''%%PYTHON2_DEFAULT%%'' and ''%%PYTHON3_DEFAULT%%'' create the supported //names// ''%%python%%'', ''%%python2%%'' and ''%%python3%%'' respectively.

Users can override the "default versions", by specifying new values in:

  * ''%%/etc/make.conf%%''
  * Poudriere make.conf files (see poudriere(8%%))%%
  * In command-line make arguments or environment variables

==== Examples ====

Users might wish to specify 3.5 as default for the Python3 branch, by
defining ''%%DEFAULT_VERSIONS=python3=3.5.%%''

To set //both// %%PostgreSQL%% 9.4 and Python 3.5 (of the 3.x) branch, one would write:

''%%DEFAULT_VERSIONS+= pgsql=9.4 python3=3.5%%''

**Note:** The above specification sets 3.5 for the **Python 3** branch, but does not
override the overall Python default version. This can be done with:

''%%DEFAULT_VERSIONS+= python=3.5%%''

Note the difference between the use of **python=** versus **python3=**.

===== Special Considerations =====

==== MySQL Fork Selection through Version ====

When it comes to %%MySQL%% forks like Percona and %%MariaDB%%, they can be chosen by using specific version of %%MySQL%%. In other words, %%MySQL%% fork selection is encoded in "mysql" version for DEFAULT_VERSIONS. If we take a look at [[https://cgit.freebsd.org/ports/tree/Mk/Uses/mysql.mk|Mk/Uses/mysql.mk]], we can see that "m" in %%MySQL%% versions are for %%MariaDB%% and "p" are for Percona. As of July 2016 these versions are supported, visible in the bsd.default-versions.mk comment kept in sync with the code backing it in Uses/mysql.mk:

''%%# Possible values: 5.1, 5.5, 5.6, 5.7, 5.5m, 10.0m, 10.1m, 5.5p, 5.6p%%''

So, for example, to install and use %%MariaDB%% 10.1 for ports that need %%MySQL%%, we can use:

''%%DEFAULT_VERSIONS= mysql=10.1m%%''

==== SSL Library Selection ====

As of [[https://svnweb.freebsd.org/ports?view=revision&revision=416965|revision 416965]] selection of the SSL library to build against has moved to DEFAULT_VERSIONS instead of using dedicated WITH_ options. This enables the //ssl=// entry and a choice between base %%OpenSSL%% or ports' %%OpenSSL%%, %%LibreSSL%% or their -devel versions.

===== More Information =====

Consult Mk/bsd.default-versions.mk for more info on the defaults, as well as
the UPDATING file for information of instructions on changes to those default
versions over time.

Please also note that arbitrarily overriding defaults might lead to additional
steps being required, backwards incompatibility or dependency issues (eg. switching
default Python version from 2.x to 3.x).

----

[[/CategoryPorts]]