.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "CLICK" "1" "2024-03-20" "0.5" "Click Packages"
.SH NAME
click \- package management tool for Ubuntu Touch
.SH SYNOPSIS
.sp
click command [options] [arguments]
.SH DESCRIPTION
.sp
\fIClick\fP is a packaging format for Ubuntu Touch applications, independent of
the packaging format used to deliver the underlying system.  The \fIclick\fP
program is the basic tool used to build, install, remove, and otherwise
manipulate these packages.
.sp
\fIclick\fP’s various functions are available via a number of commands,
described in detail below.
.sp
While \fIclick\fP supports per\-user installation, packages are normally unpacked
as a special \fBclickpkg\fP user, to ensure that applications cannot modify
their own code; it is a design goal to ensure that \fIclick\fP can be used to
install untrusted code which is then confined using \fI\%AppArmor\fP\&.  As such, \fIclick\fP should normally be
run as root (e.g. using \fBsudo\fP) when installing packages; it will drop
privileges as needed.
.SH COMMAND OVERVIEW
.INDENT 0.0
.INDENT 3.5
.sp
.EX
click build DIRECTORY
click buildsource DIRECTORY
click chroot
click contents PATH
click framework list
click hook install HOOK
click hook remove HOOK
click hook run\-system
click hook run\-user
click info PATH
click install PACKAGE\-FILE
click list
click pkgdir {PACKAGE\-NAME|PATH}
click register PACKAGE\-NAME VERSION
click unregister PACKAGE\-NAME [VERSION]
click verify PACKAGE\-FILE
.EE
.UNINDENT
.UNINDENT
.SH COMMANDS
.SS click build DIRECTORY
.sp
Build a Click package from the contents of DIRECTORY.  The build directory
must contain a JSON\-formatted manifest, described further in Click’s
file\-format documentation; by default, this is expected to be in
\fBmanifest.json\fP at the top level of the build directory.
.sp
The resulting \fB\&.click\fP file is written to the current directory, so to
avoid confusion you should generally ensure that your working directory is
not inside the build directory when running this command.
.sp
While it is possible to build a new version of a Click package by unpacking
and repacking an existing package, this is not normally recommended because
it requires some care to put the manifest file back in the right place.  It
is best to keep your application’s code in separate revision control rather
than relying on recovering it from packages.
.sp
Options:
.INDENT 0.0
.TP
.BI \-m \ PATH\fR,\fB \ \-\-manifest\fB= PATH
Read package manifest from PATH
(default: \fBmanifest.json\fP).
.TP
.BI \-I \ file\-pattern\fR,\fB \ \-\-ignore\fB= file\-pattern
Ignore the given shell\-pattern
when building the package.
The option may be repeated multiple
times to list multiple patterns to
exclude.
.TP
.B  \-\-no\-validate
Don’t run checks from click\-reviewers\-tools on
the resulting .click file.
.UNINDENT
.SS click buildsource DIRECTORY
.sp
Build a source package in \fB\&.tar.gz\fP format from the contents of DIRECTORY.
This allows you to distribute source code in the case where your package
contains compiled code (and so the Click package does not constitute its own
source).
.sp
The resulting \fB\&.tar.gz\fP file is written to the current directory, so to
avoid confusion you should generally ensure that your working directory is
not inside the build directory when running this command.
.sp
Options:
.INDENT 0.0
.TP
.BI \-m \ PATH\fR,\fB \ \-\-manifest\fB= PATH
Read package manifest from PATH
(default: \fBmanifest.json\fP).
.TP
.BI \-I \ file\-pattern\fR,\fB \ \-\-ignore\fB= file\-pattern
Ignore the given shell\-pattern
when building the package.
The option may be repeated multiple
times to list multiple patterns to
exclude.
.UNINDENT
.SS click chroot
.sp
Manage chroot environments for cross\-building Click packages.
.sp
Options:
.INDENT 0.0
.TP
.BI \-a \ ARCH\fR,\fB \ \-\-architecture \ ARCH
Set the target architecture.
.TP
.BI \-f \ FRAMEWORK\fR,\fB \ \-\-framework \ FRAMEWORK
Set the target framework (default:
ubuntu\-sdk\-13.10).
.TP
.BI \-s \ SERIES\fR,\fB \ \-\-series \ SERIES
Set the target series for
newly\-created chroots (default: a
series appropriate for the
framework).
This option is mainly for debugging;
use \-f instead.
.UNINDENT
.sp
Subcommands:
.INDENT 0.0
.TP
.B begin\-session SESSION
Begin a persistent chroot session.
.TP
.B create
Create a chroot.
.TP
.B destroy
Destroy a chroot.
.TP
.B end\-session SESSION
End a persistent chroot session.
.TP
.B install [\-n SESSION] PACKAGES
Install packages in the chroot.
.TP
.B maint [\-n SESSION] COMMAND ARGUMENTS
Run a maintenance command in the chroot.  Unlike \fBrun\fP, this runs its
command as root inside the chroot, and its effects on the chroot will
persist after \fBclick chroot maint\fP exits.
.sp
If a session name is given, run the command in that session.  The
session must previously have been created by \fBclick chroot
begin\-session\fP\&.
.TP
.B run [\-n SESSION] COMMAND ARGUMENTS
Run a program in the chroot.
.sp
If a session name is given, run the command in that session.  The
session must previously have been created by \fBclick chroot
begin\-session\fP\&.
.TP
.B upgrade [\-n SESSION]
Upgrade the chroot.
.UNINDENT
.SS click contents PATH
.sp
Display the contents of the Click package in PATH as a file listing.
.SS click framework list
.sp
Display a list of available frameworks as one framework per line.
.SS click hook install HOOK
.sp
Install files associated with HOOK for any Click packages that attach to it.
.sp
This is normally only called by maintainer scripts of system packages, by
way of dh_click(1).
.sp
Options:
.INDENT 0.0
.TP
.BI \-\-root\fB= PATH
Look for additional packages in PATH.
.UNINDENT
.SS click hook remove HOOK
.sp
Remove files associated with HOOK for any Click packages that attach to it.
.sp
This is normally only called by maintainer scripts of system packages, by
way of dh_click(1).
.sp
Options:
.INDENT 0.0
.TP
.BI \-\-root\fB= PATH
Look for additional packages in PATH.
.UNINDENT
.SS click hook run\-system
.sp
Run all system\-level hooks for all installed Click packages.  This is useful
when starting up from images with preinstalled packages which may not have
had their system\-level hooks run properly when building the image.
.sp
Options:
.INDENT 0.0
.TP
.BI \-\-root\fB= PATH
Look for additional packages in PATH.
.UNINDENT
.SS click hook run\-user
.sp
Run all user\-level hooks for all Click packages registered for a given user.
This is useful at session startup to catch up with packages that may have
been preinstalled and registered for all users.
.sp
Options:
.INDENT 0.0
.TP
.BI \-\-root\fB= PATH
Look for additional packages in PATH.
.TP
.BI \-\-user\fB= USER
Run user\-level hooks for USER (default: current
user).
.UNINDENT
.SS click info {PACKAGE\-NAME|PACKAGE\-FILE}
.sp
When given a package name (that is, a string containing no \fB/\fP
characters), display the manifest for that package, if it is registered for
the current user.
.sp
When given a path (that is, a string containing at least one \fB/\fP
character, or a string containing no \fB/\fP characters that is not a
registered package name), attempt to treat that as a path to a file
containing a Click package and display the manifest for that package.
.sp
Options:
.INDENT 0.0
.TP
.BI \-\-root\fB= PATH
Look for additional packages in PATH.
.TP
.BI \-\-user\fB= USER
List packages registered by USER (if you have
permission).
.UNINDENT
.SS click install PACKAGE\-FILE
.sp
Install the Click package in PACKAGE\-FILE.
.sp
This is a low\-level tool; to install a package as an ordinary user you
should generally use \fBpkcon install\-local PACKAGE\-FILE\fP or some
higher\-level user interface instead, which take care to use the correct set
of options.  (Do not use \fBsudo\fP when invoking \fBpkcon\fP, as it needs to
know the calling user.)
.sp
\fBclick install\fP may be used to preinstall a package in an image such that
it will be available to all users by default.  When doing this, you should
normally install it to one of the databases defined in
\fB/etc/click/databases/\fP other than the default of
\fB/var/lib/clickpkg\fP\&.  For example:
.INDENT 0.0
.INDENT 3.5
sudo click install –root=/custom/click –all\-users foo.click
.UNINDENT
.UNINDENT
.sp
The \fB\-\-force\-missing\-framework\fP option is necessary while working with
development versions of SDKs which have not yet put a framework declaration
in place.
.sp
You should always register installed packages either for a specific user or
for all users; if you do not do this then the packages may be
garbage\-collected later.  You can do this using the \fB\-\-user\fP or
\fB\-\-all\-users\fP options to this command, or using the \fBclick register\fP
command.
.sp
Options:
.INDENT 0.0
.TP
.BI \-\-root\fB= PATH
Install packages underneath PATH.
.TP
.B  \-\-force\-missing\-framework
Install despite missing system framework.
.TP
.BI \-\-user\fB= USER
Register package for USER.
.TP
.B  \-\-all\-users
Register package for all users.
.UNINDENT
.SS click list
.sp
Display a list of installed packages, either as one package per line with
each line containing a package name and version separated by a tab (the
default), or as a JSON array of manifests.
.sp
By default, \fBclick list\fP shows only packages registered for the current
user.  The \fB\-\-all\fP option causes it to show all installed packages,
regardless of user registrations.
.sp
Options:
.INDENT 0.0
.TP
.BI \-\-root\fB= PATH
Look for additional packages in PATH.
.TP
.B  \-\-all
List all installed packages.
.TP
.BI \-\-user\fB= USER
List packages registered by USER (if you have
permission).
.TP
.B  \-\-manifest
Format output as a JSON array of manifests.
.UNINDENT
.SS click pkgdir {PACKAGE\-NAME|PATH}
.sp
When given a package name (that is, a string containing no \fB/\fP
characters), display the directory where that package is installed, if it is
registered for the current user.
.sp
When given a path (that is, a string containing at least one \fB/\fP
character), attempt to treat that as a path to a file within a Click package
and print the top\-level directory where that package is installed, if one
exists.  This is particularly useful in hooks that need to find the
top\-level package directory based on a symbolic link to a single file within
it.
.sp
Exits zero if and only if a directory for the given package name or path was
found.
.sp
Options:
.INDENT 0.0
.TP
.BI \-\-root\fB= PATH
Look for additional packages in PATH.
.TP
.BI \-\-user\fB= USER
List packages registered by USER (if you have
permission).
.UNINDENT
.SS click register PACKAGE\-NAME VERSION
.sp
Register an installed Click package for a user.  This will normally cause
user\-level hooks to be run for that user, which are needed for things such
as making the application’s \fB\&.desktop\fP file available to the user
interface.
.sp
Options:
.INDENT 0.0
.TP
.BI \-\-root\fB= PATH
Look for additional packages in PATH.
.TP
.BI \-\-user\fB= USER
Register package for USER (default: current
user).
.TP
.B  \-\-all\-users
Register package for all users.
.UNINDENT
.SS click unregister PACKAGE\-NAME [VERSION]
.sp
Unregister an installed Click package for a user, and remove it entirely if
no other users still have it registered and if it does not appear to be
running.  This will normally cause user\-level hooks to be run for that user,
which are needed for things such as removing the application’s \fB\&.desktop\fP
file from the user interface.
.sp
If a version is specified, then the registered version must match it in
order to be removed.
.sp
Options:
.INDENT 0.0
.TP
.BI \-\-root\fB= PATH
Look for additional packages in PATH.
.TP
.BI \-\-user\fB= USER
Unregister package for USER (default:
\fB$SUDO_USER\fP, if known).
.TP
.B  \-\-all\-users
Unregister package that was previously
registered for all users.
.UNINDENT
.SS click verify PACKAGE\-FILE
.sp
Verify the Click package in PACKAGE\-FILE.
.sp
The \fB\-\-force\-missing\-framework\fP option is necessary while working with
development versions of SDKs which have not yet put a framework declaration
in place.
.sp
Options:
.INDENT 0.0
.TP
.BI \-\-root\fB= PATH
Install packages underneath PATH.
.TP
.B  \-\-force\-missing\-framework
Install despite missing system framework.
.UNINDENT
.SH AUTHOR
Colin Watson
.SH COPYRIGHT
2024, Canonical Ltd.
.\" Generated by docutils manpage writer.
.