# Tweaks

- What is a tweak?
- Are there different kind of tweaks?
- Who can add tweaks?
- Where are the tweaks described?
- What is the syntax of module.tweaks?
- How do I change or introduce a tweak in different mainline configurations?

## What is a tweak?

A tweak is a small variation of a feature or API. One tweak can adjust a buffer size and another can set the default text editor to be used for example. A tweak is not supposed to turn on lots of new funcionality.

## Are there different kind of tweaks?

All tweaks work on ONE define. There are two types of tweaks, working on this define. They can:

- Change the value of the define. Buffer size made configurable for example.
- Define the define if the tweak is turned on. A specific behavior can be turned on this way

## Who can add tweaks?

Tweaks can be added by all modules listed in readme.txt in the folders modules/, adjunct/ and platforms/. The tweaks are read from the file module.tweaks if present in the module root.

## Where are the tweaks described?

Each tweak is described as part of its definition in the `module.tweaks` file of the module that defines it.

The script that processes tweaks and APIs and generates the various related header files also generates an XML file containing the information in the `module.tweaks` files. This generated XML file is named `modules/hardcore/documentation/tweaks.version.xml` and uses an XSLT stylesheet to render in a semi-useful format (including a colorful tweak/profile matrix).

See:

## 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.