(Add details about changelogs.) |
|||
| (6 intermediate revisions not shown) | |||
| Line 59: | Line 59: | ||
--new=NEWYAML Create a new yaml from template | --new=NEWYAML Create a new yaml from template | ||
--newsub=NEWSUB Append a new sub-package to current yaml | --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). | ||
* ini2spectacle | * ini2spectacle | ||
| Line 151: | Line 153: | ||
* BuildConflicts: **list** of **string** | * BuildConflicts: **list** of **string** | ||
| - | * Configure: **string**, *optional*, valid values: **autogen**, **configure**, | + | * Configure: **string**, *optional*, valid values: **autogen**, **configure**, **reconfigure**, **none**<br> |
| - | + | ** If not specified, the default value "configure" will be used | |
| - | + | ||
* ConfigOptions: **list**, *optional*, extra options for ``Configure`` | * ConfigOptions: **list**, *optional*, extra options for ``Configure`` | ||
| - | * Builder: **string**, *optional*, valid values: **make**, **single-make**, | + | * Builder: **string**, *optional*, valid values: **make**, **single-make**, **python**, **perl**, **qmake**, **none**<br> |
| - | + | ** If not specified, the deault value "make" will be used. If do not want a automatic builder, please use "none". | |
| - | + | ||
| - | + | ||
* QMakeOptions: **list**, *optional*, extra options for **qmake** ``Builder`` | * QMakeOptions: **list**, *optional*, extra options for **qmake** ``Builder`` | ||
| Line 191: | Line 190: | ||
* UpdateDesktopDB: **boolean**, whether to run 'update-desktop-database' to flush cache when package (un)installation | * UpdateDesktopDB: **boolean**, whether to run 'update-desktop-database' to flush cache when package (un)installation | ||
| + | |||
| + | * NoIconCache: **boolean**, whether to run 'gtk-update-icon-cache' if icon files found in package | ||
* AutoDepend: **boolean**, for subpackages only, whether to add Require to main package automatically | * AutoDepend: **boolean**, for subpackages only, whether to add Require to main package automatically | ||
| Line 198: | Line 199: | ||
* AutoSubPackages: **list** of **string**, mainly for '-devel' | * AutoSubPackages: **list** of **string**, mainly for '-devel' | ||
| - | * SubPackages: **list** of **dict**, the **dict** item is the lower level | + | * SubPackages: **list** of **dict**, the **dict** item is the lower level directives for sub packages: |
| - | directives for sub packages: | + | |
* Name | * Name | ||
| Line 209: | Line 209: | ||
* etc. | * etc. | ||
| - | + | '''CAUTION''': The following cases of value string have special meaning in YAML syntax: | |
| - | + | ||
* string with leading **``%``** charactor | * string with leading **``%``** charactor | ||
* string with leading **``*``** charactor | * string with leading **``*``** charactor | ||
| Line 219: | Line 218: | ||
(double-quote), and the choice of quote char should not conflict with the value | (double-quote), and the choice of quote char should not conflict with the value | ||
string self. | string self. | ||
| + | |||
| + | == Mandatory and valid keywords for all packages == | ||
| + | === Mandatory keywords === | ||
| + | The following keywords are mandatory for main package: | ||
| + | |||
| + | * Name | ||
| + | * Summary | ||
| + | * Description | ||
| + | * Version | ||
| + | * Group | ||
| + | * License | ||
| + | |||
| + | The following keywords are mandatory for sub-package: | ||
| + | |||
| + | * Name | ||
| + | * Summary | ||
| + | * Description | ||
| + | * Group | ||
| + | |||
| + | === Valid keywords for sub-packages === | ||
| + | For sub-packages, only a subset of keywords can be specified: | ||
| + | |||
| + | * Name | ||
| + | * Summary | ||
| + | * Description | ||
| + | * Group | ||
| + | * License | ||
| + | * Version | ||
| + | * Release | ||
| + | * Epoch | ||
| + | * URL | ||
| + | * BuildArch | ||
| + | * Files | ||
| + | * Prefix | ||
| + | * Requires | ||
| + | * RequiresPre | ||
| + | * RequiresPreUn | ||
| + | * RequiresPost | ||
| + | * RequiresPostUn | ||
| + | * Provides | ||
| + | * Conflicts | ||
| + | * Obsoletes | ||
| + | * NoAutoReq | ||
| + | * NoAutoProv | ||
| + | * NoAutoReqProv | ||
| + | * NoIconCache | ||
| + | * FilesInput | ||
| + | |||
| + | === Keywords only for sub-packages === | ||
| + | The following keywords are only valid for sub-packages: | ||
| + | |||
| + | * AsWholeName | ||
| + | * AutoDepend | ||
== Namespace support for multi-architecture in several keywords == | == Namespace support for multi-architecture in several keywords == | ||
| Line 235: | Line 287: | ||
* ``ix86:`` - x86 platform | * ``ix86:`` - x86 platform | ||
* ``arm:`` - arm platform | * ``arm:`` - arm platform | ||
| + | * ``armv5:`` - armv5 platform, will expand to "armv5el armv5tel armv5tejl" | ||
| + | * ``armv7:`` - armv7 platform, will expand to "armv7el armv7tel armv7l armv7hl armv7nhl" | ||
Here's some samples: | Here's some samples: | ||
| Line 345: | Line 399: | ||
== Tips == | == 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 | version string in spectacle YAML file, and when you run ``specify``, it | ||
will download the needed files for you automatically. | 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 | maintainers cannot confirm whether there are locale files, they can just | ||
do not use *LocaleName* at first, and whenever "unpackaged files" rpm | do not use *LocaleName* at first, and whenever "unpackaged files" rpm | ||
| Line 356: | Line 410: | ||
though it will not block the building and packaging. | 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|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.) | |
Contents |
Spectacle is the toolset for packaging maintenance of MeeGo, 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:
Several methods available for spectacle installation:
From MeeGo Tools Repo, repo urls and install packages can be found for: * MeeGo * Fedora 10,11,12 * openSUSE(s) * xUbuntu 8.10/9.04/9.10/10.04 * Debian 5.0
The latest code in git tree can be accessed at: [git://gitorious.org/meego-developer-tools/spectacle.git]
Note on Ubuntu installation From this Edit or create /etc/apt/sources.list.d/meego.list with sudo Add
deb http://repo.meego.com/MeeGo/tools/repos/ubuntu/9.10/ /
run the following commands
sudo apt-get update
In many linux distributions, the needed package might be "python-cheetah".
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).
Usage: ini2spectacle [options] [ini-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 yaml file
-f, --include-files To store files list in YAML file
Usage: spec2spectacle [options] [spec-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 yaml file
-r, --replace-macros To replace self-defined macros in spec file
--no-builder-parsing Do NOT try to parse build/install scripts
-f, --include-files To store files list in YAML file
The syntax of YAML can be refered here: <http://www.yaml.org/spec/>
Two example spectacle YAML files are placed to examples/ directory in source code:
All available directives for spectacle are listed as the following:
* Name * Summary * Description, *optional* * Group, *optional* * License, *optional* * Requires, *optional* * etc.
CAUTION: The following cases of value string have special meaning in YAML syntax:
Then these string values need to be quoted by ``'``(single-quote) or ``"`` (double-quote), and the choice of quote char should not conflict with the value string self.
The following keywords are mandatory for main package:
The following keywords are mandatory for sub-package:
For sub-packages, only a subset of keywords can be specified:
The following keywords are only valid for sub-packages:
For the following spectacle YAML keywords:
If one of the items need to be architecture specified, we can add arch prefix to it. The supported prefix and the corresponding architectures as the followings:
Here's some samples:
Requires:
- arm:pkg-need-in-arm-image
- ix86:pkg-need-in-x86-image
- normal-pkg
ConfigOptions:
- arm:--arm-specific-opt
- ix86:--ix86-specific-opt
- --common-opt
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:
With placeholder:
# >> macros
# << macros
With placeholder:
# >> setup
# << setup
With placeholder:
# >> build pre
# << build pre
With placeholder:
# >> build post
# << build post
With placeholder:
# >> install pre
# << install pre
With placeholder:
# >> install post
# << install post
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.
With placeholder:
# >> check
# << check
NOTE**: Only if YAML boolean *Check* is specifed as ``yes``, %check with placeholder lines will be generated in .spec.
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.
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.
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.
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.
Spectacle uses cheetah templates to generate the spec file, based the metadata from YAML file. But the end users need not tackle it.
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:
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.)