Attachment #22550 for bug #39084

View | Details | Raw Unified | Return to bug 39084
Collapse All | Expand All




      </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>


    <para>Should you want to, you can continue to install software the
      <quote>traditional</quote> way with FreeBSD.  However, FreeBSD
      provides two related 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 may 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.</para>

    <para>Installing a new application can be carried out with a single &man.pkg.add.1;
      command.</para>

    <para>A FreeBSD port for an application is a collection of files designed

      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

      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

	<para>The FreeBSD web site maintains an up-to-date searchable list of
	  all the available applications, at
	  <ulink url="../../../../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>


	<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, allows you to <quote>watch</quote> one or more
	  ports, and can send you email when they are updated.</para>
      </listitem>

      <indexterm><primary>FreshMeat</primary></indexterm>

	the network.</para>

      <example>
        <title>Downloading a Package Manually and then Installing It Locally</title>

        <screen>&prompt.root; <userinput>ftp -a <replaceable>ftp2.FreeBSD.org</replaceable></userinput>
Connected to ftp2.FreeBSD.org.

      </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>

          find them at <ulink
          url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/">
          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

          <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>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>
    </sect2>

    <sect2>
      <title>Managing Packages</title>

      <indexterm>

    </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>
    </sect2>

    <sect2>
      <title>Miscellaneous</title>
      <para>All package information is stored within the 
        <filename>/var/db/pkg</filename> directory.  The installed


	<step>
	  <para>Scroll down and select <literal>Configure</literal>,
	    then press <keycap>Enter</keycap>.</para>
	</step>

	<step>
	  <para>Scroll down and select
	    <literal>Distributions</literal>, then press <keycap>Enter</keycap>.</para>
	</step>

	<step>
	  <para>Scroll down to <literal>ports</literal>, then press
	    <keycap>Space</keycap>.</para>
	</step>

	<step>
	  <para>Scroll up to <literal>Exit</literal>, then press
	    <keycap>Enter</keycap>.</para>
	</step>

	<step>
	  <para>Select your desired installation media, such as CD-ROM,
	    FTP, or something else.</para>
	</step>

	<step>

	<filename>/usr/share/examples/cvsup/ports-supfile</filename>.
	See <link linkend="cvsup">Using CVSup</link> (<xref
	  linkend="cvsup">) for more information on using
	<application>CVSup</application> and this file.</para>

      <procedure>
	<title>CVSup Method</title>

	<para>This is a quick method for getting the ports collection
	  using <application>CVSup</application>.  If you want to keep
	  your ports tree up to date, or learn more about
	  <application>CVSup</application>, read the previously


	<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>Running this 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>
    </sect2>

	<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, to verify that files have not been
	    corrupted during the download.</para>
	</listitem>
	

	    known as <quote>diffs</quote> because they are generated by the
	    <application>diff</application> program.</para>

	  <para>This directory may also contain other files used to build
	    the port.</para>
	</listitem>


	first port.  There are two ways this can be done, and each is
	explained below.</para>

      <para>Before we get into that, however, you will need to choose a
        port to install.  There are a few ways to do this, with the
	easiest method being the <ulink
	url="../../../../ports/index.html">ports listing on the FreeBSD

        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>

	can be found in the
        <filename>/usr/ports/sysutils/lsof</filename> directory.</para>

      <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


      <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

       searching for <quote>lsof</quote>.</para>

      <note>
        <para>You must be logged in as <username>root</username> to install
          ports.</para>
      </note>

      <para>Now that you have found a port you would like to install,
        you are ready to do the actual installation.  The port
        includes instructions on how to build source code, but not 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>.  You can get the distfile from a
        CD-ROM or from the Internet.</para>

      <sect3 id="ports-cd">
        <title>Installing Ports from a CD-ROM</title>

        <indexterm>
          <primary>ports</primary>
          <secondary>installing from CD-ROM</secondary>
        </indexterm>
        <para>The FreeBSD Project's official CD-ROM images no longer
	  include distfiles.  They take up a lot of room that is
	  better used for precompiled packages.  CD-ROM products such as
	  the FreeBSD PowerPak do include distfiles, and you can
	  order these sets from a vendor such as the <ulink
	  url="http://www.freebsdmall.com/">FreeBSD Mall</ulink>.
	  This section assumes you have such a FreeBSD CD-ROM
	  set.</para>

        <para>Place your FreeBSD CD-ROM in the drive.  Mount it on
	  <filename>/cdrom</filename>.  (If you use a different mount
	  point, the install will not work.)  To begin, change to the
	  directory for the port you want to install:</para>


        <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>

...
&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


        <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 (see the <link linkend="ports-inet">next
	    section</link>).</para>
	</note>


        <para>As with the last section, this section makes an assumption
          that you have a working Internet connection.  If you do not,
	  you will need to perform the <link linkend="ports-cd">CD-ROM
	  installation</link>, or put a copy of the distfile into <filename>/usr/ports/distfiles</filename> manually.</para>

        <para>Installing a port from the Internet is done exactly the same
	  way as it would be if you were installing from a CD-ROM.  The
	  only difference between the two is that the distfile
	  is downloaded from the Internet instead of read from the
	  CD-ROM.</para>

        <para>The steps involved are identical:</para>


      </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).  As with installing ports,

    <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 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>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>
    </itemizedlist>
  </sect1>

	  <para>Ah, you must be thinking of the serial ports on the back
	    of your computer.  We are using <quote>port</quote> here to
	    mean the result of <quote>porting</quote> a program from one
	    operating system to another.</para>
	  </answer>
	</qandaentry>


	  <para>A patch is a small file that specifies how to go from
	    one version of a file to another.  It contains plain text,
	    and basically says things like <quote>delete line 23</quote>,
	    <quote>add these two lines after line 468</quote>, and
	    <quote>change line 197 to this</quote>.  They are also known
	    as diffs because they are generated by the
	    <application>diff</application> program.</para>

	  </question>

	  <answer>
	  <para>A tarball is a file, with a name generally ending in <filename>.tar</filename>, <filename>.tar.gz</filename>,
	    with variations such as <filename>.tar.gz</filename>,
	    <filename>.tar.Z</filename>, <filename>.tar.bz2</filename>,
	    or even <filename>.tgz</filename>.</para>

	  <para>Basically, a tarball is a directory tree that has been archived
	    into a single file (<filename>.tar</filename>) and
	    optionally compressed (<filename>.gz</filename>, <filename>.Z</filename>, or <filename>.bz2</filename>).  This
	    technique was originally used for <emphasis>T</emphasis>ape
	    <emphasis>AR</emphasis>chives (hence the name
	    <command>tar</command>), but it is a common way of
	    distributing program source code around the Internet.</para>

	  <para>You can see what files are in tarballs, or even extract
            the contents yourself, by using the standard Unix
	    <command>tar</command> program, which comes with the base
	    FreeBSD system, like this:</para>


  <indexterm><primary>checksum</primary></indexterm>
	<qandaentry>
	  <question>
	  <para id="ports-checksum">And checksums?</para>
	  </question>

	  <answer>

	    change, the checksum will no longer be equal to the total,
	    so a simple comparison will allow you to spot the
	    difference.</para>

	  <para>If a stored checksum matches the checksum calculated
	    for a file, such as a tarball, the file matches the
	    original for which the checksum was calculated. If there's
	    a discrepancy, there's a problem, such as file corruption;
	    removing the tarball and redownloading may fix the problem.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	  <para>I did what you said for compiling ports from a CD-ROM and
	    it worked great until I tried to install the kermit
	    port.</para>


&gt;&gt; cku190.tar.gz doesn't seem to exist on this system.
&gt;&gt; Attempting to fetch from ftp://kermit.columbia.edu/kermit/archives/.</screen>

	  <para>Why can it not be found?  Have I got a dud CD-ROM?</para>
	  </question>

	  <answer>
	  <para>As explained in the <link
	    linkend="ports-cd">compiling ports from CD-ROM</link>
	    section, some distfiles cannot be put on the CD-ROM set
	    due to licensing restrictions.  Kermit is an example of
	    that.  The licensing terms for kermit do not allow us to put
	    the tarball for it on the CD-ROM, so you will have to fetch
	    it by hand&mdash;sorry!</para>

	  <para>The reason why you got all those error messages was
	    because you were not connected to the Internet at the time.
	    Once you have downloaded the distfile from any of the <makevar>MASTER_SITES</makevar>
	    (listed in the <filename>Makefile</filename>), you can restart the install
	    process.</para>
	  </answer>

	  <para>The ports mechanism will download distribution
	    tarballs into <filename>/usr/ports/distfiles</filename>,
	    but many system administrators will symlink this directory
	    to a remote file server or local read-only CD-ROM media.
	    If this is the case, then you should specify a different
	    directory to be used for storing distfiles with the
	    following command:</para>

	  job.</para>

	  <para>If you do not fancy typing all that in every time you
	    install a port, you can put these variables
	    into your environment.  Read the manual page for your shell for
	    instructions on doing so.</para>
	  </answer>


	<qandaentry>
	  <question>
	  <para>I do not have a FreeBSD CD-ROM, but I would like to have
	    all the tarballs handy on my system so I do not have to wait
	    for a download every time I install a port.  Is there any
	    way to get them all at once?</para>

	    unless you used the <option>-fno-strength-reduce</option>
	    option as well.  (Most of the ports do not use
	    <option>-O2</option>).  You <emphasis>should</emphasis> be
	    able to specify compiler options with something
	    like:</para>

	  <screen>&prompt.root; <userinput>make CFLAGS='-O2 -fno-strength-reduce' install</userinput></screen>

	    is to do <command>make configure</command>, then go into
	    the source directory and inspect the Makefiles by hand, but
	    this can get tedious if the source has lots of
	    sub-directories, each with its own Makefile.</para>

	    <para>The default FreeBSD compiler options are quite conservative, 
	      so if you have not changed them you should not have any


	<qandaentry>
	  <question>
	  <para>I tried to install the <literal>foo</literal> port but
	    the system suddenly stopped compiling it and starting
	    compiling the <literal>bar</literal> port.  What is going
	    on?</para>

	    <literal>bar</literal> might have a library with useful
	    graphics processing routines.  Or <literal>bar</literal>
	    might be a tool that is needed to compile the
	    <literal>foo</literal> port. Once <literal>bar</literal> is finished, your system should automatically resume building <literal>foo</literal>.</para>
	  </answer>
	</qandaentry>


grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up
arcade game.</screen>

	  <para>The version number can also be found using 
	    <command>pkg_info</command> or by typing:
	    <command>ls /var/db/pkg</command></para>



	<qandaentry>
	  <question>
	  <para>Speaking of disk space, the ports directory seems to be
	    taking up an awful lot of room.  Is it safe to go in there
	    and delete things?</para>
	  </question>

Return to bug 39084