Development/Tutorials/Updating KConfig Files: Difference between revisions

    From KDE TechBase
    No edit summary
    (Mark for updating)
    (9 intermediate revisions by 4 users not shown)
    Line 1: Line 1:
    {{Template:I18n/Language Navigation Bar|Development/Tutorials/Updating_KConfig_Files}}
     
    {{TutorialBrowser|
    {{TutorialBrowser|


    series=KConfig|
    series=KConfig|


    pre=[[../KConfig|Introduction to KConfig]]|
    pre=[[../KConfig| Introduction to KConfig]]|


    name=Updating KConfig files|
    name=Updating KConfig files|


    }}
    }}
    {{Review|Port to KF5}}


    =KConfig Update=
    =KConfig Update=
    Line 51: Line 53:
    Each line can contain one entry. The following entries are recognized:
    Each line can contain one entry. The following entries are recognized:


    <code>Id=<id></code>
    <syntaxhighlight lang="ini">
    Id=<id>
    </syntaxhighlight>


    With <id> identifying the group of update entries that follows. Once a group
    With <id> identifying the group of update entries that follows. Once a group
    Line 57: Line 61:
    will not be applied again.
    will not be applied again.


    <code>
    <syntaxhighlight lang="ini">
    File=<oldfile>,<newfile>
    File=<oldfile>,<newfile>
    File=<oldfile>
    File=<oldfile>
    </code>
    </syntaxhighlight>


    Specifies that configuration information is read from <oldfile> and written
    Specifies that configuration information is read from <oldfile> and written
    Line 67: Line 71:
    at the time kconf_update first checks, no related update will be performed.
    at the time kconf_update first checks, no related update will be performed.


    <code>
    <syntaxhighlight lang="ini">
    Script=<script>[,<interpreter>]
    Script=<script>[,<interpreter>]
    </code>
    </syntaxhighlight>


    <script> is the program that will be performing the updates. All entries from <oldfile> are piped into <script>. The output of <script>is used as new entries for <newfile>. Existing entries can be deleted by adding lines with "# DELETE [group]key" in the output of the script. To delete a whole group use "# DELETEGROUP [group]".
    <script> is the program that will be performing the updates. All entries from <oldfile> are piped into <script>. The output of <script>is used as new entries for <newfile>. Existing entries can be deleted by adding lines with "# DELETE [group]key" in the output of the script. To delete a whole group use "# DELETEGROUP [group]".
    Line 91: Line 95:
    To delete <oldgroup> use "# DELETEGROUP".
    To delete <oldgroup> use "# DELETEGROUP".


    <interpreter> can be something like "perl" or "ruby".
    <tt><interpreter></tt> can be something like "perl" or "ruby".


    It is also possible to have a script command without specifying <oldfile> or <newfile>. In that case the script is run but it will not be fed any input and its output will simply be discarded.
    It is also possible to have a script command without specifying <oldfile> or <newfile>. In that case the script is run but it will not be fed any input and its output will simply be discarded.


    <code>
    <syntaxhighlight lang="ini">
    ScriptArguments=<arguments>
    ScriptArguments=<arguments>
    </code>
    </syntaxhighlight>


    If specified, the arguments will be passed to <script>.
    If specified, the arguments will be passed to <script>.
    IMPORTANT: It has to be specified before Script=.
    IMPORTANT: It has to be specified before Script=.


    <code>
    <syntaxhighlight lang="ini">
    Group=<oldgroup>,<newgroup>
    Group=<oldgroup>,<newgroup>
    Group=<oldgroup>
    Group=<oldgroup>
    </code>
    </syntaxhighlight>


    Specifies that configuration information is read from the group <oldgroup>
    Specifies that configuration information is read from the group <oldgroup>
    Line 112: Line 116:
    specify keys that are not under any group.
    specify keys that are not under any group.


    <code>
    <syntaxhighlight lang="ini">
    RemoveGroup=<oldgroup>
    RemoveGroup=<oldgroup>
    </code>
    </syntaxhighlight>


    Specifies that <oldgroup> is removed entirely. This can be used
    Specifies that <oldgroup> is removed entirely. This can be used
    to remove obsolete entries or to force a revert to default values.
    to remove obsolete entries or to force a revert to default values.


    <code>
    <syntaxhighlight lang="ini">
    Options=<option1>, <option2>,
    Options=<option1>, <option2>,
    </code>
    </syntaxhighlight>


    With this entry you can specify options that apply to the next "Script",
    With this entry you can specify options that apply to the next "Script",
    Line 132: Line 136:
    new name already exists. When this option is specified the old configuration item will overwrite any existing item.
    new name already exists. When this option is specified the old configuration item will overwrite any existing item.


    <syntaxhighlight lang="ini">
    Key=<oldkey>,<newkey>
    Key=<oldkey>,<newkey>
    Key=<oldkey>
    Key=<oldkey>
    </syntaxhighlight>


    Specifies that configuration information is read from the key <oldkey>
    Specifies that configuration information is read from the key <oldkey>
    Line 139: Line 145:
    is read from as well as written to <oldkey>.
    is read from as well as written to <oldkey>.


    <code>
    <syntaxhighlight lang="ini">
    AllKeys
    AllKeys
    </code>
    </syntaxhighlight>


    Specifies that all configuration information in the selected group should
    Specifies that all configuration information in the selected group should
    be moved (All keys).
    be moved (All keys).


    <code>
    <syntaxhighlight lang="ini">
    AllGroups
    AllGroups
    </code>
    </syntaxhighlight>


    Specifies that all configuration information from all keys in ALL·
    Specifies that all configuration information from all keys in ALL·
    groups should be moved.
    groups should be moved.


    <code>
    <syntaxhighlight lang="ini">
    RemoveKey=<oldkey>
    RemoveKey=<oldkey>
    </code>
    </syntaxhighlight>


    Specifies that <oldkey> is removed from the selected group. This can be used
    Specifies that <oldkey> is removed from the selected group. This can be used
    to remove obsolete entries or to force a revert to default values.
    to remove obsolete entries or to force a revert to default values.
    ==Testing==
    See [[Development/Tools/Using_kconf_update|Using kconf_update]] for tips on how to test update files.

    Revision as of 10:20, 30 May 2019

    Updating KConfig files
    Tutorial Series   KConfig
    Previous   Introduction to KConfig
    What's Next   n/a
    Further Reading   n/a
    Warning
    This page needs a review and probably holds information that needs to be fixed.

    Parts to be reviewed:

    Port to KF5

    KConfig Update

    This page describes how a developer can use the KConfig update mechanism (kconf_update) available in kdelibs to update a user's already existing config file to accomodate changes made to the format of the default config file.

    Why should you use it?

    Over time applications sometimes need to rearrange the way configuration options are stored. Since such an update shouldn't influence the configuration options that the user has selected, the application must take care that the options stored in the old way will still be honored.

    What used to happen is that the application looks up both the old and the new configuration option and then decides which one to use. This method has several drawbacks:

    • The application may need to read more configuration files than strictly needed, resulting in a slower startup.
    • The application becomes bigger with code that will only be used once.

    kconf_update addresses these problems by offering a framework to update configuration files without adding code to the application itself.

    How it works

    Applications can install so called "update files" under $KDEDIR/share/apps/kconf_update. An update file has .upd as an extension and contains instructions for transferring/converting configuration information from one place to another.

    Updating the configuration happens automatically, either when KDE gets started or when kded detects a new update file in the above mentioned location.

    Update files are separated into sections. Each section has an id. When a section describing a configuration change has been applied, the id will be stored in the file kconf_updaterc. This information is used to make sure that a configuration update is only performed once.

    If you overwrite an existing update file with a new version that contains a new section, only the update instructions from this extra section will be performed.

    File format of the update file

    Empty lines or lines that start with '#' are considered comments Commas (,) are used to seperate fields and may not occur as part of any field and all of the keywords are case-sensitive, i.e. you cannot say "key" instead of "Key" for example.

    For the rest the file is parsed and executed sequentially from top to bottom. Each line can contain one entry. The following entries are recognized:

    Id=<id>
    

    With <id> identifying the group of update entries that follows. Once a group of entries have been applied, their <id> is stored and this group of entries will not be applied again.

    File=<oldfile>,<newfile>
    File=<oldfile>
    

    Specifies that configuration information is read from <oldfile> and written to <newfile>. If you only specify <oldfile>, the information is read from and as written to <oldfile>. Note that if the file does not exist at the time kconf_update first checks, no related update will be performed.

    Script=<script>[,<interpreter>]
    

    <script> is the program that will be performing the updates. All entries from <oldfile> are piped into <script>. The output of <script>is used as new entries for <newfile>. Existing entries can be deleted by adding lines with "# DELETE [group]key" in the output of the script. To delete a whole group use "# DELETEGROUP [group]".

    There are two types of kconf_update scripts:

    • Non-Compiled
    • Compiled

    If <script> is written in a non-compiled language (such as ruby or perl), then it should be installed into ${KCONF_UPDATE_INSTALL_DIR} .

    If <script> is a compiled application, it should be installed in ${BIN_INSTALL_DIR}/kconf_update_bin

    If the script command is issued after a "Group" command the behavior is slightly different:

    All entries from <oldfile> in <oldgroup> are piped into <script>. The output of script is used as new entries for <newfile> in <newgroup>, unless a different group is specified with "[group]". Existing entries can be deleted from <oldgroup> by adding lines with "# DELETE key" in the output of the script.· To delete <oldgroup> use "# DELETEGROUP".

    <interpreter> can be something like "perl" or "ruby".

    It is also possible to have a script command without specifying <oldfile> or <newfile>. In that case the script is run but it will not be fed any input and its output will simply be discarded.

    ScriptArguments=<arguments>
    

    If specified, the arguments will be passed to <script>. IMPORTANT: It has to be specified before Script=.

    Group=<oldgroup>,<newgroup>
    Group=<oldgroup>
    

    Specifies that configuration information is read from the group <oldgroup> and written to <newgroup>. If you only specify <oldgroup>, the information is read from as well as written to <oldgroup>. You can use <default> to specify keys that are not under any group.

    RemoveGroup=<oldgroup>
    

    Specifies that <oldgroup> is removed entirely. This can be used to remove obsolete entries or to force a revert to default values.

    Options=<option1>, <option2>,
    

    With this entry you can specify options that apply to the next "Script", "Key" or "AllKeys" entry (only to the first!). Possible options are:

    • "copy" Copy the configuration item instead of moving it. This means that

    the configuration item will not be deleted from <oldfile>/<oldgroup>

    • "overwrite" Normally, a configuration item is not moved if an item with the

    new name already exists. When this option is specified the old configuration item will overwrite any existing item.

    Key=<oldkey>,<newkey>
    Key=<oldkey>
    

    Specifies that configuration information is read from the key <oldkey> and written to <newkey>. If you only specify <oldkey>, the information is read from as well as written to <oldkey>.

    AllKeys
    

    Specifies that all configuration information in the selected group should be moved (All keys).

    AllGroups
    

    Specifies that all configuration information from all keys in ALL· groups should be moved.

    RemoveKey=<oldkey>
    

    Specifies that <oldkey> is removed from the selected group. This can be used to remove obsolete entries or to force a revert to default values.

    Testing

    See Using kconf_update for tips on how to test update files.