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

[Mathieu Arnold]

Author: mat (ports committer)
Date: Fri Apr 11 16:46:10 2014
New Revision: 44535
URL: http://svnweb.freebsd.org/changeset/doc/44535

Log:
  Add a bit about USE_GITHUB.
  
  Sponsored by:	Absolight

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	Fri Apr 11 16:09:56 2014	(r44534)
+++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml	Fri Apr 11 16:46:10 2014	(r44535)
@@ -1754,6 +1754,119 @@ MASTER_SITE_SUBDIR=	stardict/WyabdcRealP
 	  </tbody>
 	</tgroup>
       </table>
+
+      <sect3 xml:id="makefile-master_sites-github">
+	<title><varname>USE_GITHUB</varname></title>
+
+	<para>If the distribution file comes from a specific commit or
+	  tag on <link xlink:href="https://github.com">GitHub</link>
+	  for which there is no officially released file, there is an
+	  easy way to set the right <varname>DISTNAME</varname> and
+	  <varname>MASTER_SITES</varname> automatically.  These
+	  variables are available:</para>
+
+	<table xml:id="makefile-master_sites-github-description">
+	  <title><varname>USE_GITHUB</varname> Description</title>
+
+	  <tgroup cols="4">
+	    <thead>
+	      <row>
+		<entry>Variable</entry>
+		<entry>Description</entry>
+		<entry>Default</entry>
+		<entry>Mandatory</entry>
+	      </row>
+	    </thead>
+
+	    <tbody>
+	      <row>
+		<entry><varname>GH_ACCOUNT</varname></entry>
+		<entry>Account name of the GitHub user hosting the
+		  project</entry>
+		<entry>none</entry>
+		<entry>Mandatory</entry>
+	      </row>
+
+	      <row>
+		<entry><varname>GH_PROJECT</varname></entry>
+		<entry>Name of the project on GitHub</entry>
+		<entry><literal>${PORTNAME}</literal></entry>
+	      </row>
+
+
+	      <row>
+		<entry><varname>GH_TAGNAME</varname></entry>
+		<entry>Name of the tag to download (2.0.1, hash, ...)
+		  Using the name of a branch here is incorrect.  It is
+		  possible to do
+		  <literal>GH_TAGNAME=${GH_COMMIT}</literal> to do a
+		  snapshot</entry>
+		<entry><literal>${DISTVERSION}</literal></entry>
+	      </row>
+
+	      <row>
+		<entry><varname>GH_COMMIT</varname></entry>
+		<entry>first 7 digits of the commit that generated
+		  <varname>GH_TAGNAME</varname> (see
+		  <link
+		    xlink:href="http://www.freebsd.org/cgi/man.cgi?query=git-describe&sektion=1&manpath=FreeBSD+Ports">git-describe(1)</link>)</entry>
+		<entry>none</entry>
+		<entry>Mandatory</entry>
+	      </row>
+	    </tbody>
+	  </tgroup>
+	</table>
+
+	<example xml:id="makefile-master_sites-github-ex1">
+	  <title>Simple Use of <varname>USE_GITHUB</varname></title>
+
+	  <para>While trying to make a port for version
+	    <literal>1.2.7</literal> 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
+	    this (slightly stripped for the example):</para>
+
+	  <programlisting>PORTNAME=	pkg
+PORTVERSION=	1.2.7
+
+USE_GITHUB=	yes
+GH_ACCOUNT=	freebsd
+GH_COMMIT=	f53e577</programlisting>
+
+	  <para>It will automatically have
+	    <varname>MASTER_SITES</varname> set to <literal>GH
+	      GHC</literal> and <varname>WRKSRC</varname> to
+	    <literal>${WRKDIR}/freebsd-pkg-f53e577</literal>.</para>
+	</example>
+
+	<example xml:id="makefile-master_sites-github-ex2">
+	  <title>More Complete Use of
+	    <varname>USE_GITHUB</varname></title>
+
+	  <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
+	    this (slightly stripped for the example):</para>
+
+	  <programlisting>PORTNAME=	pkg-devel
+PORTVERSION=	1.3.0.a.20140411
+
+USE_GITHUB=	yes
+GH_ACCOUNT=	freebsd
+GH_PROJECT=	pkg
+GH_TAGNAME=	${GH_COMMIT}
+GH_COMMIT=	6dbb17b</programlisting>
+
+	  <para>It will automatically have
+	    <varname>MASTER_SITES</varname> set to <literal>GH
+	      GHC</literal> and <varname>WRKSRC</varname> to
+	    <literal>${WRKDIR}/freebsd-pkg-6dbb17b</literal>.</para>
+	</example>
+
+      </sect3>
     </sect2>
 
     <sect2 xml:id="makefile-extract_sufx">