What is the syntax of module.tweaks?

TWEAK_NAME			tweak-owner

	Description text.

	Define               : preprocessor-define
	Value                : default value
        Value for <profiles> : per-profile default value
	Depends on           : list of features, tweaks, apis and defines
	Category             : list of categories
        Conflicts with       : list of tweaks and apis
tweak-owner
The tweak owner is the name of the developer responsible for the tweak. If this value is set to "deprecated" it means the tweak is no longer available. The tweak cannot be set (to YES or NO), and an error will be produced if it is set. Mandatory.
Description
The description should describe the tweak in such a way that the branch manager for a platform can easily understand what the tweak does, without having to look at the source code. If possible, it should also say something about what configurations should enable or disable it. Can span several lines. Mandatory.
Define
The define this tweak work on. Mandatory.
Depends on
List of features/tweaks/defines which this tweak depends on. The other features/tweaks/defines must be turned on to be able to turn this tweak on. The items are separated by "," and/or "and". "nothing" is a valid value. Not mandatory, if left out it means "nothing". The product will not be forced to answer if it wants to turn on this tweak if the dependencies are not met.
Category
Type of tweak. Can be one or several of the following:
  • footprint - The tweak affects footprint.
  • memory - The tweak affects memory usage.
  • performance - The tweak affects performance.
  • standards - The tweak is related to the standards we support. For example, there might be a tweak to turn off some seldom-used functionality in some web standard.
  • setting - The tweak affects some setting. For example, default prefs values are tweaks with this category.
  • workaround - The tweak turns on some workaround for a problem. The problem might be occurring on only some platforms which is why it is made configurable.
If several categories are used, they shall be separated by commas. Mandatory.
Conflicts with
List of tweaks and apis which cannot be tweaked/imported if this tweak is tweaked. The items are separated by "," and/or "and". "nothing" is a valid value. Not mandatory, if left out it means "nothing".
Enabled for
List of profiles for which this tweak is enabled by default. For each listed profile X, the file hardcore/tweaks/profile_tweaks_X.h will contain the line #define TWEAK_WHATEVER YES. The value special value "none" means the tweak is not enabled for any profiles by default. Note: a tweak with a value should not be tweaked per profile via "Enabled for" but via "Value for".
Value for <profiles>
Default value for the comma separated list of profiles. For each listed profile X, the file hardcore/tweaks/profile_tweaks_X.h will contain the lines #define TWEAK_WHATEVER YES and #define WHATEVER value.
Disabled for
List of profiles for which this tweak is disabled by default. For each listed profile X, the file hardcore/tweaks/profile_tweaks_X.h will contain the line #define TWEAK_WHATEVER NO. The value special value "none" means the tweak is not disabled for any profiles by default.

Example tweak:

TWEAK_PREFS_PRINT_MARGIN_TOP		peter

	Defines the default top margin in millimeters.

	Category  : setting
	Define    : DEFAULT_TOP_MARGIN
	Value     : 250
	Depends on: FEATURE_PRINTING

All products with FEATURE_PRINTING enabled will have to take a decision on this tweak.

If the tweak is set to NO (the setting is not tweaked), the default value will be used for the define. This means, DEFAULT_TOP_MARGIN will be defined to 250. If the tweak is set to YES, DEFAULT_TOP_MARGIN must also be define to a value chosen by the product.

Example of a tweak which has no value:

TWEAK_SVG_FIX_POINT			bratell

    Use fix point instead of floats in SVG. This will improve
    performance alot on devices with slow floating point calculations,
    but the SVG engine will lose precision so the output may suffer
    from rounding errors or number overflow. If this is turned on and
    you use libvega as backend to SVG, it's likely that you want to
    turn on fixed point in libvega as well.

    Category: performance
    Define: SVG_FIX_POINT
    Depends on: FEATURE_SVG

This tweaks turns on the define SVG_FIX_POINT if the tweak is set to YES, otherwise nothing is done. The define is set automatically and need not to be set by the product, which is the case when a Value-field is present for the tweak, as in the previous example.

How do I change or introduce a tweak in different mainline configurations

The build-system can be told compile the "current" or "next" mainline configuration. Each mainline configuration has an associated version number. If the setup script finds the file module.tweaks.version, it parses that file instead of the module.tweaks. Thus a tweak can be added or changed for only one mainline configuration.

It is recommended to only keep the versiond file module.tweaks.version for the "current" mainline configuration and use the default file for the "next" mainline configuration. Thus on switching the mainline version numbers, the versioned file can be removed and only the not-versioned file remains.

Example: If the "current" mainline version is 2.3 and the "next" mainline version is 2.4, and one module needs to use different dependencis for one message on different mainline configurations, it can use two files:

module.tweaks.2.3
defines all tweaks for the "current" = 2.3 mainline configuration.
module.tweaks
defines all tweaks for the "next" = 2.4 mainline configuration.

So if you want to add or change a tweak for the "next" mainline configuration, look for the version number of the "current" mainline configuration in modules/hardcore/version.ini. If the file module.tweaks.current_version exists, you can edit module.tweaks.
Otherwise copy module.tweaks to module.tweaks.current_version, add it to the repository and modify module.tweaks. Thus the "current" mainline configuration remains unchanged.

The same applies if you want to add or change a tweak for the "current" mainline configuration: look for the version number of the "current" mainline configuration in modules/hardcore/version.ini. If the file module.tweaks.current_version exists, you can edit it
Otherwise copy module.tweaks to module.tweaks.current_version, add it to the repository and modify it. Thus the "next" mainline configuration remains unchanged.