usage.rst 4.04 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>`

Brian Douglass's avatar
Brian Douglass committed
12 13
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
14
or you can start fresh by running ``clickable create`` which is outlined in more
wayneoutthere's avatar
wayneoutthere committed
15
detail on the previous :ref:`getting started <getting-started>` page.
Brian Douglass's avatar
Brian Douglass committed
16 17

To run the default set of sub-commands, simply run ``clickable`` in the root directory
18
of your app's code. Clickable will attempt to auto detect the
Brian Douglass's avatar
Brian Douglass committed
19
:ref:`build template <builders>` and other configuration options.
wayneoutthere's avatar
wayneoutthere committed
20

21 22 23 24 25
Note: The first time you run ``clickable`` in your app directory, behind the
scenes it will download a new Docker container which is about 1GB in size - so
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
``clickable update``.
Brian Douglass's avatar
Brian Douglass committed
26 27 28

Running the default sub-commands will:

29 30
1) Clean the build directory (by default ``./build/<arch_triplet>/app``)
2) Build the app
Brian Douglass's avatar
Brian Douglass committed
31
3) Build the click package (can be found in the build directory)
Brian Douglass's avatar
Brian Douglass committed
32
4) Install the app on your phone (By default this uses adb, see below if you want to use ssh)
Brian Douglass's avatar
Brian Douglass committed
33
5) Kill the running app on the phone
Brian Douglass's avatar
Brian Douglass committed
34 35
6) Launch the app on your phone

Brian Douglass's avatar
Brian Douglass committed
36
Note: ensure your device is in `developer mode <http://docs.ubports.com/en/latest/userguide/advanceduse/adb.html?highlight=mode#enable-developer-mode>`__
Brian Douglass's avatar
Brian Douglass committed
37 38
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
39

40 41
Configuration
-------------
42 43
It is recommend to specify a configuration file in the
:ref:`clickable.json format <clickable-json>` with ``--config``. If not
44
specified, clickable will look for an optional configuration file called
45 46 47
``clickable.json`` in the current directory. If there is none Clickable will
ask if it should attempt to detect the type of app and choose a fitting
:ref:`builder <builders>` with default configuration.
48

Brian Douglass's avatar
Brian Douglass committed
49 50
.. _ssh:

Brian Douglass's avatar
Brian Douglass committed
51 52 53 54 55
Connecting to a device over ssh
-------------------------------

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
56
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
57 58
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
59 60

.. _multiple-devices:
Brian Douglass's avatar
Brian Douglass committed
61 62 63 64 65 66 67

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

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
can specify which device to install/launch/etc on by using the flag
Brian Douglass's avatar
Brian Douglass committed
68
``--serial-number`` or ``-s`` for short. You can get the serial number
69
by running ``clickable devices``.
70

71 72 73
Advanced Usage
--------------

74 75 76
.. _lxd:

Running Clickable in an LXD container
77
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
78 79 80

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``:

81 82 83
.. 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.
84 85 86 87 88 89 90 91

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