[27222] trunk/doc/guide/new/xml/portfiledev.xml

[source_changes at macosforge.org]

Revision: 27222
          http://trac.macosforge.org/projects/macports/changeset/27222
Author:   markd at macports.org
Date:     2007-07-24 22:50:57 -0700 (Tue, 24 Jul 2007)

Log Message:
-----------
Add a section for creating patchfiles.

Modified Paths:
--------------
    trunk/doc/guide/new/xml/portfiledev.xml

Modified: trunk/doc/guide/new/xml/portfiledev.xml
===================================================================
--- trunk/doc/guide/new/xml/portfiledev.xml	2007-07-25 04:37:26 UTC (rev 27221)
+++ trunk/doc/guide/new/xml/portfiledev.xml	2007-07-25 05:50:57 UTC (rev 27222)
@@ -4,9 +4,9 @@
 <chapter>
   <title>Portfile Development</title>
 
-  <para>This chapter gives an introduction to port phases, creating a local
-  Portfile repository for development, and shows how to create
-  <filename>Portfile</filename>s by example.</para>
+  <para>This chapter covers a brief introduction to port phases, how to create
+  a local Portfile repository for development, and creating
+  <filename>Portfile</filename>s.</para>
 
   <section>
     <title>Portfile Introduction</title>
@@ -348,4 +348,111 @@
 }</programlisting>
     </section>
   </section>
+
+  <section>
+    <title>Creating Patch Files</title>
+
+    <para>Patch files are files created with the Unix command
+    <command>diff</command> that are applied using the command
+    <command>patch</command> to modify text files to fix bugs or extend
+    functionality. </para>
+
+    <section>
+      <title>Portfile Patches</title>
+
+      <para>If you wish to contribute modifications or fixes to a Portfile,
+      you should do so in the form of a patch.</para>
+
+      <orderedlist>
+        <listitem>
+          <para>Make a copy of the Portfile you wish to modify. Both the
+          Portfile and its copy must be in the same directory, though it may
+          be any directory.</para>
+
+          <programlisting><prompt>%%</prompt> <userinput>cp Portfile Portfile.org</userinput></programlisting>
+        </listitem>
+
+        <listitem>
+          <para>Edit the file to make it as you want it to be after it is
+          fetched.</para>
+        </listitem>
+
+        <listitem>
+          <para>Now use the Unix command diff to create a "unified" diff patch
+          file.</para>
+
+          <programlisting><prompt>%%</prompt> <userinput>diff -u Portfile.org Portfile &gt; Portfile.diff</userinput></programlisting>
+        </listitem>
+      </orderedlist>
+
+      <para>Now you may attach the Portfile.diff to a MacPorts Trac ticket for
+      the port author to evaluate.</para>
+    </section>
+
+    <section>
+      <title>Source Code Patches</title>
+
+      <para>Necessary or useful patches to application source code should be
+      sent to the application developer (not the port author) so the
+      modifications may be included in the next version, and the port patch
+      eventually removed.</para>
+
+      <orderedlist>
+        <listitem>
+          <para>Locate the file you wish to patch in its original location
+          within the unpacked source directory and make a duplicate of
+          it.</para>
+
+          <programlisting><prompt>%%</prompt> <userinput>cd foo-1.34/src</userinput>
+<prompt>%%</prompt> <userinput>cp Makefile.in Makefile.in.org</userinput></programlisting>
+        </listitem>
+
+        <listitem>
+          <para>Edit the file to make it as you want it to be after it is
+          fetched.</para>
+        </listitem>
+
+        <listitem>
+          <para>Now use the Unix command diff to create a "unified" diff patch
+          file.</para>
+
+          <programlisting><prompt>%%</prompt> <userinput>cd foo-1.34</userinput>
+<prompt>%%</prompt> <userinput>diff -u Makefile.in.org Makefile.in &gt; patch-Makefile.in</userinput></programlisting>
+
+          <note>
+            <para>You must execute the diff command in the top-level of the
+            unpacked source code. Otherwise the patch command will look for
+            the file to be patched in the wrong place and fail.</para>
+          </note>
+        </listitem>
+
+        <listitem>
+          <para>A patch made using "-u" ("unified") is the easiest to
+          interpret by humans and this type should always be used for ports.
+          See the example below where a patch file adds DESTDIR support to a
+          <filename>Makefile.in</filename> file.</para>
+
+          <programlisting>--- Makefile.in.org   2007-06-01 16:30:47.000000000 -0700
++++ Makefile.in       2007-06-20 10:10:59.000000000 -0700
+@@ -131,23 +131,23 @@
+        $(INSTALL_DATA)/gdata $(INSTALL_DATA)/perl
+
+ install-lib:
+-       -mkdir -p $(INSTALL_LIB)
++       -mkdir -p $(DESTDIR)$(INSTALL_LIB)
+        $(PERL) tools/install_lib -s src -l $(INSTALL_LIB) $(LIBS)
+-       cp $(TEXT) $(INSTALL_LIB)/
++       cp $(TEXT) $(DESTDIR)$(INSTALL_LIB)/</programlisting>
+        </listitem>
+
+        <listitem>
+          <para>Now you may use the patch file
+          <filename>patch-Makefile.in</filename> in a port using the
+          patchfiles keyword.</para>
+
+          <programlisting>patchfiles              patch-Makefile.in</programlisting>
+        </listitem>
+      </orderedlist>
+    </section>
+  </section>
 </chapter>
\ No newline at end of file

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.macosforge.org/pipermail/macports-changes/attachments/20070724/8bb108f7/attachment.html