aboutsummaryrefslogblamecommitdiff
path: root/en_US.ISO8859-1/books/handbook/ports/chapter.xml
blob: 90a753b439e4dc80a400d0a666a403824a993d0f (plain) (tree)
1
2
3
4
5
6
7
8
9
10
                                           


                                      
              
   



                                                          
                                                            
 
                                 

                           

                                                      
                                                                   
                                                               
                                                                     

                                                                

                                                                
 
                                                           


                  
                                                                      
                 
 
                

                                                                   
                 
 
                
                                                 
                                                
                 
 
                

                                                                     
                 
 
                




                                                                  
                                                                 
                 


                   
                                 
                                                    
 

                                                                    


               

                                                                  


             
                                                                     
                                                                  

                                                          


             



                                                                      


             

                                                               

                                                     






                                                   

                                                                   




                                                                      



                                                                 




                                                                      

                  

                                                         
 

                                                                
                                                                  
                                              
 





                                                                     
                                                              


                                                                      

                  
                                     
 
                


                                                                    


                 
                                                                  
                                                                   
                                            
                                                                 
                                  


                 
                                                                      
                                                        



                   
                                  
 
                
                                                              


                                                                   


                 
                                                                     
                                                     
                                                                    
                                                            




                                                                      
                                                                      



                                                                      


                 
                                                                     

                                                                    


                 


                                                                     


                 

                                               


                   
                                                          
                                              
 
             
                                                          
                                                         


                                                              

              


                                                                    
          
 
                                             
                                   
 


                                                                  


                  
                                                                  
                                                          
                                                                                           

                                                             


                 

                                                            

                                                                         

                                                                     


                                                                      


                 

                                                             

                                                                      
                                                                           




                                                                      
                 

                




















                                                                                                     



                                                                   
                                                                    
                                                                   
                                                        
                                                                 





















                                                                                                        


                                                               


                 
                                                                     

                                                                 
                                                                     

                                                                    
 
                                                                 
                                       
 
                                                           
                      

                                                                             
                                 
 
                                                               

                                                                     


                 
                                                                
                                                                    




                                                                    
                                         

                                                                  
                                                          
                     

                                                                
                      
                
       

                 
             

                                                                  






                                                                      

                                                                   
 

                                                        
 
                                                                  
                                                               
                     


                                                                         
                                              
                              
                                                            
                                   
                                                                
                                                                  



                                                               
 

                                                                   
                                                                      

                                                 
                 


                   
                              
                                                                  
                        
 
                                                               


                                                                    
 



                                                                


                                                                      
                            




                                                              
                                     
                                                         
                      
 
                                        
                                 
                                              
 
                                                                  







                                                                 
                                                              




                                                                  
 



                                                                         
                                                               
                                            
 
                                                       




                                                                               
                                                                      
                                                                


                                                                    

                                                                      


                                                                  


                                                                      


                                                                     
                                                                  
                                                                
                                          




                                                                      
                                                           


                                                                 

             


                                                                     
                                                            


                                                            
 





                                                               
 

                                                                   
 
                                                                   
                                                              

                                                                   
                                                                   

                                                                    
                                            




                                                                            

                                                               
                                                                  


                                                                
            
 












































                                                                                                                          
                                   
                                                                   
 




                                                                    
 
                                                
                                                                
 
                                                               
                    
            
 
                                                  
                                                     
 


                                                                   
 
                                                                                                              
 



                                                                
 
                                                                   
                             





                                                                              
 

                                        
 
                                             
 
                    

                                                                
                          
                                             

                                       





                                                                   
                                                                            

                                                                                   

                                                                    
                                                             



                                                                    
                     



                                                              

                                             
 
                                    

                                                 
                                                              



                                                                       


                                                                    
            
 
                                   
                                                
 
                                                             
                                                      
                                                                   


                                                                 

                                                                          

            
                                     
                                                           
 

                                                                      

                                                                     
 
                                                                 
                           
                            



                                                                    
                                                  










































                                                                                    
            
 
                                 
                                                   
 
                                                             
                                                               

                                                                    
 

                                                                
                               

                                                              
            
 
                                                                  
                                                   

                                                                     




                                                                                                                     
                                                                 





                                                                      
 
                                                                                                                     
            
 
                                
                                            
 
                                                             
                                                       



                                                                      
 
                                                                     



                                                                        
            
 
                              



                                                               
                                                                
                                                                    


                                                  



                                                               
 
                                                                                           
 


                                                   
 
                                                                                              
 
                                                           


                                                          
 
                                                                                                         
 




                                                                      
 
                                                                                                                          
             


            
                              
                                             
 
                                          
                                                                     


                                                               
 

                                                                
 

















                                                                     



                                                                 
 
                                                    

                                    
                                            
                                                                
                                                                  

                                                            


                                                                      

            


                                                            




                                                                            

                                                                      
                                                 






                                                                              

                                                                     

                                                                   
                                                             
 




                                                                                   


                
                                                      

                                      
                                                                     
                                                                  

                                                                   
                                                                                 
                                                                


                                                     



                                                                     

                                                                                   

                                                                
                                                    
                                                                

                                                                
 
                                                                                    
 


             

                                                              
 
                                                                                                                        


             





                                                                                                                                   


                                                                     


                                                                                   






                                                                                                                                 

                





                                                                   









                                                                     


                                                                     























                                                                      


                                                                 



                                                                    
                                                                 
 
                                   






                                         

                                                                     

                                                                    
 
               



                                                                    
                                                               
                                                                      
                                                                     


                                                                     
                                                     
                                  

                
                                                                 

                                                                 



                                                                    



                                                                                  
                                                                                  
                                 


                           



                                                   


                          
                                   
   
                            
   
 
                                     
   
                             

                                           

                                                    
                       

                                                                       
                    

                      














                                                                    
 
                                                                  
                                                          


                                                                    

                                                             
                                 

                      
            
                                                                
                                                                   
             
 

                                                     
 
                                                                   

                                                                    

                                                 







                                                                      
 
             


                                                                    
                                                                      
                                            



                                                                    
              
 


                                                                      
                                                                 


                                                                



                                                                     









                                                                     


                                                                     




                                                                     

                                                                     

                                                                     
                                                                   



                                                                      
                                                                                                       
                                                     
                                                                                                             
 

                                                                      
                                                              
 
                                                                                                               
 


                                                                  


                                                                                                         


                                                                      
 
                                                                                                                
 
                                          
 


                                                                      
              
            
 
                                   

                                             
                 

                                       
                  
 

                                                                   
                                                           




                                                                              
                                                   

                                       












                                                                     

            
                                    





                                        
 



                                                                   
 
                                                                 




                                                                      
                                                                  
                                                              



                                                                                 

                                                                    
 
                                                                                 
 




                                                                  







                                                                     
                  
 
                                            
                                                        





                                                


                                                                 







                                                          



                                                                      


               
 
                                 
                                    
                                                       




                                       

                                                                

                                                                 

                                                        
                           
 
                                                                                        

                                                                

                                                                


                      

                                                             

                     
                    

                                                                  

                     
                    

                                                               

                     
                    

                                                                
                     

                       
                                                                     
 
                                                                  





                                                             
   


                                                                 
   



                                                               
   
                             
 

                                                               
 

                                                          


                                                                           
              

                                                                     
                                                                 

                                                             
                                                                      
                                                                 
                                                                      

                                                                  
                                                                    
                               
               
 


                                                                   


                                                                            
                                                                    

                                                             

                                                                  
 
                                                                                                               
 


                                                                      
              
 
                                  





                                                        




                                                                   





                                                                                         

                                                        
 



                                                                      




                                                                             


                                                                     




                                                                                    

                                                               


                                                                     

                                                                    


                                                               
 
                                                                                    





                                                                    
 


                                                                   
              
 
            
 
                                     





                                         

                                                                  
                                                            


                                                                     


                                                                 

                                                                     


                                                                         



                                                                    
                                       

                                                                         
 
                                                             

                                                                    


                                                                          

                                                                  
 

                                                                                        
                                                               

                                                                   

                                                   

                                                                  
            
          
 



                                                  
                                                   
                                                                      
                                                           






                                                                      
 
                                                                 
                                                                     
                                                                
                                                                     


                                                                   


                                                                     
                                          








                                                                      
                                                 


                                                                      


                                                                      
                                                     



                                                    
                                           
                                                                  




                                                                     
                                                     
                                                              
 















































                                                                                                                                                     
 
                                                                      


                                                                    



                                                                      



                                                                   
                                                 

                                                                     
                                                                                            




                                                                     
                                                                                                 





                                   
                                                                
                          
 
                                                                                                                                                                                                                                                                 
 

                                                     
 
                                                                                                                                                                                                                                                              
 
                                             
                                                                           
                                                




                                                                                     
                                                                    

                                                                  
 

                                                                   
                                    
                                                                                
            
           

                                                       

                                                                      
                                                                  





                                                                    
                                
                   
                  
 
                                                                    

                                                                     

                                                                                                   
                                        

                                                    
                                                                   
                                        

                                                                 
 
                               
                                                                         
                     
                  
            

          
                                  






                                                                    


                  
                                                            
                                                                    
                                                             






                                                                      


                 
                                                                   
                                                                    

                                                                     


                 
                                                                



                                                                    
                                                        







                                                                  
                 
 

                                             

                                                                    


                 

                                                                
                             



                   
                               
                                            
 

                                        
 

                 
                                                                     
                                                                
                                                                     
                                       
                 
 

                                                            
                                            


                                                                


                                                                    
 

                                                                  
                                                                


                                                                               
                                                                                            

                                                         
 
                                                  
                                                                  



                                                                     
               
 
                                                       
                                                   

                                                                            
                                               
                 
 
                

                                                                         
                                                                

                                                                 
                 
 
                
                                                               
                                                               

                  
          
          
<?xml version="1.0" encoding="iso-8859-1"?>
<!--
     The FreeBSD Documentation Project

     $FreeBSD$
-->
<chapter xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
  xml:id="ports">

  <title>Installing Applications: Packages and Ports</title>

  <sect1 xml:id="ports-synopsis">
    <title>Synopsis</title>

    <indexterm><primary>ports</primary></indexterm>
    <indexterm><primary>packages</primary></indexterm>
    <para>&os; is bundled with a rich collection of system tools as
      part of the base system.  In addition,  &os; provides two
      complementary technologies for installing third-party software:
      the &os; Ports Collection, for installing from source, and
      packages, for installing from pre-built binaries.  Either
      method may be used to install software from local media or
      from the network.</para>

    <para>After reading this chapter, you will know:</para>

    <itemizedlist>
      <listitem>
	<para>The difference between binary packages and ports.</para>
      </listitem>

      <listitem>
	<para>How to find third-party software that has been ported
	  to &os;.</para>
      </listitem>

      <listitem>
	<para>How to manage binary packages using
	  <application>pkg</application>.</para>
      </listitem>

      <listitem>
	<para>How to build third-party software from source using the
	  Ports Collection.</para>
      </listitem>

      <listitem>
	<para>How to find the files installed with the application
	  for post-installation configuration.</para>
      </listitem>

      <listitem>
	<para>What to do if a software installation fails.</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 xml:id="ports-overview">
    <title>Overview of Software Installation</title>

    <para>The typical steps for installing third-party software on a
      &unix; system include:</para>

    <procedure>
      <step>
	<para>Find and 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.  This
	  is typically a tarball compressed with a program such as
	  &man.compress.1;, &man.gzip.1;, &man.bzip2.1; or
	  &man.xz.1;.</para>
      </step>

      <step>
	<para>Locate the documentation in
	  <filename>INSTALL</filename>, <filename>README</filename>
	  or some file 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.</para>
      </step>

      <step>
	<para>Test and install the software.</para>
      </step>
    </procedure>

    <para>A &os; <emphasis>port</emphasis> is a collection of files
      designed to automate
      the process of compiling an application from source code.  The
      files that comprise a port contain all the necessary information
      to automatically download, extract, patch, compile, and install
      the application.</para>

    <para>If the software has not already been adapted and tested
      on &os;, the source code might need editing in
      order for it to install and run properly.</para>

    <para>However, over <link
	xlink:href="&url.base;/ports/index.html">&os.numports;</link>
      third-party applications have already been ported to &os;.  When
      feasible, these applications are made available for download as
      pre-compiled <emphasis>packages</emphasis>.</para>

    <para>Packages
      can be manipulated with the &os; package management
      commands.</para>

    <para>Both packages and ports understand dependencies.  If a
      package or port is used to install an application and a
      dependent library is not already installed, the library will
      automatically be installed first.</para>

    <para>A &os; package contains pre-compiled copies of all the
      commands for an application, as well as any configuration files
      and documentation.  A package can be manipulated with the
      &man.pkg.8; commands, such as
      <command>pkg install</command>.</para>

    <para>While the two technologies are similar, packages and
      ports each have their own strengths.  Select the technology that
      meets your requirements for installing a particular
      application.</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 compilation time.  For large
	  applications, such as <application>Mozilla</application>,
	  <application>KDE</application>, or
	  <application>GNOME</application>, this can be important
	  on a slow system.</para>
      </listitem>

      <listitem>
	<para>Packages do not require any understanding of the process
	  involved in compiling software on &os;.</para>
      </listitem>
    </itemizedlist>

    <itemizedlist>
      <title>Port Benefits</title>

      <listitem>
	<para>Packages are normally compiled with conservative
	  options because they have to run on the maximum number of
	  systems.  By compiling from the port, one can change the
	  compilation options.</para>
      </listitem>

      <listitem>
	<para>Some applications have compile-time options relating to
	  which features are installed.  For example,
	  <application>Apache</application> can be configured with a
	  wide variety of different built-in options.</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 <application>Xorg</application> is installed.
	  Creating multiple packages 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 forbid binary
	  distribution.  Such software must be distributed as source
	  code which must be compiled by the end-user.</para>
      </listitem>

      <listitem>
	<para>Some people do not trust binary distributions or prefer
	  to read through source code in order to look for potential
	  problems.</para>
      </listitem>

      <listitem>
	<para>Source code is needed in
	  order to apply custom patches.</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, check <link
	  xlink:href="https://vuxml.freebsd.org/"></link>
	for security issues related to the application or type
	<command>pkg audit -F</command> to check all installed
	applications for known vulnerabilities.</para>
    </warning>

    <para>The remainder of this chapter explains how to use packages
      and ports to install and manage third-party software on
      &os;.</para>
  </sect1>

  <sect1 xml:id="ports-finding-applications">
    <title>Finding Software</title>

    <para>&os;'s list of available applications is growing all the
      time.  There are a number of ways to find software to
      install:</para>

    <itemizedlist>
      <listitem>
	<para>The &os; web site maintains an up-to-date searchable
	  list of all the available applications, at <link
	    xlink:href="&url.base;/ports/index.html">https://www.FreeBSD.org/ports/</link>.
	  The ports can be searched by application name or by
	  software category.</para>
      </listitem>

      <listitem>
	<indexterm><primary>FreshPorts</primary></indexterm>

	<para>Dan Langille maintains <link
	    xlink:href="http://www.FreshPorts.org/">FreshPorts.org</link>
	  which provides a comprehensive search utility and also
	  tracks changes to the applications in the Ports Collection.
	  Registered users can create a customized watch list in order
	  to receive an automated email when their watched ports are
	  updated.</para>
      </listitem>

      <listitem>
	<indexterm><primary>SourceForge</primary></indexterm>

	<para>If finding a particular application becomes challenging,
	  try searching a site like <link
	    xlink:href="http://www.sourceforge.net/">SourceForge.net</link>
	  or <link
	    xlink:href="http://www.github.com/">GitHub.com</link> then
	  check back at the <link
	    xlink:href="&url.base;/ports/index.html">&os; site</link>
	  to see if the application has been ported.</para>
      </listitem>

      <listitem>
	<indexterm>
	  <primary>pkg</primary>
	  <secondary>search</secondary>
	</indexterm>

	<para xml:id="pkg-search">To search the binary package
	  repository for an application:</para>

	<screen>&prompt.root; <userinput>pkg search <replaceable>subversion</replaceable></userinput>
git-subversion-<replaceable>1.9.2</replaceable>
java-subversion-<replaceable>1.8.8_2</replaceable>
p5-subversion-<replaceable>1.8.8_2</replaceable>
py27-hgsubversion-<replaceable>1.6</replaceable>
py27-subversion-<replaceable>1.8.8_2</replaceable>
ruby-subversion-<replaceable>1.8.8_2</replaceable>
subversion-<replaceable>1.8.8_2</replaceable>
subversion-book-<replaceable>4515</replaceable>
subversion-static-<replaceable>1.8.8_2</replaceable>
subversion16-<replaceable>1.6.23_4</replaceable>
subversion17-<replaceable>1.7.16_2</replaceable></screen>

	<para>Package names include the version number and, in the
	  case of ports based on python, the version number of the
	  version of python the package was built with.  Some ports
	  also have multiple versions available.  In the case of
	  <application>Subversion</application>, there are different
	  versions available, as well as different compile options.
	  In this case, the statically linked version of
	  <application>Subversion</application>.  When indicating
	  which package to install, it is best to specify the
	  application by the port origin, which is the path in the
	  ports tree.  Repeat the <command>pkg search</command> with
	  <option>-o</option> to list the origin of each
	  package:</para>

	<screen>&prompt.root; <userinput>pkg search -o <replaceable>subversion</replaceable></userinput>
devel/git-subversion
java/java-subversion
devel/p5-subversion
devel/py-hgsubversion
devel/py-subversion
devel/ruby-subversion
devel/subversion16
devel/subversion17
devel/subversion
devel/subversion-book
devel/subversion-static</screen>

	<para>Searching by shell globs, regular expressions, exact
	  match, by description, or any other field in the repository
	  database is also supported by <command>pkg search</command>.
	  After installing <package>ports-mgmt/pkg</package> or
	  <package>ports-mgmt/pkg-devel</package>, see
	  &man.pkg-search.8; for more details.</para>
      </listitem>

      <listitem>
	<para>If the Ports Collection is already installed, there are
	  several methods to query the local version of the ports
	  tree.  To find out which category a port is in, type
	  <command>whereis <replaceable>file</replaceable></command>,
	  where <replaceable>file</replaceable> is the program to be
	  installed:</para>

	<screen>&prompt.root; <userinput>whereis lsof</userinput>
lsof: /usr/ports/sysutils/lsof</screen>

	<para>Alternately, an &man.echo.1; statement can be
	  used:</para>

	<screen>&prompt.root; <userinput>echo /usr/ports/*/*lsof*</userinput>
/usr/ports/sysutils/lsof</screen>

	<para>Note that this will also return any matched files
	  downloaded into the
	  <filename>/usr/ports/distfiles</filename> directory.</para>
      </listitem>

      <listitem>
	<para>Another way to find software is by using the Ports
	  Collection's built-in search mechanism.  To use the search
	  feature, <application>cd</application> to
	  <filename>/usr/ports</filename> then run <command>make
	    search name=program-name</command> where
	  <replaceable>program-name</replaceable> is the name of the
	  software.  For example, to search for
	  <command>lsof</command>:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports</userinput>
&prompt.root; <userinput>make search name=lsof</userinput>
Port:   lsof-4.88.d,8
Path:   /usr/ports/sysutils/lsof
Info:   Lists information about open files (similar to fstat(1))
Maint:  ler@lerctr.org
Index:  sysutils
B-deps:
R-deps: </screen>

	<tip>
	  <para>The built-in search mechanism uses a file
	    of index information.  If a message indicates that the
	    <filename>INDEX</filename> is required, run
	    <command>make fetchindex</command> to download the current
	    index file.  With the <filename>INDEX</filename> present,
	    <command>make search</command> will be able to perform the
	    requested search.</para>
	</tip>

	<para>The <quote>Path:</quote> line indicates where to find
	  the port.</para>

	<para>To receive less information, use the
	  <command>quicksearch</command> feature:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports</userinput>
&prompt.root; <userinput>make quicksearch name=lsof</userinput>
Port:   lsof-4.88.d,8
Path:   /usr/ports/sysutils/lsof
Info:   Lists information about open files (similar to fstat(1))</screen>

	<para>For more in-depth searching, use
	  <command>make search
	  key=<replaceable>string</replaceable></command> or
	  <command>make quicksearch
	  key=<replaceable>string</replaceable></command>, where
	  <replaceable>string</replaceable> is some text to search
	  for.  The text can be in comments, descriptions, or
	  dependencies in order to find ports which relate to a
	  particular subject when the name of the program is
	  unknown.</para>

	<para>When using <buildtarget>search</buildtarget> or
	  <buildtarget>quicksearch</buildtarget>, 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 xml:id="pkgng-intro">
    <title>Using <application>pkg</application> for Binary Package
      Management</title>

    <para><application>pkg</application> is the next generation
      replacement for the traditional &os; package management tools,
      offering many features that make dealing with binary packages
      faster and easier.</para>

    <para>For sites wishing to only use prebuilt binary packages
      from the &os; mirrors, managing packages with
      <application>pkg</application> can be sufficient.</para>

    <para>However, for those sites building from source or using their
      own repositories, a separate <link
	linkend="ports-upgrading-tools">port management tool</link>
      will be needed.</para>

    <para>Since <application>pkg</application> only works with
      binary packages, it
      is not a replacement for such tools.  Those tools can be
      used to install software from both binary packages
      and the Ports Collection, while
      <application>pkg</application> installs only binary
      packages.</para>

    <sect2 xml:id="pkgng-initial-setup">
      <title>Getting Started with
	<application>pkg</application></title>

      <para>&os; includes a bootstrap utility which can be used to
	download and install <application>pkg</application>
	and its manual pages.  This utility is designed to work
	with versions of &os; starting with
	10.<replaceable>X</replaceable>.</para>

      <note>
	<para>Not all &os; versions and architectures
	  support this bootstrap process.  The current list is at
	  <link xlink:href="https://pkg.freebsd.org/"></link>.
	  For other cases,
	  <application>pkg</application> must instead be installed
	  from the Ports Collection or as a binary package.</para>

      </note>

      <para>To bootstrap the system, run:</para>

      <screen>&prompt.root; <userinput>/usr/sbin/pkg</userinput></screen>

      <para>You must have a working Internet connection for the
	bootstrap process to succeed.</para>

      <para>Otherwise, to install the port, run:</para>

      <screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/pkg</userinput>
&prompt.root; <userinput>make</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>

      <para>When upgrading an existing system that originally used the
	older pkg_* tools, the database must be converted to the
	new format, so that the new tools are aware of the already
	installed packages.  Once <application>pkg</application> has
	been installed, the
	package database must be converted from the traditional format
	to the new format by running this command:</para>

      <screen>&prompt.root; <userinput>pkg2ng</userinput></screen>

      <note><para>This step is not required for new installations that
	do not yet have any third-party software
	installed.</para></note>

      <important>
	<para>This step is not reversible.  Once the package database
	  has been converted to the <application>pkg</application>
	  format, the traditional <literal>pkg_*</literal> tools
	  should no longer be used.</para>
      </important>

      <note>
	<para>The package database conversion may emit errors as the
	  contents are converted to the new version.  Generally, these
	  errors can be safely ignored.  However, a list of
	  software that was not successfully converted
	  is shown after <command>pkg2ng</command> finishes.
	  These applications must be manually reinstalled.</para>
      </note>

      <para>To ensure that the Ports Collection registers
	new software with <application>pkg</application> instead of
	the traditional packages database, &os; versions earlier than
	10.<replaceable>X</replaceable> require this line in
	<filename>/etc/make.conf</filename>:</para>

      <programlisting>WITH_PKGNG=	yes</programlisting>

      <para>By default, <application>pkg</application> uses the
	binary packages from the &os;
	package mirrors (the <emphasis>repository</emphasis>).
	For information about building a custom
	package repository, see
	<xref linkend="ports-poudriere"/>.</para>

      <para>Additional <application>pkg</application> configuration
	options are described in &man.pkg.conf.5;.</para>

      <para>Usage information for <application>pkg</application> is
	available in the &man.pkg.8; manual page or by running
	<command>pkg</command> without additional arguments.</para>

      <para>Each <application>pkg</application> command argument is
	documented in a command-specific manual page.  To read the
	manual page for <command>pkg install</command>, for example,
	run either of these commands:</para>

      <screen>&prompt.root; <userinput>pkg help install</userinput></screen>

      <screen>&prompt.root; <userinput>man pkg-install</userinput></screen>

      <para>The rest of this section demonstrates common binary
	package management tasks which can be performed using
	<application>pkg</application>.  Each demonstrated command
	provides many switches to customize its use.  Refer to a
	command's help or man page for details and more
	examples.</para>
    </sect2>

    <sect2 xml:id="quarterly-latest-branch">
      <title>Quarterly and Latest Ports Branches</title>

      <para>The <literal>Quarterly</literal> branch provides users
	with a more predictable and stable experience for port and
	package installation and upgrades.  This is done essentially
	by only allowing non-feature updates.  Quarterly branches aim
	to receive security fixes (that may be version updates, or
	backports of commits), bug fixes and ports compliance or
	framework changes.  The Quarterly branch is cut from HEAD at
	the beginning of every (yearly) quarter in January, April,
	July, and October.  Branches are named according to the year
	(YYYY) and quarter (Q1-4) they are created in.  For example,
	the quarterly branch created in January 2016, is named 2016Q1.
	And the <literal>Latest</literal> branch provides the latest
	versions of the packages to the users.</para>

      <para>To switch from quarterly to latest run the following
	commands:</para>

      <screen>&prompt.root; <userinput>cp /etc/pkg/FreeBSD.conf /usr/local/etc/pkg/repos/FreeBSD.conf</userinput></screen>

      <para>Edit the file
	<filename>/usr/local/etc/pkg/repos/FreeBSD.conf</filename>
	and change the string <emphasis>quarterly</emphasis> to
	<emphasis>latest</emphasis> in the <literal>url:</literal>
	line.</para>

      <para>The result should be similar to the following:</para>

      <programlisting>FreeBSD: {
  url: "pkg+http://pkg.FreeBSD.org/${ABI}/latest",
  mirror_type: "srv",
  signature_type: "fingerprints",
  fingerprints: "/usr/share/keys/pkg",
  enabled: yes
}</programlisting>

      <para>And finally run this command to update from the new
	(latest) repository metadata.</para>

      <screen>&prompt.root; <userinput>pkg update -f</userinput></screen>

    </sect2>

    <sect2 xml:id="pkgng-pkg-info">
      <title>Obtaining Information About Installed Packages</title>

      <para>Information about the packages installed on a system
	can be viewed by running <command>pkg info</command> which,
	when run without any switches, will list the package version
	for either all installed packages or the specified
	package.</para>

      <para>For example, to see which version of
	<application>pkg</application> is installed, run:</para>

      <screen>&prompt.root; <userinput>pkg info pkg</userinput>
pkg-1.1.4_1</screen>
    </sect2>

    <sect2 xml:id="pkgng-installing-deinstalling">
      <title>Installing and Removing Packages</title>

      <para>To install a binary package use the following command,
	where <replaceable>packagename</replaceable> is the name of
	the package to install:</para>

      <screen>&prompt.root; <userinput>pkg install <replaceable>packagename</replaceable></userinput></screen>

      <para>This command uses repository data to determine which
	version of the software to install and if it has any
	uninstalled dependencies.  For example, to install
	<application>curl</application>:</para>

      <screen>&prompt.root; <userinput>pkg install curl</userinput>
Updating repository catalogue
/usr/local/tmp/All/curl-7.31.0_1.txz          100% of 1181 kB 1380 kBps 00m01s

/usr/local/tmp/All/ca_root_nss-3.15.1_1.txz   100% of  288 kB 1700 kBps 00m00s

Updating repository catalogue
The following 2 packages will be installed:

        Installing ca_root_nss: 3.15.1_1
        Installing curl: 7.31.0_1

The installation will require 3 MB more space

0 B to be downloaded

Proceed with installing packages [y/N]: <userinput>y</userinput>
Checking integrity... done
[1/2] Installing ca_root_nss-3.15.1_1... done
[2/2] Installing curl-7.31.0_1... done
Cleaning up cache files...Done</screen>

	<para>The new package and any additional packages that were
	  installed as dependencies can be seen in the installed
	  packages list:</para>

	<screen>&prompt.root; <userinput>pkg info</userinput>
ca_root_nss-3.15.1_1	The root certificate bundle from the Mozilla Project
curl-7.31.0_1	Non-interactive tool to get files from FTP, GOPHER, HTTP(S) servers
pkg-1.1.4_6	New generation package manager</screen>

	<para>Packages that are no longer needed can be removed with
	  <command>pkg delete</command>.  For example:</para>

	<screen>&prompt.root; <userinput>pkg delete curl</userinput>
The following packages will be deleted:

	curl-7.31.0_1

The deletion will free 3 MB

Proceed with deleting packages [y/N]: <userinput>y</userinput>
[1/1] Deleting curl-7.31.0_1... done</screen>
    </sect2>

    <sect2 xml:id="pkgng-upgrading">
      <title>Upgrading Installed Packages</title>

      <para>Installed packages can be upgraded to their latest
	versions by running:</para>

      <screen>&prompt.root; <userinput>pkg upgrade</userinput></screen>

      <para>This command will compare the installed versions with
	those available in the repository catalogue and upgrade them
	from the repository.</para>
    </sect2>

    <sect2 xml:id="pkgng-auditing">
      <title>Auditing Installed Packages</title>

      <para>Software vulnerabilities are regularly discovered
	in third-party applications.  To address this,
	<application>pkg</application> includes a built-in auditing
	mechanism.  To determine if there are any known
	vulnerabilities for the software installed on the system,
	run:</para>

	<screen>&prompt.root; <userinput>pkg audit -F</userinput></screen>
    </sect2>

    <sect2 xml:id="pkgng-autoremove">
      <title>Automatically Removing Unused Packages</title>

      <para>Removing a package may leave behind dependencies which
	are no longer required.  Unneeded packages that were installed
	as dependencies (leaf packages) can be automatically detected
	and removed using:</para>

      <screen>&prompt.root; <userinput>pkg autoremove</userinput>
Packages to be autoremoved:
	ca_root_nss-3.15.1_1

The autoremoval will free 723 kB

Proceed with autoremoval of packages [y/N]: <userinput>y</userinput>
Deinstalling ca_root_nss-3.15.1_1... done</screen>

      <para>Packages installed as dependencies are
	called <emphasis>automatic</emphasis> packages.  Non-automatic
	packages, i.e the packages that were explicity installed not
	as a dependency to another package, can be listed
	using:</para>

      <screen>&prompt.root; <userinput>pkg prime-list</userinput>
nginx
openvpn
sudo</screen>

      <para><command>pkg prime-list</command> is an alias command
	declared in <filename>/usr/local/etc/pkg.conf</filename>.
	There are many others that can be used to query the package
	database of the system.  For instance, command
	<command>pkg prime-origins</command> can be used to get the
	origin port directory of the list mentioned above:</para>

      <screen>&prompt.root; <userinput>pkg prime-origins</userinput>
www/nginx
security/openvpn
security/sudo</screen>

      <para>This list can be used to rebuild all packages
	installed on a system using build tools such as <package>
	ports-mgmt/poudriere</package> or <package>
	ports-mgmt/synth</package>.</para>

    <para>Marking an installed package as automatic can be
      done using:</para>

      <screen>&prompt.root; <userinput>pkg set -A 1 devel/cmake</userinput></screen>

      <para>Once a package is a leaf package and is marked
	as automatic, it gets selected by
	<command>pkg autoremove</command>.</para>

      <para>Marking an installed package as <emphasis>not</emphasis>
	automatic can be done using:</para>

      <screen>&prompt.root; <userinput>pkg set -A 0 devel/cmake</userinput></screen>

    </sect2>

    <sect2 xml:id="pkgng-backup">
      <title>Restoring the Package Database</title>

      <para>Unlike the traditional package management system,
	<application>pkg</application> includes its own package
	database backup mechanism.  This functionality is enabled by
	default.</para>

      <tip>
	<para>To disable the periodic script from backing up the
	  package database, set
	  <literal>daily_backup_pkgdb_enable="NO"</literal> in
	  &man.periodic.conf.5;.</para>
      </tip>

      <para>To restore the contents of a previous package database
	backup, run the following command replacing
	<replaceable>/path/to/pkg.sql</replaceable> with the location
	of the backup:</para>

      <screen>&prompt.root; <userinput>pkg backup -r <replaceable>/path/to/pkg.sql</replaceable></userinput></screen>

      <note>
	<para>If restoring a backup taken by the periodic script,
	  it must be decompressed prior to being restored.</para>
      </note>

      <para>To run a manual backup of the
	<application>pkg</application> database, run the following
	command, replacing <replaceable>/path/to/pkg.sql</replaceable>
	with a suitable file name and location:</para>

      <screen>&prompt.root; <userinput>pkg backup -d <replaceable>/path/to/pkg.sql</replaceable></userinput></screen>
    </sect2>

    <sect2 xml:id="pkgng-clean">
      <title>Removing Stale Packages</title>

      <para>By default, <application>pkg</application> stores
	binary packages in a cache directory defined by
	<envar>PKG_CACHEDIR</envar> in &man.pkg.conf.5;.  Only copies
	of the latest installed packages are kept.  Older versions of
	<application>pkg</application> kept all previous packages.  To
	remove these outdated binary packages, run:</para>

      <screen>&prompt.root; <userinput>pkg clean</userinput></screen>

      <para>The entire cache may be cleared by running:</para>

      <screen>&prompt.root; <userinput>pkg clean -a</userinput></screen>
    </sect2>

    <sect2 xml:id="pkgng-set">
      <title>Modifying Package Metadata</title>

      <para>Software within the &os;&nbsp;Ports Collection can
	undergo major version number changes.  To address this,
	<application>pkg</application> has a built-in command to
	update package origins.  This can be useful, for example, if
	<package>lang/php5</package> is renamed to
	<package>lang/php53</package> so that
	<package>lang/php5</package> can now
	represent version <literal>5.4</literal>.</para>

      <para>To change the package origin for the above example,
	run:</para>

      <screen>&prompt.root; <userinput>pkg set -o lang/php5:lang/php53</userinput></screen>

      <para>As another example, to update
	<package>lang/ruby18</package> to
	<package>lang/ruby19</package>, run:</para>

      <screen>&prompt.root; <userinput>pkg set -o lang/ruby18:lang/ruby19</userinput></screen>

      <para>As a final example, to change the origin of the
	<filename>libglut</filename> shared libraries from
	<package>graphics/libglut</package> to
	<package>graphics/freeglut</package>, run:</para>

      <screen>&prompt.root; <userinput>pkg set -o graphics/libglut:graphics/freeglut</userinput></screen>

      <note>
	<para>When changing package origins, it is important to
	  reinstall packages that are dependent on the package with
	  the modified origin.  To force a reinstallation of dependent
	  packages, run:</para>

	<screen>&prompt.root; <userinput>pkg install -Rf <replaceable>graphics/freeglut</replaceable></userinput></screen>
      </note>
    </sect2>
  </sect1>

  <sect1 xml:id="ports-using">
    <title>Using the Ports Collection</title>

    <para>The Ports Collection is a set of
      <filename>Makefile</filename>s, patches, and description files.
      Each set of these files is used to compile and install an
      individual application on &os;, and is called a
      <emphasis>port</emphasis>.</para>

    <para>By default, the Ports Collection itself is stored as a
      subdirectory of <filename>/usr/ports</filename>.</para>

    <warning>
      <para>Before installing and using the Ports Collection, please
	be aware that it is generally ill-advised to use the
	Ports Collection in conjunction with the binary packages
	provided via <application>pkg</application> to install
	software.  <application>pkg</application>, by default,
	tracks quarterly branch-releases of the ports
	tree and not HEAD. Dependencies could be different for a port
	in HEAD compared to its counterpart in a quarterly branch
	release and this could result in conflicts between
	dependencies installed by <application>pkg</application>
	and those from the Ports Collection.
	If the Ports Collection and <application>pkg</application>
	must be used in conjunction, then be sure that your
	Ports Collection and <application>pkg</application> are
	on the same branch release of the ports tree.</para>
    </warning>

    <para>Before an application can be compiled using a port, the
      Ports Collection must first be installed.  If it was not
      installed during the installation of &os;, use one of the
      following methods to install it:</para>

    <procedure xml:id="ports-using-portsnap-method">
      <title>Portsnap Method</title>

      <para>The base system of &os; includes
	<application>Portsnap</application>.  This is a fast and
	user-friendly tool for retrieving the Ports Collection and
	is the recommended choice for most users not running
	&os.current;.  This utility
	connects to a &os; site, verifies the secure key, and
	downloads a new copy of the Ports Collection.  The key is used
	to verify the integrity of all downloaded files.</para>

      <step>
	<para>To download a compressed snapshot of the Ports
	  Collection into
	  <filename>/var/db/portsnap</filename>:</para>

	<screen>&prompt.root; <userinput>portsnap fetch</userinput></screen>
      </step>

      <step>
	<para>When running <application>Portsnap</application> for the
	  first time, extract the snapshot into
	  <filename>/usr/ports</filename>:</para>

	<screen>&prompt.root; <userinput>portsnap extract</userinput></screen>
      </step>

      <step>
	<para>After the first use of
	  <application>Portsnap</application> has been completed as
	  shown above, <filename>/usr/ports</filename> can be updated
	  as needed by running:</para>

	<screen>&prompt.root; <userinput>portsnap fetch</userinput>
&prompt.root; <userinput>portsnap update</userinput></screen>

	<para>When using <literal>fetch</literal>, the
	  <literal>extract</literal> or the <literal>update</literal>
	  operation may be run consecutively, like so:</para>

	<screen>&prompt.root; <userinput>portsnap fetch update</userinput></screen>
      </step>
    </procedure>

    <procedure xml:id="ports-using-subversion-method">
      <title>Subversion Method</title>

      <para>If more control over the ports tree is needed or if local
	changes need to be maintained, or if running &os.current;,
	<application>Subversion</application> can be used to obtain
	the Ports Collection.  Refer to <link
	  xlink:href="&url.articles.committers-guide;/subversion-primer.html">the
	  Subversion Primer</link> for a detailed description of
	<application>Subversion</application>.</para>

      <step>
	<para><application>Subversion</application> must be installed
	  before it can be used to check out the ports tree.  If a
	  copy of the ports tree is already present, install
	  <application>Subversion</application> like this:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/devel/subversion</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>

	<para>If the ports tree is not available, or
	  <application>pkg</application> is being used to manage
	  packages, <application>Subversion</application> can be
	  installed as a package:</para>

	<screen>&prompt.root; <userinput>pkg install subversion</userinput></screen>

      </step>

      <step>
	<para>Check out a copy of the HEAD branch of the ports
	  tree:</para>

	<screen>&prompt.root; <userinput>svn checkout https://svn.FreeBSD.org/ports/head /usr/ports</userinput></screen>
      </step>

      <step>
	<para>Or, check out a copy of a quarterly branch:</para>

	<screen>&prompt.root; <userinput>svn checkout https://svn.FreeBSD.org/ports/branches/2020Q3 /usr/ports</userinput></screen>
      </step>

      <step>
	<para>As needed, update <filename>/usr/ports</filename> after
	  the initial <application>Subversion</application>
	  checkout:</para>

	<screen>&prompt.root; <userinput>svn update /usr/ports</userinput></screen>
      </step>

      <step>
	<para>As needed, switch <filename>/usr/ports</filename> to a
	  different quarterly branch:</para>

	<screen>&prompt.root; <userinput>svn switch http://svn.freebsd.org/ports/branches/2020Q4/ /usr/ports</userinput></screen>
      </step>
    </procedure>

    <para>The Ports Collection contains directories
      for software categories.  Inside each category are
      subdirectories for individual applications.  Each application
      subdirectory contains a set of files that
      tells &os; how to compile and install that program,
      called a <emphasis>ports skeleton</emphasis>.  Each port
      skeleton includes these files and directories:</para>

    <itemizedlist>
      <listitem>
	<para><filename>Makefile</filename>: contains statements that
	  specify how the application should be compiled and where
	  its components should be installed.</para>
      </listitem>

      <listitem>
	<para><filename>distinfo</filename>: contains the names and
	  checksums of the files that must be downloaded to build the
	  port.</para>
      </listitem>

      <listitem>
	<para><filename>files/</filename>: this directory contains
	  any patches needed for the program to compile and install
	  on &os;.  This directory may also contain other files used
	  to build the port.</para>
      </listitem>

      <listitem>
	<para><filename>pkg-descr</filename>: provides a more detailed
	  description of the program.</para>
      </listitem>

      <listitem>
	<para><filename>pkg-plist</filename>:  a list of all the
	  files that will be installed by the port.  It also tells
	  the ports system which files to remove upon
	  deinstallation.</para>
      </listitem>
    </itemizedlist>

    <para>Some ports include <filename>pkg-message</filename> or
      other files to handle special situations.  For more details
      on these files, and on ports in general, refer to the <link
	xlink:href="&url.books.porters-handbook;/index.html">&os;
	Porter's Handbook</link>.</para>

    <para>The port does not include the actual source code, also
      known as a <filename>distfile</filename>.  The extract portion
      of building a port will automatically save the downloaded
      source to <filename>/usr/ports/distfiles</filename>.</para>

    <sect2 xml:id="ports-skeleton">
      <title>Installing Ports</title>

      <indexterm>
	<primary>ports</primary>
	<secondary>installing</secondary>
      </indexterm>

      <para>This section provides basic instructions on using the
	Ports Collection to install or remove software.  The detailed
	description of available <command>make</command> targets and
	environment variables is available in &man.ports.7;.</para>

      <warning>
	<para>Before compiling any port, be sure to update the Ports
	  Collection as described in the previous section.  Since
	  the installation of any third-party software can introduce
	  security vulnerabilities, it is recommended to first check
	  <link xlink:href="https://vuxml.freebsd.org/"></link>
	  for known security issues related to the port.  Alternately,
	  run <command>pkg audit -F</command> before installing a new
	  port.  This command can be configured to automatically
	  perform a security audit and an update of the vulnerability
	  database during the daily security system check.  For more
	  information, refer to &man.pkg-audit.8; and
	  &man.periodic.8;.</para>
      </warning>

      <para>Using the Ports Collection assumes a working Internet
	connection.  It also requires superuser privilege.</para>

      <para>To compile and install the port, change to the directory
	of the port to be installed, then type <command>make
	  install</command> at the prompt.  Messages will indicate
	the progress:</para>

      <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput>
&prompt.root; <userinput>make install</userinput>
&gt;&gt; lsof_4.88D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
&gt;&gt; Attempting to fetch from ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/.
===&gt;  Extracting for lsof-4.88
...
[extraction output snipped]
...
&gt;&gt; Checksum OK for lsof_4.88D.freebsd.tar.gz.
===&gt;  Patching for lsof-4.88.d,8
===&gt;  Applying FreeBSD patches for lsof-4.88.d,8
===&gt;  Configuring for lsof-4.88.d,8
...
[configure output snipped]
...
===&gt;  Building for lsof-4.88.d,8
...
[compilation output snipped]
...

===&gt;  Installing for lsof-4.88.d,8
...
[installation output snipped]
...
===&gt;   Generating temporary packing list
===&gt;   Compressing manual pages for lsof-4.88.d,8
===&gt;   Registering installation for lsof-4.88.d,8
===&gt;  SECURITY NOTE:
      This port has installed the following binaries which execute with
      increased privileges.
/usr/local/sbin/lsof
&prompt.root;</screen>

      <para>Since <command>lsof</command> is a program that runs
	with increased privileges, a security warning is displayed
	as it is installed.  Once the installation is complete, the
	prompt will be returned.</para>

      <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.  Users
	of the <command>tcsh</command> shell should type
	<command>rehash</command> so that a newly installed command
	can be used without specifying its full path.  Use
	<command>hash -r</command> instead for the
	<command>sh</command> shell.  Refer to the documentation
	for the shell for more information.</para>

      <para>During installation, a working subdirectory is created
	which contains all the temporary files used during
	compilation.  Removing this directory saves disk space and
	minimizes the chance of problems later when upgrading to the
	newer version of the port:</para>

      <screen>&prompt.root; <userinput>make clean</userinput>
===&gt;  Cleaning for lsof-88.d,8
&prompt.root;</screen>

      <note>
	<para>To save this extra step, instead use <command>make
	    install clean</command> when compiling the port.</para>
      </note>

      <sect3>
	<title>Customizing Ports Installation</title>

	<para>Some ports provide build options which can be used to
	  enable or disable application components, provide security
	  options, or allow for other customizations.  Examples
	  include <package>www/firefox</package>,
	  <package>security/gpgme</package>, and
	  <package>mail/sylpheed-claws</package>.  If the port depends
	  upon other ports which have configurable options, it may
	  pause several times for user interaction as the default
	  behavior is to prompt the user to select options from a
	  menu.  To avoid this and do all of the configuration in one
	  batch, run <command>make config-recursive</command> within
	  the port skeleton.  Then, run <command>make install
	    [clean]</command> to compile and install the port.</para>

	<tip>
	  <para>When using
	    <buildtarget>config-recursive</buildtarget>, the list of
	    ports to configure are gathered by the
	    <buildtarget>all-depends-list</buildtarget> target.  It is
	    recommended to run <command>make
	      config-recursive</command> until all dependent ports
	    options have been defined, and ports options screens no
	    longer appear, to be certain that all dependency options
	    have been configured.</para>
	</tip>

	<para>There are several ways to revisit a port's build options
	  menu in order to add, remove, or change these options after
	  a port has been built.  One method is to
	  <command>cd</command> into the directory containing the
	  port and type <command>make config</command>.  Another
	  option is to use <command>make showconfig</command>.
	  Another option is to execute <command>make
	    rmconfig</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
	  &man.ports.7;.</para>

	<para>The ports system uses &man.fetch.1; to download the
	  source files, which supports various environment variables.
	  The <envar>FTP_PASSIVE_MODE</envar>,
	  <envar>FTP_PROXY</envar>, and <envar>FTP_PASSWORD</envar>
	  variables may need to be set if the &os; system is behind
	  a firewall or FTP/HTTP proxy.  See &man.fetch.3; for the
	  complete list of supported variables.</para>

	<para>For users who cannot be connected to the Internet all
	  the time, <command>make fetch</command> can be run within
	  <filename>/usr/ports</filename>, to fetch all distfiles, or
	  within a category, such as
	  <filename>/usr/ports/net</filename>, or within the specific
	  port skeleton.  Note that if a port has any dependencies,
	  running this command in a category or ports skeleton will
	  <emphasis>not</emphasis> fetch the distfiles of ports from
	  another category.  Instead, use <command>make
	    fetch-recursive</command> to also fetch the distfiles for
	  all the dependencies of a port.</para>

	<para>In rare cases, such as when an organization has a local
	  distfiles repository, the <varname>MASTER_SITES</varname>
	  variable can be used to override the download locations
	  specified in the <filename>Makefile</filename>.  When using,
	  specify the alternate location:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput>
&prompt.root; <userinput>make MASTER_SITE_OVERRIDE= \
<replaceable>ftp://ftp.organization.org/pub/FreeBSD/ports/distfiles/</replaceable> fetch</userinput></screen>

	<para>The <varname>WRKDIRPREFIX</varname> and
	  <varname>PREFIX</varname> variables can override the default
	  working and target 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 the port in <filename>/usr/ports</filename>
	  and install it in
	  <filename>/usr/home/example/local</filename>.  And:</para>

	<screen>&prompt.root; <userinput>make WRKDIRPREFIX=../ports PREFIX=../local install</userinput></screen>

	<para>will combine the two.</para>

	<para>These can also be set as environmental variables.  Refer
	  to the manual page for your shell for instructions on how to
	  set an environmental variable.</para>
      </sect3>
    </sect2>

    <sect2 xml:id="ports-removing">
      <title>Removing Installed Ports</title>

      <indexterm>
	<primary>ports</primary>
	<secondary>removing</secondary>
      </indexterm>

      <para>Installed ports can be uninstalled using <command>pkg
	  delete</command>.  Examples for using this command can be
	found in the &man.pkg-delete.8; manual page.</para>

      <para>Alternately, <command>make deinstall</command> can be
	run in the port's directory:</para>

      <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput>
&prompt.root; <userinput>make deinstall</userinput>
===&gt;  Deinstalling for sysutils/lsof
===&gt;   Deinstalling
Deinstallation has been requested for the following 1 packages:

	lsof-4.88.d,8

The deinstallation will free 229 kB
[1/1] Deleting lsof-4.88.d,8... done</screen>

      <para>It is recommended to read the messages as the port is
	uninstalled.  If the port has any applications that depend
	upon it, this information will be displayed but the
	uninstallation will proceed.  In such cases, it may be better
	to reinstall the application in order to prevent broken
	dependencies.</para>
    </sect2>

    <sect2 xml:id="ports-upgrading">
      <title>Upgrading Ports</title>

      <indexterm>
	<primary>ports</primary>
	<secondary>upgrading</secondary>
      </indexterm>

      <para>Over time, newer versions of software become available
	in the Ports Collection.  This section describes how to
	determine which software can be upgraded and how to perform
	the upgrade.</para>

      <para>To determine if newer versions of installed ports are
	available, ensure that the latest version of the ports tree is
	installed, using the updating command described in either
	<xref linkend="ports-using-portsnap-method"/> or
	<xref linkend="ports-using-subversion-method"/>.  On &os; 10
	and later, or if the system has been converted to
	<application>pkg</application>, the following command will
	list the installed ports which are out of date:</para>

      <screen>&prompt.root; <userinput>pkg version -l "&lt;"</userinput></screen>

      <para>For &os; 9.<replaceable>X</replaceable> and lower, the
	following command will list the installed ports that are out
	of date:</para>

      <screen>&prompt.root; <userinput>pkg_version -l "&lt;"</userinput></screen>

      <important>
	<para>Before
	  attempting an upgrade, read
	  <filename>/usr/ports/UPDATING</filename> from the top of
	  the file to the date closest to the last time ports were
	  upgraded or the system was installed.  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 any incompatibilities with previous
	  versions.  Make note of any instructions which match any of
	  the ports that need upgrading and follow these instructions
	  when performing the upgrade.</para>
      </important>

      <sect3 xml:id="ports-upgrading-tools">
	<title>Tools to Upgrade and Manage Ports</title>

	<indexterm>
	  <primary>ports</primary>
	  <secondary>upgrading-tools</secondary>
	</indexterm>

	<para>The Ports Collection contains several utilities to
	  perform the actual upgrade.  Each has its strengths and
	  weaknesses.</para>

	<para>Historically, most installations used either
	  <application>Portmaster</application> or
	  <application>Portupgrade</application>.
	  <application>Synth</application> is a newer
	  alternative.</para>

	<note>
	  <para>The choice of which tool is best for a particular
	    system is up to the system administrator.  It is
	    recommended practice to back up your data before using any
	    of these tools.</para>
	</note>

      </sect3>

      <sect3 xml:id="portmaster">
	<title>Upgrading Ports Using
	  <application>Portmaster</application></title>

	<indexterm>
	  <primary>portmaster</primary>
	</indexterm>

	<para><package>ports-mgmt/portmaster</package> is a very
	  small utility for upgrading installed ports.
	  It is designed to use the tools installed with the &os;
	  base system
	  without depending on other ports or databases.
	  To install this utility
	  as a port:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/portmaster</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>

	<para><application>Portmaster</application> defines four
	  categories of ports:</para>

	<itemizedlist>
	  <listitem>
	    <para>Root port: has no dependencies and is not a
	      dependency of any other ports.</para>
	  </listitem>

	  <listitem>
	    <para>Trunk port: has no dependencies, but other ports
	      depend upon it.</para>
	  </listitem>

	  <listitem>
	    <para>Branch port: has dependencies and other ports
	      depend upon it.</para>
	  </listitem>

	  <listitem>
	    <para>Leaf port: has dependencies but no other ports
	      depend upon it.</para>
	  </listitem>
	</itemizedlist>

	<para>To list these categories and search for updates:</para>

	<screen>&prompt.root; <userinput>portmaster -L</userinput>
===&gt;&gt;&gt; Root ports (No dependencies, not depended on)
===&gt;&gt;&gt; ispell-3.2.06_18
===&gt;&gt;&gt; screen-4.0.3
        ===&gt;&gt;&gt; New version available: screen-4.0.3_1
===&gt;&gt;&gt; tcpflow-0.21_1
===&gt;&gt;&gt; 7 root ports
...
===&gt;&gt;&gt; Branch ports (Have dependencies, are depended on)
===&gt;&gt;&gt; apache22-2.2.3
        ===&gt;&gt;&gt; New version available: apache22-2.2.8
...
===&gt;&gt;&gt; Leaf ports (Have dependencies, not depended on)
===&gt;&gt;&gt; automake-1.9.6_2
===&gt;&gt;&gt; bash-3.1.17
        ===&gt;&gt;&gt; New version available: bash-3.2.33
...
===&gt;&gt;&gt; 32 leaf ports

===&gt;&gt;&gt; 137 total installed ports
        ===&gt;&gt;&gt; 83 have new versions available</screen>

	<para>This command is used to upgrade all outdated
	  ports:</para>

	<screen>&prompt.root; <userinput>portmaster -a</userinput></screen>

	<note>
	  <para>By default, <application>Portmaster</application>
	    makes a backup package before deleting the existing port.
	    If the installation of the new version is successful,
	    <application>Portmaster</application> deletes the
	    backup.  Using <option>-b</option> instructs
	    <application>Portmaster</application> not to automatically
	    delete the backup.  Adding <option>-i</option> starts
	    <application>Portmaster</application> in interactive mode,
	    prompting for confirmation before upgrading each port.
	    Many other options are available.  Read through the
	    manual page for &man.portmaster.8; for details regarding
	    their usage.</para>
	</note>

	<para>If errors are encountered during the upgrade process,
	  add <option>-f</option> to upgrade and rebuild all
	  ports:</para>

	<screen>&prompt.root; <userinput>portmaster -af</userinput></screen>

	<para><application>Portmaster</application> can also be used
	  to install new ports on the system, upgrading all
	  dependencies before building and installing the new
	  port.  To use this function, specify the location of the
	  port in the Ports Collection:</para>

	<screen>&prompt.root; <userinput>portmaster <replaceable>shells/bash</replaceable></userinput></screen>

	<para>More information about
	  <package>ports-mgmt/portmaster</package> may be found in its
	  <filename>pkg-descr</filename>.</para>
      </sect3>

      <sect3 xml:id="portupgrade">
	<title>Upgrading Ports Using Portupgrade</title>

	<indexterm>
	  <primary>portupgrade</primary>
	</indexterm>

	<para><package>ports-mgmt/portupgrade</package> is another
	  utility that can be used to upgrade ports.  It installs a
	  suite of applications which can be used to manage ports.
	  However, it is dependent upon Ruby.  To install the
	  port:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/portupgrade</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>

	<para>Before performing an upgrade using this utility, it is
	  recommended to scan the list of installed ports using
	  <command>pkgdb -F</command> and to fix all the
	  inconsistencies it reports.</para>

	<para>To upgrade all the outdated ports installed on the
	  system, use <command>portupgrade -a</command>.  Alternately,
	  include <option>-i</option> to be asked for confirmation
	  of every individual upgrade:</para>

	<screen>&prompt.root; <userinput>portupgrade -ai</userinput></screen>

	<para>To upgrade only a specified application instead of all
	  available ports, use <command>portupgrade
	    <replaceable>pkgname</replaceable></command>.  It is very
	  important to include <option>-R</option> to first upgrade
	  all the ports required by the given application:</para>

	<screen>&prompt.root; <userinput>portupgrade -R firefox</userinput></screen>

	<para>If
	  <option>-P</option> is included,
	  <application>Portupgrade</application> searches for
	  available packages in the local directories listed in
	  <envar>PKG_PATH</envar>.  If none are available locally, it
	  then fetches packages from a remote site.  If packages can
	  not be found locally or fetched remotely,
	  <application>Portupgrade</application> will use ports.  To
	  avoid using ports entirely, specify <option>-PP</option>.
	  This last set of options tells
	  <application>Portupgrade</application> to abort if no
	  packages are available:</para>

	<screen>&prompt.root; <userinput>portupgrade -PP gnome3</userinput></screen>

	<para>To just fetch the port distfiles, or packages, if
	  <option>-P</option> is specified, without building or
	  installing anything, use <option>-F</option>.  For further
	  information on all of the available switches, refer to the
	  manual page for <command>portupgrade</command>.</para>

	<para>More information about
	  <package>ports-mgmt/portupgrade</package> may be found in
	  its <filename>pkg-descr</filename>.</para>
      </sect3>

    </sect2>

    <sect2 xml: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 a port, running
	<command>make clean</command> within the ports skeleton will
	clean up the temporary <filename>work</filename> directory.
	If <application>Portmaster</application> is used to install a
	port, it will automatically remove this directory unless
	<option>-K</option> is specified.  If
	<application>Portupgrade</application> is installed, this
	command will remove all <filename>work</filename> directories
	found within the local copy of the Ports Collection:</para>

      <screen>&prompt.root; <userinput>portsclean -C</userinput></screen>

      <para>In addition, outdated source distribution files
	accumulate in <filename>/usr/ports/distfiles</filename> over
	time.  To use <application>Portupgrade</application> to
	delete all the distfiles that are no longer
	referenced by any ports:</para>

      <screen>&prompt.root; <userinput>portsclean -D</userinput></screen>

      <para><application>Portupgrade</application> can remove
	all distfiles not referenced by any port currently installed
	on the system:</para>

      <screen>&prompt.root; <userinput>portsclean -DD</userinput></screen>

      <para>If <application>Portmaster</application> is installed,
	use:</para>

      <screen>&prompt.root; <userinput>portmaster --clean-distfiles</userinput></screen>

      <para>By default, this command is interactive and prompts
	the user to confirm if a distfile should be deleted.</para>

      <para>In addition to these commands,
	<package>ports-mgmt/pkg_cutleaves</package>
	automates the task of removing installed ports that are no
	longer needed.</para>
    </sect2>
  </sect1>

  <sect1 xml:id="ports-poudriere">
    <title>Building Packages with
      <application>Poudriere</application></title>

    <para><application>Poudriere</application> is a
      <acronym>BSD</acronym>-licensed utility for creating and testing
      &os; packages.  It uses &os; jails to set up isolated
      compilation environments.  These jails can be used to build
      packages for versions of &os; that are different from the system
      on which it is installed, and also to build packages for i386 if
      the host is an &arch.amd64; system.  Once the packages are
      built, they are in a layout identical to the official mirrors.
      These packages are usable by &man.pkg.8; and other package
      management tools.</para>

    <para><application>Poudriere</application> is installed using
      the <package role="port">ports-mgmt/poudriere</package> package
      or port.  The installation includes a sample configuration
      file <filename>/usr/local/etc/poudriere.conf.sample</filename>.
      Copy this file to
      <filename>/usr/local/etc/poudriere.conf</filename>.  Edit the
      copied file to suit the local configuration.</para>

    <para>While <acronym>ZFS</acronym> is not required on the system
      running <application>poudriere</application>, it is beneficial.
      When <acronym>ZFS</acronym> is used,
      <varname>ZPOOL</varname> must be specified in
      <filename>/usr/local/etc/poudriere.conf</filename> and
      <varname>FREEBSD_HOST</varname> should be set to a nearby
      mirror.  Defining <varname>CCACHE_DIR</varname> enables the use
      of <package role="port">devel/ccache</package> to cache
      compilation and reduce build times for frequently-compiled code.
      It may be convenient to put
      <application>poudriere</application> datasets in an isolated
      tree mounted at <filename
	>/poudriere</filename>.  Defaults for the
      other configuration values are adequate.</para>

    <para>The number of processor cores detected is used to define how
      many builds will run in parallel.  Supply enough virtual memory,
      either with <acronym>RAM</acronym> or swap space.  If virtual
      memory runs out, the compilation jails will stop and be torn
      down, resulting in weird error messages.</para>

    <sect2 xml:id="poudriere-initialization">
      <title>Initialize Jails and Port Trees</title>

      <para>After configuration, initialize
	<application>poudriere</application> so that it installs a
	jail with the required &os; tree and a ports tree.  Specify a
	name for the jail using <option>-j</option> and the &os;
	version with <option>-v</option>.  On systems running
	&os;/&arch.amd64;, the architecture can be set with
	<option>-a</option> to either <literal>i386</literal> or
	<literal>amd64</literal>.  The default is the
	architecture shown by <command>uname</command>.</para>

      <screen>&prompt.root; <userinput>poudriere jail -c -j <replaceable>11amd64</replaceable> -v <replaceable>11.4-RELEASE</replaceable></userinput>
[00:00:00] Creating 11amd64 fs at /poudriere/jails/11amd64... done
[00:00:00] Using pre-distributed MANIFEST for FreeBSD 11.4-RELEASE amd64
[00:00:00] Fetching base for FreeBSD 11.4-RELEASE amd64
/poudriere/jails/11amd64/fromftp/base.txz              125 MB 4110 kBps    31s
[00:00:33] Extracting base... done
[00:00:54] Fetching src for FreeBSD 11.4-RELEASE amd64
/poudriere/jails/11amd64/fromftp/src.txz               154 MB 4178 kBps    38s
[00:01:33] Extracting src... done
[00:02:31] Fetching lib32 for FreeBSD 11.4-RELEASE amd64
/poudriere/jails/11amd64/fromftp/lib32.txz              24 MB 3969 kBps    06s
[00:02:38] Extracting lib32... done
[00:02:42] Cleaning up... done
[00:02:42] Recording filesystem state for clean... done
[00:02:42] Upgrading using ftp
/etc/resolv.conf -&gt; /poudriere/jails/11amd64/etc/resolv.conf
Looking up update.FreeBSD.org mirrors... 3 mirrors found.
Fetching public key from update4.freebsd.org... done.
Fetching metadata signature for 11.4-RELEASE from update4.freebsd.org... done.
Fetching metadata index... done.
Fetching 2 metadata files... done.
Inspecting system... done.
Preparing to download files... done.
Fetching 124 patches.....10....20....30....40....50....60....70....80....90....100....110....120.. done.
Applying patches... done.
Fetching 6 files... done.
The following files will be added as part of updating to
11.4-RELEASE-p1:
/usr/src/contrib/unbound/.github
/usr/src/contrib/unbound/.github/FUNDING.yml
/usr/src/contrib/unbound/contrib/drop2rpz
/usr/src/contrib/unbound/contrib/unbound_portable.service.in
/usr/src/contrib/unbound/services/rpz.c
/usr/src/contrib/unbound/services/rpz.h
/usr/src/lib/libc/tests/gen/spawnp_enoexec.sh
The following files will be updated as part of updating to
11.4-RELEASE-p1:
[&hellip;]
Installing updates...Scanning //usr/share/certs/blacklisted for certificates...
Scanning //usr/share/certs/trusted for certificates...
 done.
11.4-RELEASE-p1
[00:04:06] Recording filesystem state for clean... done
[00:04:07] Jail 11amd64 11.4-RELEASE-p1 amd64 is ready to be used</screen>

      <screen>&prompt.root; <userinput>poudriere ports -c -p <replaceable>local</replaceable> -m svn+https</userinput>
[00:00:00] Creating local fs at /poudriere/ports/local... done
[00:00:00] Checking out the ports tree... done</screen>

      <para>On a single computer, <application>poudriere</application>
	can build ports with multiple configurations, in multiple
	jails, and from different port trees.  Custom configurations
	for these combinations are called <emphasis>sets</emphasis>.
	See the CUSTOMIZATION section of &man.poudriere.8; for details
	after <package>ports-mgmt/poudriere</package> or
	<package>ports-mgmt/poudriere-devel</package> is
	installed.</para>

      <para>The basic configuration shown here puts a single jail-,
	port-, and set-specific <filename>make.conf</filename> in
	<filename
	  >/usr/local/etc/poudriere.d</filename>.
	The filename in this example is created by combining the jail
	name, port name, and set name:
	<filename><replaceable>11amd64-local-workstation</replaceable>-make.conf</filename>.
	The system <filename>make.conf</filename> and this new file
	are combined at build time to create the
	<filename>make.conf</filename> used by the build jail.</para>

      <para>Packages to be built are entered in
	<filename><replaceable>11amd64-local-workstation</replaceable>-pkglist</filename>:</para>

      <programlisting>editors/emacs
devel/git
ports-mgmt/pkg
...</programlisting>

      <para>Options and dependencies for the specified ports are
	configured:</para>

      <screen>&prompt.root; <userinput>poudriere options -j <replaceable>11amd64</replaceable> -p <replaceable>local</replaceable> -z <replaceable>workstation</replaceable> -f <replaceable>11amd64-local-workstation-pkglist</replaceable></userinput></screen>

      <para>Finally, packages are built and a package
	repository is created:</para>

      <screen>&prompt.root; <userinput>poudriere bulk -j <replaceable>11amd64</replaceable> -p <replaceable>local</replaceable> -z <replaceable>workstation</replaceable> -f <replaceable>11amd64-local-workstation-pkglist</replaceable></userinput></screen>

      <para>While running, pressing <keycombo
	  action="simul"><keycap>Ctrl</keycap><keycap>t</keycap></keycombo>
	displays the current state of the build.
	<application>Poudriere</application> also builds files in
	<filename>/poudriere/logs/bulk/<replaceable>jailname</replaceable></filename>
	that can be used with a web server to display build
	information.</para>

      <para>After completion, the new packages are now available for
	installation from the <application>poudriere</application>
	repository.</para>

      <para>For more information on using
	<application>poudriere</application>, see &man.poudriere.8;
	and the main web site, <link
	  xlink:href="https://github.com/freebsd/poudriere/wiki"></link>.</para>
    </sect2>
    <sect2>
      <title>Configuring pkg Clients to Use a Poudriere
	Repository</title>

      <para>While it is possible to use both a custom repository along
	side of the official repository, sometimes it is useful to
	disable the official repository.  This is done by creating a
	configuration file that overrides and disables the official
	configuration file.  Create
	<filename>/usr/local/etc/pkg/repos/FreeBSD.conf</filename>
	that contains the following:</para>

      <programlisting>FreeBSD: {
	enabled: no
}</programlisting>

      <para>Usually it is easiest to serve a poudriere repository to
	the client machines via HTTP.  Set up a webserver to serve up
	the package directory, for instance:
	<filename>/usr/local/poudriere/data/packages/<replaceable>11amd64</replaceable></filename>,
	where <filename><replaceable>11amd64</replaceable></filename>
	is the name of the build.</para>

      <para>If the URL to the package repository is:
	<literal>http://pkg.example.com/11amd64</literal>, then the
	repository configuration file in
	<filename>/usr/local/etc/pkg/repos/custom.conf</filename>
	would look like:</para>

      <programlisting>custom: {
	url: "<replaceable>http://pkg.example.com/11amd64</replaceable>",
	enabled: yes,
}</programlisting>
    </sect2>
  </sect1>

  <sect1 xml:id="ports-nextsteps">
    <title>Post-Installation Considerations</title>

    <para>Regardless of whether the software was installed from a
      binary package or port, most third-party applications require
      some level of configuration after installation.  The following
      commands and locations can be used to help determine what was
      installed with the application.</para>

    <itemizedlist>
      <listitem>
	<para>Most applications install at least one default
	  configuration file in <filename>/usr/local/etc</filename>.
	  In cases where an application has a large number of
	  configuration files, a subdirectory will be created to hold
	  them.  Often, sample configuration files are installed which
	  end with a suffix such as <filename>.sample</filename>.  The
	  configuration files should be reviewed and possibly
	  edited to meet the system's needs.  To edit a sample file,
	  first copy it without the <filename>.sample</filename>
	  extension.</para>
      </listitem>

      <listitem>
	<para>Applications which provide documentation will install
	  it into <filename>/usr/local/share/doc</filename> and many
	  applications also install manual pages.  This documentation
	  should be consulted before continuing.</para>
      </listitem>

      <listitem>
	<para>Some applications run services which must be added
	  to <filename>/etc/rc.conf</filename> before starting the
	  application.  These applications usually install a startup
	  script in <filename>/usr/local/etc/rc.d</filename>.  See
	  <link linkend="configtuning-starting-services">Starting
	    Services</link> for more information.</para>

	<note>
	  <para>By design, applications do not run their startup
	    script upon installation, nor do they run their stop
	    script upon deinstallation or upgrade.  This decision
	    is left to the individual system administrator.</para>
	</note>

      </listitem>

      <listitem>
	<para>Users of &man.csh.1; should run
	  <command>rehash</command> to rebuild the known binary list
	  in the shells <envar>PATH</envar>.</para>
      </listitem>

      <listitem>
	<para>Use <command>pkg info</command> to determine which
	  files, man pages, and binaries were installed with the
	  application.</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 xml:id="ports-broken">
    <title>Dealing with Broken Ports</title>

    <para>When a port does not build or
      install, try the following:</para>

    <orderedlist>
      <listitem>
	<para>Search to see if there is a fix pending for the port in
	  the <link xlink:href="&url.base;/support.html">Problem
	    Report database</link>.  If so, implementing the proposed
	  fix may fix the issue.</para>
      </listitem>

      <listitem>
	<para>Ask the maintainer of the port for help.  Type
	  <command>make maintainer</command>
	  in the ports skeleton or read the port's
	  <filename>Makefile</filename> to find the maintainer's
	  email address.  Remember to include the
	  <literal>&dollar;FreeBSD:</literal> line from the port's
	  <filename>Makefile</filename> and the output leading up to
	  the error in the email to the maintainer.</para>

	<note>
	  <para>Some ports are not maintained by an individual but
	    instead by a group maintainer represented by a <link
	      xlink:href="&url.articles.mailing-list-faq;/article.html">mailing
	      list</link>.  Many, but not all, of these addresses look
	    like <email
	      role="nolink">freebsd-<replaceable>listname</replaceable>@FreeBSD.org</email>.
	    Please take this into account when sending an
	    email.</para>

	  <para>In particular, ports maintained by
	    <email role="nolink">ports@FreeBSD.org</email> are not
	    maintained by a specific individual.  Instead, any fixes
	    and support come from the general community who subscribe
	    to that mailing list.  More volunteers are always
	    needed!</para>
	</note>

	<para>If there is no response to the email, use
	  Bugzilla to submit a bug report using the
	  instructions in <link
	    xlink:href="&url.articles.problem-reports;/article.html">Writing
	    &os; Problem Reports</link>.</para>
      </listitem>

      <listitem>
	<para>Fix it!  The <link
	    xlink:href="&url.books.porters-handbook;/index.html">Porter's
	    Handbook</link> includes detailed information on the
	  ports infrastructure so that you can fix the occasional
	  broken port or even submit your own!</para>
      </listitem>

      <listitem>
	<para>Install the package instead of the port using the
	  instructions in <xref linkend="pkgng-intro"/>.</para>
      </listitem>
    </orderedlist>
  </sect1>
</chapter>