Suddenly STAGE appeared

[Michael Gmelin]

On Fri, 04 Oct 2013 11:03:29 -0500
Paul Schmehl <pschmehl_lists at tx.rr.com> wrote:

> --On October 4, 2013 4:35:57 PM +0200 Michael Gmelin
> <freebsd at grem.de> wrote:
> 
> > On Fri, 04 Oct 2013 09:22:25 -0500
> > Paul Schmehl <pschmehl_lists at tx.rr.com> wrote:
> >
> >> Or did I miss the announcement?
> >>
> >> Is there a doc that explains STAGE and how to convert a port to the
> >> new system?  Why STAGE was created?  What it's purpose is?
> >>
> >> This is all very new to me, and I have 23 ports to worry about.
> >>
> >
> >
> > See
> > http://lists.freebsd.org/pipermail/freebsd-ports-announce/2013-October/00
> > 0067.html
> >
> > and the discussion here
> > http://lists.freebsd.org/pipermail/freebsd-ports/2013-October/086346.html
> 
> Now it make sense.  I have a port that is failing to build on 10.0
> because of CLANG.  I don't have a 10.0 install, and it builds fine
> with GCC.  So I updated the port to use USE_GCC= yes, and I was asked
> to convert the port to use STAGE.  Left me scratching my head,
> because this was all before the announcement.
> 
> And I'm having problems building the port now - and wondering if I
> should just abandon my ports because the new system is confusing to
> me.  All this transitional stuff is a lot to grasp when you've been
> building ports successfully for a while and suddenly nothing works.
> 
> For example, make makeplist doesn't actually make a pkg-plist file on
> my system.
> 
> # make makeplist
> bin/sancp
> etc/rc.d/sancp
> etc/sancp.conf.dist
> 
> But no pkg-plist file is created.
> 
> WTH???
> 
> DOCS no longer build properly, and I have no clue why?
> 
> # make install
> ===>  Building package for sancp-1.6.1_5
> Creating package 
> /usr/ports/security/sancp-update/sancp/work/sancp-1.6.1_5.tbz
> Registering depends:.
> Creating bzip'd tar ball in 
> '/usr/ports/security/sancp-update/sancp/work/sancp-1.6.1_5.tbz'
> tar: share/doc/sancp/CHANGES: Cannot stat: No such file or directory
> tar: share/doc/sancp/INSTALL: Cannot stat: No such file or directory
> tar: share/doc/sancp/ISSUES: Cannot stat: No such file or directory
> tar: share/doc/sancp/README: Cannot stat: No such file or directory
> tar: share/doc/sancp/SETUP: Cannot stat: No such file or directory
> tar: share/doc/sancp/fields.LIST: Cannot stat: No such file or
> directory tar: Error exit delayed from previous errors.
> pkg_create: make_dist: tar command failed with code 256
> *** [do-package] Error code 1
> 
> Stop in /usr/ports/security/sancp-update/sancp.
> 
> The Makefile has this:
> PORTDOCS=	CHANGES INSTALL ISSUES \
> 		README SETUP fields.LIST
> 
> The docs are actually in ${WRKSRC}/doc, so I tried adding doc/ and 
> ${WRKSRC}/doc, but neither worked.  I tried adding
> %%PORTDOCS%%/docname to pkg-plist, but that failed as well.  So now
> I'm at a complete loss to know how to get the DOCS to work.
> 
> If you're going to make changes to the ports system and expect us 
> non-programmers to successfully grasp how all the changes get
> implemented, it would be very helpful to have a HOWTO page the
> explains the changes required in understandable detail.  The current
> page - <https://wiki.freebsd.org/ports/StageDir> - is rather cryptic
> and open to interpretation.
> 
> How do I list PORTDOCS so the build nows where to find them?
> Previously we used .if !${NOPORTDOCS} and told INSTALL to descend
> into the doc directory to fetch the docs.  Then we changed to .if
> ${OPTIONS:MDOCS} and did the same.  Now I"m told I don't need that
> section at all, but obviously, without out, the build can't figure
> out where the docs are so it fails.
> 
> All of this should be anticipated and documented BEFORE these changes
> are rolled out and we're required to implement them or you can expect
> lots of frustration and people dropping ports.
> 
> I get that you're trying to do things in a better, more robust way,
> but communication is key, and that communication has to be detailed
> and understandable so us dummies can implement it.
> 

I have to agree. I love the new features in the ports system, after
extreme stability (almost stagnation) for almost a decade and most of
these things make a lot of sense to me. Especially staging is a must
have feature and I'm happy we finally got that.

That said, it would be good if documentation could keep up to give
port maintainers a chance to convert their ports in a time efficient
and non-frustrating manner.

Not contributing any of this myself, I would suggest:

 1. For every change, have a conversion howto in the FreeBSD wiki
 2. Only roll out changes if they're covered in the English version of
    the Porter's Handbook

Cheers,
Michael

-- 
Michael Gmelin