svn commit: r46900 - head/en_US.ISO8859-1/books/porters-handbook/makefiles

Author: mat
Date: Tue Jun 30 11:10:38 2015
New Revision: 46900
URL: https://svnweb.freebsd.org/changeset/doc/46900

Log:
  Document the new multiple-USE_GITHUB.
  
  Approved by:	wblock (mentor)
  Sponsored by:	Absolight
  Differential Revision:	https://reviews.freebsd.org/D2781

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml

Modified: head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml	Tue Jun 30 09:03:55 2015	(r46899)
+++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml	Tue Jun 30 11:10:38 2015	(r46900)
@@ -1930,8 +1930,9 @@ MASTER_SITE_SUBDIR=	stardict/WyabdcRealP
 	  </tgroup>
 	</table>
       </sect3>
+    </sect2>
 
-      <sect3 xml:id="makefile-master_sites-github">
+      <sect2 xml:id="makefile-master_sites-github">
 	<title><varname>USE_GITHUB</varname></title>
 
 	<para>If the distribution file comes from a specific commit or
@@ -2009,8 +2010,8 @@ GH_ACCOUNT=	freebsd</programlisting>
 	  <para>While trying to make a port for the bleeding edge
 	    version of <application>pkg</application> from the &os;
 	    user on github, at <link
-	      xlink:href="https://github.com/freebsd/pkg"/>, The
-	    <filename>Makefile</filename> would end up looking like
+	      xlink:href="https://github.com/freebsd/pkg"/>, the
+	    <filename>Makefile</filename> ends up looking like
 	    this (slightly stripped for the example):</para>
 
 	  <programlisting>PORTNAME=	pkg-devel
@@ -2051,6 +2052,87 @@ USE_GITHUB=	yes</programlisting>
 	    <varname>${WRKDIR}/foo-1.0.2</varname>.</para>
 	</example>
 
+	<sect3>
+	  <title>Fetching Multiple Files From GitHub</title>
+
+	  <para>The <varname>USE_GITHUB</varname> framework also
+	    supports fetching multiple distribution files from
+	    different places in GitHub.  It works in a way very
+	    similar to <xref
+	      linkend="porting-master-sites-n"/>.</para>
+
+	  <para>Multiple values are added to
+	    <varname>GH_ACCOUNT</varname>,
+	    <varname>GH_PROJECT</varname>, and
+	    <varname>GH_TAGNAME</varname>.  Each different value is
+	    assigned a tag.  The main value can either have no tag, or
+	    the <literal>:DEFAULT</literal> tag.  A value can be
+	    omitted if it is the same as the default as listed in
+	    <xref
+	      linkend="makefile-master_sites-github-description"/>.</para>
+
+	  <para>For each tag, a
+	    <varname>${WRKSRC_<replaceable>tag</replaceable>}</varname>
+	    helper variable is created, containing the directory into
+	    which the file has been extracted.  The
+	    <varname>${WRKSRC_<replaceable>tag</replaceable>}</varname>
+	    variables can be used to move directories around during
+	    <buildtarget>post-extract</buildtarget>, or add to
+	    <varname>CONFIGURE_ARGS</varname>, or whatever is needed
+	    so that the software builds correctly.</para>
+
+	  <example xml:id="makefile-master_sites-github-multi">
+	    <title>Use of <varname>USE_GITHUB</varname> with Multiple
+	      Distribution Files</title>
+
+	    <para>From time to time, there is a need to fetch more
+	      than one distribution file.  For example, when the
+	      upstream git repository uses submodules.  This can be
+	      done easily using tags in the
+	      <varname>GH_<replaceable>*</replaceable></varname>
+	      variables:</para>
+
+	    <programlisting>PORTNAME=	foo
+PORTVERSION=	1.0.2
+
+USE_GITHUB=	yes
+GH_ACCOUNT=	bar:icons,contrib
+GH_PROJECT=	foo-icons:icons foo-contrib:contrib
+GH_TAGNAME=	1.0:icons fa579bc:contrib
+
+CONFIGURE_ARGS=	--with-contrib=${WRKSRC_contrib}
+
+post-extract:
+	@${MV} ${WRKSRC_icons} ${WRKSRC}/icons</programlisting>
+
+	    <para>This will fetch three distribution files from
+	      github.  The default one comes from
+	      <filename>foo/foo</filename> and is version
+	      <literal>1.0.2</literal>.  The second one, tagged
+	      <literal>icons</literal>, comes from
+	      <filename>bar/foo-icons</filename> and is in version
+	      <literal>1.0</literal>.  The third one comes from
+	      <filename>bar/foo-contrib</filename> and uses the
+	      <application>Git</application> commit
+	      <literal>fa579bc</literal>.  The distribution files are
+	      named <filename>foo-foo-1.0.2_GH0.tar.gz</filename>,
+	      <filename>bar-foo-icons-1.0_GH0.tar.gz</filename>, and
+	      <filename>bar-foo-contrib-fa579bc_GH0.tar.gz</filename>.</para>
+
+	    <para>All the distribution files are extracted in
+	      <varname>${WRKDIR}</varname> in their respective
+	      subdirectories.  The default file is still extracted in
+	      <varname>${WRKSRC}</varname>, in this case,
+	      <filename>${WRKDIR}/foo-1.0.2</filename>.  Each
+	      additional distribution file is extracted in
+	      <varname>${WRKSRC_<replaceable>tag</replaceable>}</varname>.
+	      Here, for the <literal>icons</literal> tag, it is called
+	      <varname>${WRKSRC_icons}</varname> and it contains
+	      <filename>${WRKDIR}/foo-icons-1.0</filename>.  The file
+	      with the <literal>contrib</literal> tag is called
+	      <varname>${WRKSRC_contrib}</varname> and contains
+	      <literal>${WRKDIR}/foo-contrib-fa579bc</literal>.</para>
+	  </example>
       </sect3>
     </sect2>
 
@@ -2185,9 +2267,8 @@ EXTRACT_ONLY=	source.tar.gz</programlist
     </sect2>
 
     <sect2 xml:id="porting-master-sites-n">
-      <title>Multiple Distribution Files or Patches from Different
-	Sites and Subdirectories
-	(<literal>MASTER_SITES:n</literal>)</title>
+      <title>Multiple Distribution or Patches Files from Multiple
+	Locations</title>
 
       <para>(Consider this to be a somewhat
 	<quote>advanced topic</quote>; those new to this document
_______________________________________________
[email protected] mailing list
http://lists.freebsd.org/mailman/listinfo/svn-doc-all
To unsubscribe, send any mail to "[email protected]"