Commit d208d3b8 authored by Brian Douglass's avatar Brian Douglass
Browse files

Added docs

parent 42bf6b64
......@@ -2,3 +2,4 @@ parts
prime
stage
tmp
_build
......@@ -4,16 +4,6 @@ Compile, build, and deploy Ubuntu Touch click packages all from the command line
## Install
For a great tutorial on how to get started with clickable, check out the one in the
[UBports Wiki](https://wiki.ubports.com/wiki/Set-up-an-app-development-environment).
### Prerequisites
* `adb` For installing and running commands on your device
* `lxd` For building any binaries and the click package
* After installing lxd make sure you run `lxd init`
* `docker` For building any binaries and the click package (alternative to lxd)
### Via PPA (Ubuntu)
* Add the PPA to your system: `sudo add-apt-repository ppa:bhdouglass/clickable`
......@@ -22,100 +12,25 @@ For a great tutorial on how to get started with clickable, check out the one in
### Via Snap
* Make sure you have the dependencies `adb` and `docker` insalled
* Download the latest version from the OpenStore: <https://open.uappexplorer.com/snap/clickable>
* Install the snap: `sudo snap install --force-dangerous --classic <path/to/snap>`
### Post Setup
If you want to use lxd for compiling, run `clickable setup-lxd` to create a
container to build clicks and binaries in.
## Usage
1) Create a `clickable.json` file in your project root with the contents:
```
{
"package": "full package name (appname.developer) [Optional, will be read from manifest.json if left blank]",
"app": "app name (for auto launch) [Optional, will be read from manifest.json if left blank]",
"sdk": "ubuntu-sdk-15.04 [Optional]",
"arch": "armhf [Optional, default is armhf, or specify as a cli arg (ex: --arch="armhf")]",
"prebuild": "custom prebuild command [Optional]",
"template": "pure-qml-qmake,qmake,pure-qml-cmake,cmake,custom,cordova,pure [Required if not specified as a cli arg (ex: --template="cmake")]",
"premake": "custom command before make is run [Optional]",
"build": "custom build command [Required if using custom template]",
"postbuild": "custom command for after build, pre click build [Optional]",
"launch": "custom launch command [Optional]",
"ssh": "IP of device to install to (if not using phablet-shell) [Optional]",
"dir": "./path/to/build/dir/ [Optional, default is ./build/]",
"kill": "Name of the process to kill (useful for killing the running app, then relaunching it) [Optional, if not specified it will be assumed]",
"scripts": "An object that lists custom scripts to run, see below for more details",
"chroot": "Whether or not to use a chroot (default is False, which means use an lxd container) [Optional]",
"default": "A list of space separated sub-commands to run when no sub-commands are specified",
"dependencies": "An array of dependencies that will be installed in the build container",
"ignore": "An array of files to ignore when building a 'pure' template [Optional, only for pure templates]",
"make_jobs": "number of jobs to use when running make, equivalent to make's -j option [Optional, if missing `make -j` will be run]",
}
```
2) From the root directory of your project you have the following sub-commands available:
* `clickable kill` - Kills a running process (specified by the config). Using this you can relaunch your app.
* `clickable clean` - Cleans out the build dir
* `clickable build` - Builds the project using the specified template, build dir, and build commands
* `clickable click-build` - Takes the built files and compiles them into a click package (you can find it in the build dir)
* `clickable install` - Takes a built click package and installs it on a device
* `clickable launch` - Launches the app on a device
* `clickable logs` - Follow the apps logfile on the device
* `clickable setup-lxd` - Setup an lxd container for building in
* `clickable <custom command>` - Runs a custom command specified in the "scripts" config
* `clickable <custom command> --device` - Runs a custom command specified in the "scripts" config on the device
* `clickable` - Runs the default sub-commands specified in the "default" config
You can combine the commands together like `clickable build click_build install launch`
## Connecting to a device over ssh
By default the device is connected to via adb and phablet-shell.
If you want to access a device over ssh you need to either specify the device
IP address on the command line (ex: `clickable logs --ip 192.168.1.10`) or you
can specify the IP address in the clickable.json file's `ssh` property.
## LXD Container Building
Clickable supports building in a lxd container. In order to use them you first
need to setup a container using `clickable setup-lxd` (once for each target architecture).
This requires that you have `usdk-target` command installed. If you have the Ubuntu
SDK IDE installed you may already have this command installed, but the version
included in this repo is more up to date than the Ubuntu SDK IDE verion. If
you are not running Ubuntu or do not already have the SDK IDE setup you will
need to use the usdk-target binary included in this repo.
## Docker Container Building
Clickable supports building in a docker container. To use them you just need
to have docker installed on your system and running and use the `--docker`
argument when running clickable.
## Chroot Building
Clickable supports the legacy chroots for building apps. In order to use them just
specify `"chroot": true` in your clickable.json. This requires that you already
have a chroot setup (via `click chroot create...`).
Run `clickable setup-docker` to ensure that docker is configured for use with clickable.
## Templates
## Docs
* `pure-qml-qmake` - A purely qml qmake project
* `qmake` - A project that builds using qmake (has more than just QML)
* `pure-qml-cmake` - A purely qml cmake project
* `cmake` - A project that builds using cmake (has more than just QML)
* `custom` - The custom build command will be used
* `cordova` - A project that builds using cordova
* `pure` - A project that does not need to be compiled. All files in the project root will be copied into the click
- [Usage](http://clickable.bhdouglass.com/usage.html)
- [Install](http://clickable.bhdouglass.com/install.html)
- [Commands](http://clickable.bhdouglass.com/commands.html)
- [clickable.json Format](http://clickable.bhdouglass.com/clickable-json.html)
- [Build Templates](http://clickable.bhdouglass.com/build-templatess.html)
## License
Copyright (C) 2016 [Brian Douglass](http://bhdouglass.com/)
Copyright (C) 2017 [Brian Douglass](http://bhdouglass.com/)
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3, as published
by the Free Software Foundation.
......
......@@ -21,6 +21,7 @@ import xml.etree.ElementTree as ElementTree
# TODO include phablet-shell
# TODO include phablet-config
# TODO update to python3
# TODO add option to run inside a container
class Colors:
......@@ -172,6 +173,9 @@ class Config(object):
if isinstance(self.dependencies, basestring):
self.dependencies = self.dependencies.split(' ')
if type(self.default) == list:
self.default = ' '.join(self.default)
def __getattr__(self, name):
return self.config[name]
......
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXPROJ = clickable
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
.. _build-templates:
Build Templates
===============
+----------------+
| pure-qml-qmake |
+----------------+
A purely qml qmake project.
+-------+
| qmake |
+-------+
A project that builds using qmake (has more than just QML).
+----------------+
| pure-qml-cmake |
+----------------+
A purely qml cmake project
+-------+
| cmake |
+-------+
A project that builds using cmake (has more than just QML)
+--------+
| custom |
+--------+
A custom build command will be used.
+---------+
| cordova |
+---------+
A project that builds using cordova
+------+
| pure |
+------+
A project that does not need to be compiled. All files in the project root will be copied into the click.
+--------+
| python |
+--------+
A project that uses python and does not need to be compiled.
.. _clickable-json:
clickable.json Format
=====================
Example:
.. code-block:: javascript
{
"template": "cmake",
"scripts": {
"test": "make test"
},
"dependencies": [
"libpoppler-qt5-dev"
]
}
+---------+
| package |
+---------+
The full package name (appname.developer). This is optional and will be read
from manifest.json if left blank.
+-----+
| app |
+-----+
The app name (appname.developer). This is optional and will be read
from manifest.json if left blank.
+-----+
| sdk |
+-----+
Optional, Defaults to `ubuntu-sdk-15.04`
+------+
| arch |
+------+
Optional, the default is armhf. You may also specify this as a cli arg
(ex: ``--arch="armhf"``)
+----------+
| prebuild |
+----------+
Optional, a custom command to run before a build.
+----------+
| template |
+----------+
Optional, see :ref:`build template <build-templates>` for the full list of options.
If left blank the template will be auto detected.
+---------+
| premake |
+---------+
Optional, a custom command to execute before make is run.
+-------+
| build |
+-------+
Optional, a custom command to run instead of the default build. If using
the `custom` template this is required.
+-----------+
| postbuild |
+-----------+
Optional, a custom command to execute after build and before click build.
+--------+
| launch |
+--------+
Optional, a custom command to launch the app.
+-----+
| ssh |
+-----+
Optional, the IP of the device you wish to install and launch the app on.
+-----+
| dir |
+-----+
Optional, a custom build directory. Defaults to ``./build/``
+------+
| kill |
+------+
Optional, a custom process name to kill (useful for killing the running app,
then relaunching it). If left blank the process name will be assumed.
+---------+
| scripts |
+---------+
Optional, an object detailing custom commands to run. For example:
.. code-block:: javascript
{
"test": "make test",
"echo": "echo Hello World"
}
To run the command on the device use the ``--device`` argument ( ex: ``clickable test --device`` ).
+--------+
| chroot |
+--------+
Optional, whether or not to use a chroot to build the app. Default is to use
docker to build the app. Chroots are deprecated and their support will be removed
in a future version of clickable.
+-----+
| lxd |
+-----+
Optional, whether or not to use a lxd container to build the app. Default is to use
docker to build the app. LXD is deprecated and its support will be removed
in a future version of clickable.
+---------+
| default |
+---------+
Optional, a list of space separated sub-commands to run when no sub-commands are
specified. Defaults to ``kill clean build click-build install launch``.
+--------------+
| dependencies |
+--------------+
Optional, a list of dependencies that will be installed in the build container.
These will be assumed to be `dependencie:arch` unless `specificDependencies`
is set to `true`.
+--------+
| ignore |
+--------+
Optional, a list of files to ignore when building a `pure` template
+-----------+
| make_jobs |
+-----------+
Optional, the number of jobs to use when running make, equivalent to make's `-j`
option. If left blank this defaults to the number of cpus your computer has.
.. _commands:
Commands
========
From the root directory of your project you have the following sub-commands available:
You can combine the commands together like ``clickable build click_build install launch``
``clickable``
Runs the default sub-commands specified in the "default" config
``clickable kill``
Kills a running process (specified by the config). Using this you can relaunch your app.
``clickable clean``
Cleans out the build dir.
``clickable build``
Builds the project using the specified template, build dir, and build commands.
``clickable click-build``
Takes the built files and compiles them into a click package (you can find it in the build dir).
``clickable install``
Takes a built click package and installs it on a device.
``clickable install --click ./path/to/click/app.click``
Installs the specified click package on the device
``clickable launch``
Launches the app on a device.
``clickable launch --app <app name>``
Launches the specified app on a device.
``clickable logs``
Follow the apps log file on the device.
``clickable setup-docker``
Configure docker for use with clickable.
``clickable display-on``
Turns on the device's display and keeps it on until you hit CTRL+C.
``clickable no-lock``
Turns off the device's display timeout.
``clickable <custom command>``
Runs a custom command specified in the "scripts" config
``clickable <custom command> - -device``
Runs a custom command specified in the "scripts" config on the device.
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# clickable documentation build configuration file, created by
# sphinx-quickstart on Fri Dec 15 10:32:02 2017.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = 'clickable'
copyright = '2017, Brian Douglass'
author = 'Brian Douglass'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '2.0.0'
# The full version, including alpha/beta/rc tags.
release = '2.0.0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# This is required for the alabaster theme
# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
html_sidebars = {
'**': [
'relations.html', # needs 'show_related': True theme option to display
'searchbox.html',
]
}
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'clickabledoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'clickable.tex', 'clickable Documentation',
'Brian Douglass', 'manual'),
]
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'clickable', 'clickable Documentation',
[author], 1)
]
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'clickable', 'clickable Documentation',
author, 'clickable', 'Compile, build, and deploy Ubuntu Touch click packages all from the command line.',
'Miscellaneous'),
]
Clickable
=========
Compile, build, and deploy Ubuntu Touch click packages all from the command line.
Using Clickable
---------------