usage.rst 4.67 KB
Newer Older
Brian Douglass's avatar
Brian Douglass committed
1
2
3
4
5
6
7
8
.. _usage:

Usage
=====

Getting Started
---------------

Brian Douglass's avatar
Brian Douglass committed
9
At this point it is assumed that you have completed the :ref:`installation
wayneoutthere's avatar
wayneoutthere committed
10
11
process <install>`

12
13
To find out all supported command line arguments run ``clickable --help``.

14
15
You can get started with using Clickable with an existing Ubuntu Touch app.
You can use Clickable with apps generated from the old Ubuntu Touch SDK IDE
Brian Douglass's avatar
Brian Douglass committed
16
or you can start fresh by running ``clickable create`` which is outlined in more
wayneoutthere's avatar
wayneoutthere committed
17
detail on the previous :ref:`getting started <getting-started>` page.
Brian Douglass's avatar
Brian Douglass committed
18

19
20
To run the default set of commands, simply run ``clickable`` in the root
directory of your app's code. Clickable will attempt to auto detect which
21
:ref:`builder <builders>` is able to build your app.
wayneoutthere's avatar
wayneoutthere committed
22

23
24
Note: The first time you run ``clickable`` in your app directory,
it will download a new Docker container which is about 1GB in size - so
25
26
plan your time and data transfer environment accordingly. This will only happen
the first time you build your app for a specific architecture and when you run
27
``clickable update-images``.
Brian Douglass's avatar
Brian Douglass committed
28

29
Running the default commands will:
Brian Douglass's avatar
Brian Douglass committed
30

31
32
33
34
1) Build the app
2) Build the click package (can be found in the build directory)
3) Uninstall the app from your phone
4) Install the newly built app on your phone
35
5) Kill the app on the phone (if already running)
Brian Douglass's avatar
Brian Douglass committed
36
37
6) Launch the app on your phone

38
By default the device is accessed using ADB, see below if you want to use SSH)
39

Brian Douglass's avatar
Brian Douglass committed
40
Note: ensure your device is in `developer mode <http://docs.ubports.com/en/latest/userguide/advanceduse/adb.html?highlight=mode#enable-developer-mode>`__
41
42
for the app to be installed when using ADB or `enable ssh <http://docs.ubports.com/en/latest/userguide/advanceduse/ssh.html>`__
when using SSH.
wayneoutthere's avatar
wayneoutthere committed
43

44
45
Configuration
-------------
46
47
48
One can specify the path to a :ref:`project config file <project-config>`
with ``--config``. If not
specified, Clickable will look for an optional configuration file called
49
50
``clickable.yaml`` and then ``clickable.json`` in the current and all
parent directories.
51
If there is none, Clickable will
52
53
ask if it should attempt to detect the type of app and choose a fitting
:ref:`builder <builders>` with default configuration.
54

Brian Douglass's avatar
Brian Douglass committed
55
56
.. _ssh:

57
Connecting to a device over SSH
Brian Douglass's avatar
Brian Douglass committed
58
59
-------------------------------

60
61
By default the device is connected to via ADB.
If you want to access a device over SSH you need to either specify the device
62
IP address or hostname on the command line (ex: ``clickable logs --ssh 192.168.1.10`` ) or you
Brian Douglass's avatar
Brian Douglass committed
63
64
can use the ``CLICKABLE_SSH`` env var. Make sure to `enable ssh <http://docs.ubports.com/en/latest/userguide/advanceduse/ssh.html>`__
on your device for this to work.
Brian Douglass's avatar
Brian Douglass committed
65
66

.. _multiple-devices:
Brian Douglass's avatar
Brian Douglass committed
67
68
69
70

Multiple connected devices
--------------------------

71
72
By default Clickable assumes that there is only one device connected to your
computer via ADB. If you have multiple devices attached to your computer you
Brian Douglass's avatar
Brian Douglass committed
73
can specify which device to install/launch/etc on by using the flag
Brian Douglass's avatar
Brian Douglass committed
74
``--serial-number`` or ``-s`` for short. You can get the serial number
75
by running ``clickable devices``.
76

77
78
79
80
81
App Manifest
------------

The ``architecture`` and ``framework`` fields in the ``manifest.json`` need to be set according
to the architecture the app is build for (``--arch``) and the minimum framework version it
82
requires, e.g. depending on the QT Version (:ref:`qt_version <project-config-qt_version>`).
83
84
85
86
87
88
To let Clickable automatically set those fields, leave them empty or set them to
``@CLICK_ARCH@`` and ``@CLICK_FRAMEWORK@`` respectively.

Note: The app templates provided by Clickable make use of CMake's ``configure()`` to set
the fields in the ``manifest.json``.

89
90
91
Advanced Usage
--------------

92
93
94
.. _lxd:

Running Clickable in an LXD container
95
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
96
97
98

It is possible to run ``clickable`` in a container itself, using ``lxd``. This is not using ``--container-mode``, but allowing ``clickable`` to create docker containers as normal, but inside the existing ``lxd`` container. This may fail with a permissions error when mounting ``/proc``:

99
100
101
.. code-block:: bash

   docker: Error response from daemon: OCI runtime create failed: container_linux.go:349: starting container process caused "process_linux.go:449: container init caused \"rootfs_linux.go:58: mounting \\\"proc\\\" to rootfs \\\"/var/lib/docker/vfs/dir/bffeb203fe06662876a521b1bea3b74e4d5c6ea3535352215c199c75836aa925\\\" at \\\"/proc\\\" caused \\\"permission denied\\\"\"": unknown.
102
103
104
105
106
107
108
109

If this error occurs then ``lxd`` needs to be `configured to allow nested containers <https://stackoverflow.com/questions/46645910/docker-rootfs-linux-go-permission-denied-when-mounting-proc>` on the host:

.. code-block:: bash

   lxc stop your-container-name
   lxc config set your-container-name security.nesting true
   lxc start your-container-name