os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

* Add USE_GITLAB

Browse source 
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
This commit is contained in:
Richard Gallamore 2018-03-03 07:03:10 +00:00
parent d755d32cc9
commit 37487225bb
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=51456
1 changed files with 288 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

288
en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
View file

@ -2907,6 +2907,294 @@ GH_TUPLE= utelle:wxsqlite3:v3.4.0:wxsqlite3/lib/wxsqlite3 \
</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>