/usr/local/opt
Unless using a Nix system, storing files in consistent locations is an important part of keeping a system clean and maintainable. On most Linux systems, the majority of software is installed using a package manager. A package manager tracks the files that are installed, so it can update and remove software with minimal side-effects.
There are times, however, when software that is not available through
the package manager must be installed. To minimize the side-effects on
the filesystem, such software is installed within the
/usr/local directory. UNIX-style installation of software
puts files in the bin, lib,
share, etc. subdirectories under the local root, but it is
very common to install software into package-specific directories and
add soft-links from the local root instead. Doing so allows for easy
removal of the software—simply remove the package-specific directory as
well as any links pointing into it.
Some software provides local installation instructions that promote
creating a package-specific directory directly in
/usr/local. This does not promote good organization, as it
mixes UNIX hierarchy directories with package-specific directories.
Installation of software into package-specific directories is already
done elsewhere, in the /opt directory, and it would
therefore make sense to follow the same conventions and put locally
installed package-specific directories in a /usr/local/opt
directory.
General Usage
A common reason for installing software locally is that the software
(or a specific version of the software) is not available via the package
manager. For example, a user may need to use the most recent version of
Calibre on Debian stable. (At
the time of writing, version 5.16.1 is the latest version while only
version 3.48.0 is available via backports.) The user can install the
software into a /usr/local/opt/calibre-5.16.1 directory. By
adding a soft-link named calibre in
/usr/local/bin (which is already in the user’s
PATH) that points to the executable, the software is easily
accessible.
Including a version number in the directory name is not required, but
it is good practice for locally-installed software because it allows
multiple versions to be installed and tested simultaneously. To run a
specific version of the software, run the executable under the package
directory directly. Any version can be made the default by
controlling which executable is linked to from
/usr/local/bin. For example, a new version of software can
be installed and tested without removing the old version. When the new
version is ready, the link in /usr/local/bin can be updated
to point to it. The old version of the software can then be removed when
it is no longer needed.
Links to software with a UNIX-style installation (with
/usr/local/opt/PACKAGE/{bin,lib,share} directories) can be
managed using GNU Stow.
The software uses /usr/local/stow by default, but it works
fine with /usr/local/opt/, which is more consistent with
the Filesystem
Hierarchy Standard.
Development
Software developers need to test software with many versions of libraries in order to determine or maintain compatibility. For example, software written in Python should be tested with each version of Python that the software may be run with. At the time of writing, a project that supports Python 3.7 or later may use the following Python installations:
/usr/local/opt/python-3.9.4/usr/local/opt/python-3.8.9/usr/local/opt/python-3.7.10
In this case, no links to the packages are added to the
/usr/local hierarchy, as these installations must not
interfere with the system versions of Python and the software that
depends on them. Testing is done within virtual environments that are
specific to the software being tested:
$ cd ~/projects/example
$ /usr/local/opt/python-3.9.4/bin/python -m venv virtualenv-3.9.4
$ /usr/local/opt/python-3.8.9/bin/python -m venv virtualenv-3.8.9
$ /usr/local/opt/python-3.7.10/bin/python -m venv virtualenv-3.7.10