os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Did you know that we don't talk about packages anywhere in the Handbook?

Browse source 
Rectify that oversight.  Unfinished (needs some examples) but it's better
than nothing.
This commit is contained in:
Nik Clayton 2001-04-12 07:36:08 +00:00
parent b545dba68e
commit 1949bb09e0
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=9178
2 changed files with 480 additions and 202 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

341
en_US.ISO8859-1/books/handbook/ports/chapter.sgml
View file

@ -1,45 +1,258 @@
<!--
The FreeBSD Documentation Project
$FreeBSD: doc/en_US.ISO_8859-1/books/handbook/ports/chapter.sgml,v 1.112 2000/11/23 11:32:51 ben Exp $
$FreeBSD: doc/en_US.ISO_8859-1/books/handbook/ports/chapter.sgml,v 1.113 2001/02/09 19:03:22 nik Exp $
-->
<chapter id="ports">
<title>Installing Applications: The Ports collection</title>
<para><emphasis>Rewritten by &a.jim;, 22 November 1999. Original work
by various people.</emphasis></para>
<title>Installing Applications: Packages and Ports</title>
<sect1>
<title>Synopsis</title>
<para>The FreeBSD Ports collection allows you to compile and install a
very wide range of applications with a minimum amount of
effort.</para>
<para>There is only so much you can do with FreeBSD. If you are an
operating systems developer then the base system likely contains
everything you need. If that is not what you are planning to do with
FreeBSD then you will probably want to install additional
software&mdash;perhaps a web server, or a mail reader, or a graphical
environment such as KDE or GNOME.</para>
<para>In general, it is a group of <link
linkend="ports-skeleton">skeletons</link>
which contain a minimal set of items needed to make an application
compile and install cleanly on FreeBSD.</para>
<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>
<para>Even with all the hype about open standards, getting a program
to compile on various UNIX platforms can be a tricky task.
Occasionally, you might be lucky enough to find that the program you
want compiles cleanly on your system, install everything into all
the right directories, and run flawlessly
<quote>out-of-the-box</quote>, but this behavior is somewhat rare.
Most of the time, you find yourself needing to make modifications in
order to get the program to work. This is where the FreeBSD Ports
collection comes to the rescue.</para>
<procedure>
<step>
<para>Download the software, which might be distributed in source code
format, or as a binary.</para>
</step>
<para>The general idea behind the Ports collection is to eliminate all
of the messy steps involved with making things work properly so that
the installation is simple and very painless. With the Ports
collection, all of the hard work has already been done for you, and
you are able to install any of the Ports collection ports by simply
typing <command>make install</command>.</para>
<step>
<para>Unpack the software from its distribution format (typically a
tarball compressed with either &man.compress.1; or &man.gzip.1;).</para>
</step>
<step>
<para>Locate the documentation (perhaps a <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 4,000 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 <literal>pkg_*</literal> commands, such as
&man.pkg.add.1; &man.pkg.delete.1;, &man.pkg.info.1;, and so on.</para>
<para>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 (unpacking, patching, compiling,
installing). The files that make up a port contain all the necessary
information to alllow 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 the <literal>pkg_*</literal>
commands.</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 the commands will 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 you to understand any 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 686 processor.</para>
</listitem>
<listitem>
<para>Some packages have compile time options relating to what they
can and can't do. For example, <application>Apache</application>
can be configured with a wide variety of different builtin 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>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>
<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.
Currently there are over 4,000 applications available as packages or
ports. 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="http://www.FreeBSD.org/ports/">http://www.FreeBSD.org/ports/</ulink>.
The name space is divided in to categories, and you may either
search for an application by name (if you know it), or you can list
all the applications available in a category.</para>
</listitem>
<listitem>
<para>Dan Langille maintains FreshPorts, at
<ulink url="http://www.freshports.org/">http://www.freshports.org/</ulink>.
FreshPorts tracks changes to the applications in the ports tree as
they happen, and allows you to <quote>watch</quote> one or more
ports, and will send you an e-mail when they are updated.</para>
</listitem>
<listitem>
<para>If you do not know the name of the application you want, try
using a site like FreshMeat
(<ulink url="http://www.freshmeat.net/">http://www.freshmeat.net/</ulink>)
or AppWatch
(<ulink url="http://www.appwatch.com/">http://www.appwatch.com/</ulink>)
to find an application, then check back at the FreeBSD site to see
if the application has been ported yet.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>* Using the Packages System</title>
<sect2>
<title>Installing a Package</title>
<para>After you have decided which application you want to install you
need to download the package file and install it.</para>
<para>There are several ways you can do this.</para>
<example>
<title>Downloading and installing in multiple steps</title>
<para></para>
</example>
</sect2>
<sect2>
<title>Deleting a Package</title>
<para></para>
</sect2>
<sect2>
<title>Updating a Package</title>
<para></para>
</sect2>
<sect2>
<title></title>
<para></para>
</sect2>
</sect1>
<sect1 id="ports-using">
<title>Using the Ports Collection</title>
@ -361,80 +574,6 @@ Receiving xchat-1.3.8.tar.bz2 (305543 bytes): 100%
</answer>
</qandaentry>
<qandaentry>
<question>
<para>I thought you were supposed to use packages to install
extra programs?</para>
</question>
<answer>
<para>Yes, that is usually the quickest and easiest way of
doing it.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>So why bother with ports then?</para>
</question>
<answer>
<para>Several reasons:</para>
<orderedlist>
<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>You might have opinions on how a program should be
compiled that differ from the person who did the
package&mdash;some people have strong views on what
optimization settings should be used, whether to build
debug versions and then strip them or not, and so on.</para>
</listitem>
<listitem>
<para>Packages are normally built with quite conservative
settings. If a port has a compilation option to use code
for a specific processor, or a particular add-on board you
can enable this yourself in the port, without the people
making the package having to produce many, many different
packaged versions.</para>
<para>The most obvious exception to this rule is paper sizes.
If a package can be provided with default support for
different paper sizes we will often provide multiple
packages, one per paper size.</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>
<listitem>
<para>If you ain't got the source, it ain't software!
<!-- smiley -->;-)</para>
</listitem>
</orderedlist>
</answer>
</qandaentry>
<qandaentry>
<question>
<para id="ports-patch">What is a patch?</para>

341
en_US.ISO_8859-1/books/handbook/ports/chapter.sgml
View file

@ -1,45 +1,258 @@
<!--
The FreeBSD Documentation Project
$FreeBSD: doc/en_US.ISO_8859-1/books/handbook/ports/chapter.sgml,v 1.112 2000/11/23 11:32:51 ben Exp $
$FreeBSD: doc/en_US.ISO_8859-1/books/handbook/ports/chapter.sgml,v 1.113 2001/02/09 19:03:22 nik Exp $
-->
<chapter id="ports">
<title>Installing Applications: The Ports collection</title>
<para><emphasis>Rewritten by &a.jim;, 22 November 1999. Original work
by various people.</emphasis></para>
<title>Installing Applications: Packages and Ports</title>
<sect1>
<title>Synopsis</title>
<para>The FreeBSD Ports collection allows you to compile and install a
very wide range of applications with a minimum amount of
effort.</para>
<para>There is only so much you can do with FreeBSD. If you are an
operating systems developer then the base system likely contains
everything you need. If that is not what you are planning to do with
FreeBSD then you will probably want to install additional
software&mdash;perhaps a web server, or a mail reader, or a graphical
environment such as KDE or GNOME.</para>
<para>In general, it is a group of <link
linkend="ports-skeleton">skeletons</link>
which contain a minimal set of items needed to make an application
compile and install cleanly on FreeBSD.</para>
<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>
<para>Even with all the hype about open standards, getting a program
to compile on various UNIX platforms can be a tricky task.
Occasionally, you might be lucky enough to find that the program you
want compiles cleanly on your system, install everything into all
the right directories, and run flawlessly
<quote>out-of-the-box</quote>, but this behavior is somewhat rare.
Most of the time, you find yourself needing to make modifications in
order to get the program to work. This is where the FreeBSD Ports
collection comes to the rescue.</para>
<procedure>
<step>
<para>Download the software, which might be distributed in source code
format, or as a binary.</para>
</step>
<para>The general idea behind the Ports collection is to eliminate all
of the messy steps involved with making things work properly so that
the installation is simple and very painless. With the Ports
collection, all of the hard work has already been done for you, and
you are able to install any of the Ports collection ports by simply
typing <command>make install</command>.</para>
<step>
<para>Unpack the software from its distribution format (typically a
tarball compressed with either &man.compress.1; or &man.gzip.1;).</para>
</step>
<step>
<para>Locate the documentation (perhaps a <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 4,000 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 <literal>pkg_*</literal> commands, such as
&man.pkg.add.1; &man.pkg.delete.1;, &man.pkg.info.1;, and so on.</para>
<para>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 (unpacking, patching, compiling,
installing). The files that make up a port contain all the necessary
information to alllow 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 the <literal>pkg_*</literal>
commands.</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 the commands will 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 you to understand any 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 686 processor.</para>
</listitem>
<listitem>
<para>Some packages have compile time options relating to what they
can and can't do. For example, <application>Apache</application>
can be configured with a wide variety of different builtin 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>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>
<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.
Currently there are over 4,000 applications available as packages or
ports. 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="http://www.FreeBSD.org/ports/">http://www.FreeBSD.org/ports/</ulink>.
The name space is divided in to categories, and you may either
search for an application by name (if you know it), or you can list
all the applications available in a category.</para>
</listitem>
<listitem>
<para>Dan Langille maintains FreshPorts, at
<ulink url="http://www.freshports.org/">http://www.freshports.org/</ulink>.
FreshPorts tracks changes to the applications in the ports tree as
they happen, and allows you to <quote>watch</quote> one or more
ports, and will send you an e-mail when they are updated.</para>
</listitem>
<listitem>
<para>If you do not know the name of the application you want, try
using a site like FreshMeat
(<ulink url="http://www.freshmeat.net/">http://www.freshmeat.net/</ulink>)
or AppWatch
(<ulink url="http://www.appwatch.com/">http://www.appwatch.com/</ulink>)
to find an application, then check back at the FreeBSD site to see
if the application has been ported yet.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>* Using the Packages System</title>
<sect2>
<title>Installing a Package</title>
<para>After you have decided which application you want to install you
need to download the package file and install it.</para>
<para>There are several ways you can do this.</para>
<example>
<title>Downloading and installing in multiple steps</title>
<para></para>
</example>
</sect2>
<sect2>
<title>Deleting a Package</title>
<para></para>
</sect2>
<sect2>
<title>Updating a Package</title>
<para></para>
</sect2>
<sect2>
<title></title>
<para></para>
</sect2>
</sect1>
<sect1 id="ports-using">
<title>Using the Ports Collection</title>
@ -361,80 +574,6 @@ Receiving xchat-1.3.8.tar.bz2 (305543 bytes): 100%
</answer>
</qandaentry>
<qandaentry>
<question>
<para>I thought you were supposed to use packages to install
extra programs?</para>
</question>
<answer>
<para>Yes, that is usually the quickest and easiest way of
doing it.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>So why bother with ports then?</para>
</question>
<answer>
<para>Several reasons:</para>
<orderedlist>
<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>You might have opinions on how a program should be
compiled that differ from the person who did the
package&mdash;some people have strong views on what
optimization settings should be used, whether to build
debug versions and then strip them or not, and so on.</para>
</listitem>
<listitem>
<para>Packages are normally built with quite conservative
settings. If a port has a compilation option to use code
for a specific processor, or a particular add-on board you
can enable this yourself in the port, without the people
making the package having to produce many, many different
packaged versions.</para>
<para>The most obvious exception to this rule is paper sizes.
If a package can be provided with default support for
different paper sizes we will often provide multiple
packages, one per paper size.</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>
<listitem>
<para>If you ain't got the source, it ain't software!
<!-- smiley -->;-)</para>
</listitem>
</orderedlist>
</answer>
</qandaentry>
<qandaentry>
<question>
<para id="ports-patch">What is a patch?</para>