Solved make.conf for poudriere: confusion

<https://www.freshports.org/deskutils/recoll#config> for 1.27.3_16 includes:

X11MON=off

Re: <https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=259679> I performed the patch, then added this line:

X11MON=on += deskutils/recoll

– to my /usr/local/etc/poudriere.d/make.conf.

Built, packaged, installed, X11MON is off:

Code:
% pkg info recoll
recoll-1.31.2
Name           : recoll
Version        : 1.31.2
Installed on   : Sun Nov  7 07:31:30 2021 GMT
Origin         : deskutils/recoll
Architecture   : FreeBSD:14:amd64
Prefix         : /usr/local
Categories     : deskutils
Licenses       : GPLv2+
Maintainer     : jjuanino@…
WWW            : https://www.lesbonscomptes.com/recoll/
Comment        : Personal full text search package, based on Xapian
Options        :
        ASPELL         : on
        CHM            : on
        DJVU           : off
        IMAGE          : on
        LATEX          : off
        PDF            : on
        PS             : on
        QT5            : on
        SOUND          : on
        X11MON         : off
…

What am I doing wrong?

Code:
% pkg info -x poudriere
poudriere-devel-3.3.99.20211017_2
%
 
This alternative works for any make variable you want to set specifically for one port. But don't use it to set options any more, as this is directly supported by the <category>_<port>_(UN)?SET variables, which is much more readable.
 
Also, I can't make sense of parts of the manual page for poudriere-options(8).

In the synopsis, what's meant by this?

[poudriere-options]

<https://github.com/freebsd/poudriere/wiki/poudriere-options.8#SYNOPSIS> | <https://www.freebsd.org/cgi/man.cgi?query=poudriere-options&sektion=8&manpath=Ports#SYNOPSIS>

I mean, what (for example) would one enter in its place?



Does this 2013 topic help?

 
Partly related, I probably subscribed a few weeks or months ago:

Allow use of portconf style port configuration files; ease transition of live builds to package building for users · Issue #835 · freebsd/poudriere

… (I never used ports-mgmt/portconf, and so on.) … Note to self: make.conf(5) uses the standard makefile syntax.

If I need to learn more about standard makefile syntax, is <https://en.wikipedia.org/wiki/Make_(software)#Makefile> a reasonable starting point? Or better to begin with one of the resources under <https://en.wikipedia.org/wiki/Make_(software)#External_links>?

(I'm not a developer; documentation that assumes developer expertise will be lost on me.)



From the 2013 topic:

… characteristics of OptionsNg, …

Google found <https://wiki.freebsd.org/Ports/Options/OptionsNG> … deprecated in 2014, there's direction to part of the FreeBSD Porter's Handbook.

(I'm no more a porter than I am a developer. I see a wall of text.)

Does anything in Chapter 5 stray from standard makefile syntax?
 
Last edited:

This is understandable enough:

Code:
root@mowa219-gjp4-8570p-freebsd:~ # poudriere options -s -n deskutils/recoll
[00:00:00] Working on options directory /usr/local/etc/poudriere.d/options
[00:00:00] Appending to make.conf: /usr/local/etc/poudriere.d/make.conf
===> The following configuration options are available for recoll-1.31.2:
     ASPELL=on: Spell checking support via GNU Aspell
     CHM=on: Python bindings for Microsoft ITSS/CHM format
     DJVU=off: DjVu document support
     IMAGE=on: Store personal tags or textual descriptions in images
     LATEX=off: LaTeX support
     PDF=on: PDF document support
     PS=on: PostScript document support
     QT5=on: Qt 5 toolkit support
     SOUND=on: Sound (audio) support
     X11MON=off: X11 session monitoring support
===> Use 'make config' to modify these settings
root@mowa219-gjp4-8570p-freebsd:~ #
  • I know to not run make config
  • (and there is no append to make.conf)
– instead, I can/should use poudriere-options(8) to set what's required.

PEBKAM: I can not figure out how to use -n when setting instead of showing, so I choose to abort (Control-C) when there appears a succession of dialogues:
  • what's required in the opening post is X11MON=on – nothing more
Then, housekeeping:

Code:
ot@mowa219-gjp4-8570p-freebsd:~ # ls -hl /usr/local/etc/poudriere.d/options
total 2
drwxr-xr-x  2 root  wheel     3B Nov  7 13:17 deskutils_recoll
drwxr-xr-x  2 root  wheel     2B Nov  7 13:17 lang_python38
drwxr-xr-x  2 root  wheel     2B Nov  7 13:17 ports-mgmt_pkg
root@mowa219-gjp4-8570p-freebsd:~ # rm -r /usr/local/etc/poudriere.d/options/*
root@mowa219-gjp4-8570p-freebsd:~ #

If I abort quickly enough, I can get this (before housekeeping):

Code:
…
===> Setting user-specified options for recoll-1.31.2 and dependencies
^C*** Signal 2
[00:00:07] Error: Signal SIGINT caught, cleaning up and exiting
root@mowa219-gjp4-8570p-freebsd:~ # ls -hl /usr/local/etc/poudriere.d/options
total 1
drwxr-xr-x  2 root  wheel     3B Nov  8 02:01 deskutils_recoll
root@mowa219-gjp4-8570p-freebsd:~ # cat /usr/local/etc/poudriere.d/options/deskutils_recoll/options
# This file is auto-generated by 'make config'.
# Options for recoll-1.31.2
_OPTIONS_READ=recoll-1.31.2
_FILE_COMPLETE_OPTIONS_LIST=ASPELL CHM DJVU IMAGE LATEX PDF PS QT5 SOUND X11MON
OPTIONS_FILE_SET+=ASPELL
OPTIONS_FILE_SET+=CHM
OPTIONS_FILE_UNSET+=DJVU
OPTIONS_FILE_SET+=IMAGE
OPTIONS_FILE_UNSET+=LATEX
OPTIONS_FILE_SET+=PDF
OPTIONS_FILE_SET+=PS
OPTIONS_FILE_SET+=QT5
OPTIONS_FILE_SET+=SOUND
OPTIONS_FILE_SET+=X11MON
root@mowa219-gjp4-8570p-freebsd:~ #



Back to the opening post:

my /usr/local/etc/poudriere.d/make.conf

I'd like to use that file (instead of /usr/local/etc/poudriere.d/options/deskutils_recoll/options).

Is OPTIONS_FILE_SET+=X11MON suitable, standard syntax for part of what must be written to the make.conf?
 
man just read my post and do it like that. You're writing walls of text about something dead simple...
 
PEBKAM: I can not figure out how to use -n when setting instead of showing,

– and:

In the synopsis, what's meant by this?

[poudriere-options]

– can anyone help with either of those things? Thanks.

The synopses at <https://www.freebsd.org/cgi/man.cgi?query=poudriere-options&sektion=8&manpath=Ports#SYNOPSIS> look quite different from the synopsis that appears in response to poudriere options.

That syntax looks odd

I can't recall where it was learnt/taught.

My code comment in <https://forums.freebsd.org/posts/519207> reminded me of a license-oriented example from a few months ago, <https://forums.freebsd.org/posts/517869>, thanks rigoletto@ I'm probably on the right track now for part of this topic.



Honestly, I'm parroting stuff into configuration files without properly understanding the reasons for syntaxes being as they are :) … the dyslexic side of me will probably never clear the mental block that began after trying to make sense of <https://docs.freebsd.org/doc/12.1-R...reebsd/en/books/handbook/ports-poudriere.html> or however it was written at the time (I knew nothing about jails).
 
PEBKAM: I can not figure out how to use -n when setting instead of showing, so I choose to abort (Control-C) when there appears a succession of dialogues:
I'm not sure I understand the question, but here goes anyway. Have you tried poudriere options -ns ...?

In the synopsis, what's meant by this?
[poudriere-options]

I mean, what (for example) would one enter in its place?
This is a standard man page-style command description. It's formatted strangely on Github. The online man page for poudriere-options(8) is much clearer. The fact that you're specifying options for an options command probably adds a little to the confusion, too.

The poudriere(8) command itself takes options. E.g. "-A Force color support, even if not in a TTY."

Then the poudriere-options(8) command also takes options. E.g. "-s Show port options instead of configuring them".

So you could conceivably want to run something like this if you hate colorized output like I do poudriere -N options -ns deskutils/recoll.
 
Where did you find this weird syntax?

To configure port options in make.conf, use <category>_<port>_SET and <category>_<port>_UNSET.

Here: deskutils_recoll_SET += X11MON.
I've seen both styles used in make.conf... and I have to say, the first one makes a LOT more sense. The second one looks like it was borrowed from /var/db/ports (where the per-port options get saved).
 
It makes no sense at all, as make.conf is just included by make. how should you ever sensibly evaluate a variable called X11MON defined to a value of on += deskutils/recoll with make? No, I really wonder where this idea is coming from. It doesn't work (no surprise!) for sure.
 
Also, I can't make sense of parts of the manual page for poudriere-options(8).

In the synopsis, what's meant by this?

[poudriere-options]
I find it confusing as well.

[...] So you could conceivably want to run something like this if you hate colorized output like I do poudriere -N options -ns deskutils/recoll.


Poudriere-man-8.png


Poudriere-OPTIONS-man-8.png


At poudriere-options(8) there is a part that is mentioned in the section SYNOPSIS: [poudriere-options] but, it is not described in that man-page (see ?-1, in the image above of poudriere-options(8)).

Also, you have to realise that at the SYNOPSIS section of poudriere-options(8) the string options is not a placeholder but an actual string that has to be typed in literally. This is because poudriere-options(8) is an incarnation of the general poudriere(8) format for one specific command, namely the options command as specified at poudriere(8) in its SYNOPSIS section by the placeholder command. Compare that with pkg(8), there the placeholder in the SYNOPSIS section is designated in a much cleaner way by:
<command>

IMO, it can also be unclear that in the NAME section of poudriere-options(8) the following string is written as:
poudriere-options This is not the actual command that is to be typed in. Compare for example:
  1. man(1)
  2. ls(1)
  3. pkg(8)
Because of the (complex) syntax of poudriere(8), its man-pages are split into several man-pages and you have to use a unique name for a man-page; however, this gives rise to ?-2 ambiguity in the image of poudriere-options(8) above. pkg(8) faces similar difficulties and is also split up. That might have something to do with the naming conventions or limitations of man-pages.

Firstly, however, note that with pkg(8) there is a subtle but significant difference. pkg(8) is also split up into seperate man-pages, for example for the incarnation pkg‑info(8) (as mentioned in the SEE ALSO section of pkg(8)). The man-page of pkg‑info(8) is tagged by the string "pkg-info" but, at the NAME section of pkg‑info(8) it correctly uses the string pkg info (note: no dash between the two words), which string (=pkg info) is also used in that exact same way in all other sections.

Secondly, compare with pkg-static at the NAME section of pkg(8) as an alternative name. pkg-static functions as an exact synonym of pkg. Here the dash between the two words is mandatory.

At the SYNOPSIS section of poudriere(8) there is a part poudriere-options These options are not described by a similar name in subsequent sections. They appear to be described in the section GLOBAL OPTIONS (see ?-3, in the image of poudriere(8) above). If this is the case, why are are such different terms used to indicate the same item?

If I understand Jose's description correctly, at poudriere-options(8) in the section SYNOPSIS the string [poudriere-options] (note: the presence of the two "[" & "]") is not described in poudriere-options(8) but is described in the section GLOBAL OPTIONS of poudriere(8). If this is indeed the case, I do not find that self-evident. The name change into "GLOBAL OPTIONS" does not help. I have not seen any other man-pages where you have to cross reference to find a description of a certain item for which there is not an expliciet cross-reference present. I may be wrong; if so, I'd appreciate examples where that is the case.

It seems that the use of the word argument(s) of a command is not in line with the usage elsewhere in man-pages. With the command poudriere of poudriere(8) the first (optional) argument is [poudriere-options]. The second argument is command. In the COMMANDS section of poudriere(8) this is described as:
The first argument to poudriere must be a command from the following list:
This could be reworded as:
<command> must be one of the following list:

This also begs the question if, instead of the command/argument options, something like useopts or portoptions would not have been a more apropriate term, not clashing with the terminology option(s) used pervasively in man-pages.


Perhaps this (differences highlighted) is clearer:

ALT-poudriere.png


ALT-options.png
 
Last edited:
… see ?-3, in the image …

That single red arrow beneath the heading POUDRIERE(8) was enough for an immediate, at-a-glance realisation. Big thanks.

With one less source of confusion (word blindness ending), other things began falling into place.

… PEBKAM: I can not figure out how to use -n when setting instead of showing, …

-c to show the dialog for the given ports.

poudriere options -c -n deskutils/recoll

– works perfectly, although I'll probably not make a habit of this approach. The presence of directories at /usr/local/etc/poudriere.d/options is too easily forgotten.

poudriere -N options …

Yep, global option -N suppresses colour, although (below, bottom left) I prefer the colours to be visible. They help me to see things.

1636511076519.png



Solved.

Suggestions for enhancements to manual pages can be made in GitHub.
 
The poudriere(8) command itself takes options. E.g. "-A Force color support, even if not in a TTY."

Then the poudriere-options(8) command also takes options. E.g. "-s Show port options instead of configuring them".
I've been studying that documentation, as well, since July. And my understanding of poudriere-options (as posed by Erichans in post #19) is for automating the management of per-port options that are found in /var/db/ports/. From poudriere(8):
Code:
Custom build    options
     Before building a package,    poudriere can mount a directory    containing op-
     tion files    if available.  poudriere will check for    any of these directo-
     ries in this order:

       /usr/local/etc/poudriere.d/_jailname_-_tree_-_setname_-options
       /usr/local/etc/poudriere.d/_jailname_-_setname_-options
       /usr/local/etc/poudriere.d/_jailname_-_tree_-options
       /usr/local/etc/poudriere.d/_tree_-_setname_-options
       /usr/local/etc/poudriere.d/_setname_-options
       /usr/local/etc/poudriere.d/_tree_-options
       /usr/local/etc/poudriere.d/_jailname_-options
       /usr/local/etc/poudriere.d/options

     If    a directory with this name exists, it is null-mounted into the
     /var/db/ports/ directory of the jail, thus    allowing to build package with
     custom OPTIONS.

What I'm curious about is whether /usr/local/etc/poudriere.d/options should be empty or not. The way the manpage is written, I could take it to mean either of the two scenarios:
  1. /usr/local/etc/poudriere.d/options does need to exist, but be empty. Then null-mounting it into /var/db/ports will let the two paths point to the same per-port options files (similar to ln -s) that Poudriere will use.
  2. /usr/local/etc/poudriere.d/options should not be empty, and in fact can be different than the original /var/db/ports on the bare metal. Null-mounting is needed so that correct set of options is 'seen' via /var/db/ports by the make portion of Poudriere's build process.
So, is 1 or 2 correct, or am I on the wrong track altogether?
 
Back
Top