Packages

The ZTC features a package manager to search, install and publish components of the Zerynth ecosystem. A package is an archive generated from a tagged git repository and identified by a unique fullname. There exist several package types, each one targeting a different Zerynth functionality:

  • core packages contain core Zerynth components (i.e. the ZTC, the Studio, etc...)
  • sys packages contain plaform dependent third party tools used by the ZTC (i.e. gcc, device specific tools, the Python runtime, etc..)
  • board packages contain device definitions
  • vhal packages contain low level drivers for various microcontroller families
  • meta packages contain sets of other packages
  • lib packages contain Zerynth libraries to add new modules to Zerynth programs

A package fullname is composed of three fields uniquely identifying the package:

For example, the package lib.broadcom.bmc43362 contains the Python driver for the Broadcom bcm43362 wifi chip. Its fullname contains the type (lib), the namespace (broadcom) grouping all packages implementing Broadcom drivers, and the actual package name (bcm43362) specifying which particular driver is implemented. A package has one or more available versions each one tagged following a modified semantic versionig scheme.

Moreover packages can belong to multiple “repositories” (collections of packages). There are two main public repositories, the official one, containing packages created, published and mantained by the Zerynth team, and the community one, containing packages created by community members.

The ZTC mantains a local databases of installed packages and refers to the online database of packages to check for updates and new packages.

Package Info

The command:

ztc package info fullname

displays information about the package identified by fullname.

Install

Packages can be added to the current Zerynth installation with the command:

ztc package install -p fullname:version

where fullname is the package fullname and version is the version of the package to install (or update if a previous version is already installed). The command first downloads the online package database and then recursively check package dependencies in order to install all required packages.

The command accepts many additional options:

  • -p fullname:version can be repeated multiple times to install more than one package at a time
  • --db skips the downloading of the online package database
  • --last while checking dependencies, selects the more up to date version of the dependency
  • --force performs installation of packages ignoring dependencies errors (warning: this could break the ZTC, use with caution)
  • --justnew while checking dependencies, avoids installing packages whose version is already installed
  • --simulate performs a simulated install, printing the list of modified packages only
  • --offline path performs installation searching packages in path instead of downloading them. Used for offline installations.
  • --mute supresses messages to stdout

Note

when the package meta.zerynth.core is installed, a new ZTC version is created and will be automatically used on subsequent executions of the ZTC. Previously installed versions of the ZTC can be reactivated by modifying the config.json setting the version field to the desired value.

Note

packages sys.zerynth.runtime and sys.zerynt.browser are not automatically installed! They are downloaded and uncompressed under sys/newpython and sys/newbrowser directories respectively. For the packages to be activated, such directories must be renamed to sys/python and sys/browser respectively.

Publishing a package

Zerynth projects can be published as library packages and publicly shared on different repositories (default is community). In order to convert a project into a publishable packages some requirements must be met:

  • The project must exist as a repository on the Zerynth backend (see git_init)
  • The user must own at least a namespace
  • The project folder must contain a package.json file with all relevant package information

In particular, the package.json must contain the following mandatory fields:

  • title: the title of the package
  • description: a longer description of the package
  • keywords: an array of keywords that will be used by the package search engine
  • repo: the name of the repository to publish to. Users can generally publish only to “community” unless permission is granted for a different repository
  • fullname: the unique name of the package obtained from its type (generally lib), a namespace owned or accessible by the user and the actual library name.
  • whatsnew: a string describing what has changed from the previous version of the package
  • dependencies: a dictionary containing the required packages that must be installed together with the package. A dictionary key is the fullnames of a required package whereas the value is the minimum required version of such package.

An example of package.json:

{
    "fullname": "lib.foo.ds1307",
    "title": "DS1307 Real Time Clock",
    "description": "Foo's DS1307 RTC Driver ... ",
    "keywords": [
        "rtc",
        "maxim",
        "time"
    ],
    "repo": "community",
    "whatsnew": "Fixed I2C bugs",
    "dependencies": {
        "core.zerynth.stdlib":"r2.0.0"
    }

}

The previous file describes the package lib.foo.ds1307, published in the community repository under the namespace foo. It is a package for DS1307 RTC that requires the Zerynth standard library to be installed with a version greater or equal then r2.0.0.

The command:

ztc package publish path version

first checks for the validity of the package.json at path, then modifies it adding the specified version and the remote git repository url. A git commit of the project is created and tagged with the version parameter; the commit is pushed to the Zerynth backend together with the just created tag. The backend is informed of the new package version and queues it for review. After the review process is finished, the package version will be available for installation.

Package Documentation

Each published package can feature its own documentation that will be built and hosted on the Zerynth documentation website. The documentation files must be saved under a docs folder in the project and formatted as reported here. It is strongly suggested to build the documentation locally and double check for typos or reStructuredText errors.

Package Examples

Packages be distributed with a set of examples stored under an examples folder in the project. Each example must be contained in its own folder respecting the following requirements:

  • The example folder name will be converted into the example “title” (shown in the Zerynth Studio example panel) by replacing underscores (“_”) with spaces
  • The example folder can contain any number of files, but only two are mandatory: main.py, the entry point file and project.md, a description of the example. Both files will be automatically included in the package documentation.

Moreover, for the examples to be displayed in the Zerynth Studio example panel, a file order.txt must be placed in the examples folder. It contains information about the example positioning in the example tree:

; order.txt of the lib.adafruit.neopixel package
; comments starts with ";"
; inner tree nodes labels start with a number of "#" corresponding to their level
; leaves corresponds to the actual example folder name
#Adafruit
    ##Neopixel
       Neopixel_LED_Strips
       Neopixel_Advanced

; this files is translated to:
; example root
; |
; |--- ...
; |--- ...
; |--- Adafruit
; |        |--- ...
; |        \--- Neopixel
; |                |--- Neopixel LED Strips
; |                \--- Neopixel Advanced
; |--- ...
; |--- ...

Update all packages

The current ZTC installation can be updated with the following command:

ztc package update_all

All packages are checked for new versions and installed. If the meta.zerynth.core packages is updated, a new ZTC installation is also created.

Options --db and --simulate are available with the same meaning as in the install command.

Sync

The local database of available packages is a copy of the online package database. The command:

ztc package sync

overwrites the local database with the online one. Subsequent ZTC commands on packages will use the updated database. Most package commands automatically sync package database before executing. Such behaviour can be disabled by providing the --db option

Published packages

The command:

ztc package published

retrieves the list of packages published by the user.

Installed packages

The list of currently installed packages can be retrieved with:

ztc package installed

providing the --extended prints additional information.

Updated packages

The list of packages with updated versions with respect to the current installation can be retrieved with:

ztc package updated

Available packages

The list of packages available on the backend can be retrieved with:

ztc package available

New Devices

The list of new supported devices with respect to the current installation can be retrieved with:

ztc package devices