Differential D12921 Diff 40128 en_US.ISO8859-1/books/porters-handbook/ph-introduction/chapter.xml

Changeset View

Standalone View

en_US.ISO8859-1/books/porters-handbook/ph-introduction/chapter.xml

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

				$FreeBSD: head/en_US.ISO8859-1/books/porters-handbook/porting-why/chapter.xml 50632 2017-08-04 11:34:16Z mat $
				-->
				<chapter xmlns="http://docbook.org/ns/docbook"
				xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
				xml:id="ph-introduction">



				<sect1 xml:id="introduction">
				<title>Introduction</title>
				<para>The &os; ports system is a combination of tools and source files designed to build and install applications on &os;. While any user is free to download and build the sources themselves, some applications do not target &os; and may require minor modifications to enable them to work correctly. These modifications are known as patches. The ports system allows users to package these patches and distribute them with the correct build instructions, thus allowing other users to duplicate the fixes and run the application. </para>
				<para>
				The Ports system is a fundamental part of &os;. All binary installations performed by the &man.pkg.8; system pull applications from repositories built with ports (see &man.poudriere.8;). Amazingly, all the port packages are maintained by the user base themselves. Users decide which applications they want included in the ports system and provide a port to share their user experience. It is also users that monitor the upstream application repositories (i.e. the people that created the software) and create fixes to keep the Ports system up to date.
				</para>

				<para>
				This handbook is designed to explain how the Ports system works at an intermediate to advanced level, and how you can help contribute to the maintenance of this fundamental system on FreeBSD.
				</para>
				<note>
				<para>The Ports Collection appeared in FreeBSD 1.0. It has since spread to
				NetBSD and OpenBSD.
				</para>
				</note>
				</sect1>

				<sect1 xml:id="tools-introduction">
				<title>Porting Tools</title>
				<sect2 xml:id="background-tools">
				<title>Background Tools</title>
				<para>
				This handbook requires basic working knowledge of the Ports tools. For more information about the Ports system, please see:
				</para>
				<para>
				<link>https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/ports.html</link>
				</para>
				<para>
				<link xlink:href="&url.base;/cgi/man.cgi?ports">Ports man link?</link>
				</para>
				<para>
				A complete list of ports is available on the FreeBSD website <link xlink:href="&url.base;/ports/index.html">ports page.</link>
				</para>
				<para>
				More detailed information about the state of various ports can be found through the excellent <link xlink:href="https://www.freshports.org/">freshports.org website</link> (The search is in the right hand column halfway down the page):
				</para>
				<para>
				Freshports also provides a view into the building and maintenance of all ports for all Architectures[1] through access to the PortsMon. The PortsMon system plugs into the overall Release Engineering structure to provide notification of build failures and ensure the software is available. To see an example of a port and it's RE information, find a port in freshports and click on the PortsMon link.
				</para>
				</sect2>

				<sect2 xml:id="development-tools">
				<title>Development Tools</title>

				<para>
				In order to create or maintain a "port", there are tools with which the user should be familiar.
				</para>

				<para>
				Ports Tree - <link xlink:href="https://svnweb.freebsd.org/ports/head/">Ports Tree</link>
				</para>
				<para>
				The ports tree is the directory structure of build tools and build instructions (source files) that are used to create the binaries on the target computer.
				</para>
				<para>
				Subversion - <link xlink:href="https://subversion.apache.org/">Subversion download site</link>
				</para>
				<para>
				While any user with wheel privilege is able to modify the ports files under /usr/loca/ports, this pattern creates complications. If any user on the computer performs a portsnap update, all modifications will be lost. Also, updating these files requires wheel privilege. Performing development using elevated privilege can be both frustrating and dangerous. It is therefore recommended that users download a "development" copy of the ports tree using subversion. This alternate tree can be placed under the users home directory, which gives the user write privileges and differentiates the "base" ports and a users working copies.
				</para>
				<para>
				Information about how to use subversion with FreeBSD is available here:
				<link xlink:href="&url.books.handbook;/svn.html">Using Subversion with FreeBSD</link>
				With more detailed instructions at <link xlink:href="http://svnbook.red-bean.com/">Subversion handbook</link>
				</para>
				<para>
				Getting the Ports Tree Through Subversion
				The typical user will want to checkout the latest ports tree.

				#Install subversion
				sudo pkg install subversion
				...
				#Create structure.
				#The work folder gives you a place to collect /scripts and /notes directories applicable to your changes and your ports tree.
				mkdir -p ~/work/ports
				cd ~/work/ports
				svn svn://svn.freebsd.org/ports/head/ .
				</para>
				</sect2>

				<sect2 xml:id="issue-and-review-tools">
				<title>Issue tracking and Review Tools</title>
				<para>
				<link xlink:href="http://bugs.freebsd.org">Bugzilla</link><uri>http://bugs.freebsd.org</uri>
				</para>
				<para>
				Bugzilla is the bug tracker used by FreeBSD to keep a master list of issues and tasks pertaining to the maintenance and development of FreeBSD. Users that have issues in the functionality of FreeBSD are encouraged to search the bug list for similar problems. While general internet searches can typically find answers to simple problems, deeper technical problems may have already been identified. If the issue is not in the list, users are encouraged to create a new account and create a bug entry. Duplicates are quickly identified and support can many times be offered.
				</para>
				<para>
				Bugzilla is the tool you will use to make sure your port is working correctly, or look for other ports that you are interested in that may need work. If a port is un-maintained, bugzilla is the place to go to volunteer to maintain the package.
				</para>

				<para>
				Phabricator - <link>https://reviews.freebsd.org/</link>
				</para>
				<para>
				Phabricator is a code review tool that has been integrated into the FreeBSD release process to streamline community review and help nurture new developers. FreeBSD users are encouraged (lots of encouragement!) to create an account and observe the development/review/development process that takes place to ensure the quality of the software released. This iterative feedback process is your gateway to getting your port update submitted, and to give you the skills to eventually become a full maintainer with a "Ports Commit Bit". [*]
				</para>
				</sect2>
				</sect1>

				<sect1 xml:id="example-porting">
				<title>Example Development Process</title>
				<para>
				An example of how a typical port might be maintained would look like this:
				</para>
				<para>
				Suppose you were using the Lua scripting language and came across a bug on FreeBSD. After doing some research, you noted that the bug has been patched by the upstream maintainer (i.e. the authors) but the port does not seem to contain the fix.
				</para>
				<para>
				Your first stop would be bugs.freebsd.org to search to see if someone else has reported the problem. Depending on the circumstance, there may be some discussions, or perhaps the port doesn't seem to be maintained. After said discussion on the forum, you decide that the patch (and Lua) is important to you and you want others to share your work. Perhaps you discussed it with the port maintainer, and that person asked you to put together a patch. Or perhaps the port is currently un-maintained. Either way, you decide to update the port.
				</para>
				<para>
				After some simple modifications and proper verification using the tools provided, you will have a patch file. This patch file is then submitted through reviews.freebsd.org with a brief written overview of what you have done and why. One or more people will review the patch files and then make comments asking you to make some changes/fixes. Once those changes are in place and everyone is satisfied, the patch is committed to the head revision and is now available after a user updates the ports tree using "ports update".
				</para>
				<para>
				That's it, you've maintained a Port!
				</para>
				<para>
				The next section will describe how the ports system builds the application, what a basic (new) port would look like, and the steps you will take to make changes to a port. Happy Porting!</para>
				</sect1>
				</chapter>