<?xml version="1.0" ?>
<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
  <!ENTITY % English "INCLUDE"><!-- change language only here -->
]>

<refentry>

<refentryinfo>
<title>&kde; Frameworks: KService</title>
<author>
<firstname>Scarlett</firstname>
<surname>Clark</surname>
<contrib>Wrote the original documentation.</contrib>
<affiliation>
<address><email>scarlett@scarlettgatelyclark.com</email></address>
</affiliation>
</author>
<author>
<firstname>Alex</firstname>
<surname>Merry</surname>
<contrib>Edited the documentation.</contrib>
<affiliation>
<address><email>alexmerry@kde.org</email></address>
</affiliation>
</author>

<date>2014-04-01</date>
<releaseinfo>5.0</releaseinfo>

</refentryinfo>


<refmeta>
<refentrytitle><command>desktoptojson</command></refentrytitle>
<manvolnum>8</manvolnum>
</refmeta>

<refnamediv>
<refname><command>desktoptojson</command></refname>
<refpurpose>Converts a <filename class="extension">.desktop</filename> file to a <filename class="extension">.json</filename> file.</refpurpose>
</refnamediv>

<refsynopsisdiv>
<title>Synopsis</title>

<cmdsynopsis>
<command>desktoptojson</command>
<arg choice="plain">--input <replaceable>DESKTOP-FILE</replaceable></arg>
<arg choice="plain">--output <replaceable>JSON-FILE</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>desktoptojson</command>
<group choice="req">
<arg choice="plain">--version</arg>
<arg choice="plain">--help</arg>
</group>
</cmdsynopsis>

</refsynopsisdiv>




<refsect1>
<title>Description</title>

<para>The KService framework uses information contained in <filename class="extension">.desktop</filename> files to locate services, including plugins for Qt5-based applications and libraries.  The Qt5 plugin system, however, uses JSON data embedded in the plugin itself.  <command>desktoptojson</command> allows the information contained in a <filename class="extension">.desktop</filename> file to also be used as the embedded data for a Qt5 plugin by converting the <filename class="extension">.desktop</filename> file entries into JSON data.</para>

<para>The generated JSON data is a JSON object that maps the entries from the <literal>[Desktop Entry]</literal> group of the <filename class="extension">.desktop</filename> file.  Any other groups are ignored.  Most entries are just converted to JSON strings, but certain entries (such as <literal>Hidden</literal> and <literal>X-KDE-PluginInfo-EnabledByDefault</literal>) are known to be boolean values and converted as such, and similarly some (such as <literal>X-KDE-ServiceTypes</literal> and <literal>X-KDE-PluginInfo-Depends</literal>) are always converted to arrays of strings.</para>
</refsect1>



<refsect1>
<title>Options</title>
<variablelist>

<varlistentry>
  <term><option>--input <replaceable>DESKTOP-FILE</replaceable></option></term>
<listitem>
<para>The <filename class="extension">.desktop</filename> file to convert.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>--output <replaceable>JSON-FILE</replaceable></option></term>
<listitem>
<para>The file to write the generated JSON data to.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>--help</option></term>
<listitem>
<para>Show a brief help text.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>--version</option></term>
<listitem>
<para>Show version information.</para>
</listitem>
</varlistentry>

</variablelist>
</refsect1>



<refsect1>
<title>Usage</title>
<para>
Most users of this utility will use the CMake macro
<function>kservice_desktop_to_json</function> as part of the process of building
a plugin.
<programlisting language="cmake">
<![CDATA[
add_library(myplugin MODULE ${myplugin_SRCS})
kservice_desktop_to_json(myplugin myplugin.desktop)
]]>
</programlisting>
This will produce the JSON file <filename>myplugin.json</filename>, which can be
referenced from the <function>K_PLUGIN_FACTORY_WITH_JSON</function> or
<function>Q_PLUGIN_METADATA</function> macros.
</para>
</refsect1>



<refsect1>
<title>Bugs</title>
<para>There are probably tons of bugs. Use <ulink url="http://bugs.kde.org">KDE's bugtracker</ulink> to report them.</para>
</refsect1>

</refentry>



