Date: Sat, 3 Mar 2018 07:03:10 +0000 (UTC) From: Richard Gallamore <ultima@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r51456 - head/en_US.ISO8859-1/books/porters-handbook/makefiles Message-ID: <201803030703.w2373AgM024183@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: ultima (ports committer) Date: Sat Mar 3 07:03:10 2018 New Revision: 51456 URL: https://svnweb.freebsd.org/changeset/doc/51456 Log: * Add USE_GITLAB This will explain how to properly use the new USE_GITLAB feature. Reviewed by: mat wblock Approved by: mat Differential Revision: https://reviews.freebsd.org/D12261 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 Sat Mar 3 00:01:48 2018 (r51455) +++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml Sat Mar 3 07:03:10 2018 (r51456) @@ -2907,6 +2907,294 @@ GH_TUPLE= utelle:wxsqlite3:v3.4.0:wxsqlite3/lib/wxsqli </sect3> </sect2> + <sect2 xml:id="makefile-master_sites-gitlab"> + <title><varname>USE_GITLAB</varname></title> + + <para>Similar to GitHub, if the distribution file comes from + <link xlink:href="https://gitlab.com">gitlab.com</link>; + or is hosting the <application>GitLab</application> + software, these variables are available for use and might + need to be set.</para> + + <table xml:id="makefile-master_sites-gitlab-description"> + <title><varname>USE_GITLAB</varname> Description</title> + + <tgroup cols="3"> + <thead> + <row> + <entry>Variable</entry> + <entry>Description</entry> + <entry>Default</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>GL_SITE</varname></entry> + <entry>Site name hosting the <application>GitLab</application> + project</entry> <entry>https://gitlab.com</entry>; + </row> + + <row> + <entry><varname>GL_ACCOUNT</varname></entry> + <entry>Account name of the <application>GitLab</application> + user hosting the project</entry> + <entry><literal>${PORTNAME}</literal></entry> + </row> + + <row> + <entry><varname>GL_PROJECT</varname></entry> + <entry>Name of the project on <application>GitLab</application></entry> + <entry><literal>${PORTNAME}</literal></entry> + </row> + + <row> + <entry><varname>GL_COMMIT</varname></entry> + <entry>The commit hash to download. Must be the full + 160 bit, 40 character hex sha1 hash. This is a required + variable for <application>GitLab</application>.</entry> + <entry><literal>(none)</literal></entry> + </row> + + <row> + <entry><varname>GL_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-gitlab-multiple"/> + for more information.</entry> + <entry>(none)</entry> + </row> + + <row> + <entry><varname>GL_TUPLE</varname></entry> + <entry><varname>GL_TUPLE</varname> allows putting + <varname>GL_SITE</varname>, + <varname>GL_ACCOUNT</varname>, + <varname>GL_PROJECT</varname>, + <varname>GL_COMMIT</varname>, and + <varname>GL_SUBDIR</varname> into a single variable. + The format is + <replaceable>site</replaceable><literal>:</literal><replaceable>account</replaceable><literal>:</literal><replaceable>project</replaceable><literal>:</literal><replaceable>commit</replaceable><literal>:</literal><replaceable>group</replaceable><literal>/</literal><replaceable>subdir</replaceable>. + The <replaceable>site</replaceable><literal>:</literal> and + <literal>/</literal><replaceable>subdir</replaceable> + part is optional. It is helpful when there are more + than one <application>GitLab</application> project from + which to fetch.</entry> + </row> + </tbody> + </tgroup> + </table> + + <example xml:id="makefile-master_sites-gitlab-ex1"> + <title>Simple Use of <varname>USE_GITLAB</varname></title> + + <para>While trying to make a port for version + <literal>1.14</literal> of <application>libsignon-glib</application> + from the accounts-sso user on gitlab.com, at <link + xlink:href="https://gitlab.com/accounts-sso/libsignon-glib"/>, The + <filename>Makefile</filename> would end up looking like + this for fetching the distribution files:</para> + + <programlisting>PORTNAME= libsignon-glib +DISTVERSION= 1.14 + +USE_GITLAB= yes +GL_ACCOUNT= accounts-sso +GL_COMMIT= e90302e342bfd27bc8c9132ab9d0ea3d8723fd03</programlisting> + + <para>It will automatically have + <varname>MASTER_SITES</varname> set to <link + xlink:href="https://gitlab.com">gitlab.com</link>; + and <varname>WRKSRC</varname> to + <literal>${WRKDIR}/libsignon-glib-e90302e342bfd27bc8c9132ab9d0ea3d8723fd03-e90302e342bfd27bc8c9132ab9d0ea3d8723fd03</literal>.</para> + </example> + + <example xml:id="makefile-master_sites-gitlab-ex2"> + <title>More Complete Use of + <varname>USE_GITLAB</varname></title> + + <para>A more complete use of the above if + port had no versioning and <application>foobar</application> + from the foo user on project bar on a self hosted <application>GitLab</application> + site <literal>https://gitlab.example.com</literal>, the <filename>Makefile</filename> + ends up looking like this for fetching distribution files:</para> + + <programlisting>PORTNAME= foobar +DISTVERSION= g20170906 + +USE_GITLAB= yes +GL_SITE= https://gitlab.example.com +GL_ACCOUNT= foo +GL_PROJECT= bar +GL_COMMIT= 9c1669ce60c3f4f5eb43df874d7314483fb3f8a6</programlisting> + + <para>It will have <varname>MASTER_SITES</varname> set to + "<literal>https://gitlab.example.com</literal>" and <varname>WRKSRC</varname> to + <literal>${WRKDIR}/bar-9c1669ce60c3f4f5eb43df874d7314483fb3f8a6-9c1669ce60c3f4f5eb43df874d7314483fb3f8a6</literal>.</para> + + <tip> + <para><literal>20170906</literal> is the date of the + commit referenced in <varname>GL_COMMIT</varname>, not + the date the <filename>Makefile</filename> is edited, or + the date the commit to the &os; ports tree is made.</para> + </tip> + + <note> + <para><varname>GL_SITE</varname>'s protocol, port and + webroot can all be modified in the same variable.</para> + </note> + </example> + + <sect3 xml:id="makefile-master_sites-gitlab-multiple"> + <title>Fetching Multiple Files from <application>GitLab</application></title> + + <para>The <varname>USE_GITLAB</varname> framework also + supports fetching multiple distribution files from + different places from <application>GitLab</application> + and <application>GitLab</application> hosted sites. It + works in a way very similar to <xref + linkend="porting-master-sites-n"/> and xref + linkend="makefile-master_sites-gitlab-multiple".</para> + + <para>When fetching multiple files using <application>GitLab</application>, + sometimes the default distribution file is not fetched from a <application>GitLab</application> + site. To disable fetching the default distribution, set:</para> + + <programlisting>USE_GITLAB= nodefault</programlisting> + + <para>Multiple values are added to + <varname>GL_SITE</varname>, + <varname>GL_ACCOUNT</varname>, + <varname>GL_PROJECT</varname> and + <varname>GL_COMMIT</varname>. Each different value is + assigned a group. + <xref + linkend="makefile-master_sites-gitlab-description"/>.</para> + + <para><varname>GL_TUPLE</varname> can also be used when there + are a lot of distribution files. It helps keep the site, + account, project, commit, and group information at the same + place.</para> + + <para>For each group, a + <varname>${WRKSRC_<replaceable>group</replaceable>}</varname> + helper variable is created, containing the directory into + which the file has been extracted. The + <varname>${WRKSRC_<replaceable>group</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> + + <caution> + <para>The + <literal>:<replaceable>group</replaceable></literal> part + <emphasis>must</emphasis> be used for <emphasis>only + one</emphasis> distribution file. It is used as a + unique key and using it more than once will overwrite the + previous values.</para> + </caution> + + <note> + <para>As this is only syntastic sugar above + <varname>DISTFILES</varname> and + <varname>MASTER_SITES</varname>, the group names must + adhere to the restrictions on group names outlined in + <xref linkend="porting-master-sites-n"/></para> + </note> + + <example xml:id="makefile-master_sites-gitlab-multi"> + <title>Use of <varname>USE_GITLAB</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 groups in the + <varname>GL_<replaceable>*</replaceable></varname> + variables:</para> + + <programlisting>PORTNAME= foo +DISTVERSION= 1.0.2 + +USE_GITLAB= yes +GL_SITE= https://gitlab.example.com:9434/gitlab:icons +GL_ACCOUNT= bar:icons,contrib +GL_PROJECT= foo-icons:icons foo-contrib:contrib +GL_COMMIT= c189207a55da45305c884fe2b50e086fcad4724b ae7368cab1ca7ca754b38d49da064df87968ffe4:icons 9e4dd76ad9b38f33fdb417a4c01935958d5acd2a:contrib +GL_SUBDIR= ext/icons:icons + +CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib}</programlisting> + + <para>This will fetch two distribution files from + gitlab.com and one from <literal>gitlab.example.com</literal> + hosting <application>GitLab</application>. The default one comes + from <filename>https://gitlab.com/foo/foo</filename>; and commit is + <literal>c189207a55da45305c884fe2b50e086fcad4724b</literal>. The + second one, with the <literal>icons</literal> group, comes from + <filename>https://gitlab.example.com:9434/gitlab/bar/foo-icons</filename>; + and commit is <literal>ae7368cab1ca7ca754b38d49da064df87968ffe4</literal>. + The third one comes from <filename>https://gitlab.com/bar/foo-contrib</filename>; + and is commit <literal>9e4dd76ad9b38f33fdb417a4c01935958d5acd2a</literal>. + The distribution files are named <filename>foo-foo-c189207a55da45305c884fe2b50e086fcad4724b_GL0.tar.gz</filename>, + <filename>bar-foo-icons-ae7368cab1ca7ca754b38d49da064df87968ffe4_GL0.tar.gz</filename>, and + <filename>bar-foo-contrib-9e4dd76ad9b38f33fdb417a4c01935958d5acd2a_GL0.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-c189207a55da45305c884fe2b50e086fcad4724b-c189207a55da45305c884fe2b50e086fcad4724b</filename>. + Each additional distribution file is extracted in + <varname>${WRKSRC_<replaceable>group</replaceable>}</varname>. + Here, for the <literal>icons</literal> group, it is called + <varname>${WRKSRC_icons}</varname> and it contains + <filename>${WRKDIR}/foo-icons-ae7368cab1ca7ca754b38d49da064df87968ffe4-ae7368cab1ca7ca754b38d49da064df87968ffe4</filename>. + The file with the <literal>contrib</literal> group is + called <varname>${WRKSRC_contrib}</varname> and contains + <literal>${WRKDIR}/foo-contrib-9e4dd76ad9b38f33fdb417a4c01935958d5acd2a-9e4dd76ad9b38f33fdb417a4c01935958d5acd2a</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>GL_SUBDIR</varname> is used. + <varname>GL_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-gitlab-multi2"> + <title>Use of <varname>USE_GITLAB</varname> with Multiple + Distribution Files Using + <varname>GL_TUPLE</varname></title> + + <para>This is functionally equivalent to <xref + linkend="makefile-master_sites-gitlab-multi"/>, but + using <varname>GL_TUPLE</varname>:</para> + + <programlisting>PORTNAME= foo +DISTVERSION= 1.0.2 + +USE_GITLAB= yes +GL_COMMIT= c189207a55da45305c884fe2b50e086fcad4724b +GL_TUPLE= https://gitlab.example.com:9434/gitlab:bar:foo-icons:ae7368cab1ca7ca754b38d49da064df87968ffe4:icons/ext/icons \ + bar:foo-contrib:9e4dd76ad9b38f33fdb417a4c01935958d5acd2a:contrib + +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>GL_TUPLE</varname> + because grouping is not possible.</para> + </example> + </sect3> + </sect2> + <sect2 xml:id="makefile-extract_sufx"> <title><varname>EXTRACT_SUFX</varname></title>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201803030703.w2373AgM024183>