Date: Mon, 29 Nov 2010 17:36:53 GMT From: Rene Ladan <rene@FreeBSD.org> To: Perforce Change Reviews <perforce@FreeBSD.org> Subject: PERFORCE change 186425 for review Message-ID: <201011291736.oATHarhb062442@skunkworks.freebsd.org>
next in thread | raw e-mail | index | archive | help
http://p4web.freebsd.org/@@186425?ac=10 Change 186425 by rene@rene_acer on 2010/11/29 17:36:49 IFC Affected files ... .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/porters-handbook/book.sgml#94 integrate Differences ... ==== //depot/projects/docproj_nl/en_US.ISO8859-1/books/porters-handbook/book.sgml#94 (text+ko) ==== @@ -1,7 +1,7 @@ <!-- The FreeBSD Documentation Project - $FreeBSD: doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v 1.1083 2010/11/22 19:15:29 jkois Exp $ + $FreeBSD: doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v 1.1085 2010/11/29 14:13:01 pav Exp $ --> <!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ @@ -56,7 +56,7 @@ </chapter> <chapter id="own-port"> - <title>Making a port yourself</title> + <title>Making a new port yourself</title> <para>So, you are interested in making your own port or upgrading an existing one? Great!</para> @@ -91,7 +91,7 @@ <chapter id="quick-porting"> <title>Quick Porting</title> - <para>This section tells you how to do a quick port. In many cases, it + <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> @@ -363,9 +363,9 @@ </sect1> <sect1 id="porting-submitting"> - <title>Submitting the port</title> + <title>Submitting the new port</title> - <para>First, make sure you have read the <link + <para>Before you submit the new port, make sure you have read the <link linkend="porting-dads">DOs and DON'Ts</link> section.</para> <para>Now that you are happy with your port, the only thing remaining @@ -386,7 +386,8 @@ <literal>change-request</literal> (Do not mark the report <literal>confidential</literal>!). Also add a short description of the program you ported - to the <quote>Description</quote> field of the PR and + to the <quote>Description</quote> field of the PR (e.g. + perhaps a short version of the <makevar>COMMENT</makevar>), and add the shar file to the <quote>Fix</quote> field.</para> <note> @@ -394,23 +395,23 @@ description in the synopsis of the problem report. We prefer something like <quote>New port: <category>/<portname> - <short description of the port></quote> for new ports and - <quote>Update port: <category>/<portname> - <short description of the update></quote> for port updates. + <short description of the port></quote> for new ports. If you stick to this scheme, the chance that someone will take a look at your PR soon is much better.</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>.</para> + you built with <command>make package</command></emphasis>; + and, do use &man.shar.1; for new ports, not &man.diff.1;. + </para> <para>After you have submitted your port, please be patient. Sometimes it can take a few months before a port is included in &os;, although it might only take a few days. You can view the list of <ulink url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports">ports - waiting to be committed to &os;</ulink>.</para> + PRs waiting to be committed to &os;</ulink>.</para> <para>Once we have looked at your port, we will get back to you if necessary, and put it in the tree. Your name will also appear in the list of @@ -2292,28 +2293,132 @@ helping this effort.</para> <para>If the original tarball is part of one of the popular - archives such as X-contrib, GNU, or Perl CPAN, you may be able + archives such as SourceForge, GNU, or Perl CPAN, you may be able refer to those sites in an easy compact form using <makevar>MASTER_SITE_<replaceable>*</replaceable></makevar> - (e.g., <makevar>MASTER_SITE_XCONTRIB</makevar>, + (e.g., <makevar>MASTER_SITE_SOURCEFORGE</makevar>, <makevar>MASTER_SITE_GNU</makevar> and <makevar>MASTER_SITE_PERL_CPAN</makevar>). Simply set <makevar>MASTER_SITES</makevar> to one of these variables and <makevar>MASTER_SITE_SUBDIR</makevar> to the path within the archive. Here is an example:</para> - <programlisting>MASTER_SITES= ${MASTER_SITE_XCONTRIB} -MASTER_SITE_SUBDIR= applications</programlisting> + <programlisting>MASTER_SITES= ${MASTER_SITE_GNU} +MASTER_SITE_SUBDIR= make</programlisting> + + <para>Or you can use a condensed format:</para> + + <programlisting>MASTER_SITES= GNU/make</programlisting> <para>These variables are defined in <filename>/usr/ports/Mk/bsd.sites.mk</filename>. There are new entries added all the time, so make sure to check the latest version of this file before submitting a port.</para> - <para>The user can also set the <makevar>MASTER_SITE_*</makevar> - variables in <filename>/etc/make.conf</filename> to override our - choices, and use their favorite mirrors of these popular archives - instead.</para> + <para>Several <emphasis>magic</emphasis> macros exist for popular sites + with a predictable directory structure. For these, just use the + abbreviation and the system will try to guess the correct + subdirectory for you.</para> + + <programlisting>MASTER_SITES= SF</programlisting> + + <para>If the guess is incorrect, it can be overriden as follows.</para> + + <programlisting>MASTER_SITES= SF/stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting> + + <table frame="none"> + <title>Popular magic <makevar>MASTER_SITES</makevar> macros</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Macro</entry> + + <entry>Assumed subdirectory</entry> + </row> + </thead> + + <tbody> + <row> + <entry><makevar>APACHE_JAKARTA</makevar></entry> + + <entry><makevar>/dist/jakarta/${PORTNAME:S,-,,/,}/source</makevar></entry> + </row> + + <row> + <entry><makevar>BERLIOS</makevar></entry> + + <entry><makevar>/${PORTNAME:L}</makevar></entry> + </row> + + <row> + <entry><makevar>CHEESESHOP</makevar></entry> + + <entry><makevar>/packages/source/source/${DISTNAME:C/(.).*/\1/}/${DISTNAME:C/(.*)-[0-9].*/\1/}</makevar></entry> + </row> + + <row> + <entry><makevar>DEBIAN</makevar></entry> + + <entry><makevar>/debian/pool/main/${PORTNAME:C/^((lib)?.).*$/\1/}/${PORTNAME}</makevar></entry> + </row> + + <row> + <entry><makevar>GCC</makevar></entry> + + <entry><makevar>/pub/gcc/releases/${DISTNAME}</makevar></entry> + </row> + + <row> + <entry><makevar>GNOME</makevar></entry> + + <entry><makevar>/pub/GNOME/sources/${PORTNAME}/${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/}</makevar></entry> + </row> + + <row> + <entry><makevar>GNU</makevar></entry> + + <entry><makevar>/gnu/${PORTNAME}</makevar></entry> + </row> + + <row> + <entry><makevar>MOZDEV</makevar></entry> + + <entry><makevar>/pub/mozdev/${PORTNAME:L}</makevar></entry> + </row> + + <row> + <entry><makevar>PERL_CPAN</makevar></entry> + + <entry><makevar>/pub/CPAN/modules/by-module/${PORTNAME:C/-.*//}</makevar></entry> + </row> + + <row> + <entry><makevar>PYTHON</makevar></entry> + + <entry><makevar>/ftp/python/${PYTHON_PORTVERSION:C/rc[0-9]//}</makevar></entry> + </row> + + <row> + <entry><makevar>RUBYFORGE</makevar></entry> + + <entry><makevar>/${PORTNAME:L}</makevar></entry> + </row> + + <row> + <entry><makevar>SAVANNAH</makevar></entry> + + <entry><makevar>/${PORTNAME:L}</makevar></entry> + </row> + + <row> + <entry><makevar>SF</makevar></entry> + + <entry><makevar>/project/${PORTNAME:L}/${PORTNAME:L}/${PORTVERSION}</makevar></entry> + </row> + </tbody> + </tgroup> + </table> </sect2> <sect2> @@ -9301,7 +9406,7 @@ </chapter> <chapter id="port-upgrading"> - <title>Upgrading</title> + <title>Upgrading an individual port</title> <para>When you notice that a port is out of date compared to the latest version from the original authors, you should first ensure that you @@ -9346,9 +9451,22 @@ <para>If the maintainer asks you to do the upgrade or there is no maintainer, then you have a chance to help out &os; by - preparing the update yourself! Please make the changes and save + preparing the update yourself! Please do this by using the + &man.diff.1; command in the base system.</para> + + <para>To create a suitable <command>diff</command> for a single patch, copy + the file that needs patching to <replaceable>something.orig</replaceable>, + save your changes to <replaceable>something</replaceable> and then create + your patch:</para> + + <informalexample> + <screen>&prompt.user; <userinput>/usr/bin/diff something.orig something > something.diff</userinput></screen> + </informalexample> + + <para>Otherwise, you should copy the contents of the port to an entire + different directory and use the result of the - recursive <command>diff</command> output + recursive &man.diff.1; output of the new and old ports directories (e.g., if your modified port directory is called <filename>superedit</filename> and the original is in our tree @@ -9359,7 +9477,11 @@ option—this is the accepted way to force diff to properly deal with the case of new files being added or old files being deleted. Before sending us the diff, please examine the - output to make sure all the changes make sense. To + output to make sure all the changes make sense. (In particular, + make sure you first clean out the work directories with + <command>make clean</command>).</para> + + <para>To simplify common operations with patch files, you can use <filename>/usr/ports/Tools/scripts/patchtool.py</filename>. Before using it, please read @@ -9405,7 +9527,8 @@ <note> <para>Once again, please use &man.diff.1; and not &man.shar.1; to send - updates to existing ports!</para> + updates to existing ports! This helps ports committers understand + exactly what is being changed.</para> </note> <para>Now that you have done all that, you will want to read about
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201011291736.oATHarhb062442>