Date: Tue, 30 Jun 2015 11:10:39 +0000 (UTC) From: Mathieu Arnold <mat@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r46900 - head/en_US.ISO8859-1/books/porters-handbook/makefiles Message-ID: <201506301110.t5UBAdM2007840@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201506301110.t5UBAdM2007840>