Bug 164281

Summary: rpmbuild man page omits --define
Product: [Fedora] Fedora Reporter: Jeff Stern <jas>
Component: rpmAssignee: Panu Matilainen <pmatilai>
Status: CLOSED UPSTREAM QA Contact: Mike McLean <mikem>
Severity: medium Docs Contact:
Priority: medium    
Version: 4   
Target Milestone: ---   
Target Release: ---   
Hardware: i386   
OS: Linux   
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2007-08-10 09:11:33 UTC Type: ---
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:

Description Jeff Stern 2005-07-26 15:27:37 UTC
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):

How reproducible:

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.

Comment 1 Paul Nasrat 2005-07-26 15:55:52 UTC
rpmbuild --help | grep define
  -D, --define='MACRO EXPR'        define MACRO with value EXPR

Comment 2 Jeff Stern 2005-07-29 17:20:25 UTC
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
-E, --eval
-r (though its equivalent, '--root', is)
--verbose (though its equivalent, '-v', is)

also, conversely, the following are *not* documented in 'rpmbuild --help' but
*are* in the man page:


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.

Comment 3 Paul Nasrat 2005-07-29 17:41:06 UTC
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.

Comment 4 Jeff Stern 2005-08-01 16:24:02 UTC
you are making the case for not documenting something based on the *way* that
thing is implemented. how is that tenable?

Comment 5 Jeff Johnson 2005-08-25 16:50:25 UTC
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.

Comment 6 Christian Iseli 2007-01-22 12:01:01 UTC
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 ?


Comment 7 Jeff Stern 2007-01-22 18:56:28 UTC
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.

Comment 8 Panu Matilainen 2007-08-10 09:11:33 UTC
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.