1559 lines
60 KiB
XML
1559 lines
60 KiB
XML
<?xml version="1.0" encoding="ISO8859-1" standalone="no"?>
|
|
<!--
|
|
The FreeBSD Documentation Project
|
|
|
|
$FreeBSD$
|
|
-->
|
|
|
|
<chapter id="ports">
|
|
<title>Installing Applications: Packages and Ports</title>
|
|
|
|
<sect1 id="ports-synopsis">
|
|
<title>Synopsis</title>
|
|
|
|
<indexterm><primary>ports</primary></indexterm>
|
|
<indexterm><primary>packages</primary></indexterm>
|
|
<para>FreeBSD is bundled with a rich collection of system tools as
|
|
part of the base system. However, there is only so much one can
|
|
do before needing to install an additional third-party
|
|
application to get real work done. FreeBSD provides two
|
|
complementary technologies for installing third-party software
|
|
on your system: the FreeBSD Ports Collection (for installing from
|
|
source), and packages (for installing from pre-built binaries).
|
|
Either method may be used to install the
|
|
newest version of your favorite applications from local media or
|
|
straight off the network.</para>
|
|
|
|
<para>After reading this chapter, you will know:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>How to install third-party binary software packages.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>How to build third-party software from source by using the ports
|
|
collection.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>How to remove previously installed packages or ports.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>How to override the default values that the ports
|
|
collection uses.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>How to find the appropriate software package.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>How to upgrade your applications.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
|
|
<sect1 id="ports-overview">
|
|
<title>Overview of Software Installation</title>
|
|
|
|
<para>If you have used a &unix; system before you will know that
|
|
the typical procedure for installing third-party software goes
|
|
something like this:</para>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para>Download the software, which might be distributed in
|
|
source code format, or as a binary.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Unpack the software from its distribution format
|
|
(typically a tarball compressed with &man.compress.1;,
|
|
&man.gzip.1;, or &man.bzip2.1;).</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Locate the documentation (perhaps an
|
|
<filename>INSTALL</filename> or <filename>README</filename>
|
|
file, or some files in a <filename>doc/</filename>
|
|
subdirectory) and read up on how to install the
|
|
software.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>If the software was distributed in source format,
|
|
compile it. This may involve editing a
|
|
<filename>Makefile</filename>, or running a
|
|
<command>configure</command> script, and other work.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Test and install the software.</para>
|
|
</step>
|
|
</procedure>
|
|
|
|
<para>And that is only if everything goes well. If you are
|
|
installing a software package that was not deliberately ported
|
|
to FreeBSD you may even have to go in and edit the code to make
|
|
it work properly.</para>
|
|
|
|
<para>Should you want to, you can continue to install software the
|
|
<quote>traditional</quote> way with FreeBSD. However, FreeBSD
|
|
provides two technologies which can save you a lot of effort:
|
|
packages and ports. At the time of writing, over &os.numports;
|
|
third-party applications have been made available in this
|
|
way.</para>
|
|
|
|
<para>For any given application, the FreeBSD package for that
|
|
application is a single file which you must download. The
|
|
package contains pre-compiled copies of all the commands for the
|
|
application, as well as any configuration files or
|
|
documentation. A downloaded package file can be manipulated
|
|
with FreeBSD package management commands, such as
|
|
&man.pkg.add.1;, &man.pkg.delete.1;, &man.pkg.info.1;, and so
|
|
on. Installing a new application can be carried out with a
|
|
single command.</para>
|
|
|
|
<para>A FreeBSD port for an application is a collection of files
|
|
designed to automate the process of compiling an application
|
|
from source code.</para>
|
|
|
|
<para>Remember that there are a number of steps you would normally
|
|
carry out if you compiled a program yourself (downloading,
|
|
unpacking, patching, compiling, installing). The files that
|
|
make up a port contain all the necessary information to allow
|
|
the system to do this for you. You run a handful of simple
|
|
commands and the source code for the application is
|
|
automatically downloaded, extracted, patched, compiled, and
|
|
installed for you.</para>
|
|
|
|
<para>In fact, the ports system can also be used to generate packages
|
|
which can later be manipulated with <command>pkg_add</command>
|
|
and the other package management commands that will be introduced
|
|
shortly.</para>
|
|
|
|
<para>Both packages and ports understand
|
|
<emphasis>dependencies</emphasis>. Suppose you want to install
|
|
an application that depends on a specific library being
|
|
installed. Both the application and the library have been made
|
|
available as FreeBSD ports and packages. If you use the
|
|
<command>pkg_add</command> command or the ports system to add
|
|
the application, both will notice that the library has not been
|
|
installed, and automatically install the library first.</para>
|
|
|
|
<para>Given that the two technologies are quite similar, you might
|
|
be wondering why FreeBSD bothers with both. Packages and ports
|
|
both have their own strengths, and which one you use will depend
|
|
on your own preference.</para>
|
|
|
|
<itemizedlist>
|
|
<title>Package Benefits</title>
|
|
|
|
<listitem>
|
|
<para>A compressed package tarball is typically smaller than
|
|
the compressed tarball containing the source code for the
|
|
application.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Packages do not require any additional compilation. For
|
|
large applications, such as
|
|
<application>Mozilla</application>,
|
|
<application>KDE</application>, or
|
|
<application>GNOME</application> this can be important,
|
|
particularly if you are on a slow system.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Packages do not require any understanding of the process
|
|
involved in compiling software on FreeBSD.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<itemizedlist>
|
|
<title>Ports Benefits</title>
|
|
|
|
<listitem>
|
|
<para>Packages are normally compiled with conservative options,
|
|
because they have to run on the maximum number of systems. By
|
|
installing from the port, you can tweak the compilation options to
|
|
(for example) generate code that is specific to a Pentium
|
|
4 or Athlon processor.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Some applications have compile-time options relating to
|
|
what they can and cannot do. For example,
|
|
<application>Apache</application> can be configured with a
|
|
wide variety of different built-in options. By building
|
|
from the port you do not have to accept the default options,
|
|
and can set them yourself.</para>
|
|
|
|
<para>In some cases, multiple packages will exist for the same
|
|
application to specify certain settings. For example,
|
|
<application>Ghostscript</application> is available as a
|
|
<filename>ghostscript</filename> package and a
|
|
<filename>ghostscript-nox11</filename> package, depending on
|
|
whether or not you have installed an X11 server. This sort
|
|
of rough tweaking is possible with packages, but rapidly
|
|
becomes impossible if an application has more than one or
|
|
two different compile-time options.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The licensing conditions of some software distributions forbid
|
|
binary distribution. They must be distributed as source
|
|
code.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Some people do not trust binary distributions. At least
|
|
with source code, you can (in theory) read through it and
|
|
look for potential problems yourself.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you have local patches, you will need the source in order to
|
|
apply them.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Some people like having code around, so they can read it
|
|
if they get bored, hack it, borrow from it (license
|
|
permitting, of course), and so on.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>To keep track of updated ports, subscribe to the
|
|
&a.ports; and the &a.ports-bugs;.</para>
|
|
|
|
<warning>
|
|
<para>Before installing any application, you should check <ulink
|
|
url="http://vuxml.freebsd.org/"></ulink> for security issues
|
|
related to your application.</para>
|
|
|
|
<para>You can also install <filename
|
|
role="package">ports-mgmt/portaudit</filename> which will
|
|
automatically check all installed applications for known
|
|
vulnerabilities; a check will be also performed before any port
|
|
build. Meanwhile, you can use the command <command>portaudit
|
|
-F -a</command> after you have installed some
|
|
packages.</para>
|
|
</warning>
|
|
|
|
<para>The remainder of this chapter will explain how to use
|
|
packages and ports to install and manage third-party software on
|
|
FreeBSD.</para>
|
|
</sect1>
|
|
|
|
<sect1 id="ports-finding-applications">
|
|
<title>Finding Your Application</title>
|
|
|
|
<para>Before you can install any applications you need to know what you
|
|
want, and what the application is called.</para>
|
|
|
|
<para>FreeBSD's list of available applications is growing all the
|
|
time. Fortunately, there are a number of ways to find what you
|
|
want:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The FreeBSD web site maintains an up-to-date searchable
|
|
list of all the available applications, at <ulink
|
|
url="&url.base;/ports/index.html">http://www.FreeBSD.org/ports/</ulink>.
|
|
The ports are divided into categories, and you may either
|
|
search for an application by name (if you know it), or see
|
|
all the applications available in a category.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<indexterm><primary>FreshPorts</primary></indexterm>
|
|
|
|
<para>Dan Langille maintains FreshPorts, at <ulink
|
|
url="http://www.FreshPorts.org/"></ulink>. FreshPorts
|
|
tracks changes to the applications in the ports tree as they
|
|
happen, allows you to <quote>watch</quote> one or more
|
|
ports, and can send you email when they are updated.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<indexterm><primary>Freecode</primary></indexterm>
|
|
|
|
<para>If you do not know the name of the application you want,
|
|
try using a site like Freecode (<ulink
|
|
url="http://www.freecode.com/"></ulink>) to find an
|
|
application, then check back at the FreeBSD site to see if
|
|
the application has been ported yet.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you know the exact name of the port, but just need to
|
|
find out which category it is in, you can use the
|
|
&man.whereis.1; command.
|
|
Simply type <command>whereis
|
|
<replaceable>file</replaceable></command>, where
|
|
<replaceable>file</replaceable> is the program you want to
|
|
install. If it is found on your system, you will be told
|
|
where it is, as follows:</para>
|
|
|
|
<screen>&prompt.root; <userinput>whereis lsof</userinput>
|
|
lsof: /usr/ports/sysutils/lsof</screen>
|
|
|
|
<para>This tells us that <command>lsof</command> (a system
|
|
utility) can be found in the
|
|
<filename>/usr/ports/sysutils/lsof</filename>
|
|
directory.</para></listitem>
|
|
|
|
<listitem>
|
|
<para>Additionally, you can use a simple &man.echo.1; statement
|
|
to find where a port exists in the ports tree. For
|
|
example:</para>
|
|
|
|
<screen>&prompt.root; <userinput>echo /usr/ports/*/*lsof*</userinput>
|
|
/usr/ports/sysutils/lsof</screen>
|
|
|
|
<para>Note that this will return any matched files downloaded into the
|
|
<filename class="directory">/usr/ports/distfiles</filename>
|
|
directory.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Yet another way to find a particular port is by using the
|
|
Ports Collection's built-in search mechanism. To use the
|
|
search feature, you will need to be in the
|
|
<filename>/usr/ports</filename> directory. Once in that
|
|
directory, run <command>make <maketarget>search</maketarget>
|
|
name=<replaceable>program-name</replaceable></command> where
|
|
<replaceable>program-name</replaceable> is the name of the
|
|
program you want to find. For example, if you were looking
|
|
for <command>lsof</command>:</para>
|
|
|
|
<screen>&prompt.root; <userinput>cd /usr/ports</userinput>
|
|
&prompt.root; <userinput>make search name=lsof</userinput>
|
|
Port: lsof-4.56.4
|
|
Path: /usr/ports/sysutils/lsof
|
|
Info: Lists information about open files (similar to fstat(1))
|
|
Maint: obrien@FreeBSD.org
|
|
Index: sysutils
|
|
B-deps:
|
|
R-deps: </screen>
|
|
|
|
<para>The part of the output you want to pay particular
|
|
attention to is the <quote>Path:</quote> line, since that
|
|
tells you where to find the port. The other information
|
|
provided is not needed in order to install the port, so it
|
|
will not be covered here.</para>
|
|
|
|
<para>For more in-depth searching you can also use <command>make
|
|
<maketarget>search</maketarget> key=<replaceable>string</replaceable></command>
|
|
where <replaceable>string</replaceable> is some text to search for.
|
|
This searches port names, comments, descriptions and
|
|
dependencies and can be used to find ports which relate to a
|
|
particular subject if you do not know the name of the program
|
|
you are looking for.</para>
|
|
|
|
<para>In both of these cases, the search string is case-insensitive.
|
|
Searching for <quote>LSOF</quote> will yield the same results as
|
|
searching for <quote>lsof</quote>.</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
</sect1>
|
|
|
|
<sect1 id="packages-using">
|
|
<sect1info>
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Chern</firstname>
|
|
<surname>Lee</surname>
|
|
<contrib>Contributed by </contrib>
|
|
</author>
|
|
</authorgroup>
|
|
<!-- 30 Mar 2001 -->
|
|
</sect1info>
|
|
|
|
<title>Using the Packages System</title>
|
|
|
|
<para>There are several different tools used to manage packages on
|
|
FreeBSD:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para>The <command>sysinstall</command> utility can be invoked on a
|
|
running system to install, delete, and list available and
|
|
installed packages. For more information, see <xref
|
|
linkend="packages"/>.</para></listitem>
|
|
<listitem><para>The package management command line tools, which are
|
|
the subject of the rest of this section.</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<sect2>
|
|
<title>Installing a Package</title>
|
|
<indexterm>
|
|
<primary>packages</primary>
|
|
<secondary>installing</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary><command>pkg_add</command></primary>
|
|
</indexterm>
|
|
<para>You can use the &man.pkg.add.1; utility to install a
|
|
FreeBSD software package from a local file or from a server on
|
|
the network.</para>
|
|
|
|
<example>
|
|
<title>Downloading a Package Manually and Installing It Locally</title>
|
|
|
|
<screen>&prompt.root; <userinput>ftp -a <replaceable>ftp2.FreeBSD.org</replaceable></userinput>
|
|
Connected to ftp2.FreeBSD.org.
|
|
220 ftp2.FreeBSD.org FTP server (Version 6.00LS) ready.
|
|
331 Guest login ok, send your email address as password.
|
|
230-
|
|
230- This machine is in Vienna, VA, USA, hosted by Verio.
|
|
230- Questions? E-mail freebsd@vienna.verio.net.
|
|
230-
|
|
230-
|
|
230 Guest login ok, access restrictions apply.
|
|
Remote system type is UNIX.
|
|
Using binary mode to transfer files.
|
|
<prompt>ftp></prompt> <userinput>cd /pub/FreeBSD/ports/packages/sysutils/</userinput>
|
|
250 CWD command successful.
|
|
<prompt>ftp></prompt> <userinput>get lsof-4.56.4.tgz</userinput>
|
|
local: lsof-4.56.4.tgz remote: lsof-4.56.4.tgz
|
|
200 PORT command successful.
|
|
150 Opening BINARY mode data connection for 'lsof-4.56.4.tgz' (92375 bytes).
|
|
100% |**************************************************| 92375 00:00 ETA
|
|
226 Transfer complete.
|
|
92375 bytes received in 5.60 seconds (16.11 KB/s)
|
|
<prompt>ftp></prompt> <userinput>exit</userinput>
|
|
&prompt.root; <userinput>pkg_add <replaceable>lsof-4.56.4.tgz</replaceable></userinput></screen>
|
|
</example>
|
|
|
|
<para>If you do not have a source of local packages (such as a
|
|
FreeBSD CD-ROM set) then it will probably be easier to use the
|
|
<option>-r</option> option to &man.pkg.add.1;. This will
|
|
cause the utility to automatically determine the correct
|
|
object format and release and then fetch and install the
|
|
package from an FTP site.
|
|
</para>
|
|
|
|
<indexterm>
|
|
<primary><command>pkg_add</command></primary></indexterm>
|
|
<screen>&prompt.root; <userinput>pkg_add -r <replaceable>lsof</replaceable></userinput></screen>
|
|
|
|
<para>The example above would download the correct package and
|
|
add it without any further user intervention.
|
|
If you want to specify an alternative &os; Packages Mirror,
|
|
instead of the main distribution site, you have to set the
|
|
<envar>PACKAGESITE</envar> environment variable accordingly, to
|
|
override the default settings. &man.pkg.add.1;
|
|
uses &man.fetch.3; to download the files, which honors various
|
|
environment variables, including
|
|
<envar>FTP_PASSIVE_MODE</envar>, <envar>FTP_PROXY</envar>, and
|
|
<envar>FTP_PASSWORD</envar>. You may need to set one or more
|
|
of these if you are behind a firewall, or need to use an
|
|
FTP/HTTP proxy. See &man.fetch.3; for the complete list.
|
|
Note that in the example above
|
|
<literal>lsof</literal> is used instead of
|
|
<literal>lsof-4.56.4</literal>. When the remote fetching
|
|
feature is used, the version number of the package must be
|
|
removed. &man.pkg.add.1; will automatically fetch the latest
|
|
version of the application.</para>
|
|
|
|
<note>
|
|
<para>&man.pkg.add.1; will download the latest version of
|
|
your application if you are using &os.current; or
|
|
&os.stable;. If you run a -RELEASE version, it will grab
|
|
the version of the package that was built with your
|
|
release. It is possible to change this behavior by
|
|
overriding <envar>PACKAGESITE</envar>.
|
|
For example, if you run a &os; 8.1-RELEASE
|
|
system, by default &man.pkg.add.1; will try to fetch
|
|
packages from
|
|
<literal>ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-8.1-release/Latest/</literal>.
|
|
If you want to force &man.pkg.add.1; to download
|
|
&os; 8-STABLE packages, set <envar>PACKAGESITE</envar>
|
|
to
|
|
<literal>ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-8-stable/Latest/</literal>.
|
|
</para>
|
|
</note>
|
|
|
|
<para>Package files are distributed in <filename>.tgz</filename>
|
|
and <filename>.tbz</filename> formats. You can find them at <ulink
|
|
url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/"></ulink>,
|
|
or on the FreeBSD CD-ROM distribution. Every CD on the
|
|
FreeBSD 4-CD set (and the PowerPak, etc.) contains packages
|
|
in the <filename>/packages</filename> directory. The layout
|
|
of the packages is similar to that of the
|
|
<filename>/usr/ports</filename> tree. Each category has its
|
|
own directory, and every package can be found within the
|
|
<filename>All</filename> directory.
|
|
</para>
|
|
|
|
<para>The directory structure of the package system matches the
|
|
ports layout; they work with each other to form the entire
|
|
package/port system.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Managing Packages</title>
|
|
|
|
<indexterm>
|
|
<primary>packages</primary>
|
|
<secondary>managing</secondary>
|
|
</indexterm>
|
|
<para>&man.pkg.info.1; is a utility that lists and describes
|
|
the various packages installed.
|
|
</para>
|
|
|
|
<indexterm>
|
|
<primary><command>pkg_info</command></primary>
|
|
</indexterm>
|
|
<screen>&prompt.root; <userinput>pkg_info</userinput>
|
|
cvsup-16.1 A general network file distribution system optimized for CV
|
|
docbook-1.2 Meta-port for the different versions of the DocBook DTD
|
|
...</screen>
|
|
<para>&man.pkg.version.1; is a utility that summarizes the
|
|
versions of all installed packages. It compares the package
|
|
version to the current version found in the ports tree.
|
|
</para>
|
|
<indexterm>
|
|
<primary><command>pkg_version</command></primary>
|
|
</indexterm>
|
|
<screen>&prompt.root; <userinput>pkg_version</userinput>
|
|
cvsup =
|
|
docbook =
|
|
...</screen>
|
|
|
|
<para>The symbols in the second column indicate the relative age
|
|
of the installed version and the version available in the
|
|
local ports tree.</para>
|
|
|
|
<informaltable frame="none" pgwide="1">
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Symbol</entry>
|
|
<entry>Meaning</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry>=</entry> <entry>The version of the
|
|
installed package matches the one found in the
|
|
local ports tree.</entry>
|
|
</row>
|
|
|
|
<row><entry><</entry>
|
|
<entry>The installed version is older than the one available
|
|
in the ports tree.</entry>
|
|
</row>
|
|
|
|
<row><entry>></entry><entry>The installed version is newer
|
|
than the one found in the local ports tree. (The local ports
|
|
tree is probably out of date.)</entry></row>
|
|
|
|
<row><entry>?</entry><entry>The installed package cannot be
|
|
found in the ports index. (This can happen, for instance, if an
|
|
installed port is removed from the Ports Collection or
|
|
renamed.)</entry></row>
|
|
|
|
<row><entry>*</entry><entry>There are multiple versions of the
|
|
package.</entry></row>
|
|
|
|
<row><entry>!</entry><entry>The installed package exists in the
|
|
index but for some reason, <command>pkg_version</command> was
|
|
unable to compare the version number of the installed package
|
|
with the corresponding entry in the index.</entry></row>
|
|
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Deleting a Package</title>
|
|
<indexterm>
|
|
<primary><command>pkg_delete</command></primary>
|
|
</indexterm>
|
|
<indexterm>
|
|
<primary>packages</primary>
|
|
<secondary>deleting</secondary>
|
|
</indexterm>
|
|
<para>To remove a previously installed software package, use the
|
|
&man.pkg.delete.1; utility.
|
|
</para>
|
|
|
|
<screen>&prompt.root; <userinput>pkg_delete <replaceable>xchat-1.7.1</replaceable></userinput></screen>
|
|
|
|
<para>Note that &man.pkg.delete.1; requires the full package
|
|
name and number; the above command would not work if
|
|
<replaceable>xchat</replaceable> was given instead of
|
|
<replaceable>xchat-1.7.1</replaceable>. It is, however, easy
|
|
to use &man.pkg.version.1; to find the version of the
|
|
installed package. You could instead simply use a wildcard:</para>
|
|
|
|
<screen>&prompt.root; <userinput>pkg_delete <replaceable>xchat\*</replaceable></userinput></screen>
|
|
|
|
<para>in this case, all packages whose names start with
|
|
<literal>xchat</literal> will be deleted.</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Miscellaneous</title>
|
|
<para>All package information is stored within the
|
|
<filename>/var/db/pkg</filename> directory. The installed
|
|
file list and descriptions of each package can be found within
|
|
files in this directory.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="ports-using">
|
|
<title>Using the Ports Collection</title>
|
|
|
|
<para>The following sections provide basic instructions on using the
|
|
Ports Collection to install or remove programs from your
|
|
system. The detailed description of available <command>make</command>
|
|
targets and environment variables is available in &man.ports.7;.</para>
|
|
|
|
<sect2 id="ports-tree">
|
|
<title>Obtaining the Ports Collection</title>
|
|
|
|
<para>Before you can install ports, you must first obtain the
|
|
Ports Collection—which is essentially a set of
|
|
<filename>Makefiles</filename>, patches, and description files
|
|
placed in <filename>/usr/ports</filename>.
|
|
</para>
|
|
|
|
<para>When installing your FreeBSD system,
|
|
<application>sysinstall</application> asked if you would like
|
|
to install the Ports Collection. If you chose no, you can
|
|
follow these instructions to obtain the ports
|
|
collection:</para>
|
|
|
|
<procedure>
|
|
<title>CVSup Method</title>
|
|
|
|
<para>This is a quick method for getting and keeping your copy of the
|
|
Ports Collection up to date using <application>CVSup</application>
|
|
protocol. If you want to learn more about
|
|
<application>CVSup</application>, see <link
|
|
linkend="cvsup">Using CVSup</link>.</para>
|
|
|
|
<note>
|
|
<para>The implementation of <application>CVSup</application> protocol
|
|
included with the &os; system is called
|
|
<application>csup</application>.</para>
|
|
</note>
|
|
|
|
<para>Make sure <filename class="directory">/usr/ports</filename>
|
|
is empty before you run <application>csup</application> for
|
|
the first time! If you already have the Ports Collection present,
|
|
obtained from another source, <application>csup</application>
|
|
will not prune removed patch files.</para>
|
|
|
|
<step>
|
|
<para>Run <command>csup</command>:</para>
|
|
|
|
<screen>&prompt.root; <userinput>csup -L 2 -h <replaceable>cvsup.FreeBSD.org</replaceable> /usr/share/examples/cvsup/ports-supfile</userinput></screen>
|
|
|
|
<para>Change
|
|
<replaceable>cvsup.FreeBSD.org</replaceable> to a
|
|
<application>CVSup</application> server near you. See
|
|
<link linkend="cvsup-mirrors">CVSup Mirrors</link> (<xref
|
|
linkend="cvsup-mirrors"/>) for a complete listing of mirror
|
|
sites.</para>
|
|
|
|
<note>
|
|
<para>One may want to use his own
|
|
<filename>ports-supfile</filename>, for example to avoid
|
|
the need of passing the <application>CVSup</application>
|
|
server on the command line.</para>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para>In this case, as <username>root</username>, copy
|
|
<filename>/usr/share/examples/cvsup/ports-supfile</filename>
|
|
to a new location, such as
|
|
<filename>/root</filename> or your home
|
|
directory.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Edit <filename>ports-supfile</filename>.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Change
|
|
<replaceable>CHANGE_THIS.FreeBSD.org</replaceable>
|
|
to a <application>CVSup</application> server near
|
|
you. See <link linkend="cvsup-mirrors">CVSup
|
|
Mirrors</link> (<xref linkend="cvsup-mirrors"/>) for
|
|
a complete listing of mirror sites.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>And now to run <command>csup</command>, use the
|
|
following:</para>
|
|
|
|
<screen>&prompt.root; <userinput>csup -L 2 <replaceable>/root/ports-supfile</replaceable></userinput></screen>
|
|
</step>
|
|
</procedure>
|
|
</note>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Running the &man.csup.1; command later will download and apply
|
|
all the recent changes to your Ports Collection, except
|
|
actually rebuilding the ports for your own system.</para>
|
|
</step>
|
|
</procedure>
|
|
|
|
<procedure>
|
|
<title>Portsnap Method</title>
|
|
|
|
<para><application>Portsnap</application> is an alternative system for
|
|
distributing the Ports Collection.
|
|
Please refer to <link linkend="updating-upgrading-portsnap">Using Portsnap</link>
|
|
for a detailed description of all <application>Portsnap</application>
|
|
features.</para>
|
|
|
|
<step>
|
|
<para>Download a compressed snapshot of the Ports Collection into
|
|
<filename class="directory">/var/db/portsnap</filename>. You can
|
|
disconnect from the Internet after this step, if you wish.</para>
|
|
|
|
<screen>&prompt.root; <userinput>portsnap fetch</userinput></screen>
|
|
</step>
|
|
|
|
<step>
|
|
<para>If you are running <application>Portsnap</application> for the
|
|
first time, extract the snapshot into <filename
|
|
class="directory">/usr/ports</filename>:
|
|
</para>
|
|
|
|
<screen>&prompt.root; <userinput>portsnap extract</userinput></screen>
|
|
|
|
<para>If you already have a populated <filename
|
|
class="directory">/usr/ports</filename> and you are just updating,
|
|
run the following command instead:</para>
|
|
|
|
<screen>&prompt.root; <userinput>portsnap update</userinput></screen>
|
|
</step>
|
|
|
|
</procedure>
|
|
|
|
<procedure>
|
|
<title>Sysinstall Method</title>
|
|
|
|
<para>This method involves using <application>sysinstall</application>
|
|
to install the Ports Collection from the installation media. Note
|
|
that the old copy of Ports Collection from the date of the release
|
|
will be installed. If you have Internet access, you should always
|
|
use one of the methods mentioned above.</para>
|
|
|
|
<step>
|
|
<para>As <username>root</username>, run
|
|
<command>sysinstall</command> as shown below:</para>
|
|
|
|
<screen>&prompt.root; <userinput>sysinstall</userinput></screen>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Scroll down and select <guimenuitem>Configure</guimenuitem>,
|
|
press <keycap>Enter</keycap>.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Scroll down and select
|
|
<guimenuitem>Distributions</guimenuitem>, press
|
|
<keycap>Enter</keycap>.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Scroll down to <guimenuitem>ports</guimenuitem>, press
|
|
<keycap>Space</keycap>.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Scroll up to <guimenuitem>Exit</guimenuitem>, press
|
|
<keycap>Enter</keycap>.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Select your desired installation media, such as CDROM,
|
|
FTP, and so on.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Scroll up to <guimenuitem>Exit</guimenuitem> and press
|
|
<keycap>Enter</keycap>.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Press <keycap>X</keycap> to exit
|
|
<application>sysinstall</application>.</para>
|
|
</step>
|
|
</procedure>
|
|
</sect2>
|
|
|
|
<sect2 id="ports-skeleton">
|
|
<title>Installing Ports</title>
|
|
|
|
<indexterm>
|
|
<primary>ports</primary>
|
|
<secondary>installing</secondary>
|
|
</indexterm>
|
|
<para>The first thing that should be explained when it comes to
|
|
the Ports Collection is what is actually meant by a
|
|
<quote>skeleton</quote>. In a nutshell, a port skeleton is a
|
|
minimal set of files that tell your FreeBSD system how to
|
|
cleanly compile and install a program. Each port skeleton
|
|
includes:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>A <filename>Makefile</filename>. The
|
|
<filename>Makefile</filename> contains various statements
|
|
that specify how the application should be compiled and
|
|
where it should be installed on your system.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>A <filename>distinfo</filename> file. This file
|
|
contains information about the files that must be
|
|
downloaded to build the port, and their checksums
|
|
(using &man.sha256.1;), to
|
|
verify that files have not been corrupted during the
|
|
download.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>A <filename>files</filename> directory. This
|
|
directory contains patches to make the program compile and
|
|
install on your FreeBSD system. Patches are basically
|
|
small files that specify changes to particular files.
|
|
They are in plain text format, and basically say
|
|
<quote>Remove line 10</quote> or <quote>Change line 26 to
|
|
this ...</quote>. Patches are also known as
|
|
<quote>diffs</quote> because they are generated by the
|
|
&man.diff.1; program.</para>
|
|
|
|
<para>This directory may also contain other files used to build
|
|
the port.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>A <filename>pkg-descr</filename> file. This is a more
|
|
detailed, often multiple-line, description of the program.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>A <filename>pkg-plist</filename> file. This is a list
|
|
of all the files that will be installed by the port. It
|
|
also tells the ports system what files to remove upon
|
|
deinstallation.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Some ports have other files, such as
|
|
<filename>pkg-message</filename>. The ports system uses these
|
|
files to handle special situations. If you want more details
|
|
on these files, and on ports in general, check out the <ulink
|
|
url="&url.books.porters-handbook;/index.html">FreeBSD Porter's
|
|
Handbook</ulink>.</para>
|
|
|
|
<para>The port includes instructions on how to build source
|
|
code, but does not include the actual source code. You can
|
|
get the source code from a CD-ROM or from the Internet.
|
|
Source code is distributed in whatever manner the software
|
|
author desires. Frequently this is a tarred and gzipped file,
|
|
but it might be compressed with some other tool or even
|
|
uncompressed. The program source code, whatever form it comes
|
|
in, is called a <quote>distfile</quote>. The two methods for
|
|
installing a &os; port are described below.</para>
|
|
|
|
<note>
|
|
<para>You must be logged in as <username>root</username> to
|
|
install ports.</para>
|
|
</note>
|
|
|
|
<warning>
|
|
<para>Before installing any port, you should be sure to have
|
|
an up-to-date Ports Collection and you should check <ulink
|
|
url="http://vuxml.freebsd.org/"></ulink> for security issues
|
|
related to your port.</para>
|
|
|
|
<para>A security vulnerabilities check can be automatically
|
|
done by <application>portaudit</application> before any new
|
|
application installation. This tool can be found in the
|
|
Ports Collection (<filename
|
|
role="package">ports-mgmt/portaudit</filename>). Consider
|
|
running <command>portaudit -F</command> before installing a
|
|
new port, to fetch the current vulnerabilities database. A
|
|
security audit and an update of the database will be
|
|
performed during the daily security system check. For more
|
|
information read the &man.portaudit.1; and &man.periodic.8;
|
|
manual pages.</para>
|
|
</warning>
|
|
|
|
<para>The Ports Collection makes an assumption that you have a working
|
|
Internet connection. If you do not, you will need to put a copy of the
|
|
distfile into <filename>/usr/ports/distfiles</filename>
|
|
manually.</para>
|
|
|
|
<para>To begin, change to the directory for the port you want to
|
|
install:</para>
|
|
|
|
<screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput></screen>
|
|
|
|
<para>Once inside the <filename>lsof</filename> directory, you
|
|
will see the port skeleton. The next step is to compile, or
|
|
<quote>build</quote>, the port. This is done by simply
|
|
typing <command>make</command> at the prompt. Once you have
|
|
done so, you should see something like this:</para>
|
|
|
|
<screen>&prompt.root; <userinput>make</userinput>
|
|
>> lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
|
|
>> Attempting to fetch from ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/.
|
|
===> Extracting for lsof-4.57
|
|
...
|
|
[extraction output snipped]
|
|
...
|
|
>> Checksum OK for lsof_4.57D.freebsd.tar.gz.
|
|
===> Patching for lsof-4.57
|
|
===> Applying FreeBSD patches for lsof-4.57
|
|
===> Configuring for lsof-4.57
|
|
...
|
|
[configure output snipped]
|
|
...
|
|
===> Building for lsof-4.57
|
|
...
|
|
[compilation output snipped]
|
|
...
|
|
&prompt.root;</screen>
|
|
|
|
<para>Notice that once the compile is complete you are
|
|
returned to your prompt. The next step is to install the
|
|
port. In order to install it, you simply need to tack one word
|
|
onto the <command>make</command> command, and that word is
|
|
<maketarget>install</maketarget>:</para>
|
|
|
|
<screen>&prompt.root; <userinput>make install</userinput>
|
|
===> Installing for lsof-4.57
|
|
...
|
|
[installation output snipped]
|
|
...
|
|
===> Generating temporary packing list
|
|
===> Compressing manual pages for lsof-4.57
|
|
===> Registering installation for lsof-4.57
|
|
===> SECURITY NOTE:
|
|
This port has installed the following binaries which execute with
|
|
increased privileges.
|
|
&prompt.root;</screen>
|
|
|
|
<para>Once you are returned to your prompt, you should be able to
|
|
run the application you just installed. Since
|
|
<command>lsof</command> is a
|
|
program that runs with increased privileges, a security
|
|
warning is shown. During the building and installation of
|
|
ports, you should take heed of any other warnings that
|
|
may appear.</para>
|
|
|
|
<para>It is a good idea to delete the working subdirectory,
|
|
which contains all the temporary files used during compilation.
|
|
Not only does it consume valuable disk space, but it would also
|
|
cause problems later when upgrading to the newer version of the
|
|
port.</para>
|
|
|
|
<screen>&prompt.root; <userinput>make clean</userinput>
|
|
===> Cleaning for lsof-4.57
|
|
&prompt.root;</screen>
|
|
|
|
<note>
|
|
<para>You can save two extra steps by just running <command>make
|
|
<maketarget>install clean</maketarget></command> instead of
|
|
<command>make</command>,
|
|
<command>make <maketarget>install</maketarget></command> and
|
|
<command>make <maketarget>clean</maketarget></command>
|
|
as three separate steps.</para>
|
|
</note>
|
|
|
|
<note>
|
|
<para>Some shells keep a cache of the commands that are
|
|
available in the directories listed in the
|
|
<envar>PATH</envar> environment variable, to speed up
|
|
lookup operations for the executable file of these
|
|
commands. If you are using one of these shells, you might
|
|
have to use the <command>rehash</command> command after
|
|
installing a port, before the newly installed commands can
|
|
be used. This command will work for shells like
|
|
<command>tcsh</command>. Use the <command>hash -r</command>
|
|
command for shells like <command>sh</command>. Look at the
|
|
documentation for your shell for more information.</para>
|
|
</note>
|
|
|
|
<para>Some third-party DVD-ROM products such as the FreeBSD Toolkit
|
|
from the <ulink url="http://www.freebsdmall.com/">FreeBSD
|
|
Mall</ulink> contain distfiles. They can be used with the Ports
|
|
Collection. Mount the DVD-ROM on <filename>/cdrom</filename>. If
|
|
you use a different mount point, set <makevar>CD_MOUNTPTS</makevar>
|
|
make variable. The needed distfiles will be automatically used
|
|
if they are present on the disk.</para>
|
|
|
|
<note>
|
|
<para>Please be aware that the licenses of a few ports do
|
|
not allow for inclusion on the CD-ROM. This could be
|
|
because a registration form needs to be filled out before
|
|
downloading or redistribution is not allowed, or for
|
|
another reason. If you wish to install a port not
|
|
included on the CD-ROM, you will need to be online in
|
|
order to do so.</para>
|
|
</note>
|
|
|
|
<para>The ports system uses &man.fetch.1; to download the
|
|
files, which honors various environment variables, including
|
|
<envar>FTP_PASSIVE_MODE</envar>, <envar>FTP_PROXY</envar>,
|
|
and <envar>FTP_PASSWORD</envar>. You may need to set one or
|
|
more of these if you are behind a firewall, or need to use
|
|
an FTP/HTTP proxy. See &man.fetch.3; for the complete
|
|
list.</para>
|
|
|
|
<para>For users which cannot be connected all the time, the
|
|
<command>make <maketarget>fetch</maketarget></command> option is
|
|
provided. Just run this command at the top level directory
|
|
(<filename>/usr/ports</filename>) and the required files
|
|
will be downloaded for you. This command will also work in
|
|
the lower level categories, for example:
|
|
<filename>/usr/ports/net</filename>.
|
|
Note that if a port depends on libraries or other ports this will
|
|
<emphasis>not</emphasis> fetch the distfiles of those ports too.
|
|
Replace <maketarget>fetch</maketarget> with
|
|
<maketarget>fetch-recursive</maketarget>
|
|
if you want to fetch all the dependencies of a port too.</para>
|
|
|
|
<note><para>You can build all the ports in a category or as a
|
|
whole by running <command>make</command> in the top level
|
|
directory, just like the aforementioned <command>make
|
|
<maketarget>fetch</maketarget></command> method. This is
|
|
dangerous, however, as some ports cannot co-exist. In other
|
|
cases, some ports can install two different files with the
|
|
same filename.</para></note>
|
|
|
|
<para>In some rare cases, users may need to acquire the
|
|
tarballs from a site other than the
|
|
<makevar>MASTER_SITES</makevar> (the location where files
|
|
are downloaded from). You can override the
|
|
<makevar>MASTER_SITES</makevar> option with the following
|
|
command:</para>
|
|
|
|
<screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput>
|
|
&prompt.root; <userinput>make MASTER_SITE_OVERRIDE= \
|
|
ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch</userinput></screen>
|
|
|
|
<para>In this example we change the
|
|
<makevar>MASTER_SITES</makevar> option to <hostid
|
|
role="fqdn">ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/</hostid>.</para>
|
|
|
|
<note><para>Some ports allow (or even require) you to provide
|
|
build options which can enable/disable parts of the
|
|
application which are unneeded, certain security options,
|
|
and other customizations. A few which come to mind are
|
|
<filename role="package">www/firefox</filename>, <filename
|
|
role="package">security/gpgme</filename>, and <filename
|
|
role="package">mail/sylpheed-claws</filename>. A message
|
|
will be displayed when options such as these are
|
|
available.</para></note>
|
|
|
|
<sect3>
|
|
<title>Overriding the Default Ports Directories</title>
|
|
|
|
<para>Sometimes it is useful (or mandatory) to use a different
|
|
working and target directory. The
|
|
<makevar>WRKDIRPREFIX</makevar> and <makevar>PREFIX</makevar>
|
|
variables can override the default directories. For
|
|
example:</para>
|
|
|
|
<screen>&prompt.root; <userinput>make WRKDIRPREFIX=/usr/home/example/ports install</userinput></screen>
|
|
|
|
<para>will compile the port in
|
|
<filename>/usr/home/example/ports</filename> and install
|
|
everything under <filename>/usr/local</filename>.</para>
|
|
|
|
<screen>&prompt.root; <userinput>make PREFIX=/usr/home/example/local install</userinput></screen>
|
|
|
|
<para>will compile it in <filename>/usr/ports</filename> and
|
|
install it in
|
|
<filename>/usr/home/example/local</filename>.</para>
|
|
|
|
<para>And of course,</para>
|
|
|
|
<screen>&prompt.root; <userinput>make WRKDIRPREFIX=../ports PREFIX=../local install</userinput></screen>
|
|
|
|
<para>will combine the two (it is too long to completely write
|
|
on this page, but it should give you the general
|
|
idea).</para>
|
|
|
|
<para>Alternatively, these variables can also be set as part
|
|
of your environment. Read the manual page for your shell
|
|
for instructions on doing so.</para>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>Dealing with <command>imake</command></title>
|
|
|
|
<para>Some ports that use <command>imake</command> (a part of
|
|
the X Window System) do not work well with
|
|
<makevar>PREFIX</makevar>, and will insist on installing
|
|
under <filename>/usr/X11R6</filename>. Similarly, some Perl
|
|
ports ignore <makevar>PREFIX</makevar> and install in the
|
|
Perl tree. Making these ports respect
|
|
<makevar>PREFIX</makevar> is a difficult or impossible
|
|
job.</para>
|
|
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>Reconfiguring Ports</title>
|
|
|
|
<para>When building certain ports, you may be presented with a
|
|
ncurses-based menu from which you can select certain build options.
|
|
It is not uncommon for users to wish to revisit this menu to add,
|
|
remove, or change these options after a port has been built. There
|
|
are many ways to do this. One option is to go into the directory
|
|
containing the port and type <command>make
|
|
<maketarget>config</maketarget></command>, which will simply present
|
|
the menu again with the same options selected. Another option is to
|
|
use <command>make <maketarget>showconfig</maketarget></command>,
|
|
which will show you all the configuration options for the port. Yet
|
|
another option is to execute <command>make
|
|
<maketarget>rmconfig</maketarget></command> which will remove all
|
|
selected options and allow you to start over. All of these options,
|
|
and others, are explained in great detail in the manual page for
|
|
&man.ports.7;.</para>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2 id="ports-removing">
|
|
<title>Removing Installed Ports</title>
|
|
|
|
<indexterm>
|
|
<primary>ports</primary>
|
|
<secondary>removing</secondary>
|
|
</indexterm>
|
|
<para>Now that you know how to install ports, you are probably
|
|
wondering how to remove them, just in case you install one and
|
|
later on decide that you installed the wrong port.
|
|
We will remove our previous example (which was
|
|
<command>lsof</command> for
|
|
those of you not paying attention). Ports are being removed exactly
|
|
the same as the packages (discussed in the <link
|
|
linkend="packages-using">Packages section</link>), using the
|
|
&man.pkg.delete.1; command:</para>
|
|
|
|
<screen>&prompt.root; <userinput>pkg_delete lsof-4.57</userinput></screen>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="ports-upgrading">
|
|
<title>Upgrading Ports</title>
|
|
|
|
<indexterm>
|
|
<primary>ports</primary>
|
|
<secondary>upgrading</secondary>
|
|
</indexterm>
|
|
<para>First, list outdated ports that have a newer version available in
|
|
the Ports Collection with the &man.pkg.version.1; command:</para>
|
|
|
|
<screen>&prompt.root; <userinput>pkg_version -v</userinput></screen>
|
|
|
|
<sect3 id="ports-file-updating">
|
|
<title><filename>/usr/ports/UPDATING</filename></title>
|
|
|
|
<para>Once you have updated your Ports Collection, before
|
|
attempting a port upgrade, you should check
|
|
<filename>/usr/ports/UPDATING</filename>. This file
|
|
describes various issues and additional steps users may
|
|
encounter and need to perform when updating a port, including
|
|
such things as file format changes, changes in locations of
|
|
configuration files, or other such incompatibilities with
|
|
previous versions.</para>
|
|
|
|
<para>If <filename>UPDATING</filename> contradicts something you
|
|
read here, <filename>UPDATING</filename> takes precedence.</para>
|
|
</sect3>
|
|
|
|
<sect3 id="portupgrade">
|
|
<title>Upgrading Ports Using Portupgrade</title>
|
|
|
|
<indexterm>
|
|
<primary>portupgrade</primary>
|
|
</indexterm>
|
|
|
|
<para>The <application>portupgrade</application> utility is designed
|
|
to easily upgrade installed ports. It is available from the <filename
|
|
role="package">ports-mgmt/portupgrade</filename> port. Install it like
|
|
any other port, using the <command>make <maketarget>install
|
|
clean</maketarget></command> command:</para>
|
|
|
|
<screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/portupgrade</userinput>
|
|
&prompt.root; <userinput>make install clean</userinput></screen>
|
|
|
|
<para>Scan the list of installed ports with the <command>pkgdb
|
|
-F</command> command and fix all the inconsistencies it reports. It is
|
|
a good idea to do this regularly, before every upgrade.</para>
|
|
|
|
<para>When you run <command>portupgrade -a</command>,
|
|
<application>portupgrade</application> will begin to upgrade all the
|
|
outdated ports installed on your system. Use the <option>-i</option>
|
|
flag if you want to be asked for confirmation of every individual
|
|
upgrade.</para>
|
|
|
|
<screen>&prompt.root; <userinput>portupgrade -ai</userinput></screen>
|
|
|
|
<para>If you want to upgrade only a
|
|
certain application, not all available ports, use <command>portupgrade
|
|
<replaceable>pkgname</replaceable></command>. Include the
|
|
<option>-R</option> flag if <application>portupgrade</application>
|
|
should first upgrade all the ports required by the given
|
|
application.</para>
|
|
|
|
<screen>&prompt.root; <userinput>portupgrade -R firefox</userinput></screen>
|
|
|
|
<para>To use packages instead of ports for installation, provide
|
|
<option>-P</option> flag. With this option
|
|
<application>portupgrade</application> searches
|
|
the local directories listed in <envar>PKG_PATH</envar>, or
|
|
fetches packages from remote site if it is not found locally.
|
|
If packages can not be found locally or fetched remotely,
|
|
<application>portupgrade</application> will use ports.
|
|
To avoid using ports, specify <option>-PP</option>.</para>
|
|
|
|
<screen>&prompt.root; <userinput>portupgrade -PP gnome2</userinput></screen>
|
|
|
|
<para>To just fetch distfiles (or packages, if
|
|
<option>-P</option> is specified) without building or
|
|
installing anything, use <option>-F</option>.
|
|
For further information see &man.portupgrade.1;.</para>
|
|
</sect3>
|
|
|
|
<sect3 id="portmanager">
|
|
<title>Upgrading Ports Using Portmanager</title>
|
|
|
|
<indexterm>
|
|
<primary>portmanager</primary>
|
|
</indexterm>
|
|
|
|
<para><application>Portmanager</application> is another utility for
|
|
easy upgrading of installed ports. It is available from the
|
|
<filename role="package">ports-mgmt/portmanager</filename>
|
|
port:</para>
|
|
|
|
<screen>&prompt.root; <userinput>cd <filename class="directory">/usr/ports/ports-mgmt/portmanager</filename></userinput>
|
|
&prompt.root; <userinput>make install clean</userinput></screen>
|
|
|
|
<para>All the installed ports can be upgraded using this simple
|
|
command:</para>
|
|
|
|
<screen>&prompt.root; <userinput>portmanager -u</userinput></screen>
|
|
|
|
<para>You can add the <option>-ui</option> flag to the above
|
|
command (<userinput>portmanager -u -ui</userinput>) to be
|
|
prompted for
|
|
confirmation of every step <application>Portmanager</application>
|
|
will perform. <application>Portmanager</application> can also be
|
|
used to install new ports on the system. Unlike the usual
|
|
<command>make <maketarget>install clean</maketarget></command>
|
|
command, it will upgrade all the dependencies prior to building and
|
|
installing the selected port.</para>
|
|
|
|
<screen>&prompt.root; <userinput>portmanager <replaceable>x11/gnome2</replaceable></userinput></screen>
|
|
|
|
<para>If there are any problems regarding the dependencies for the
|
|
selected port, you can use <application>Portmanager</application> to
|
|
rebuild all of them in the correct order. Once finished, the
|
|
problematic port will be rebuilt too.</para>
|
|
|
|
<screen>&prompt.root; <userinput>portmanager <replaceable>graphics/gimp</replaceable> -f</userinput></screen>
|
|
|
|
<para>For further information see &man.portmanager.1;.</para>
|
|
</sect3>
|
|
|
|
<sect3 id="portmaster">
|
|
<title>Upgrading Ports Using Portmaster</title>
|
|
|
|
<indexterm>
|
|
<primary>portmaster</primary>
|
|
</indexterm>
|
|
|
|
<para><application>Portmaster</application> is another utility for
|
|
upgrading installed ports. <application>Portmaster</application>
|
|
was designed make use of the tools found in the <quote>base</quote>
|
|
system (it does not depend upon other ports) and uses the
|
|
information in <filename class="directory">/var/db/pkg/</filename>
|
|
to determine which ports to upgrade. It is available from the
|
|
<filename role="package">ports-mgmt/portmaster</filename>
|
|
port:</para>
|
|
|
|
<screen>&prompt.root; <userinput>cd <filename class="directory">/usr/ports/ports-mgmt/portmaster</filename></userinput>
|
|
&prompt.root; <userinput>make install clean</userinput></screen>
|
|
|
|
<para><application>Portmaster</application> groups ports into four
|
|
categories:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Root ports (no dependencies, not depended on)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Trunk ports (no dependencies, are depended on)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Branch ports (have dependencies, are depended on)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Leaf ports (have dependencies, not depended on)</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>You can list all the installed ports and search
|
|
for updates using the <option>-L</option> option:</para>
|
|
|
|
<screen>&prompt.root; <userinput>portmaster -L</userinput>
|
|
===>>> Root ports (No dependencies, not depended on)
|
|
===>>> ispell-3.2.06_18
|
|
===>>> screen-4.0.3
|
|
===>>> New version available: screen-4.0.3_1
|
|
===>>> tcpflow-0.21_1
|
|
===>>> 7 root ports
|
|
...
|
|
===>>> Branch ports (Have dependencies, are depended on)
|
|
===>>> apache-2.2.3
|
|
===>>> New version available: apache-2.2.8
|
|
...
|
|
===>>> Leaf ports (Have dependencies, not depended on)
|
|
===>>> automake-1.9.6_2
|
|
===>>> bash-3.1.17
|
|
===>>> New version available: bash-3.2.33
|
|
...
|
|
===>>> 32 leaf ports
|
|
|
|
===>>> 137 total installed ports
|
|
===>>> 83 have new versions available
|
|
</screen>
|
|
|
|
<para>All the installed ports can be upgraded using this simple
|
|
command:</para>
|
|
|
|
<screen>&prompt.root; <userinput>portmaster -a</userinput></screen>
|
|
|
|
<note><para>By default, <application>Portmaster</application>
|
|
will make a backup package before deleting the existing port. If
|
|
the installation of the new version is successful,
|
|
<application>Portmaster</application> will delete the backup.
|
|
Using the <option>-b</option> will instruct
|
|
<application>Portmaster</application> not to automatically delete
|
|
the backup. Adding the <option>-i</option> option will start
|
|
<application>Portmaster</application> in interactive mode, prompting
|
|
you before upgrading each port.</para></note>
|
|
|
|
<para>If you encounter errors during the upgrade process, you can use
|
|
the <option>-f</option> option to upgrade/rebuild all ports:</para>
|
|
|
|
<screen>&prompt.root; <userinput>portmaster -af</userinput></screen>
|
|
|
|
<para>You can also use <application>Portmaster</application> to
|
|
install new ports on the system, upgrading all dependencies
|
|
before building and installing the new port:</para>
|
|
|
|
<screen>&prompt.root; <userinput>portmaster <replaceable>shells/bash</replaceable></userinput></screen>
|
|
|
|
<para>Please see &man.portmaster.8; for more information.</para>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2 id="ports-disk-space">
|
|
<title>Ports and Disk Space</title>
|
|
|
|
<indexterm>
|
|
<primary>ports</primary>
|
|
<secondary>disk-space</secondary>
|
|
</indexterm>
|
|
<para>Using the Ports Collection will use up disk
|
|
space over time. After building and installing software from the
|
|
ports, you should always remember to clean up
|
|
the temporary <filename class="directory">work</filename> directories
|
|
using the <command>make <maketarget>clean</maketarget></command>
|
|
command. You can sweep the whole Ports Collection with the following
|
|
command:</para>
|
|
|
|
<screen>&prompt.root; <userinput>portsclean -C</userinput></screen>
|
|
|
|
<para>You will accumulate a lot of old source distribution files in the
|
|
<filename class="directory">distfiles</filename> directory over time.
|
|
You can remove them by hand, or you can use the following command to
|
|
delete all the distfiles that are no longer referenced by any
|
|
ports:</para>
|
|
|
|
<screen>&prompt.root; <userinput>portsclean -D</userinput></screen>
|
|
|
|
<para>Or to remove all distfiles not referenced by any port
|
|
currently installed on your system:</para>
|
|
|
|
<screen>&prompt.root; <userinput>portsclean -DD</userinput></screen>
|
|
|
|
<note>
|
|
<para>The <command>portsclean</command> utility is part of the
|
|
<application>portupgrade</application> suite.</para>
|
|
</note>
|
|
|
|
<para>Do not forget to remove the installed ports once you no longer need
|
|
them. A nice tool to help automate this task is available from the
|
|
<filename role="package">ports-mgmt/pkg_cutleaves</filename>
|
|
port.</para>
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="ports-nextsteps">
|
|
<title>Post-installation Activities</title>
|
|
|
|
<para>After installing a new application you will normally want to
|
|
read any documentation it may have included, edit any
|
|
configuration files that are required, ensure that the
|
|
application starts at boot time (if it is a daemon), and so
|
|
on.</para>
|
|
|
|
<para>The exact steps you need to take to configure each
|
|
application will obviously be different. However, if you have
|
|
just installed a new application and are wondering <quote>What
|
|
now?</quote> these tips might help:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Use &man.pkg.info.1; to find out which files were installed,
|
|
and where. For example, if you have just
|
|
installed FooPackage version 1.0.0, then this command</para>
|
|
|
|
<screen>&prompt.root; <userinput>pkg_info -L foopackage-1.0.0 | less</userinput></screen>
|
|
|
|
<para>will show all the files installed by the package. Pay
|
|
special attention to files in <filename>man/</filename>
|
|
directories, which will be manual pages,
|
|
<filename>etc/</filename> directories, which will be
|
|
configuration files, and <filename>doc/</filename>, which
|
|
will be more comprehensive documentation.</para>
|
|
|
|
<para>If you are not sure which version of the application was
|
|
just installed, a command like this</para>
|
|
|
|
<screen>&prompt.root; <userinput>pkg_info | grep -i <replaceable>foopackage</replaceable></userinput></screen>
|
|
|
|
<para>will find all the installed packages that have
|
|
<replaceable>foopackage</replaceable> in the package name.
|
|
Replace <replaceable>foopackage</replaceable> in your
|
|
command line as necessary.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Once you have identified where the application's manual
|
|
pages have been installed, review them using &man.man.1;.
|
|
Similarly, look over the sample configuration files, and any
|
|
additional documentation that may have been provided.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If the application has a web site, check it for
|
|
additional documentation, frequently asked questions, and so
|
|
forth. If you are not sure of the web site address it may
|
|
be listed in the output from</para>
|
|
|
|
<screen>&prompt.root; <userinput>pkg_info <replaceable>foopackage-1.0.0</replaceable></userinput></screen>
|
|
|
|
<para>A <literal>WWW:</literal> line, if present, should provide a URL
|
|
for the application's web site.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Ports that should start at boot (such as Internet
|
|
servers) will usually install a sample script in
|
|
<filename>/usr/local/etc/rc.d</filename>. You should
|
|
review this script for correctness and edit or rename it if
|
|
needed. See <link
|
|
linkend="configtuning-starting-services">Starting
|
|
Services</link> for more information.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
|
|
<sect1 id="ports-broken">
|
|
<title>Dealing with Broken Ports</title>
|
|
|
|
<para>If you come across a port that does not work for you,
|
|
there are a few things you can do, including:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Find out if there is a fix pending for the port in
|
|
the <ulink url="&url.base;/support.html#gnats">Problem Report
|
|
database</ulink>. If so, you may be able to use the
|
|
proposed fix.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Ask the maintainer of the port for help. Type
|
|
<command>make <maketarget>maintainer</maketarget></command> or read
|
|
the <filename>Makefile</filename> to find the maintainer's
|
|
email address. Remember to include the name and version
|
|
of the port (send the <literal>$FreeBSD:</literal>
|
|
line from the <filename>Makefile</filename>) and the
|
|
output leading up to the error when you email the
|
|
maintainer.</para>
|
|
|
|
<note>
|
|
<para>Some ports are not maintained by an individual but
|
|
instead by a <ulink
|
|
url="&url.articles.mailing-list-faq;/article.html">mailing
|
|
list</ulink>. Many, but not all, of these addresses look like
|
|
<email role="nolink">freebsd-listname@FreeBSD.org</email>.
|
|
Please take this into account when phrasing your
|
|
questions.</para>
|
|
|
|
<para>In particular, ports shown as maintained by
|
|
<email role="nolink">ports@FreeBSD.org</email> are
|
|
actually not maintained by anyone. Fixes and support, if
|
|
any, come from the general community who subscribe to that
|
|
mailing list. More volunteers are always needed!</para>
|
|
</note>
|
|
|
|
<para>If you do not get a response,
|
|
you can use &man.send-pr.1; to submit a bug
|
|
report (see <ulink
|
|
url="&url.articles.problem-reports;/article.html">Writing
|
|
FreeBSD Problem Reports</ulink>).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Fix it! The <ulink
|
|
url="&url.books.porters-handbook;/index.html">Porter's
|
|
Handbook</ulink> includes detailed information on the
|
|
<quote>Ports</quote> infrastructure so that you can fix the
|
|
occasional broken port or even submit your own!</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Grab the package from an FTP site near you. The
|
|
<quote>master</quote> package collection is on <hostid
|
|
role="fqdn">ftp.FreeBSD.org</hostid> in the <ulink
|
|
url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/">packages
|
|
directory</ulink>, but be sure to check your closer <link
|
|
linkend="mirrors-ftp">mirror sites</link>
|
|
<emphasis>first</emphasis>! These are more likely to work
|
|
than trying to compile from source and are a lot faster as
|
|
well. Use the &man.pkg.add.1; program to install the
|
|
package on your system.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect1>
|
|
|
|
</chapter>
|