Contributing a component to the Community store

To publish an Ubuntu SDK component to the Community store, you will need a Launchpad account, and you will need to be familiar with using bzr to push code to Launchpad.

Community components can be pure QML, or they can be compiled binary components.

Publishing a pure QML component

Create a branch on Launchpad (in any project of your choice) which is named how you plan to name the component, with a top-level qml folder, and put your QML file and any required assets for your component in that qml folder. Add an ubuntu_component_store.json file. Then, submit the component to the community store with ucs submit lp:~username/project/branch.

So, your branch should look like:

/qml/
     MyComponent.qml
     required_image.png
     included_script.js
/ubuntu_component_store.json

If your component does not have any external assets, it is fine to have a branch with qml/MyComponent.qml and nothing else in it. Your branch may also contain any other files you choose outside the qml top-level folder; these files are not installed with your component, but may provide useful guidance, READMEs, or other code for people who want to make changes to the component and contribute them back to you.

The name of the component itself is defined by ubuntu_component_store.json; the QML filename is what names the QML Item that it provides. So, if you are Launchpad user sil, and you push your component to lp:~sil/SomeProject/mything, it defines its own name in ubuntu_component_store.json as UsefulComponent, and it contains qml/RedRectangle.qml, an app developer will use it like this:

import QtQuick 2.0
import ubuntu_component_store.sil.UsefulComponent 1.0
....
MainView {
    RedRectangle {
        ....
    }
}

Most components should have component name and QML file name be the same thing to avoid confusion.

Do not publish two unrelated QML components in one UCS component; publish them separately, so they can be used separately.

Note

if you do not want to create a whole Launchpad project just for this component, you can push to a Launchpad “junk” branch: lp:~username/+junk/somename

Once your branch is created, publish it to the Community store with

$ ucs submit lp:~username/project/somename
(submitting to community repository)
Checking Launchpad branch lp:~username/project/somename
Checks passed OK
Calculated package summary data
Updating master record
Component username/ComponentName updated successfully

It should then be visible to ucs search.

Note

Once added to the community store, there is no way (yet) to remove your component.

Publishing a compiled component

Publishing a compiled component is a little more complicated, for CPU architecture reasons. Your component must be an Extension Plugin, “a plugin library to make it available to the QML engine as a new QML import module”. Creating such a plugin is currently beyond the scope of this document. (We are hoping to provide an Ubuntu SDK IDE template for creating such components with the proper filesystem layout; before then, the “App with QML Extension Library” option creates an appropriate type of component.)

You must compile your component for three different architectures: ARM, x86, and amd64 (for Ubuntu phones, the desktop emulator, and Ubuntu desktops). Once you have compiled it as such, you will have three different libMyComponent.so files.

Assemble a Launchpad branch with a top-level qmllib folder, and in it put a folder for each architecture, named for the GNU architecture triplet, and then the .so file within. So:

/qmllib
    /x86_64-linux-gnu
                     /libMyComponent.so
    /i386-linux-gnu
                     /libMyComponent.so
    /arm-linux-gnueabihf
                     /libMyComponent.so
/ubuntu_component_store.json

Add an ubuntu_component_store.json file to the root of the branch.

Your branch may contain any other files of your choice outside the /qmllib folder; in particular, it should contain the source code for the plugin so others can build it themselves if they choose!

The name of the component itself is defined by ubuntu_component_store.json; your component is expected to use qmlRegisterType to provide QML Item types. So, if you are Launchpad user sil, and you push your component to lp:~sil/SomeProject/Whatever, it defines its name in ubuntu_component_store.json as SomeComponent, and it registers a Triangle type, an app developer will use it like this:

import QtQuick 2.0
import ubuntu_component_store.sil.SomeComponent 1.0
....
MainView {
    Triangle {
        ....
    }
}

Do not publish two unrelated components in one UCS component; publish them separately, so they can be used separately.

Note

if you do not want to create a whole Launchpad project just for this component, you can push to a Launchpad “junk” branch: lp:~username/+junk/somename

Once your branch is created, publish it to the Community store with

$ ucs submit lp:~username/project/somename
(submitting to community repository)
Checking Launchpad branch lp:~username/project/somename
Checks passed OK
Calculated package summary data
Updating master record
Component username/ComponentName updated successfully

It should then be visible to ucs search.

A component can contain both qml and qmllib folders and so contain both QML parts and binary parts; both will be installed when a developer uses ucs install to install your component.

ubuntu_component_store.json

A community component must contain a file ubuntu_component_store.json describing metadata about the component. It must be valid JSON, with keys name, version, and description:

{
    "name": "GenericPodcastApp",
    "version": "1.0",
    "description": "A component which manages a podcast RSS feed, with playback and display of episodes"
}

Other keys may be added in future. Note that the public name of the component will be launchpadusername/name, where name is the name taken from ubuntu_component_store.json. The branch name in Launchpad is ignored.