Notice

Some of below info may be outdated and is taken from Meego.

Introduction

Spectacle is the toolset for packaging maintenance from Mer, including the tool
to generate spec files from metadata file in YAML format, and tools to convert
spec files or spec-builder's ini files to YAML format.

For spectacle managed packages, all generic packaging information will be stored
in the YAML file, and it also allows maintaining customizations in the spec file
directly with special enclosure tags.

Three separated tools will be installed:

specify: the tool to generate or to update spec file, based on YAML

ini2spectacle: the tool to convert spec-builder .ini to YAML and new spec file

spec2spectacle: the tool to convert original spec to YAML and new spec file

Requirements

python 2.x, above 2.5

PyYAML, the python module for YAML parsing

cheetah, one popular templating system for python

In many linux distributions, the needed package might be "python-cheetah".

Usage

specify

Usage: specify [options] [yaml-path]
Options:
--version show program's version number and exit
-h, --help show this help message and exit
-o OUTFILE_PATH, --output=OUTFILE_PATH
Path of output spec file
-s, --skip-scm Skip to check upstream SCM when specified in YAML
-N, --not-download Do not try to download newer source files
-n, --non-interactive
Non interactive running, to use default answers
--new=NEWYAML Create a new yaml from template
--newsub=NEWSUB Append a new sub-package to current yaml

For example, `specify widget.yaml` will create (or update) the file widget.spec. The update will clobber/delete everything that is not enclosed in the customization sections (<<< and >>>). Note that the %changelog section will always be clobbered (see Tips below about changelogs).

Customizations in spec

Generated spec files by specify will have many placeholders for customizations,
such as:

# >> build pre
# << build pre

You can add any custom code between the markers, next time when you run
``specify``, the text between the markers will be kept as is, all other sections
relying on the meta data from the YAML file will be changed depending on the
values in the YAML file.

The following placeholders in spec can be customized:

Private Macros, used in this package's spec

With placeholder:
# >> macros
# << macros

Extra setup scripts in the last of ``%prep``

With placeholder:
# >> setup
# << setup

Pre-Build, scripts before package building

With placeholder:
# >> build pre
# << build pre

Post-Build, scripts after package building

With placeholder:
# >> build post
# << build post

Pre-Install, scripts before package installation

With placeholder:
# >> install pre
# << install pre

Post-Install, scripts after package installation

With placeholder:
# >> install post
# << install post

Files, files list in packaged rpm

With placeholder:
# >> files [sub-package]
# << files [sub-package]

NOTE**: "sub-packge" stands for the name of sub-package, and it is optional. If no sub-package name specified, it means the files of **main** package.
NOTE**: If the file list is simple enough, you can use YAML *Files* keyword instead to record it.

Scriptlets for %check section

With placeholder:
# >> check
# << check

NOTE**: Only if YAML boolean *Check* is specifed as ``yes``, %check with placeholder lines will be generated in .spec.

Scriptlets for %pre section

With placeholder:
# >> pre
# << pre

NOTE**: The placeholder lines will NOT generated in spec by default. If you need customized %pre scripts, it need be added manually, and only once.

Scriptlets for %preun section

With placeholder:
# >> preun
# << preun

NOTE**: The placeholder lines will NOT generated in spec by default. If you need customized %preun scripts, it need be added manually, and only once.

Scriptlets for %post section

With placeholder:
# >> post
# << post

NOTE**: The placeholder lines will NOT generated in spec by default. If you need customized %post scripts, it need be added manually, and only once.

Scriptlets for %postun section

With placeholder:
# >> postun
# << postun

NOTE**: The placeholder lines will NOT generated in spec by default. If you need customized %postun scripts, it need be added manually, and only once.

Internal Implementation

Spectacle uses cheetah templates to generate the spec file, based the metadata
from YAML file. But the end users need not tackle it.

Tips

To upgrade the pkg to a newer version, you can just edit the
version string in spectacle YAML file, and when you run ``specify``, it
will download the needed files for you automatically.

For packages with locale data, *LocaleName* is needed. If package
maintainers cannot confirm whether there are locale files, they can just
do not use *LocaleName* at first, and whenever "unpackaged files" rpm
packaging errors encountered, it means *LocaleName* should be added. And
please do not use it for packages without locale data to keep them clean,
though it will not block the building and packaging.

When using spec2spectacle/ini2spectacle to generate spectacle, the following problems should be checked:

Remove duplicate Requires(include pre/post/preun/postun) which were added automatically based on the analysis of file list.

Review and clean up the reserved scripts in "build|install pre|post" sections in new generated spec file.

User can use "series.conf" file to specify multiple patches under package directory. The "series.conf" can be used by ``quilt`` and the content can be updated to spec automatically when running ``specify``.

When you use ``specify`` to update a .spec file, any %changelog section will be removed in total. This is because the Packaging Guidelines require using *.changes files instead of an explicit %changelog section in your .spec. (And spectacle doesn't have any changelog support for the .yaml file.) Before rebuilding a package, OBS will add the .changes file to the end of the .spec. (So, if you're building packages without OBS/osc, then you will need to do this manually.)