From owner-svn-doc-all@freebsd.org Sat Mar 3 07:03:11 2018 Return-Path: Delivered-To: svn-doc-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 31B24F456E0; Sat, 3 Mar 2018 07:03:11 +0000 (UTC) (envelope-from ultima@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id C2F8171BD1; Sat, 3 Mar 2018 07:03:10 +0000 (UTC) (envelope-from ultima@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id B7FFE22FEB; Sat, 3 Mar 2018 07:03:10 +0000 (UTC) (envelope-from ultima@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id w2373ARw024184; Sat, 3 Mar 2018 07:03:10 GMT (envelope-from ultima@FreeBSD.org) Received: (from ultima@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id w2373AgM024183; Sat, 3 Mar 2018 07:03:10 GMT (envelope-from ultima@FreeBSD.org) Message-Id: <201803030703.w2373AgM024183@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: ultima set sender to ultima@FreeBSD.org using -f From: Richard Gallamore Date: Sat, 3 Mar 2018 07:03:10 +0000 (UTC) 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 X-SVN-Group: doc-head X-SVN-Commit-Author: ultima X-SVN-Commit-Paths: head/en_US.ISO8859-1/books/porters-handbook/makefiles X-SVN-Commit-Revision: 51456 X-SVN-Commit-Repository: doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.25 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 03 Mar 2018 07:03:11 -0000 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 + + <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 use and might + need to be set. + + + <varname>USE_GITLAB</varname> Description + + + + + Variable + Description + Default + + + + + + GL_SITE + Site name hosting the GitLab + project https://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>