Add-on repositories: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
>NedBot
m (Robot: Cosmetic changes)
No edit summary
(24 intermediate revisions by 9 users not shown)
Line 1: Line 1:
{{DevsHeader|'''XBMC Add-on development'''}}
{{mininav|[[Development]]|[[Add-on development]]}}
See this [[HOW-TO: Create a Repository to host your Add-on]]


Beginning with Dharma, XBMC includes an interface to browse remote repositories where add-ons can be retrieved. The model is similar to the way many current Linux distributions work, whereby there is a "main" repository that is the default, and additional ones may be added by the user. The [[Official Add-on Repository]] is included with XBMC by default and is maintained by the XBMC team.


After you have created your repository, consider adding it to the [[3rd party add-on repositories]] list.
Beginning with Dharma, Kodi includes an interface to browse remote repositories where add-ons can be retrieved. The model is similar to the way many current Linux distributions work, whereby there is a "main" repository that is the default, and additional ones may be added by the user. The [[Official_add-on_repository|Official Add-on Repository]] is included with Kodi by default and is maintained by the Kodi team.
 
After you have created your repository, consider adding it to the [[Unofficial add-on repositories]] list.


== Ingredients for a Repository ==
== Ingredients for a Repository ==
Line 18: Line 18:
   addon.id
   addon.id
     addon.id-x.y.z.zip
     addon.id-x.y.z.zip
     changelog-x.y.z.txt
     ...
    fanart.jpg
    icon.png
   addon2.id
   addon2.id
     addon2.id-x.y.z.zip
     addon2.id-x.y.z.zip
     changelog-x.y.z.txt
     ...
    fanart.jpg
 
    icon.png
In addition, each add-on directory should contain icon.png, fanart.jpg, changelog-x.y.z.txt and all files from the [[Addon.xml#.3Cassets.3E]] element.


* addon.id should be the same as the addon's id, which is expected to be unique.
* addon.id should be the same as the addon's id, which is expected to be unique.
Line 31: Line 29:


== Addons.xml ==
== Addons.xml ==
XBMC expects to fetch a master xml file that contains the information for each add-on inside the repo. This file is named addons.xml - it can be placed external to the main repository of add-on files if you wish. This file merely encapsulates the other addon.xml files in an <addons> tag. See below for the basic structure:
Kodi expects to fetch a master xml file that contains the information for each add-on inside the repo. This file is named addons.xml - it can be placed external to the main repository of add-on files if you wish. This file merely encapsulates the other addon.xml files in an <addons> tag. See below for the basic structure:
<source lang="xml">
<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<addons>
<addons>
Line 45: Line 43:
   </addon>
   </addon>
</addons>
</addons>
</source>
</syntaxhighlight>


== Repository Add-on ==
== Repository Add-on ==
Repositories are distributed just like any other add-on. In order for you to browse one in XBMC, you'll need to [[Add-ons for XBMC (Developement)|create an add-on]] and install it. The repository addon extends the xbmc.addon.repository extension point, so in addition to the general XML structure and icons required for an icon, you'll need an 'extension' block as follows:
Repositories are distributed just like any other add-on. In order for you to browse one in Kodi, you'll need to [[Add-on_development|create an add-on]] and install it. The repository addon extends the xbmc.addon.repository extension point, so in addition to the general XML structure, you'll need an 'extension' block as follows:
<source lang="xml">
<syntaxhighlight lang="xml" enclose="div">
   <extension point="xbmc.addon.repository"
   <extension point="xbmc.addon.repository">
              name="Official XBMC.org Add-on Repository">
     <info>https://example.com/addons/addons.xml</info>
     <info compressed="true">http://mirrors.xbmc.org/addons/dharma-pre/addons.xml</info>
     <checksum>https://example.com/addons/addons.xml.md5</checksum>
     <checksum>http://mirrors.xbmc.org/addons/dharma-pre/addons.xml.md5</checksum>
     <datadir>https://example.com/addons/</datadir>
     <datadir zip="true">http://mirrors.xbmc.org/addons/dharma-pre</datadir>
   </extension>
   </extension>
</source>
</syntaxhighlight>


=== info ===
=== info ===
URL to the main xml file, compressed="true" parameter specifies whether or not the xml should be fetched with compression (gzip) enabled.
URL to the main xml file.
 
When fetching the file, Kodi will request a gzip encoded response. If the server for some reason does not support gzip encoding, it ''may'' be pre-gzipped, in which case it must have a .gz ending ending.
 
Note: Kodi v15 and older do not support pre-gzipped files and must specify the attribute compressed="true" to request gzip content encoding.


=== checksum ===
=== checksum ===
An MD5 checksum file of the main xml file. If present, XBMC verifies the addons.xml file against this MD5. This is the mechanism that XBMC uses to decide whether we need to fetch the full XML file to verify whether updates are required. If the MD5 file has changed we fetch the full info file. If not, we don't. Thus, in order for automatic updates to work, you must ensure that you have the checksum file in place.
A text file that identifies the content of <code><info></code>.
 
Before fetching the full info file, Kodi will fetch the "checksum" and compare it to the previously fetched one. If changed, the info file will be fetched.
 
Note: for historical reason it is called "checksum", but it is not verified and not required to be a checksum as long as it is changed whenever addons.xml has changed.


=== datadir ===
=== datadir ===
URL to the root directory that contains the addons (i.e. the directory holding the addon.id subdirectories). If the zip attribute is set to true, then XBMC downloads addons via /datadir/addon.id/addon.id-x.y.z.zip. If zip is set to false, then XBMC assumes that each addon.id directory simply contains the addon itself, i.e. /datadir/addon.id/files for addon. Online repositories should always have zip set to true, both for efficiency of download and for the protection that .zip offers by way of verifying the download (i.e. can we unzip it).
URL to the root directory that contains the addons (i.e. the directory holding the addon.id subdirectories). The location of the zip files should be /datadir/addon.id/addon.id-x.y.z.zip.
If the <code>zip</code> attribute (Note: this feature has been dropped in v17 Krypton) is set to false, then Kodi assumes that each addon.id directory simply contains the addon itself, i.e. /datadir/addon.id/files for addon. Online repositories should always have zip set to true, both for efficiency of download and for the protection that .zip offers by way of verifying the download (i.e. can we unzip it).
 
== Security ==
 
We '''highly''' recommend you to enable SSL on your HTTP server and only use https URIs for your repository. Otherwise, you expose yourself and users of your repository to a great risk as they can easily be served malicious add-ons. Kodi writes a warning to the log file if you do not use https URIs starting with Leia.
 
== Repository Tools ==
 
Once the individual add-ons have been created, the repository itself can be put together by a script.
The script will package up your add-ons from your source folders or it can fetch the sources directly from a Git repository.
* [https://raw.githubusercontent.com/chadparry/kodi-repository.chad.parry.org/master/tools/create_repository.py Download the <tt>create_repository.py</tt> script from GitHub with this link] or with this command:
wget https://raw.githubusercontent.com/chadparry/kodi-repository.chad.parry.org/master/tools/create_repository.py && chmod +x create_repository.py
* Run the script, and pass it the location of your add-ons. The location can be a local folder, a local ZIP file, or a Git repository URL.
For example, if you have one zipped add-on and one add-on folder, then the following command will create the add-on repository in the current directory:
./create_repository.py ~/my.spectacular.project.zip ~/development.project/
* The <tt>--datadir</tt> option can specify a different directory for the repository. The <tt>--compressed</tt> flag uses gzip to pre-compress the addons.xml file. Also, a Git URL can have an optional <tt>#''branch''</tt> or <tt>#''tag''</tt> and optional <tt>:''path''</tt> at the end to designate the add-on's location within the repository.
For example, if you are publishing two add-ons that are both stored within separate Git repositories, then the following command would create a compressed repository:
<nowiki>./create_repository.py --datadir=~/html/software/kodi --compressed \
    https://github.com/chadparry/kodi-repository.chad.parry.org.git#release-1.0.0:repository.chad.parry.org \
    https://github.com/chadparry/kodi-plugin.program.remote.control.browser.git:plugin.program.remote.control.browser</nowiki>
* Every time you update an add-on, run the script again.


== See also ==
== See also ==
Line 72: Line 98:
* [[Skinning]]
* [[Skinning]]


[[Category:XBMC Manual]]
 
[[Category:Add-on development]]
[[Category:Add-on development]]
[[Category:Team XBMC specific notes]]

Revision as of 06:33, 11 July 2020

Home icon grey.png   ▶ Development ▶ Add-on development ▶ Add-on repositories


Beginning with Dharma, Kodi includes an interface to browse remote repositories where add-ons can be retrieved. The model is similar to the way many current Linux distributions work, whereby there is a "main" repository that is the default, and additional ones may be added by the user. The Official Add-on Repository is included with Kodi by default and is maintained by the Kodi team.

After you have created your repository, consider adding it to the Unofficial add-on repositories list.

Ingredients for a Repository

Repositories were created with the idea that they should be simple and easy enough to setup for anyone interested. The basic requirements are as follows:

  • An HTTP server. Any should work.
  • Some add-ons.
  • A master xml file. This file contains metadata about all available add-ons.
  • A checksum of the above file.
  • A repository add-on for distribution. This allows you to share your repository with others.

Directory Structure

 addon.id
    addon.id-x.y.z.zip
    ...
 addon2.id
    addon2.id-x.y.z.zip
    ...

In addition, each add-on directory should contain icon.png, fanart.jpg, changelog-x.y.z.txt and all files from the Addon.xml#.3Cassets.3E element.

  • addon.id should be the same as the addon's id, which is expected to be unique.
  • x.y.z is the addon's version, the same should be listed in its version attribute.

Addons.xml

Kodi expects to fetch a master xml file that contains the information for each add-on inside the repo. This file is named addons.xml - it can be placed external to the main repository of add-on files if you wish. This file merely encapsulates the other addon.xml files in an <addons> tag. See below for the basic structure:

<?xml version="1.0" encoding="UTF-8"?>
<addons>
  <addon
    id="sample.addon1"
    ...
  </addon>

  <addon
    id="sample.addon2"
    ...
  </addon>
</addons>

Repository Add-on

Repositories are distributed just like any other add-on. In order for you to browse one in Kodi, you'll need to create an add-on and install it. The repository addon extends the xbmc.addon.repository extension point, so in addition to the general XML structure, you'll need an 'extension' block as follows:

  <extension point="xbmc.addon.repository">
    <info>https://example.com/addons/addons.xml</info>
    <checksum>https://example.com/addons/addons.xml.md5</checksum>
    <datadir>https://example.com/addons/</datadir>
  </extension>

info

URL to the main xml file.

When fetching the file, Kodi will request a gzip encoded response. If the server for some reason does not support gzip encoding, it may be pre-gzipped, in which case it must have a .gz ending ending.

Note: Kodi v15 and older do not support pre-gzipped files and must specify the attribute compressed="true" to request gzip content encoding.

checksum

A text file that identifies the content of <info>.

Before fetching the full info file, Kodi will fetch the "checksum" and compare it to the previously fetched one. If changed, the info file will be fetched.

Note: for historical reason it is called "checksum", but it is not verified and not required to be a checksum as long as it is changed whenever addons.xml has changed.

datadir

URL to the root directory that contains the addons (i.e. the directory holding the addon.id subdirectories). The location of the zip files should be /datadir/addon.id/addon.id-x.y.z.zip. If the zip attribute (Note: this feature has been dropped in v17 Krypton) is set to false, then Kodi assumes that each addon.id directory simply contains the addon itself, i.e. /datadir/addon.id/files for addon. Online repositories should always have zip set to true, both for efficiency of download and for the protection that .zip offers by way of verifying the download (i.e. can we unzip it).

Security

We highly recommend you to enable SSL on your HTTP server and only use https URIs for your repository. Otherwise, you expose yourself and users of your repository to a great risk as they can easily be served malicious add-ons. Kodi writes a warning to the log file if you do not use https URIs starting with Leia.

Repository Tools

Once the individual add-ons have been created, the repository itself can be put together by a script. The script will package up your add-ons from your source folders or it can fetch the sources directly from a Git repository.

wget https://raw.githubusercontent.com/chadparry/kodi-repository.chad.parry.org/master/tools/create_repository.py && chmod +x create_repository.py
  • Run the script, and pass it the location of your add-ons. The location can be a local folder, a local ZIP file, or a Git repository URL.

For example, if you have one zipped add-on and one add-on folder, then the following command will create the add-on repository in the current directory:

./create_repository.py ~/my.spectacular.project.zip ~/development.project/
  • The --datadir option can specify a different directory for the repository. The --compressed flag uses gzip to pre-compress the addons.xml file. Also, a Git URL can have an optional #branch or #tag and optional :path at the end to designate the add-on's location within the repository.

For example, if you are publishing two add-ons that are both stored within separate Git repositories, then the following command would create a compressed repository:

./create_repository.py --datadir=~/html/software/kodi --compressed \
     https://github.com/chadparry/kodi-repository.chad.parry.org.git#release-1.0.0:repository.chad.parry.org \
     https://github.com/chadparry/kodi-plugin.program.remote.control.browser.git:plugin.program.remote.control.browser
  • Every time you update an add-on, run the script again.

See also

Development: