~nik90/component-store/fix-debian-packaging

Contributing a component to the Community store

===============================================

 

To publish an Ubuntu SDK component to the Community store, you will need a `Launchpad account <https://help.launchpad.net/YourAccount/NewAccount>`_, and you will need to be familiar with `using bzr to push code to Launchpad <https://help.launchpad.net/Code/UploadingABranch>`_.

 

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. Then, submit the component to the community store with *ucs submit lp:~username/project/branch*, passing the name of the branch.

 

So, your branch should look like: ::

 

    qml/

        MyComponent.qml

        required_image.png

        included_script.js

 

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 *branch name* is the name of the component itself; 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/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 branch name and QML file name be the same thing.

 

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/ComponentName

 

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

 

    $ ucs submit lp:~username/project/ComponentName

    (submitting to community repository)

    Checking Launchpad branch lp:~username/project/ComponentName

    Checks passed OK

    Calculated package summary data

    Updating master record

    Component username/ComponentName updated successfully

 

It should then be visible to *ucs search*.

 

Publishing a compiled component

-------------------------------

 

Publishing a compied component is a little more complicated, for CPU architecture reasons. Your component must be `an Extension Plugin <http://doc.qt.io/qt-5/qtqml-tutorials-extending-qml-example.html#chapter-6-writing-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 *bin* folder, and in it put a folder for each architecture, named for the GNU architecture triplet, and then the *.so* file within. So: ::

 

    /bin

        /x86_64-linux-gnu

                         /libMyComponent.so

        /i386-linux-gnu

                         /libMyComponent.so

        /arm-linux-gnueabihf

                         /libMyComponent.so

 

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

 

The *branch name* is the name of the component itself; your component is expected to use `qmlRegisterType <http://doc.qt.io/qt-5/qqmlextensionplugin.html#details>`_ to provide QML Item types. So, if you are Launchpad user *sil*, and you push your component to *lp:~sil/SomeProject/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 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/ComponentName

 

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

 

    $ ucs submit lp:~username/project/ComponentName

    (submitting to community repository)

    Checking Launchpad branch lp:~username/project/ComponentName

    Checks passed OK

    Calculated package summary data

    Updating master record

    Component username/ComponentName updated successfully

 

It should then be visible to *ucs search*.