Creating Channels

A channel is a decentralized registry storing the manifests of published ips. This section provides steps for ways to configure a channel.

Guides

• Configuring a local directory as a channel
• Configuring a git repository as a channel
• Configuring a channel as default
• Viewing available channels

Configuring a local directory as a channel

This guide outlines how to set up a directory on the local file system as a recognized channel. In this guide, our channel is called local-chipyard.

1. Create a new directory in the Orbit home directory:

mkdir -p "$(orbit env ORBIT_HOME)/channels/local-chipyard"

2. Open the global Orbit configuration file located at $ORBIT_HOME/config.toml.

3. Make a new entry in the [[channel]] array:

[[channel]]
name = "local-chipyard"
description = "Local registry of available ip"
root = "./channels/local-chipyard"

4. View your available channel:

orbit publish --list

Configuring a git repository as a channel

This guide outlines one way to create a channel that can be automatically tracked using git. In this guide, our channel is called remote-chipyard.

1. Create a new repository along with a remote configured for it to allow pushing and pulling.

2. Add an Orbit configuration file at the root of the repository called config.toml:

$ touch config.toml

3. Add a new entry in the [[channel]] array for the configuration file:

[[channel]]
name = "remote-chipyard"
description = "Remote registry of available ip"

4. Specify the directory where data for published ip should exist within the repository:

[[channel]]
# ...
root = "./index"

5. Set up synchronization hooks for this channel such that users that have this channel configured can seamlessly get updates using orbit --sync:

[[channel]]
# ...
sync.command = "git"
sync.args = ["pull"]

6. Create a Python script called publish.py to handle automatically adding, committing, and pushing published ips:

import subprocess
import os

ip_index = os.environ.get("ORBIT_CHANNEL_IP_DIR")
ip_name = os.environ.get("ORBIT_IP_NAME")
ip_version = os.environ.get("ORBIT_IP_VERSION") 

# Add untracked files
child = subprocess.Popen(['git', 'add', ip_index])
rc = child.wait()
if rc != 0:
    exit(rc)
# Commit the changes
child = subprocess.Popen(['git', 'commit', '-m', "Publishes "+ip_name+':'+ip_version])
rc = child.wait()
if rc != 0:
    exit(rc)
# Push the changes to the remote
child = subprocess.Popen(['git', 'push'])
rc = child.wait()
if rc != 0:
    exit(rc)

7. Configure the publish.py Python script to run within the publishing process after Orbit copies the published ip metadata into the channel:

[[channel]]
# ...
post.command = "python3"
post.args = ["publish.py"]

8. Add, commit, and push these changes to the git repository.

9. Modify the global Orbit configuration file to include this repository's configuration file:

$ orbit config --push include="$PWD/config.toml"

10. View the configured channel:

$ orbit publish --list

Configuring a channel as default

This guide walks through how to configure existing channels to be the default when an ip does not specify any particular channels during the publishing process.

1. Open an Orbit configuration file.

2. Add the default-channels field in the [publish] section, where the value is an array of one or more strings representing the names of a previously defined channels (such as local-chipyard and remote-chipyard):

[publish]
default-channels = ["local-chipyard", "remote-chipyard"]

Viewing available channels

This guide walks through how to view the channels already configured and available for an ip to publish to.

1. Return the list of configured channels:

$ orbit publish --list

2. Return configuration data about a particular channel, such as local-chipyard:

$ orbit publish --list --channel local-chipyard