Date: Mon, 5 Sep 2016 11:34:07 +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: r49366 - in head: en_US.ISO8859-1/books/porters-handbook/makefiles share/xml Message-ID: <201609051134.u85BY7ZP057244@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>">;
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201609051134.u85BY7ZP057244>