Page MenuHomeFreeBSD
Files F133330993

D12261.diff
No OneTemporary
Actions

D12261.diff
View Options

Index: head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
===================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
+++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
@@ -2907,6 +2907,294 @@
</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>

File Metadata

Mime Type
text/plain
Expires
Sat, Oct 25, 11:52 PM (12 h, 45 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
24198827
Default Alt Text
D12261.diff (14 KB)

Event Timeline