Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add GitHub portgroup #12

Merged
merged 1 commit into from Mar 1, 2018
Merged

Add GitHub portgroup #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
3 changes: 3 additions & 0 deletions guide/xml/portfileref.xml
View file
Open in desktop
Expand Up @@ -38,6 +38,9 @@
<xi:include href="portgroups.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />

<xi:include href="portgroup-github.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />

<xi:include href="portgroup-gnustep.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />

Expand Down
198 changes: 198 additions & 0 deletions guide/xml/portgroup-github.xml
View file
Open in desktop
@@ -0,0 +1,198 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V5.0//EN"
"http://docbook.org/xml/5.0/dtd/docbook.dtd">
<section xml:id="reference.portgroup.github">

<title>PortGroup github</title>

<para>The <code>github</code> portgroup allows for efficient porting of
software hosted on GitHub.</para>

<section xml:id="reference.portgroup.github.description">
<title>Description</title>

<para>
This portgroup greatly simplifies the porting of software hosted on
GitHub. Provided a GitHub repository author follows common GitHub
practices, a port can be almost fully configured simply by declaring the
repository coordinates. The <code>github</code> portgroup is indeed
capable of configuring, amongst other things:

<itemizedlist>
<listitem>
<para>The port <code>name</code>.</para>
</listitem>
<listitem>
<para>The port <code>version</code>.</para>
</listitem>
<listitem>
<para>The <code>distfiles</code> (if the project uses GitHub
releases).</para>
</listitem>
<listitem>
<para>The <code>livecheck</code> parameters.</para>
</listitem>
</itemizedlist>
</para>
</section>

<section xml:id="reference.portgroup.github.setup">
<title>Setting up the GitHub repository coordinates</title>

<para>
The main port configuration is triggered by the usage of the
<code>github.setup</code> keyword:

<programlisting>
PortGroup github 1.0
github.setup author project version [tag_prefix]</programlisting>
</para>

<para>
By default, the port <code>name</code> will be set to the GitHub project
name (<code>project</code>) and <code>version</code> will be set to the
GitHub project <code>version</code>. The port name can be overridden by
using the <code>name</code> keyword.
</para>

<para>
The <code>tag_prefix</code> is optional, and it's used to specify a prefix
to use when constructing the tag name. If, for example, the project uses
tags such as <code>v1.0.0</code>, then the <code>tag_prefix</code> should
be set to <code>v</code>, as in the following example:

<programlisting>
github.setup author project version v</programlisting>
</para>
</section>

<section xml:id="reference.portgroup.github.distfilestrategy">
<title>Choosing a distfile strategy</title>

<para>
GitHub, and as a consequence the <code>github</code> portgroup, offers
multiple mechanisms to get a distfile:

<itemizedlist>
<listitem>
<para>Distfile from a <code>git</code> commit or tag.</para>
</listitem>
<listitem>
<para>
Distfile from a GitHub <link
xlink:href="https://github.com/blog/1547-release-your-software">release</link>.
</para>
</listitem>
<listitem>
<para>
Distfile from a GitHub <link
xlink:href="https://github.com/blog/1302-goodbye-uploads">download</link>.
</para>
</listitem>
</itemizedlist>
</para>

<para>
The default behaviour of the portgroup is using GitHub automatically
generated distfile from a <code>git</code> commit or tag. However, the
best practice should be using a GitHub release.
</para>
</section>

<section xml:id="reference.portgroup.github.distfile">
<title>Distfile from tag or commit</title>

<para>
The default behaviour of the <code>github</code> portgroup is leveraging
GitHub's ability to create a distfile from a <code>git</code> tag or
commit. In this case, the <code>distname</code> is irrelevant and should
not be set.
</para>

<para>
If the project's developers do not tag their releases, they should be
encouraged to do so. Until they do, or in the case in which an untagged
development version has to be used, port maintainers have the possibility
of specifying a <code>git</code> commit hash and manually set the
<code>version</code> field. If the project does not assign version
numbers the port maintainer has to define one. Such versions typically
format the date of the chosen commit using the <code>YYYYMMDD</code>
pattern. If, for example, the port maintainer decides to use a changeset
with the hash <code>0ff25277c3842598d919cd3c73d60768</code>, committed on
April 1, 2014, then the following would be used:

<programlisting>
github.setup someone someproject 0ff25277c3842598d919cd3c73d60768
version 20140401</programlisting>
</para>
</section>

<section xml:id="reference.portgroup.github.releases">
<title>Distfile from a GitHub release</title>

<para>
The <code>github</code> portgroup allows maintainers to easily configure
the distfiles when the project uses GitHub releases. A release is the
best distfile candidate, and project maintainers should be encouraged to
use them. To enable this feature, the following keyword must be used:

<programlisting>
github.tarball_from releases</programlisting>

By default, the <code>github</code> portgroup sets <code>distname</code>
to:

<programlisting>
distname ${github.project}-${github.version}</programlisting>

However, GitHub does not enforce any rule for release distfiles, so port
maintainers may need to override the <code>distname</code> as they would
do for other ports.
</para>
</section>

<section xml:id="reference.portgroup.github.downloads">
<title>Distfile from a GitHub download</title>

<para>
Older projects use the discontinued <link
xlink:href="https://github.com/blog/1302-goodbye-uploads">downloads</link>
service. New GitHub downloads can no longer be created, but old ones are
still available.
</para>

<para>
If the project doesn't have GitHub releases but does have GitHub
downloads, they can be used using the following keyword:

<programlisting>
github.tarball_from downloads</programlisting>

Since GitHub doesn't enforce any naming rules for downloads, the portgroup
can only provide a sensible default value for <code>distname</code>, which
can be overridden if necessary.
</para>
</section>

<section xml:id="reference.portgroup.github.submodule">
<title>Using repositories with git submodules</title>

<para>
If the project uses <code>git</code> submodules, some projects' tag- or
commit-based distfiles will not contain all the necessary files. Once
again, the best distfile candidate (if available) is a distfile from
GitHub releases, as described in the previous sections. However, in the
case a project doesn't provide any other alternative, a project using
submodules can be successfully retrieved by fetching the sources using
<code>git</code> and then using a <code>post-fetch</code> to initialize
the submodules:

<programlisting>
fetch.type git

post-fetch {
system -W ${worksrcpath} "git submodule update --init"
}</programlisting>
</para>
</section>
</section>
30 changes: 18 additions & 12 deletions guide/xml/portgroups.xml
View file
Open in desktop
Expand Up @@ -10,27 +10,33 @@
group of portfiles, in order that those portfiles can be expressed as simply as possible with
minimum redundancy.</para>

<para>See the following folder for PortGroup definitions:</para>
<para>See the following folder for PortGroup definitions:</para>
<para>
<filename>${prefix}/var/macports/sources/rsync.macports.org/release/tarballs/ports/_resources/port1.0/group/</filename>
</para>

<para>A sample listing follows:</para>
<para>
<programlisting><prompt>%%</prompt> <userinput>ls -1 /opt/local/var/macports/sources/rsync.macports.org/release/tarballs/ports/_resources/port1.0/group/</userinput></programlisting>
<programlisting><prompt>%%</prompt> <userinput>ls -1 /opt/local/var/macports/sources/rsync.macports.org/macports/release/tarballs/ports/_resources/port1.0/group/</userinput></programlisting>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI, that wasn't a typo, but it was an old value and you're right to change it as you did.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks.


<screen>archcheck-1.0.tcl
<screen>active_variants-1.1.tcl
apache2-1.0.tcl
app-1.0.tcl
archcheck-1.0.tcl
bitbucket-1.0.tcl
cmake-1.0.tcl
cmake-1.1.tcl
compiler_blacklist_versions-1.0.tcl
compilers-1.0.tcl
conflicts_build-1.0.tcl
crossbinutils-1.0.tcl
gnustep-1.0.tcl
haskell-1.0.tcl
hocbinding-1.0.tcl
hunspelldict-1.0.tcl
kde4-1.0.tcl
kde4-1.1.tcl
.
.
.</screen>
crossgcc-1.0.tcl
cxx11-1.0.tcl
cxx11-1.1.tcl
debug-1.0.tcl
elisp-1.0.tcl
github-1.0.tcl
...</screen>
</para>

<para>The requirements of a minimum portfile using a portgroup varies by portgroup.
Expand Down