svn commit: r49366 - in head: en_US.ISO8859-1/books/porters-handbook/makefiles share/xml
Mathieu Arnold
mat at FreeBSD.org
Mon Sep 5 11:34:08 UTC 2016
Author: mat
Date: Mon Sep 5 11:34:07 2016
New Revision: 49366
URL: https://svnweb.freebsd.org/changeset/doc/49366
Log:
Document GH_SUBDIR.
While there, add an example on how to do work with git submodules.
Reviewed by: wblock
Sponsored by: Absolight
Differential Revision: https://reviews.freebsd.org/D7661
Modified:
head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
head/share/xml/man-refs.ent
Modified: head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml Fri Sep 2 21:40:36 2016 (r49365)
+++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml Mon Sep 5 11:34:07 2016 (r49366)
@@ -1982,15 +1982,29 @@ MASTER_SITE_SUBDIR= stardict/WyabdcRealP
</row>
<row>
+ <entry><varname>GH_SUBDIR</varname></entry>
+ <entry>When the software needs an additional
+ distribution file to be extracted within
+ <varname>${WRKSRC}</varname>, this variable can be
+ used. See the examples in <xref
+ linkend="makefile-master_sites-github-multiple"/>
+ for more information.</entry>
+ <entry>(none)</entry>
+ </row>
+
+ <row>
<entry><varname>GH_TUPLE</varname></entry>
- <entry><varname>GH_TUPLE</varname> allows putting all
- the <varname>GH_ACCOUNT</varname>,
- <varname>GH_PROJECT</varname>, and
- <varname>GH_TAGNAME</varname> into one variable. The
- format is
- <replaceable>account</replaceable><literal>:</literal><replaceable>project</replaceable><literal>:</literal><replaceable>tagname</replaceable><literal>:</literal><replaceable>group</replaceable>.
- It is helpful when there is more than one GitHub
- project from which to fetch.</entry>
+ <entry><varname>GH_TUPLE</varname> allows putting
+ <varname>GH_ACCOUNT</varname>,
+ <varname>GH_PROJECT</varname>,
+ <varname>GH_TAGNAME</varname>, and
+ <varname>GH_SUBDIR</varname> into a single variable.
+ The format is
+ <replaceable>account</replaceable><literal>:</literal><replaceable>project</replaceable><literal>:</literal><replaceable>tagname</replaceable><literal>:</literal><replaceable>group</replaceable><literal>/</literal><replaceable>subdir</replaceable>.
+ The
+ <literal>/</literal><replaceable>subdir</replaceable>
+ part is optional. It is helpful when there is more
+ than one GitHub project from which to fetch.</entry>
</row>
</tbody>
</tgroup>
@@ -2132,11 +2146,9 @@ USE_GITHUB= yes
GH_ACCOUNT= bar:icons,contrib
GH_PROJECT= foo-icons:icons foo-contrib:contrib
GH_TAGNAME= 1.0:icons fa579bc:contrib
+GH_SUBDIR= ext/icons:icons
-CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib}
-
-post-extract:
- @${MV} ${WRKSRC_icons} ${WRKSRC}/icons</programlisting>
+CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib}</programlisting>
<para>This will fetch three distribution files from
github. The default one comes from
@@ -2165,6 +2177,17 @@ post-extract:
with the <literal>contrib</literal> tag is called
<varname>${WRKSRC_contrib}</varname> and contains
<literal>${WRKDIR}/foo-contrib-fa579bc</literal>.</para>
+
+ <para>The software's build system expects to find the icons
+ in a <filename>ext/icons</filename> subdirectory in its
+ sources, so <varname>GH_SUBDIR</varname> is used.
+ <varname>GH_SUBDIR</varname> makes sure that
+ <filename>ext</filename> exists, but that
+ <filename>ext/icons</filename> does not already exist.
+ Then it does this:</para>
+
+ <programlisting>post-extract:
+ @${MV} ${WRKSRC_icons} ${WRKSRC}/ext/icons</programlisting>
</example>
<example xml:id="makefile-master_sites-github-multi2">
@@ -2180,19 +2203,118 @@ post-extract:
PORTVERSION= 1.0.2
USE_GITHUB= yes
-GH_TUPLE= bar:foo-icons:1.0:icons \
+GH_TUPLE= bar:foo-icons:1.0:icons/ext/icons \
bar:foo-contrib:fa579bc:contrib
-CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib}
-
-post-extract:
- @${MV} ${WRKSRC_icons} ${WRKSRC}/icons</programlisting>
+CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib}</programlisting>
<para>Grouping was used in the previous example with
<literal>bar:icons,contrib</literal>. Some redundant
information is present with <varname>GH_TUPLE</varname>
because grouping is not possible.</para>
</example>
+
+ <example xml:id="makefile-master_sites-github-submodules">
+ <title>How to Use <varname>USE_GITHUB</varname> with
+ <application>Git</application> Submodules?</title>
+
+ <para>Ports with GitHub as an upstream repository sometimes
+ use submodules. See &man.git-submodule.1; for more
+ information.</para>
+
+ <para>The problem with submodules is that each is a separate
+ repository. As such, they each must be fetched
+ separately.</para>
+
+ <para>Using <package
+ role="port">finance/moneymanagerex</package> as an
+ example, its GitHub repository is <link
+ xlink:href="https://github.com/moneymanagerex/moneymanagerex"/>.
+ It has a <link
+ xlink:href="https://github.com/moneymanagerex/moneymanagerex/blob/master/.gitmodules"><filename>.gitmodules</filename></link>
+ file at the root. This file describes all the submodules
+ used in this repository, and lists additional repositories
+ needed. This file will tell what additional repositories
+ are needed:</para>
+
+ <programlisting>[submodule "lib/wxsqlite3"]
+ path = lib/wxsqlite3
+ url = https://github.com/utelle/wxsqlite3.git
+[submodule "3rd/mongoose"]
+ path = 3rd/mongoose
+ url = https://github.com/cesanta/mongoose.git
+[submodule "3rd/LuaGlue"]
+ path = 3rd/LuaGlue
+ url = https://github.com/moneymanagerex/LuaGlue.git
+[submodule "3rd/cgitemplate"]
+ path = 3rd/cgitemplate
+ url = https://github.com/moneymanagerex/html-template.git
+[...]</programlisting>
+
+ <para>The only information missing from that file is the
+ commit hash or tag to use as a version. This information
+ is found after cloning the repository:</para>
+
+ <screen>&prompt.user; <userinput>git clone --recurse-submodules https://github.com/moneymanagerex/moneymanagerex.git</userinput>
+Cloning into 'moneymanagerex'...
+remote: Counting objects: 32387, done.
+[...]
+Submodule '3rd/LuaGlue' (https://github.com/moneymanagerex/LuaGlue.git) registered for path '3rd/LuaGlue'
+Submodule '3rd/cgitemplate' (https://github.com/moneymanagerex/html-template.git) registered for path '3rd/cgitemplate'
+Submodule '3rd/mongoose' (https://github.com/cesanta/mongoose.git) registered for path '3rd/mongoose'
+Submodule 'lib/wxsqlite3' (https://github.com/utelle/wxsqlite3.git) registered for path 'lib/wxsqlite3'
+[...]
+Cloning into '/home/mat/work/freebsd/ports/finance/moneymanagerex/moneymanagerex/3rd/LuaGlue'...
+Cloning into '/home/mat/work/freebsd/ports/finance/moneymanagerex/moneymanagerex/3rd/cgitemplate'...
+Cloning into '/home/mat/work/freebsd/ports/finance/moneymanagerex/moneymanagerex/3rd/mongoose'...
+Cloning into '/home/mat/work/freebsd/ports/finance/moneymanagerex/moneymanagerex/lib/wxsqlite3'...
+[...]
+Submodule path '3rd/LuaGlue': checked out 'c51d11a247ee4d1e9817dfa2a8da8d9e2f97ae3b'
+Submodule path '3rd/cgitemplate': checked out 'cd434eeeb35904ebcd3d718ba29c281a649b192c'
+Submodule path '3rd/mongoose': checked out '2140e5992ab9a3a9a34ce9a281abf57f00f95cda'
+Submodule path 'lib/wxsqlite3': checked out 'fb66eb230d8aed21dec273b38c7c054dcb7d6b51'
+[...]
+&prompt.user; <userinput>cd moneymanagerex</userinput>
+&prompt.user; <userinput>git submodule status</userinput>
+ c51d11a247ee4d1e9817dfa2a8da8d9e2f97ae3b 3rd/LuaGlue (heads/master)
+ cd434eeeb35904ebcd3d718ba29c281a649b192c 3rd/cgitemplate (cd434ee)
+ 2140e5992ab9a3a9a34ce9a281abf57f00f95cda 3rd/mongoose (6.2-138-g2140e59)
+ fb66eb230d8aed21dec273b38c7c054dcb7d6b51 lib/wxsqlite3 (v3.4.0)
+[...]</screen>
+
+ <para>It can also be found on GitHub. Each subdirectory
+ that is a submodule is shown as
+ <replaceable>directory</replaceable><literal> @ </literal><replaceable>hash</replaceable>,
+ for example,
+ <literal>mongoose @ 2140e59</literal>.</para>
+
+ <note>
+ <para>While getting the information from GitHub seems more
+ straightforward, the information found using
+ <command>git submodule status</command> will provide
+ more meaningful information. For example, here,
+ <literal>lib/wxsqlite3</literal>'s commit hash
+ <literal>fb66eb2</literal> correspond to
+ <literal>v3.4.0</literal>. Both can be used
+ interchangeably, but when a tag is available, use
+ it.</para>
+ </note>
+
+ <para>Now that all the required information has been
+ gathered, the <filename>Makefile</filename> can be written
+ (only GitHub-related lines are shown):</para>
+
+ <programlisting>PORTNAME= moneymanagerex
+PORTVERSION= 1.3.0
+DISTVERSIONPREFIX= v
+
+USE_GITHUB= yes
+GH_TUPLE= utelle:wxsqlite3:v3.4.0:wxsqlite3/lib/wxsqlite3 \
+ moneymanagerex:LuaGlue:c51d11a:lua_glue/3rd/LuaGlue \
+ moneymanagerex:html-template:cd434ee:html_template/3rd/cgitemplate \
+ cesanta:mongoose:2140e59:mongoose/3rd/mongoose \
+ [...]</programlisting>
+ </example>
</sect3>
</sect2>
@@ -4755,6 +4877,10 @@ LIB_DEPENDS+= libb.so:devel/b
</listitem>
<listitem>
+ <para><varname>GH_SUBDIR</varname></para>
+ </listitem>
+
+ <listitem>
<para><varname>GH_TAGNAME</varname></para>
</listitem>
Modified: head/share/xml/man-refs.ent
==============================================================================
--- head/share/xml/man-refs.ent Fri Sep 2 21:40:36 2016 (r49365)
+++ head/share/xml/man-refs.ent Mon Sep 5 11:34:07 2016 (r49366)
@@ -257,6 +257,7 @@
<!ENTITY man.getfacl.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>getfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
<!ENTITY man.getopt.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>getopt</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
<!ENTITY man.getopts.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>getopts</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
+<!ENTITY man.git-submodule.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>git-submodule</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
<!ENTITY man.glob.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>glob</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
<!ENTITY man.gnu-ar.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>gnu-ar</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
<!ENTITY man.gnu-ranlib.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>gnu-ranlib</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
More information about the svn-doc-all
mailing list