Date: Sun, 9 Feb 2014 01:50:54 +0000 (UTC) From: Tom Rhodes <trhodes@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43840 - in head/en_US.ISO8859-1/books/porters-handbook: . appendices keeping-up makefiles new-port pkg-files plist porting-dads porting-samplem porting-why quick-porting security slow-... Message-ID: <201402090150.s191osWP016334@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: trhodes Date: Sun Feb 9 01:50:53 2014 New Revision: 43840 URL: http://svnweb.freebsd.org/changeset/doc/43840 Log: Break the porters handbook out into individual chapters like our other books (fdp primer, handbook dev handbook, etc). I've done some small naming changes for cleaner chapters but not much. Thumbs up: wblock, mat Added: head/en_US.ISO8859-1/books/porters-handbook/appendices/ head/en_US.ISO8859-1/books/porters-handbook/appendices/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/appendices/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/chapters.ent (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/keeping-up/ head/en_US.ISO8859-1/books/porters-handbook/keeping-up/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/keeping-up/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/makefiles/ head/en_US.ISO8859-1/books/porters-handbook/makefiles/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/new-port/ head/en_US.ISO8859-1/books/porters-handbook/new-port/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/new-port/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/pkg-files/ head/en_US.ISO8859-1/books/porters-handbook/pkg-files/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/plist/ head/en_US.ISO8859-1/books/porters-handbook/plist/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/porting-dads/ head/en_US.ISO8859-1/books/porters-handbook/porting-dads/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/porting-dads/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/porting-samplem/ head/en_US.ISO8859-1/books/porters-handbook/porting-samplem/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/porting-samplem/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/porting-why/ head/en_US.ISO8859-1/books/porters-handbook/porting-why/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/porting-why/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/quick-porting/ head/en_US.ISO8859-1/books/porters-handbook/quick-porting/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/security/ head/en_US.ISO8859-1/books/porters-handbook/security/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/security/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/slow-porting/ head/en_US.ISO8859-1/books/porters-handbook/slow-porting/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/special/ head/en_US.ISO8859-1/books/porters-handbook/special/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/testing/ head/en_US.ISO8859-1/books/porters-handbook/testing/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/upgrading/ head/en_US.ISO8859-1/books/porters-handbook/upgrading/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml (contents, props changed) Modified: head/en_US.ISO8859-1/books/porters-handbook/Makefile head/en_US.ISO8859-1/books/porters-handbook/book.xml Modified: head/en_US.ISO8859-1/books/porters-handbook/Makefile ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/Makefile Sat Feb 8 22:08:51 2014 (r43839) +++ head/en_US.ISO8859-1/books/porters-handbook/Makefile Sun Feb 9 01:50:53 2014 (r43840) @@ -19,6 +19,22 @@ INSTALL_ONLY_COMPRESSED?= # # XML content +#SRCS+= quick-porting/chapter.xml +#SRCS+= own-port/chapter.xml +#SRCS+= porting-why/chapter.xml +SRCS+= makefiles/chapter.xml +#SRCS+= plist/chapter.xml +#SRCS+= testing/chapter.xml +#SRCS+= security/chapter.xml +#SRCS+= porting-samplem/chapter.xml +#SRCS+= appendices/chapter.xml +#SRCS+= keeping-up/chapter.xml +#SRCS+= porting-dads/chapter.xml +#SRCS+= upgrading/chapter.xml +#SRCS+= pkg-files/chapter.xml +#SRCS+= specials/chapter.xml +#SRCS+= slow-porting/chapter.xml + SRCS= book.xml SRCS+= uses.xml SRCS+= versions.xml @@ -49,4 +65,14 @@ IMAGES_LIB+= callouts/21.png URL_RELPREFIX?= ../../../.. DOC_PREFIX?= ${.CURDIR}/../../.. +# Entities +SRCS+= chapters.ent + +SYMLINKS= ${DESTDIR} index.html handbook.html + +# Turn on all the chapters. +CHAPTERS?= ${SRCS:M*chapter.xml} + +XMLFLAGS+= ${CHAPTERS:S/\/chapter.xml//:S/^/-i chap./} + .include "${DOC_PREFIX}/share/mk/doc.project.mk" Added: head/en_US.ISO8859-1/books/porters-handbook/appendices/Makefile ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/en_US.ISO8859-1/books/porters-handbook/appendices/Makefile Sun Feb 9 01:50:53 2014 (r43840) @@ -0,0 +1,15 @@ +# +# Build the Porters Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= appendices/chapter.xml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" Added: head/en_US.ISO8859-1/books/porters-handbook/appendices/chapter.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/en_US.ISO8859-1/books/porters-handbook/appendices/chapter.xml Sun Feb 9 01:50:53 2014 (r43840) @@ -0,0 +1,72 @@ +<?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="appendencies"> + <title>Appendices</title> + + <sect1 xml:id="uses-values"> + <title>Values of <varname>USES</varname></title> + + <table> + <title>Values of <varname>USES</varname></title> + + <tgroup cols="3"> + <thead> + <row> + <entry>Feature</entry> + <entry>Arguments</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody valign="top"> + &values.uses; + </tbody> + </tgroup> + </table> + </sect1> + + <sect1 xml:id="freebsd-versions"> + <title><literal>__FreeBSD_version</literal> Values</title> + + <para>Here is a convenient list of + <literal>__FreeBSD_version</literal> values as defined in + <link + xlink:href="http://svnweb.FreeBSD.org/base/head/sys/sys/param.h?view=markup">sys/param.h</link>:</para>; + + <table frame="none"> + <title><literal>__FreeBSD_version</literal> Values</title> + + <tgroup cols="3"> + <thead> + <row> + <entry>Value</entry> + <entry>Date</entry> + <entry>Release</entry> + </row> + </thead> + + <tbody> + &values.versions; + </tbody> + </tgroup> + </table> + + <note> + <para>Note that 2.2-STABLE sometimes identifies itself as + <quote>2.2.5-STABLE</quote> after the 2.2.5-RELEASE. The + pattern used to be year followed by the month, but we + decided to change it to a more straightforward major/minor + system starting from 2.2. This is because the parallel + development on several branches made it infeasible to + classify the releases simply by their real release dates. + If you are making a port now, you do not have to worry about + old -CURRENTs; they are listed here just for your + reference.</para> + </note> + </sect1> + </chapter> Modified: head/en_US.ISO8859-1/books/porters-handbook/book.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/book.xml Sat Feb 8 22:08:51 2014 (r43839) +++ head/en_US.ISO8859-1/books/porters-handbook/book.xml Sun Feb 9 01:50:53 2014 (r43840) @@ -3,13 +3,17 @@ "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [ <!ENTITY values.uses SYSTEM "uses.xml"> <!ENTITY values.versions SYSTEM "versions.xml"> -]> + <!-- The FreeBSD Documentation Project $FreeBSD$ --> +<!ENTITY % chapters SYSTEM "chapters.ent"> +%chapters; +]> + <book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> @@ -56,12747 +60,19 @@ <releaseinfo>$FreeBSD$</releaseinfo> </info> - <chapter xml:id="why-port"> - <title>Introduction</title> - - <para>The &os; Ports Collection is the way almost everyone - installs applications ("ports") on &os;. Like everything - else about &os;, it is primarily a volunteer effort. - It is important to keep this in mind when reading this - document.</para> - - <para>In &os;, anyone may submit a new port, or volunteer - to maintain an existing port if it is unmaintained—you - do not need any special commit privileges to do so.</para> - - </chapter> - - <chapter xml:id="own-port"> - <title>Making a New Port Yourself</title> - - <para>So, you are interested in making your own port or - upgrading an existing one? Great!</para> - - <para>What follows are some guidelines for creating a new port for - &os;. If you want to upgrade an existing port, you should - read this and then read <xref linkend="port-upgrading"/>.</para> - - <para>When this document is not sufficiently detailed, you should - refer to <filename>/usr/ports/Mk/bsd.port.mk</filename>, which - all port Makefiles include. Even if you do not hack Makefiles - daily, it is well commented, and you will still gain much - knowledge from it. Additionally, you may send specific - questions to the &a.ports;.</para> - - <note> - <para>Only a fraction of the variables - (<varname><replaceable>VAR</replaceable></varname>) that can - be overridden are mentioned in this document. Most (if not - all) are documented at the start of - <filename>/usr/ports/Mk/bsd.port.mk</filename>; the others - probably ought to be. Note that this file uses a non-standard - tab setting: <application>Emacs</application> and - <application>Vim</application> should recognize the setting on - loading the file. Both &man.vi.1; and &man.ex.1; can be set - to use the correct value by typing - <command>:set tabstop=4</command> once the file has been - loaded.</para> - </note> - - <para> - Looking for something easy to start with? Take a look at the - <link xlink:href="http://wiki.freebsd.org/WantedPorts">list of - requested ports</link> and see if you can work on one (or - more).</para> - </chapter> - - <chapter xml:id="quick-porting"> - <title>Quick Porting</title> - - <para>This section tells you how to quickly create a new port. In - many cases, it is not sufficient, so you will have to read - further on into the document.</para> - - <para>First, get the original tarball and put it into - <varname>DISTDIR</varname>, which defaults to - <filename>/usr/ports/distfiles</filename>.</para> - - <note> - <para>The following assumes that the software compiled - out-of-the-box, i.e., there was absolutely no change required - for the port to work on your &os; box. If you needed to - change something, you will have to refer to the next section - too.</para> - </note> - - <note> - <para>It is recommended to set the <varname>DEVELOPER</varname> - &man.make.1; variable in <filename>/etc/make.conf</filename> - before getting into porting.</para> - - <screen>&prompt.root; <userinput>echo DEVELOPER=yes >> /etc/make.conf</userinput></screen> - - <para>This setting enables the <quote>developer mode</quote> - that displays deprecation warnings and activates some further - quality checks on calling <command>make</command>.</para> - </note> - - <sect1 xml:id="porting-makefile"> - <title>Writing the <filename>Makefile</filename></title> - - <para>The minimal <filename>Makefile</filename> would look - something like this:</para> - - <programlisting># $FreeBSD$ - -PORTNAME= oneko -PORTVERSION= 1.1b -CATEGORIES= games -MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/ - -MAINTAINER= youremail@example.com -COMMENT= Cat chasing a mouse all over the screen - -.include <bsd.port.mk></programlisting> - - <note> - <para>In some cases, the <filename>Makefile</filename> of an - existing port may contain additional lines in the header, - such as the name of the port and the date it was created. - This additional information has been declared obsolete, and - is being phased out.</para> - </note> - - <para>See if you can figure it out. Do not worry about the - contents of the <literal>$FreeBSD$</literal> - line, it will be filled in automatically by - <application>Subversion</application> when the port is - imported to our main ports tree. You can find a more detailed - example in the - <link linkend="porting-samplem">sample Makefile</link> - section.</para> - </sect1> - - <sect1 xml:id="porting-desc"> - <title>Writing the Description Files</title> - - <para>There are two description files that are required for - any port, whether they actually package or not. They are - <filename>pkg-descr</filename> and - <filename>pkg-plist</filename>. Their - <filename>pkg-</filename> prefix distinguishes them from other - files.</para> - - <sect2> - <title><filename>pkg-descr</filename></title> - - <para>This is a longer description of the port. One to a few - paragraphs concisely explaining what the port does is - sufficient.</para> - - <note> - <para>This is <emphasis>not</emphasis> a manual or an - in-depth description on how to use or compile the port! - <emphasis>Please be careful if you are copying from the - <filename>README</filename> or manpage</emphasis>; too - often they are not a concise description of the port or - are in an awkward format (e.g., manpages have justified - spacing, which looks particularly bad with monospaced - fonts).</para> - </note> - - <para>A well-written <filename>pkg-descr</filename> describes - the port completely enough that users would not have to - consult the documentation or visit the website to understand - what the software does, how it can be useful, or what - particularly nice features it has. Mentioning certain - requirements like a graphical toolkit, heavy dependencies, - runtime environment, or implementation languages help users - decide whether this port will work for them.</para> - - <para>Include a URL to the official WWW homepage. Prepend - <emphasis>one</emphasis> of the websites (pick the most - common one) with <literal>WWW:</literal> (followed by single - space) so that automated tools will work correctly. If the - URI is the root of the website or directory, it should be - terminated with a slash.</para> - - <note> - <para>If the listed webpage for a port is not available, try - to search the Internet first to see if the official site - moved, was renamed, or is hosted elsewhere.</para> - </note> - - <para>The following example shows how your - <filename>pkg-descr</filename> should look:</para> - - <programlisting>This is a port of oneko, in which a cat chases a poor mouse all over -the screen. - : -(etc.) - -WWW: http://www.oneko.org/</programlisting>; - </sect2> - - <sect2> - <title><filename>pkg-plist</filename></title> - - <para>This file lists all the files installed by the port. It - is also called the <quote>packing list</quote> because the - package is generated by packing the files listed here. The - pathnames are relative to the installation prefix (usually - <filename>/usr/local</filename>. - If the - port creates directories during installation, make sure to - add <literal>@dirrm</literal> lines to remove them when the - package is deleted.</para> - - <para>Here is a small example:</para> - - <programlisting>bin/oneko -man/man1/oneko.1.gz -lib/X11/app-defaults/Oneko -lib/X11/oneko/cat1.xpm -lib/X11/oneko/cat2.xpm -lib/X11/oneko/mouse.xpm -@dirrm lib/X11/oneko</programlisting> - - <para>Refer to the &man.pkg-create.8; manual page for details - on the packing list.</para> - - <note> - <para>It is recommended that you keep all the filenames in - this file sorted alphabetically. It will make verifying - the changes when you upgrade the port much easier.</para> - </note> - - <note> - <para>Creating a packing list manually can be a very tedious - task. If the port installs a large numbers of files, - <link linkend="plist-autoplist">creating the packing list - automatically</link> might save time.</para> - </note> - - <para>There is only one case when - <filename>pkg-plist</filename> can be omitted from a port. - If the port installs just a handful of files, and perhaps - directories, the files and directories may be listed in the - variables <varname>PLIST_FILES</varname> and - <varname>PLIST_DIRS</varname>, respectively, within the - port's <filename>Makefile</filename>. For instance, we - could get along without <filename>pkg-plist</filename> in - the above <filename>oneko</filename> port by adding the - following lines to the <filename>Makefile</filename>:</para> - - <programlisting>PLIST_FILES= bin/oneko \ - man/man1/oneko.1.gz \ - lib/X11/app-defaults/Oneko \ - lib/X11/oneko/cat1.xpm \ - lib/X11/oneko/cat2.xpm \ - lib/X11/oneko/mouse.xpm -PLIST_DIRS= lib/X11/oneko</programlisting> - - <para>Of course, <varname>PLIST_DIRS</varname> should be left - unset if a port installs no directories of its own.</para> - - <note> - - <para>Several ports can share a common directory. In that - case, <varname>PLIST_DIRS</varname> should be replaced by - <varname>PLIST_DIRSTRY</varname> so that the directory is - removed only if empty, otherwise it is silently ignored. - <varname>PLIST_DIRS</varname> and - <varname>PLIST_DIRSTRY</varname> are equivalent to using - <literal>@dirrm</literal> and <literal>@dirrmtry</literal> - in <filename>pkg-plist</filename>, as described in - <xref linkend="plist-dir-cleaning"/>.</para> - </note> - - <para>The price for this way of listing port's files and - directories is that you cannot use command sequences - described in &man.pkg-create.8;. Therefore, it is suitable - only for simple ports and makes them even simpler. At the - same time, it has the advantage of reducing the number of - files in the ports collection. Please consider using this - technique before you resort to - <filename>pkg-plist</filename>.</para> - - <para>Later we will see how <filename>pkg-plist</filename> - and <varname>PLIST_FILES</varname> can be used to fulfill - <link linkend="plist">more sophisticated - tasks</link>.</para> - </sect2> - </sect1> - - <sect1 xml:id="porting-checksum"> - <title>Creating the Checksum File</title> - - <para>Just type <command>make makesum</command>. The ports make - rules will automatically generate the file - <filename>distinfo</filename>.</para> - - <para>If a file fetched has its checksum changed regularly and - you are certain the source is trusted (i.e., it comes from - manufacturer CDs or documentation generated daily), you should - specify these files in the <varname>IGNOREFILES</varname> - variable. Then the checksum is not calculated for that file - when you run <command>make makesum</command>, but set to - <literal>IGNORE</literal>.</para> - </sect1> - - <sect1 xml:id="porting-testing"> - <title>Testing the Port</title> - - <para>You should make sure that the port rules do exactly what - you want them to do, including packaging up the port. These - are the important points you need to verify.</para> - - <itemizedlist> - <listitem> - <para><filename>pkg-plist</filename> does not contain - anything not installed by the port.</para> - </listitem> - - <listitem> - <para><filename>pkg-plist</filename> contains everything - that is installed by the port.</para> - </listitem> - - <listitem> - <para>The port can be installed using the - <buildtarget>install</buildtarget> target. This verifies - that the install script works correctly.</para> - </listitem> - - <listitem> - <para>The port can be deinstalled properly using the - <buildtarget>deinstall</buildtarget> target. This - verifies that the deinstall script works correctly.</para> - </listitem> - - <listitem> - <para>Make sure that <command>make package</command> can be - run as a normal user (that is, not as - <systemitem class="username">root</systemitem>). If that - fails, <literal>NEED_ROOT=yes</literal> must be added to - the port <filename>Makefile</filename>.</para> - </listitem> - </itemizedlist> - - <procedure> - <title>Recommended Test Ordering</title> - - <step> - <para><command>make stage</command></para> - </step> - - <step> - <para><command>make check-orphans</command></para> - </step> - - <step> - <para><command>make package</command></para> - </step> - - <step> - <para><command>make install</command></para> - </step> - - <step> - <para><command>make deinstall</command></para> - </step> - - <step> - <para><command>pkg add package-filename</command></para> - </step> - - <step> - <para><command>make package</command> (as user)</para> - </step> - </procedure> - - <para>Make certain no warnings are shown in any of - the stages.</para> - - <para>Thorough automated testing can be done with - <package role="port">ports-mgmt/tinderbox</package> or - <package role="port">ports-mgmt/poudriere</package> from the - Ports Collection. These applications maintain - <literal>jails</literal> where all of the steps shown above - can be tested without affecting the state of the host - system.</para> - </sect1> - - <sect1 xml:id="porting-portlint"> - <title>Checking Your Port with - <command>portlint</command></title> - - <para>Please use <command>portlint</command> to see if your port - conforms to our guidelines. The - <package role="port">ports-mgmt/portlint</package> - program is part of the ports collection. In particular, you - may want to check if the - <link linkend="porting-samplem">Makefile</link> is in the - right shape and the - <link linkend="porting-pkgname">package</link> is named - appropriately.</para> - </sect1> - - <sect1 xml:id="porting-submitting"> - <title>Submitting the New Port</title> - - <para>Before submitting the new port, read - the <link linkend="porting-dads">DOs and DON'Ts</link> - section.</para> - - <para>Once happy with your port, the only thing remaining is to - put it in the main &os; ports tree and make everybody else - happy about it too. We do not need the - <filename>work</filename> directory or the - <filename>pkgname.tgz</filename> package, so delete them - now.</para> - - <para>Next, build the &man.shar.1; file. Assuming the port is - called <literal>oneko</literal>, <command>cd</command> to the - directory above where the <literal>oneko</literal> directory - is located, and then type: - <command>shar `find oneko` > oneko.shar</command></para> - - <para>Include <filename>oneko.shar</filename> in a bug - report and send it with &man.send-pr.1;. See - <link - xlink:href="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug - Reports and General Commentary</link> for more information - about &man.send-pr.1;.</para> - - <para>Classify the bug report as Category - <literal>ports</literal> and Class - <literal>change-request</literal>. Do - <emphasis>not</emphasis> mark the report - <literal>confidential</literal>! Add a short description of - the program to the Description field of the PR (perhaps a - short version of the <varname>COMMENT</varname>), and add the - <filename>.shar</filename> file to the Fix field.</para> - - <note> - <para>Giving a good description in the synopsis of the problem - report makes the work of port committers a lot easier. We - prefer something like <quote>New port: - <category>/<portname> <short description of - the port></quote> for new ports. Using this - scheme makes it easier and faster to begin the work of - committing the new port.</para> - </note> - - <para>One more time, <emphasis>do not include the original - source distfile, the <filename>work</filename> directory, or - the package you built with - <command>make package</command></emphasis>; and, do use - &man.shar.1; for new ports, not &man.diff.1;.</para> - - <para>After submitting the port, please be patient. The time - needed to include a new port in &os; can vary from a few days - to a few months. The list of pending port - <acronym>PR</acronym>s can be viewed at <link - xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports"></link>.</para>; - - <para>After looking at the new port, we will reply if necessary, - and put it in the tree. Your name will also be added to the - list of <link - xlink:href="&url.articles.contributors;/contrib-additional.html">Additional - &os; Contributors</link> and other files.</para> - </sect1> - </chapter> - - <chapter xml:id="slow"> - <title>Slow Porting</title> - - <para>Okay, so it was not that simple, and the port required some - modifications to get it to work. In this section, we will - explain, step by step, how to modify it to get it to work with - the ports paradigm.</para> - - <sect1 xml:id="slow-work"> - <title>How Things Work</title> - - <para>First, this is the sequence of events which occurs when - the user first types <command>make</command> in your port's - directory. You may find that having - <filename>bsd.port.mk</filename> in another window while you - read this really helps to understand it.</para> - - <para>But do not worry if you do not really understand what - <filename>bsd.port.mk</filename> is doing, not many people - do... <!-- smiley --><emphasis>:-)</emphasis></para> - - <procedure> - <step> - <para>The <buildtarget>fetch</buildtarget> target is run. - The <buildtarget>fetch</buildtarget> target is responsible - for making sure that the tarball exists locally in - <varname>DISTDIR</varname>. If - <buildtarget>fetch</buildtarget> cannot find the required - files in <varname>DISTDIR</varname> it will look up the - URL <varname>MASTER_SITES</varname>, which is set in the - Makefile, as well as our FTP mirrors where we put - distfiles as backup. It will then attempt to fetch the - named distribution file with <varname>FETCH</varname>, - assuming that the requesting site has direct access to the - Internet. If that succeeds, it will save the file in - <varname>DISTDIR</varname> for future use and - proceed.</para> - </step> - - <step> - <para>The <buildtarget>extract</buildtarget> target is run. - It looks for your port's distribution file (typically a - <command>gzip</command>ped tarball) in - <varname>DISTDIR</varname> and unpacks it into a temporary - subdirectory specified by <varname>WRKDIR</varname> - (defaults to <filename>work</filename>).</para> - </step> - - <step> - <para>The <buildtarget>patch</buildtarget> target is run. - First, any patches defined in - <varname>PATCHFILES</varname> are applied. Second, if any - patch files named - <filename>patch-*</filename> - are found in <varname>PATCHDIR</varname> (defaults to the - <filename>files</filename> subdirectory), they are applied - at this time in alphabetical order.</para> - </step> - - <step> - <para>The <buildtarget>configure</buildtarget> target is - run. This can do any one of many different things.</para> - - <orderedlist> - <listitem> - <para>If it exists, - <filename>scripts/configure</filename> is run.</para> - </listitem> - - <listitem> - <para>If <varname>HAS_CONFIGURE</varname> or - <varname>GNU_CONFIGURE</varname> is set, - <filename>WRKSRC/configure</filename> - is run.</para> - </listitem> - - </orderedlist> - </step> - - <step> - <para>The <buildtarget>build</buildtarget> target is run. - This is responsible for descending into the port's private - working directory (<varname>WRKSRC</varname>) and building - it.</para> - </step> - - <step> - <para>The <buildtarget>stage</buildtarget> target is run. - This puts the final set of built files into a temporary - directory (<varname>STAGEDIR</varname>, see - <xref linkend="staging"/>). The hierarchy of this - directory mirrors that of the system on which the package - will be installed.</para> - </step> - - <step> - <para>The <buildtarget>install</buildtarget> target is run. - This copies the files listed in the port's pkg-plist to - the host system.</para> - </step> - </procedure> - - <para>The above are the default actions. In addition, you can - define targets - <buildtarget>pre-<replaceable>something</replaceable></buildtarget> - or - <buildtarget>post-<replaceable>something</replaceable></buildtarget>, - or put scripts with those names, in the - <filename>scripts</filename> subdirectory, and they will be - run before or after the default actions are done.</para> - - <para>For example, if you have a - <buildtarget>post-extract</buildtarget> target defined in your - <filename>Makefile</filename>, and a file - <filename>pre-build</filename> in the - <filename>scripts</filename> subdirectory, the - <buildtarget>post-extract</buildtarget> target will be called - after the regular extraction actions, and the - <filename>pre-build</filename> script will be executed before - the default build rules are done. It is recommended that you - use <filename>Makefile</filename> targets if the actions are - simple enough, because it will be easier for someone to figure - out what kind of non-default action the port requires.</para> - - <para>The default actions are done by the - <filename>bsd.port.mk</filename> targets - <buildtarget>do-<replaceable>something</replaceable></buildtarget>. - For example, the commands to extract a port are in the target - <buildtarget>do-extract</buildtarget>. If you are not happy - with the default target, you can fix it by redefining the - <buildtarget>do-<replaceable>something</replaceable></buildtarget> - target in your <filename>Makefile</filename>.</para> - - <note> - <para>The <quote>main</quote> targets (e.g., - <buildtarget>extract</buildtarget>, - <buildtarget>configure</buildtarget>, etc.) do nothing more - than make sure all the stages up to that one are completed - and call the real targets or scripts, and they are not - intended to be changed. If you want to fix the extraction, - fix <buildtarget>do-extract</buildtarget>, but never ever - change the way <buildtarget>extract</buildtarget> - operates! Additionally, the target - <buildtarget>post-deinstall</buildtarget> is invalid and - is not run by the ports infrastructure.</para> - </note> - - <para>Now that you understand what goes on when the user types - <command>make install</command>, let - us go through the recommended steps to create the perfect - port.</para> - </sect1> - - <sect1 xml:id="slow-sources"> - <title>Getting the Original Sources</title> - - <para>Get the original sources (normally) as a compressed - tarball - (<filename>foo.tar.gz</filename> or - <filename>foo.tar.bz2</filename>) - and copy it into <varname>DISTDIR</varname>. Always use - <emphasis>mainstream</emphasis> sources when and where you - can.</para> - - <para>You will need to set the variable - <varname>MASTER_SITES</varname> to reflect where the original - tarball resides. You will find convenient shorthand - definitions for most mainstream sites in - <filename>bsd.sites.mk</filename>. Please use these - sites—and the associated definitions—if at all - possible, to help avoid the problem of having the same - information repeated over again many times in the source base. - As these sites tend to change over time, this becomes a - maintenance nightmare for everyone involved.</para> - - <para>If you cannot find a FTP/HTTP site that is well-connected - to the net, or can only find sites that have irritatingly - non-standard formats, you might want to put a copy on a - reliable FTP or HTTP server that you control (e.g., your home - page).</para> - - <para>If you cannot find somewhere convenient and reliable to - put the distfile we can <quote>house</quote> it ourselves on - <systemitem>ftp.FreeBSD.org</systemitem>; however, this is the - least-preferred solution. The distfile must be placed into - <filename>~/public_distfiles/</filename> of someone's - <systemitem>freefall</systemitem> account. Ask the person who - commits your port to do this. This person will also set - <varname>MASTER_SITES</varname> to - <varname>MASTER_SITE_LOCAL</varname> and - <varname>MASTER_SITE_SUBDIR</varname> to their - <systemitem>freefall</systemitem> username.</para> - - <para>If your port's distfile changes all the time without any - kind of version update by the author, consider putting the - distfile on your home page and listing it as the first - <varname>MASTER_SITES</varname>. If you can, try to talk the - port author out of doing this; it really does help to - establish some kind of source code control. Hosting your own - version will prevent users from getting - <errorname>checksum mismatch</errorname> errors, and also - reduce the workload of maintainers of our FTP site. Also, if - there is only one master site for the port, it is recommended - that you house a backup at your site and list it as the second - <varname>MASTER_SITES</varname>.</para> - - <para>If your port requires some additional `patches' that are - available on the Internet, fetch them too and put them in - <varname>DISTDIR</varname>. Do not worry if they come from a - site other than where you got the main source tarball, we have - a way to handle these situations (see the description of - <link linkend="porting-patchfiles">PATCHFILES</link> - below).</para> - </sect1> - - <sect1 xml:id="slow-modifying"> - <title>Modifying the Port</title> - - <para>Unpack a copy of the tarball in a private directory and - make whatever changes are necessary to get the port to compile - properly under the current version of &os;. Keep - <emphasis>careful track</emphasis> of everything you do, as - you will be automating the process shortly. Everything, - including the deletion, addition, or modification of files - should be doable using an automated script or patch file when - your port is finished.</para> - - <para>If your port requires significant user - interaction/customization to compile or install, you should - take a look at one of Larry Wall's classic - <application>Configure</application> scripts and perhaps do - something similar yourself. The goal of the new ports - collection is to make each port as - <quote>plug-and-play</quote> as possible for the end-user - while using a minimum of disk space.</para> - - <note> - <para>Unless explicitly stated, patch files, scripts, and - other files you have created and contributed to the &os; - ports collection are assumed to be covered by the standard - BSD copyright conditions.</para> - </note> - </sect1> - - <sect1 xml:id="slow-patch"> - <title>Patching</title> - - <para>In the preparation of the port, files that have been added - or changed can be recorded with &man.diff.1; for later - feeding to &man.patch.1;. Doing this with a typical file - involves saving a copy of the original file before making any - changes.</para> - - <screen>&prompt.user; <userinput>cp <replaceable>file</replaceable> <replaceable>file</replaceable>.orig</userinput></screen> - - <para>Patches are saved into files named - <filename>patch-*</filename> where - <replaceable>*</replaceable> indicates the pathname of the - file that is patched, such as - <filename>patch-Imakefile</filename> or - <filename>patch-src-config.h</filename>.</para> - - <para>After the file has been modified, &man.diff.1; is used to - record the differences between the original and the modified - version. <option>-u</option> causes &man.diff.1; to produce - <quote>unified</quote> diffs, the preferred form.</para> - - <screen>&prompt.user; <userinput>diff -u <replaceable>file</replaceable>.orig <replaceable>file</replaceable> > patch-<replaceable>pathname-file</replaceable></userinput></screen> - - <para>When generating patches for new, added files, - <option>-N</option> is added to tell &man.diff.1; to treat the - non-existent original file as if it existed but was - empty:</para> - - <screen>&prompt.user; <userinput>diff -u -N <replaceable>newfile</replaceable>.orig <replaceable>newfile</replaceable> > patch-<replaceable>pathname-newfile</replaceable></userinput></screen> - - <para>Patch files are stored in <varname>PATCHDIR</varname> - (usually <filename class="directory">files/</filename>, from - where they will be automatically applied. All patches must be - relative to <varname>WRKSRC</varname> (generally the directory - the port's tarball unpacks itself into, that being where the - build is done). To make fixes and upgrades easier, avoid - having more than one patch fix the same file (that is, - <filename>patch-file</filename> and - <filename>patch-file2</filename> both changing - <filename>WRKSRC/foobar.c</filename>). Note that if the path - of a patched file contains an underscore - (<literal>_</literal>) character, the patch needs to have two - underscores instead in its name. For example, to patch a file - named <filename>src/freeglut_joystick.c</filename>, the - corresponding patch should be named - <filename>patch-src-freeglut__joystick.c</filename>.</para> - - <para>Please only use characters - <literal>[-+._a-zA-Z0-9]</literal> for naming patches. Do not - use any other characters besides them. Do not name patches - like <filename>patch-aa</filename> or - <filename>patch-ab</filename>, always mention the path and - file name in patch names.</para> - - <para>There is an alternate, easier method for creating patches - to existing files. The first steps are the same, make a copy - of the unmodified file with an <filename>.orig</filename> - extension, then make modifications. Then use - <command>make makepatch</command> to write updated patch files - to the <filename>files</filename> directory of the - port.</para> - - <para>Do not put RCS strings in patches. - <application>Subversion</application> will mangle them when we - put the files into the ports tree, and when we check them out - again, they will come out different and the patch will fail. - RCS strings are surrounded by dollar - (<literal>$</literal>) signs, and typically start with - <literal>$Id</literal> or - <literal>$RCS</literal>.</para> - - <para>Using the recurse (<option>-r</option>) option to - &man.diff.1; to generate patches is fine, but please - look at the resulting patches to make sure there is no - unnecessary junk in there. In particular, diffs between two - backup files, <filename>Makefile</filename>s when the port - uses <command>Imake</command> or GNU - <command>configure</command>, etc., are unnecessary and should - be deleted. If it was necessary to edit - <filename>configure.in</filename> and run - <command>autoconf</command> to regenerate - <command>configure</command>, do not take the diffs of - <command>configure</command> (it often grows to a few thousand - lines!). Instead, define - <literal>USE_AUTOTOOLS=autoconf:261</literal> and take the - diffs of <filename>configure.in</filename>.</para> - - <para>Try to minimize the amount of non-functional whitespace - changes in patches. It is common in the Open Source world for - projects to share large amounts of a code base, but obey - different style and indenting rules. When taking a working - piece of functionality from one project to fix similar areas - in another, please be careful: the resulting line patch may be - full of non-functional changes. It not only increases the - size of the <application>Subversion</application> repository - but makes it hard to find out what exactly caused the problem - and what was changed at all.</para> - - <para>If a file must be deleted, do it in the - <buildtarget>post-extract</buildtarget> target rather than as - part of the patch.</para> - - <para>Simple replacements can be performed directly from the - port <filename>Makefile</filename> using the in-place mode of - &man.sed.1;. This is useful when changes use the value of a - variable:</para> - - <programlisting>post-patch: - @${REINPLACE_CMD} -e 's|for Linux|for FreeBSD|g' ${WRKSRC}/README</programlisting> - - <para>Quite often, software being ported uses the CR/LF - convention in source files. This may cause problems with - further patching, compiler warnings, or script execution (like - <literal>/bin/sh^M not found</literal>.) To quickly convert - all files from CR/LF to just LF, add this entry to the port - <filename>Makefile</filename>:</para> - - <programlisting>USES= dos2unix</programlisting> - - <para>A list of specific files to convert can - be given:</para> - - <programlisting>USES= dos2unix -DOS2UNIX_FILES= util.c util.h</programlisting> - - <para>Use <varname>DOS2UNIX_REGEX</varname> to convert a group - of files across subdirectories. Its argument is a - &man.find.1;-compatible regular expression. More on the - format is in &man.re.format.7;. This option is useful for - converting all files of a given extension. For example, - convert all source code files, leaving binary files - intact:</para> - - <programlisting>USES= dos2unix -DOS2UNIX_REGEX= .*\.([ch]|cpp)</programlisting> - - <para>A similar option is <varname>DOS2UNIX_GLOB</varname>, - which invokes <command>find</command> for each element listed - in it.</para> - - <programlisting>USES= dos2unix -DOS2UNIX_GLOB= *.c *.cpp *.h</programlisting> - </sect1> - *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201402090150.s191osWP016334>