Date: Fri, 14 Dec 2012 14:11:54 GMT From: Matthew Rezny <mrezny@hexaneinc.com> To: freebsd-gnats-submit@FreeBSD.org Subject: ports/174435: Port options are often insufficiently detailed due to field constraints Message-ID: <201212141411.qBEEBs3R052902@red.freebsd.org> Resent-Message-ID: <201212141420.qBEEK0nF056964@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>Number: 174435 >Category: ports >Synopsis: Port options are often insufficiently detailed due to field constraints >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-ports-bugs >State: open >Quarter: >Keywords: >Date-Required: >Class: change-request >Submitter-Id: current-users >Arrival-Date: Fri Dec 14 14:20:00 UTC 2012 >Closed-Date: >Last-Modified: >Originator: Matthew Rezny >Release: 9.1-PRERELEASE >Organization: RezTek, s.r.o. >Environment: >Description: Ports which have options display a screen to select said options at the start of the build process. The screen which displays these options has limited room for descriptive text. This leads too often to situations where that information is insufficient to make an intelligent decision about the port's options. Some are rather obvious, for example if I'm building VLC and I see PulseAudio as option I know that enabling that allows VLC to use PA for audio output. Unfortunately, this is not the common case. Simply stating what the library is or does often does not clearly indicate the impact on the port. I will use Subversion as an example based on the questions I've seen raised on the mailing lists in regards to it. I happen to know all these options, but for a moment I'll pretend to be a typical user who knows nothing of svn other than he needs it to replace csup for source/ports updates. BDB=off: Berkeley Database OK, I know what BDB is but what does this mean to svn? BOOK=off: Install the Subversion Book OK, sounds good ENHANCED_KEYWORD=on: Enhanced svn:keyword support what does this mean to me? FREEBSD_TEMPLATE=on: FreeBSD Project log template do I need this to use on freebsd? GNOME_KEYRING=off: Build with GNOME Keyring auth support not needed for ana KDE_KWALLET=off: Build with KDE KWallet auth support not needed for anon MAINTAINER_DEBUG=off: Build debug version not me MOD_DAV_SVN=off: mod_dav_svn module for Apache 2.X I guess I don't need this for checkout b/c why would I have Apache involved... MOD_DONTDOTHAT=off: mod_dontdothat for Apache 2.X well, dn't need this without that other NEON=on: WebDAV/Delta-V repo access module (neon) huh? I just want to check out, this sound like Apache related stuff, maybe server, maybe I'll turn this off... (tell me not to shoot myself in the foot here) P4_STYLE_MARKERS=on: Perforce-style conflict markers huh? off SASL=off: SASL support that's auth right? i just want anon checkout... SERF=off: WebDAV/Delta-V repo access module (serf) uhh.. how is this different than the option two up that looks exactly the same? neon and serf do what now and differ how? (tell me to keep at least one of these, but please also tell me why to choose one b/c I really don't know what material difference this makes as a user of svn for nearly a decade) STATIC=off: Build static version (no shared libs) don't need that SVNAUTHZ_VALIDATE=off: install svnauthz-validate just want anon, not needed I guess, not sure SVNMUCC=off: Install Multiple URL Command Client sounds interesting but what's it do? SVNSERVE_WRAPPER=off: Enable svnserve wrapper do I need this to checkout? TEST=off: Run subversion test suite not for me Given that sea of options, it's no surprise people are posting to the mailing list asking why svn can't checkout when they have neon and serf disabled. I first thought not to pick on any port in particular, but decided an example would be worth the risk of annoying someone, so I preemptively apologize to svn maintainer for criticizing the option descriptions. >How-To-Repeat: Build a port you are not familiar with, then read the Makefile to see what flags those options set, then wonder why you are searching the internet for explanations of those flags. >Fix: The fix is to have a help screen that describes the options. We have some precedent for such a thing from sysinstall. It seemed a surprise to me that port options did not have the same help screen. I had grown accustomed to that but recently had the thought that this should change. I propose a simple help screen system that ports can opt into as the maintainers choose. Similar to the pkg-descr file, a port shall optionally provide an optn-descr file. If this file is present, then when the options screen is display, the contents shall be shown upon the user pressing F1 (or other sensible choice of help key). The display should use most of the screen and have provision to scroll vertically if necessary. The text should be a well worded description of what these options mean, preferably grouped by relation. I specifically propose one collective help screen per port and not a longer per-option description as I think it put more burner on both sides to split it up (the user must choose to view the help for each, the author must write them all out separately and risk repeating information for related option). Here is a (partial) example optn-descr for subversion: The Subversion port covers both client and server options. You do not need to enable server option to use subversion client. Client options: The options ENHANCED_KEYWORD, FREEBSD_TEMPLATE, and P4_STYLE_MARKERS are FreeBSD specific extensions to svn. If you will be using svn to checkout src or ports, you should enable these options. The BOOK option will install a local copy of documentation for offline access. The book is available online for reference. At least one of the options NEON and SERF must be chosen to have a functional client. Both may be chosen together. [Describe why I might want one or the other here if possible.] You should choose the SASL option if you want to use non-Anonymous repos. Additionally, you may want to use the GNOME_KEYRING or KDE_WALLET option to allow your desktop password manager to handle your svn logins. The option SVNMUCC enables an additional client command which eases the ability to coalesce multiple cp and mv actions into a single commit. Server options: Subversion has multiple formats in which the repository may be stored. The current default and recommended storage is FS-FS. Early versions defaulted to BDB storage which is not recommended. If you need to serve a repo with BDB storage, then you must enable the BDB option. Subversion can serve clients through multiple protocols. By default, clients may be served with svn:// protocol. The MOD_DAV_SVN option will enable support for serving clients with http:// protocol. [Describe MOD_DONTDOTHAT as in relation to the former.] [Describe SVNAUTHZ_VALIDATE] [Describe SVNSERVE_WRAPPER] Additional options: The STATIC option may be used to create a version in which all dependent libraries are statically linked rather than dynamically linked. In most cases you do not want this. The MAINTAINER_DEBUG and TEST options are development options that you may find useful if you are making changed to Subversion itself. If you have local patches, you should enable TEST. >Release-Note: >Audit-Trail: >Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201212141411.qBEEBs3R052902>