I was pleasantly surprised to discover that, although a deceiving initial impression, setting up my first port file was way easier than I first believed. Furthermore, the MacPorts guys have been very supportive and provided many insights that helped me improve the port file and my understanding of the MacPorts port system (beyond what is described in the nice MacPorts Guide).
The Basic Portfile
The basic Portfile for a source tarball generated by the GNU Build System, that is a package which is built and installed with the now classic:$ ./configure
$ make
$ make install
is typically very simple, since these two operations are performed out of the box by the Configure, Build and Destroot phases of a port installation life cycle.
In this case, the basic Portfile includes:
- The modeline (optional).
- The Subversion ID tag: placeholder string automatically expanded by the MacPorts infrastructure.
- The PortSystem line: required by all ports.
- The port name and version: many other port variables (including the source tarball name) depend on these values.
- The category line: one or more port categories.
- The platform: darwin most of the times.
- The maintainers.
- The short and long description.
- The homepage.
- The download URLs.
- The checksums (used to verify the integrity of the downloaded files).
- The dependencies (optional).
- The configure arguments (optional).
A fully working, basic port is the following:
In this example you can see how the download URL is split in two pieces: the master_sites and the distfiles (or distnames). The rationale behind this choice is the fact that a package may typically be hosted by multiple master sites (such as mirrors).
In this example, distfiles is specified. This variable contains the full distribution file name, including the suffix (the file extension). By default this value is set to ${distname}${extract.suffix}. You may as well define the distname (which defaults to ${name}-${version}) and the extract.suffix separately. These parameters, in the example above, are redundant, since they simply set the corresponding default value (and use_zip is used as a shortcut to set extract.suffix and other variables related to processing zip files).
A Portfile for a GitHub-Hosted Project
fswatch, such as many other projects nowadays, is hosted at GitHub. Although not yet documented on the MacPorts Guide, a recently added PortGroup called github greatly simplifies the Portfile for such projects. The only existing documentation, at the moment, is this port group source code.Many of the aforementioned configuration variables are inferred by a much simpler GitHub configuration such as:
github.setup emcrisostomo fswatch 1.3.9
github.tarball_from releases
This expands to:
- name is set as the GitHub project name (fswatch in this case).
- version is set as the GitHub version tag (1.3.9 in this case).
- The download URL and the distribution file name is inferred from the repository configuration and the corresponding release URL. If the distribution file name is different than the default (${name}-${version}) then you still have to configure it as described in the previous section.
Checking Your Portfile
The port utility can check whether a Portfile conforms to the MacPorts guidelines using the lint command:$ port lint --nitpick fswatch
---> Verifying Portfile for fswatch
---> 0 errors and 0 warnings found.
In the example above the fswatch Portfile passes verification with no errors nor warnings. Be sure to check your Portfile before submitting it to the MacPorts repository.
Testing Your Portfile With a Local Repository
You can test and store your Portfiles in a local repository before submitting them to a public repository in a private repository. Furthermore, you can take advantage of the MacPorts package management features to maintain your own local packages.Adding a Portfile to a local repository is very simple:
- Create the local repository directory somewhere (if it does not exist).
- Create a subdirectory (if it does not exist) named after the primary category of the port you are adding.
- Create a subdirectory named after the port.
- Move the Portfile into this directory.
- Make sure the user macports has sufficient privileges to read the repository (I usually give him ownership of the port directory).
- Update the port repository indexes running portindex from the repository root.
If you have not done it yet, you have to configure MacPorts to use your local repository, adding a line in $MACPORTS_HOME/etc/macports/sources.conf:
file:///ports
right above any other repository so that ports in the local one take precedence over ports in the public repository.
If everything is setup correctly, you will be able to query and install ports from your local repository.
You're welcome Dilawar.
ReplyDelete