Re: confused about the use of the %doc directive

[Eric Backus <ericjb wolfenet com>]

rpjday wrote:

> 
>   i was reading a tutorial at ibm's developerworks web site
> on simple RPM construction, and it mentioned using a %doc
> directive in the %files section to add documentation files.
>  
>   specifically, it stated that, if you give just a simple
> unqualified filename, it will look for a file of that name
> in the build directory, and assume you want to install that
> file (and others like it) in the directory
> /usr/share/doc/%{name}-%{version}.
> 
>   so, for example, if i have the simple line
> 
>   %doc README
> 
> that file will be placed automatically in the above directory.
> 
>   but what's confusing is that the build process looks for this
> file in the *build* directory which, in my case if i'm building
> RPMs under my home directory, might be /home/rpjday/RPM/BUILD.
> 
>   however, i might be using this BUILD directory as the build
> root of several RPMs, so i might have subdirectories such as
> pkg1-root, pkg2-root and so on as subdirectories of BUILD.
> i would have thought the build process would look for a README
> file in the appropriate build root directory, *not* in the
> overall BUILD directory, for which there can obviously be only
> one README with all packages competing for that single file.
> 
>   is this correct?  i just tested it and it seems to be the
> case.  this makes no sense to me.  can someone explain this?
> 
> rday


I think you're confusing the BUILD directory (which is where you do things 
to build the files you want to package up) and the BuildRoot directory 
(where you install the files that you built under the BUILD directory).

When you do the "prep" stage of the build, you should end up with a unique 
directory under BUILD in which to do your build.  Normally the directory is 
called BUILD/<pkgname>-<version>, but it doesn't have to be.

WHen you do the "install" stage of the build, you should end up with the 
complete directory structure that the RPM file will install, underneath the 
BuildRoot directory.  The BuildRoot directory should also be unique, 
typically called something like /tmp/<pkgname>-root or something similar.

I think you've combined these two concepts in a clever way for packages 
that require no actual building, just file installation, but they're 
normally separate concepts.


Also, the directory that RPM looks in for files (like the README that you 
mentioned above), seems to vary depending on whether the BUILD directory 
really is called BUILD/<pkgname>-<version> or something else.  I discovered 
that by experimentation, I don't think it's documented anywhere.

-- 
                        Eric Backus <eric_backus@agilent.com>
                        PGP:  B6 CC EC B2 CD A4 79 A8  1C BF 19 96 69 EE E5 CC
                        GPG: 1567 EB6E D580 7CCD 13FB  34EC A51C C498 7F7F 9944