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 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

def restore(path: str, staged: bool):
    """
    Restore the modified directory `path` in the channel from the publish command back to their original state.
    """
    args = ['--staged'] if staged else []
    subprocess.Popen(['git', 'restore'] + args + [path]).wait()

channel_dir = os.environ.get("ORBIT_CHANNEL_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', channel_dir])
rc = child.wait()
if rc != 0:
    restore(channel_dir, staged=False)
    exit(rc)
# Commit the changes
child = subprocess.Popen(['git', 'commit', '-m', "Publishes "+ip_name+':'+ip_version])
rc = child.wait()
if rc != 0:
    restore(channel_dir, staged=True)
    restore(channel_dir, staged=False)
    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