quick-docs/en-US/modules/con_rpm_spec_file_overview.adoc

== Spec file overview
[[con_rpm_spec_file_overview]]

Use this guide for information about the specific macros in a `.spec` file.  


[NOTE]
You can use the macros `%{name}`, `%{version}` and `%{release}` to refer to the Name, Version and Release tags respectively. When you change the tag, the macros automatically update to use the new value.

.Name 
Add the base name of the package, which must match the `.spec` file name. Follow the http://fedoraproject.org/wiki/Packaging:Naming[Package Naming Guidelines] and write the file name in lower-case letters. 

.Version 
Add the upstream version number. See http://fedoraproject.org/wiki/Packaging:Versioning[Package Versioning]. If the version contains tags that are non-numeric, you might need to include the non-numeric characters in the `Release` tag. If upstream uses full dates to distinguish versions, consider using version numbers of the form. For example, `yy.mm[dd]` where `2008-05-01` becomes `8.05`.

.Release 
Set the initial value to `1%{?dist}`. Increment the number every time you release a new package for the same version of software. When a new upstream version is released, change the `Version` tag to match and reset the `Release` number to `1`. For more information, see the http://fedoraproject.org/wiki/Packaging:Versioning[Versioning Guide] of the packaging guidelines. 

.Summary
Enter a brief, one-line summary of the package. Use American English. Do not end with a period.

.Group 
This tag is deprecated since Fedora 17. See https://docs-old.fedoraproject.org/en-US/Fedora_Draft_Documentation/0.1/html/Packagers_Guide/chap-Packagers_Guide-Spec_File_Reference-Preamble.html[Spec
File Reference Preamble]

.License 
Enter an open source software license. Do not use the old Copyright tag. Use a standard abbreviation, for example, "`GPLv2+`" and be specific. For example, use "`GPLv2+`" for GPL version 2 or greater rather than "`GPL`" or "`GPLv2`" where it's true). For more information, see the http://fedoraproject.org/wiki/Packaging:LicensingGuidelines[Licensing Guidelines]. 

You can list multiple licenses by combining them with "`and`" and "`or`" (e.g. "`GPLv2 and BSD`".

.URL
The full URL for more information about the program. For example, the project website. 

[NOTE]
Do not add a link to the original source code. Add the link to the source code to the `Source0` tag.

.Source0
Enter the full URL for the compressed archive that contains the original, pristine source code, as upstream released it. "`Source`" is synonymous with "`Source0`". 

The full URL basename is used when looking in the `SOURCES` directory. If possible, embed `%{name}` and `%{version}`, so that changes to the  go to the right place. Preserve the timestamps when downloading source files. For more information, see http://fedoraproject.org/wiki/Packaging:Guidelines#Timestamps[Preserve timestamps]. 

If there is more than one source, name them `Source1`, `Source2`. 

If you add whole new files in addition to the pristine sources, list them as sources after the pristine sources. A copy of each of these sources is included in any source RPM(SRPM) you create, unless you specifically direct otherwise. For more information on special cases, for example, revision control, see https://fedoraproject.org/wiki/Packaging:SourceURL?rd=Packaging/SourceURL[Source URL]. 

.Patch0 
Enter the name of the first patch to apply to the source code. If you must patch the files after you extract them, edit the files and save their differences as a "patch" file in your `~/rpmbuild/SOURCES` directory. Patches must make only one logical change each, so it's quite possible to have multiple patch files.

.BuildArch
If you package files that are architecture-independent, for example shell scripts, data files, then add `BuildArch: noarch`. The architecture for the binary RPM is then `noarch`.

.BuildRoot 
This is now redundant in Fedora and is only needed for EPEL5. By default, the build root is placed in "`%{_topdir}/BUILDROOT/`".

In EPEL5, this is where files are installed during the %install process (after the %build process). 

.BuildRequires 
Add a comma-separated list of packages that are required for compiling the program. Usually, this field is repeated on multiple lines. These dependencies are not automatically determined. You must include everything that the package needs to build the program. 

Verify that you have specified all the necessary build requirementss by link:Using_Mock_to_test_package_builds[performing a "mock
build"] of your package. You can specify a minimum version if necessary, for example, `ocaml >= 3.08`. 

If you need the file `/EGGS`, determine the package that owns it by running `rpm -qf /EGGS`. 

If you need the program `EGGS`, determine the package that owns it by running "`rpm -qf \`which EGGS\``". Keep dependencies to a minimum. For example, use `sed` instead of `perl` if you do not need perl, but note that some applications permanently disable functions if the associated dependency is not present; in those cases you might need to include the additional packages. 

.Requires 
Enter a comma-separate list of packages that are required when the program is installed. Note that the `BuildRequires` tag lists what is required to build the binary RPM, while the `Requires` tag lists what is required when installing and running the program; a package may be in one list or in both. 


.%description
Enter a longer, multi-line description of the program. Use American English. All lines must be 80 characters or less. Blank lines indicate a new paragraph. 

Some graphical user interface installation programs reformat paragraphs; lines that start with whitespace might be treated as preformatted text and displayed as is, normally with a fixed-width font. See
https://docs-old.fedoraproject.org/en-US/Fedora_Draft_Documentation/0.1/html/RPM_Guide/ch09s03.html[RPM
Guide].

.%prep 
Add script commands to "prepare" the program. For example, to extract the program, so that it is ready for building. Typically this is just "`%autosetup`"; a common variation is "`%autosetup -n NAME`" if the
source file unpacks into `NAME`. 

.%build
Add script commands to compile the program and get it ready for installing. The program must come with instructions on how to do this. 

.%install 
Add script commands to "install" the program. The commands must copy the files from the `BUILD` directory `%{_builddir}` into the buildroot directory, `%{buildroot}`. 

.%check
Add script commands to "test" the program. This is run after the `%install` procedure, so place it there if you have this section. Often it contains `make test` or `make check`. This is separated from `%build` so that people can skip the self-test if they desire.

.%clean
Note that this section is now redundant in Fedora and is only necessary for EPEL.
Typically this contains only the following command:

`rm -rf %{buildroot}`

.%files
Add the list of files to be installed. 

.%changelog
Add changes in the package. Use the format example above.

Do not put software's change log here. This change log is only for the RPM.
 
.ExcludeArch 
If the package does not successfully compile, build or work on a particular architecture, list those architectures under this
tag.


RPM also supports the creation of several packages called subpackages from a single `.spec` file, such as `name-libs` and `name-devel` packages.

Do *not* create a "relocatable" package; they do not add value in Fedora and make things more complicated.


.Inserting comments 

Insert comments with a leading "`#`" character, and beware of macros (beginning with `%`) that are potentially multi-line, as they are expanded first. 

When commenting out a line, double the percent signs (`%%`) of the macros appearing after the "`#`". 

Also avoid inline comments on the same line as script commands.