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 @@ -1982,13 +1982,28 @@ + GH_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) + + + GH_TUPLE GH_TUPLE allows putting all the GH_ACCOUNT, - GH_PROJECT, and - GH_TAGNAME into one variable. The + GH_PROJECT, + GH_TAGNAME, and + GH_SUBDIR into one variable. The format is - account:project:tagname:group. + account:project:tagname:group/subdir. + The + /subdir + part is optional. It is helpful when there is more than one GitHub project from which to fetch. @@ -2132,11 +2147,9 @@ GH_ACCOUNT= bar:icons,contrib GH_PROJECT= foo-icons:icons foo-contrib:contrib GH_TAGNAME= 1.0:icons fa579bc:contrib +GH_SUBDIR= ext/icons:icons -CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib} - -post-extract: - @${MV} ${WRKSRC_icons} ${WRKSRC}/icons +CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib} This will fetch three distribution files from github. The default one comes from @@ -2165,6 +2178,16 @@ with the contrib tag is called ${WRKSRC_contrib} and contains ${WRKDIR}/foo-contrib-fa579bc. + + The software's build system expects to find the icons + in an ext/icons subdirectory in its + sources, so GH_SUBDIR is used. What it + basically does, after making sure + ext/icons does not exist, and that + ext exists, is this: + + post-extract: + @${MV} ${WRKSRC_icons} ${WRKSRC}/ext/icons @@ -2180,19 +2203,118 @@ PORTVERSION= 1.0.2 USE_GITHUB= yes -GH_TUPLE= bar:foo-icons:1.0:icons \ +GH_TUPLE= bar:foo-icons:1.0:icons/ext/icons \ bar:foo-contrib:fa579bc:contrib -CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib} - -post-extract: - @${MV} ${WRKSRC_icons} ${WRKSRC}/icons +CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib} Grouping was used in the previous example with bar:icons,contrib. Some redundant information is present with GH_TUPLE because grouping is not possible. + + + How to Use <varname>USE_GITHUB</varname> with + <application>Git</application> Submodules? + + When dealing with GitHub as an upstream, it sometimes + happens that the repository uses submodules. See + &man.git-submodule.1; for more information on what + submodules are. + + The problem with submodules is that each is a separate + repository. As such, they each need to be fetched + separately. + + Using finance/moneymanagerex as an + example, its GitHub repository is . + It has a .gitmodules + file at the root of it, it is the file describing all the + submodules used in this repository. This file will tell + what additional repositories are needed: + + [submodule "lib/wxsqlite3"] + path = lib/wxsqlite3 + url = https://github.com/utelle/wxsqlite3.git +[submodule "3rd/mongoose"] + path = 3rd/mongoose + url = https://github.com/cesanta/mongoose.git +[submodule "3rd/LuaGlue"] + path = 3rd/LuaGlue + url = https://github.com/moneymanagerex/LuaGlue.git +[submodule "3rd/cgitemplate"] + path = 3rd/cgitemplate + url = https://github.com/moneymanagerex/html-template.git +[...] + + The only information missing from that file is the + commit hash or tag to use as a version. This information + is found after cloning the repository: + + &prompt.user; git clone --recurse-submodules https://github.com/moneymanagerex/moneymanagerex.git +Cloning into 'moneymanagerex'... +remote: Counting objects: 32387, done. +[...] +Submodule '3rd/LuaGlue' (https://github.com/moneymanagerex/LuaGlue.git) registered for path '3rd/LuaGlue' +Submodule '3rd/cgitemplate' (https://github.com/moneymanagerex/html-template.git) registered for path '3rd/cgitemplate' +Submodule '3rd/mongoose' (https://github.com/cesanta/mongoose.git) registered for path '3rd/mongoose' +Submodule 'lib/wxsqlite3' (https://github.com/utelle/wxsqlite3.git) registered for path 'lib/wxsqlite3' +[...] +Cloning into '/home/mat/work/freebsd/ports/finance/moneymanagerex/moneymanagerex/3rd/LuaGlue'... +Cloning into '/home/mat/work/freebsd/ports/finance/moneymanagerex/moneymanagerex/3rd/cgitemplate'... +Cloning into '/home/mat/work/freebsd/ports/finance/moneymanagerex/moneymanagerex/3rd/mongoose'... +Cloning into '/home/mat/work/freebsd/ports/finance/moneymanagerex/moneymanagerex/lib/wxsqlite3'... +[...] +Submodule path '3rd/LuaGlue': checked out 'c51d11a247ee4d1e9817dfa2a8da8d9e2f97ae3b' +Submodule path '3rd/cgitemplate': checked out 'cd434eeeb35904ebcd3d718ba29c281a649b192c' +Submodule path '3rd/mongoose': checked out '2140e5992ab9a3a9a34ce9a281abf57f00f95cda' +Submodule path 'lib/wxsqlite3': checked out 'fb66eb230d8aed21dec273b38c7c054dcb7d6b51' +[...] +&prompt.user; cd moneymanagerex +&prompt.user; git submodule status + c51d11a247ee4d1e9817dfa2a8da8d9e2f97ae3b 3rd/LuaGlue (heads/master) + cd434eeeb35904ebcd3d718ba29c281a649b192c 3rd/cgitemplate (cd434ee) + 2140e5992ab9a3a9a34ce9a281abf57f00f95cda 3rd/mongoose (6.2-138-g2140e59) + fb66eb230d8aed21dec273b38c7c054dcb7d6b51 lib/wxsqlite3 (v3.4.0) +[...] + + It can also be found on GitHub, each subdirectory that + is in fact a submodule is shown as + directory @ hash, + for example, + mongoose @ 2140e59. + + + While getting the information from GitHub seems more + straightforward, the information found using + git submodule status will get more + meaningful information, for example, here, + lib/wxsqlite3's commit hash + fb66eb2 correspond to + v3.4.0. Both can be used + interchangeably, but when a tag is available, it is + always better to use it. + + + Now that all the required information have been + gathered, the Makefile can be written + (only showing the GitHub related lines): + + PORTNAME= moneymanagerex +PORTVERSION= 1.3.0 +DISTVERSIONPREFIX= v + +USE_GITHUB= yes +GH_TUPLE= utelle:wxsqlite3:v3.4.0:wxsqlite3/lib/wxsqlite3 \ + moneymanagerex:LuaGlue:c51d11a:lua_glue/3rd/LuaGlue \ + moneymanagerex:html-template:cd434ee:html_template/3rd/cgitemplate \ + cesanta:mongoose:2140e59:mongoose/3rd/mongoose \ + [...] + Index: share/xml/man-refs.ent =================================================================== --- share/xml/man-refs.ent +++ share/xml/man-refs.ent @@ -257,6 +257,7 @@ getfacl1"> getopt1"> getopts1"> +git-submodule1"> glob1"> gnu-ar1"> gnu-ranlib1">