submitting a new port, sort of

Wed Jun 18 21:20:30 UTC 2025

Hello, Elwood Downey, and welcome to MacPorts-dev!

On 2025-06-17 21:20, Elwood Downey wrote:
> ...I skimmed your instructions for submitting a new port but 1) I do 
> not have and do not want a github account and 2) I am super lazy when 
> it comes to systemy things, I only enjoy programming.
>
> So on the outside chance someone else would be willing to do it all 
> for me, I hereby humbly submit my amateur radio program HamClock 
> <https://clearskyinstitute.com/ham/HamClock> for consideration as a 
> new port.
> ...[elided]...
> name                hamclock
> version             4.18
> categories          amateur radio
> platforms           darwin
> license             MIT
> maintainers         Elwood Downey, ecdowney at clearskyinstitute.com
> description         provides useful data for amateur radio operators
> long_description    HamClock is a kiosk-style application that 
> provides real time space weather, radio propagation models, operating 
> events and other information particularly useful to the radio amateur.
> homepage https://www.clearskyinstitute.com/ham/HamClock
> master_sites 
> https://www.clearskyinstitute.com/ham/HamClock/ESPHamClock.tgz

What a lovely project! HamClock appears to integrate a lot of useful 
data from many sources. I can imagine it being very valuable to the 
people for whom it is intended. It would be a fine port IMHO.

I took the liberty of doing a "systemy thing" for you: creating a 
Macports trac ticket #72625[1] requesting that a port be created for 
Hamclock. This doesn't commit me or anyone else to do the work, but it 
provides a starting point for anyone interested. It includes a link to 
this thread[2] in the macports-dev archives.

 From my limited experience writing ports, I can imagine five or so 
hurdles.

One, as Ryan said, HamClock's self-update function conflicts with a 
macports principle that ports don't modify themselves, only macports 
modifies ports.

Two, and related, there appears to be only URLs for the current version 
of the source code, while macports works better with repositories which 
offer URLs for each software version. So for HamClock that might be:

    https://www.clearskyinstitute.com/ham/HamClock/4.18/ESPHamClock.tgz

Normally, macports deal with target project version changes by having 
someone update the portfile and submit it to Macports. Each version of a 
portfile describes a specific version of the target project, and gives a 
specific URL for that verion of the target project's source code. When 
the target project releases a new version, someone notices and updates 
the portfile to specify the new version and the new download URL. They 
submit the new portfile to Macports. Eventually Macports users update 
their Portfile collection from Macports. Then the user's copy of 
Macports becomes aware of the new port version, and offers to perform 
the update.

Three, as Dave Allured points out, the portfile author needs to figure 
out what other libs HamClock depends on, and which ports supply those 
libs. These dependencies get recorded in the portfile.

Four, the HamClock top-level Makefile hard-codes some install paths and 
library paths. The portfile will need to patch these. That is a normal 
thing to do, and functions exist to do it, but it will be an extra task 
for the portfile author.

Five, HamClock can display graphics at various horizontal and vertical 
pixel sizes, and as a local display (via X11) or as a web service. The 
portfile can offer "variants" as a way to let the user choose these 
options at build time. The portfile author might choose to offer these 
variants, and tie them back to the Makefile targets. That is a further 
task.

Also, at the risk of distracting you with "systemy" things, might I 
suggest a few clarifications to the HamClock website[3]?

  * The download tab did not make it clear to me that it offered source
    code. I interpreted it as offering precompiled binaries. Consider
    adding a subheading "Source code" before the first line of the tab,
    and changing the following line "revision history" to be a subheading.
  * If you decide to have separate URLs to the various versions of the
    source code, then maybe you will want somewhere a list of versions,
    each with the download link for that version's source code.
  * The website doesn't make it clear that the project's code is freely
    licensed. Yes, the source code archive has a LICENSE file containing
    the MIT licence text, but that isn't visible before downloading.
    Consider having a tab "License", or a link from a relevant place
    like the source code link in the Download tab, pointing to the
    software license.
  * Do you seek contributions of bug fixes and patches with
    improvements?  If so, I would expect to see a tab reading "How to
    contribute" or the like. I don't see that.

Overall, HamClock looks like a lovely project. Thank you for proposing 
it to macports. I hope someone takes the offer and finishes the portfile.

Best regards,
     —Jim "VE7YJD" DeLaHunt

[1] hamclock: make a port for Hamclock project 
<https://trac.macports.org/ticket/72625>
[2] thread "submitting a new port, sort of" 
<https://lists.macports.org/pipermail/macports-dev/2025-June/046320.html>
[3] <https://www.clearskyinstitute.com/ham/HamClock/>

-- 
.   --Jim DeLaHunt,jdlh at jdlh.com     http://blog.jdlh.com/ (http://jdlh.com/)
       multilingual websites consultant, Vancouver, B.C., Canada
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macports.org/pipermail/macports-dev/attachments/20250618/3f74b04d/attachment.htm>