1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
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. 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*.
Publishing a compiled component
-------------------------------
Publishing a compiled 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 *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 <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/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.
|