![]() |
![]() |
![]() |
Cockpit Guide | ![]() |
---|
Cockpit is separated into various packages, each of which brings specific features and/or code.
It is not yet possible to implement arbitrary new packages.
In addition, any APIs or behavior not explicitly documented here is an internal API and can be changed at any time.
A package consists of one or more files placed in a directory or its
subdirectories. It must have a manifest.json
file and follow
certain naming conventions.
The name of a package is the name of the directory.
The name of the package must be ASCII alphanumeric, and may contain an underscore. Names of directories and files in the package must consist of ASCII alphanumeric along with dash, underscore, dot, and comma. No spaces are allowed.
Cockpit uses the data directories from the
XDG Base Directory
Specification
to locate packages. The $XDG_DATA_DIRS
represents a colon separate list of system data
directories, and $XDG_DATA_HOME
is a user specific data directory. If the environment
variables are not set, defaults are used, according to the spec.
A cockpit/
subdirectories in any of these data directories is the location where
packages are loaded by Cockpit. If Cockpit finds a package with the same name, in multiple data
directories, then the first one wins. According to the spec the first data directory is
$XDG_DATA_HOME
and then $XDG_DATA_DIRS
in order.
This means that, by default the following directories are searched for cockpit packages, and in this order:
~/.local/share/cockpit/
/usr/local/share/cockpit/
/usr/share/cockpit/
Packages placed in $XDG_DATA_HOME
are not cached by Cockpit or the web browser.
Other packages are cached agressively, and are accessed using a checksum of the files in
the packages and their names.
To further clarify things, here is an example package called "my-package" and its file layout:
/usr/share/cockpit/ my-package/ manifest.json file.html some.js
Place or symlink packages in your ~/.local/share/cockpit
directory (or appropriate
$XDG_DATA_HOME
location) that you would like to modify and develop. System installed
packages should not change while Cockpit is running.
Each package has a manifest.json
file. It is a JSON object. The following
fields may be present in the manifest:
alias |
Additonal package name or names for this package. If a string, then just one name, if an array then multiple names. These names are usually well-known names that the package should provide resources for. |
version |
An informational version number for the package. |
When referring to files in your package, such as in a hyperlink or a <style>
tag or <script>
tag, simply use a relative path, and refer to the files
in the same directory.
However often the need arises to refer from one package to another, for example when
loading the base cockpit.js
javascript. To do this the path must be
crafted in a specific way: ../@@package@@/path
The @@package@@
is replaced by the relevant path component to address the
the package. Put the package name between the @@
signs. It will be replaced with
a cacheable checksum of the package, or qualified package name at the given host. Don't hardcode
the path, use the @@
syntax.
For example here's how to include the base cockpit.js
script in your HTML
from the latest
package:
<script src="../@@latest@@"></script>
Do not assume you can link to any file in any other package. Refer to the list of API packages for those that are available for use.
If minified resources are provided, they should be provided along with the non-minified file. This allows developers to debug package code when necessary.
Minified files should contain a .min
suffix before their usual file
extension. They will automatically be used in place of the unminified file, when your
the package is installed. This applies for HTML, JS, CSS or other types of resources.
For example if you have a javascript file called test.js
its minified
version should be placed in a file called test.min.js
in the same directory.
To force Cockpit to use non-minified resources, link the package into your home directory as described in the section on Package Layout.
Cockpit has API available for writing packages. There is no API available for external callers to invoke via HTTP, REST or otherwise.
Unless an API is explicitly marked as stable, it is unstable and can be changed when Cockpit is upgraded.
API from various packages can be used to implement Cockpit packages. Each package listed here has some API available for use. Only the API explicitly documented should be used. In some cases even though the API is available it is not (yet) stable.
To include javascript from the API, simply load it into your HTML using
a script tag. Alternatively you can use an javascript loader. Always refer to
the package using the @@package@@
syntax. This allows Cockpit to
optimize and cache multiple uses of the same resources.