Red Hat Bugzilla – Bug 164281
rpmbuild man page omits --define
Last modified: 2007-11-30 17:11:10 EST
From Bugzilla Helper: User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.7.10) Gecko/20050720 Fedora/1.0.6-1.1.fc3 Firefox/1.0.6 Description of problem: rpmbuild man page does not make any reference to the '--define' parameter, even though rpmbuild recognizes it (and is needed for sending options to certain spec files). Version-Release number of selected component (if applicable): rpm-4.3.2-21 How reproducible: Always Steps to Reproduce: 1. man rpmbuild 2. look for any reference to '--define' parameter 3. repeat Actual Results: i lost my hair Expected Results: the whole family comes together around the monitor and shares quality time reading about the '--define' parameter of rpmbuild Additional info: since many .spec files aren't documented, and (for one who normally doesn't compile rpm's on a daily basis) rpmbuild documentation can be hard to find (IF one doesn't already know where to go to get it), and since many .spec files need options/variables defined, but one cannot figure out *how* to do this, 'man rpmbuild' seems like the likely place to go. however, there is no mention of '--define', or of how to define variables from the command line, with rpmbuild, in the rpmbuild man page. thus, one can spend a lot of extra time searching for how to do this, when a reference to it in the man page (and comments in .spec files about how to use rpmbuild to specify a certain parameter/value) would save time. multiplied across the many programmers worldwide who occasionally re-build an rpm and need to send a parameter to a .spec file, humanity would be saved billions and billions of man-hours, and we'd have landed on saturn by now.
rpmbuild --help | grep define -D, --define='MACRO EXPR' define MACRO with value EXPR
hmmm good point. so to be more thorough, i suppose we should list them all. the following is a complete list of command paremeters listed by 'rpmbuild --help' but not explained in the man page: -D, --define --nodeps --nodirtokens -E, --eval --macros --nodigest --nosignature --rcfile -r (though its equivalent, '--root', is) --querytags --dbpath --with --without --usage --verbose (though its equivalent, '-v', is) also, conversely, the following are *not* documented in 'rpmbuild --help' but *are* in the man page: -vv -tl --sign --pipe finally, several options appear in the rpmbuild man page *without* the = sign (e.g. '--dbpath DIRECTORY') whereas they appear in the 'rpmbuild --help' *with* the = sign (e.g. '--dbpath=DIRECTORY'), so it is unclear which syntax is correct, or whether they both will work. examples include --macros=, --without=, --buildroot, and others.
rpm uses popt - as such some of the options and their help come from /usr/lib/rpm/rpmpopt-VERSION as such they aren't in the man page. Indeed the syntax can vary depending on the specific popt method for the argument.
you are making the case for not documenting something based on the *way* that thing is implemented. how is that tenable?
The argument is "tenable" because popyt permits option aliasing, i.e. optionsd can be retrofiitted to an application without recompiling. Demanding that all options -- including the aliases -- be documented, and be displayed, is directly at odds with advantage of extending application options through popt aliases.
This report targets the FC3 or FC4 products, which have now been EOL'd. Could you please check that it still applies to a current Fedora release, and either update the target product or close it ? Thanks.
sure, i can check if it is the same with fc6. by the way, i personally disagree with the reasoning of johnson (i believe he is missing the point entirely). however, i thought that after he posted that in defense of the status quo, that the issue had been closed. indeed, nothing has been done about it since then. it will take me a few days before i can get to this (need to upgrade a server to check it). i will post an update by the end of next week, to let you know whether it applies to fc6.
Added <command> --help to SEE ALSO section of the manuals with explanation why it's impossible to guarantee that documented and actually available options match on any given system.