Index: en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
===================================================================
--- en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
+++ en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
@@ -2876,6 +2876,294 @@
+
+ <varname>USE_GITLAB</varname>
+
+ Similar to GitHub, if the distribution file comes from
+ gitlab.com
+ or is hosting the GitLab
+ software, these variables are available for uses and may
+ need to be set.
+
+
+ <varname>USE_GITLAB</varname> Description
+
+
+
+
+ Variable
+ Description
+ Default
+
+
+
+
+
+ GL_SITE
+ Site name hosting the GitLab
+ projecthttps://gitlab.com
+
+
+
+ GL_ACCOUNT
+ Account name of the GitLab
+ user hosting the project
+ ${PORTNAME}
+
+
+
+ GL_PROJECT
+ Name of the project on GitLab
+ ${PORTNAME}
+
+
+
+ GL_COMMIT
+ The commit hash to download. Must be the full
+ 160 bit, 40 character hex sha1 hash. This is a required
+ variable for GitLab.
+ (none)
+
+
+
+ GL_SUBDIR
+ When the software needs an additional
+ distribution file to be extracted within
+ ${WRKSRC}, this variable can be
+ used. See the examples in
+ for more information.
+ (none)
+
+
+
+ GL_TUPLE
+ GL_TUPLE allows putting
+ GL_SITE,
+ GL_ACCOUNT,
+ GL_PROJECT,
+ GL_COMMIT, and
+ GL_SUBDIR into a single variable.
+ The format is
+ site:account:project:commit:group/subdir.
+ The site: and
+ /subdir
+ part is optional. It is helpful when there are more
+ than one GitLab project from
+ which to fetch.
+
+
+
+
+
+
+ Simple Use of <varname>USE_GITLAB</varname>
+
+ While trying to make a port for version
+ 1.14 of libsignon-glib
+ from the accounts-sso user on gitlab.com, at , The
+ Makefile would end up looking like
+ this for fetching the distribution files:
+
+ PORTNAME= libsignon-glib
+DISTVERSION= 1.14
+
+USE_GITLAB= yes
+GL_ACCOUNT= accounts-sso
+GL_COMMIT= e90302e342bfd27bc8c9132ab9d0ea3d8723fd03
+
+ It will automatically have
+ MASTER_SITES set to gitlab.com
+ and WRKSRC to
+ ${WRKDIR}/libsignon-glib-e90302e342bfd27bc8c9132ab9d0ea3d8723fd03-e90302e342bfd27bc8c9132ab9d0ea3d8723fd03.
+
+
+
+ More Complete Use of
+ <varname>USE_GITLAB</varname>
+
+ A more complete use of the above if
+ port had no versioning and foobar
+ from the foo user on project bar on a self hosted GitLab
+ site https://gitlab.example.com, the Makefile
+ ends up looking like this for fetching distribution files:
+
+ PORTNAME= foobar
+DISTVERSION= g20170906
+
+USE_GITLAB= yes
+GL_SITE= https://gitlab.example.com
+GL_ACCOUNT= foo
+GL_PROJECT= bar
+GL_COMMIT= 9c1669ce60c3f4f5eb43df874d7314483fb3f8a6
+
+ It will have MASTER_SITES set to
+ "https://gitlab.example.com" and WRKSRC to
+ ${WRKDIR}/bar-9c1669ce60c3f4f5eb43df874d7314483fb3f8a6-9c1669ce60c3f4f5eb43df874d7314483fb3f8a6.
+
+
+ 20170906 is the date of the
+ commit referenced in GL_COMMIT, not
+ the date the Makefile is edited, or
+ the date the commit to the &os; ports tree is made.
+
+
+
+ GL_SITE's protocol, port and
+ webroot can all be modified in the same variable.
+
+
+
+
+ Fetching Multiple Files from <application>GitLab</application>
+
+ The USE_GITLAB framework also
+ supports fetching multiple distribution files from
+ different places from GitLab
+ and GitLab hosted sites. It
+ works in a way very similar to and xref
+ linkend="makefile-master_sites-gitlab-multiple".
+
+ When fetching multiple files using GitLab,
+ sometimes the default distribution file is not fetched from a GitLab
+ site. To disable fetching the default distribution, set:
+
+ USE_GITLAB= nodefault
+
+ Multiple values are added to
+ GL_SITE,
+ GL_ACCOUNT,
+ GL_PROJECT and
+ GL_COMMIT. Each different value is
+ assigned a group.
+ .
+
+ GL_TUPLE 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.
+
+ For each group, a
+ ${WRKSRC_group}
+ helper variable is created, containing the directory into
+ which the file has been extracted. The
+ ${WRKSRC_group}
+ variables can be used to move directories around during
+ post-extract, or add to
+ CONFIGURE_ARGS, or whatever is needed
+ so that the software builds correctly.
+
+
+ The
+ :group part
+ must be used for only
+ one distribution file. It is used as a
+ unique key and using it more than once will overwrite the
+ previous values.
+
+
+
+ As this is only syntastic sugar above
+ DISTFILES and
+ MASTER_SITES, the group names must
+ adhere to the restrictions on group names outlined in
+
+
+
+
+ Use of <varname>USE_GITLAB</varname> with Multiple
+ Distribution Files
+
+ 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
+ GL_*
+ variables:
+
+ 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}
+
+ This will fetch two distribution files from
+ gitlab.com and one from gitlab.example.com
+ hosting GitLab. The default one comes
+ from https://gitlab.com/foo/foo and commit is
+ c189207a55da45305c884fe2b50e086fcad4724b. The
+ second one, with the icons group, comes from
+ https://gitlab.example.com:9434/gitlab/bar/foo-icons
+ and commit is ae7368cab1ca7ca754b38d49da064df87968ffe4.
+ The third one comes from https://gitlab.com/bar/foo-contrib
+ and is commit 9e4dd76ad9b38f33fdb417a4c01935958d5acd2a.
+ The distribution files are named foo-foo-c189207a55da45305c884fe2b50e086fcad4724b_GL0.tar.gz,
+ bar-foo-icons-ae7368cab1ca7ca754b38d49da064df87968ffe4_GL0.tar.gz, and
+ bar-foo-contrib-9e4dd76ad9b38f33fdb417a4c01935958d5acd2a_GL0.tar.gz.
+
+ All the distribution files are extracted in
+ ${WRKDIR} in their respective
+ subdirectories. The default file is still extracted in
+ ${WRKSRC}, in this case,
+ ${WRKDIR}/foo-c189207a55da45305c884fe2b50e086fcad4724b-c189207a55da45305c884fe2b50e086fcad4724b.
+ Each additional distribution file is extracted in
+ ${WRKSRC_group}.
+ Here, for the icons group, it is called
+ ${WRKSRC_icons} and it contains
+ ${WRKDIR}/foo-icons-ae7368cab1ca7ca754b38d49da064df87968ffe4-ae7368cab1ca7ca754b38d49da064df87968ffe4.
+ The file with the contrib group is
+ called ${WRKSRC_contrib} and contains
+ ${WRKDIR}/foo-contrib-9e4dd76ad9b38f33fdb417a4c01935958d5acd2a-9e4dd76ad9b38f33fdb417a4c01935958d5acd2a.
+
+ The software's build system expects to find the icons
+ in a ext/icons subdirectory in its
+ sources, so GL_SUBDIR is used.
+ GL_SUBDIR makes sure that
+ ext exists, but that
+ ext/icons does not already exist.
+ Then it does this:
+
+ post-extract:
+ @${MV} ${WRKSRC_icons} ${WRKSRC}/ext/icons
+
+
+
+ Use of <varname>USE_GITLAB</varname> with Multiple
+ Distribution Files Using
+ <varname>GL_TUPLE</varname>
+
+ This is functionally equivalent to , but
+ using GL_TUPLE:
+
+ 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}
+
+ Grouping was used in the previous example with
+ bar:icons,contrib. Some redundant
+ information is present with GL_TUPLE
+ because grouping is not possible.
+
+
+
+
<varname>EXTRACT_SUFX</varname>