Orbit is an agile package manager and extensible build tool for hardware description languages (HDL).

The boom of AI and emerging workloads have shown just how fast new advancements can be made in models and algorithms. Today's hardware is no longer good enough to meet the immediate demands of tomorrow's innovations; today's hardware must shift to a more agile development approach. It's time to build tomorrow's hardware, today. It's time to live at the cutting edge of hardware design.

As codebases scale and increase in complexity, it becomes of upmost importance to have the right system in place to efficiently manage the increasing number of resources. Without the right system, the codebase can become bogged down by technical debt, leaving you stuck in yesterday's designs.

However, using just any package management system does not guarantee that technical debt is minimized. Poorly-designed package managers will simply shift the technical debt to different resources, while a well-designed package manager will minimize the overall amount of technical debt. With minimal technical debt, you can bring up tomorrow's hardware today. Orbit is an agile package manager designed to minimize technical debt.

Hardware development involves many complex processes, from running simulations to generating bitstreams. Orbit simplifies the build process into two stages: planning and execution. Orbit performs the planning of a build by resolving all HDL source code dependencies to produce a single file listing the topologically sorted source file order. From here, Orbit invokes any user-configured target to execute and process the planned list of source files. By allowing users to add their own execution processes, Orbit is an extensible build tool designed to support any workflow.

Orbit is available free to use and open source to encourage adoption, contribution, and integration among the hardware community. We rely on the open source community for feedback and new ideas, while remaining focused on our design goals and principles.

Orbit's use case is targeted toward anyone interested in developing digital hardware; this includes industrial, academic, and personal settings. Create your next commerical product, university lab assignment, or personal project, using a tool that is tailored to today's advanced development processes.

Prebuilt binaries are available for Linux, MacOS, and Windows with no dependencies. Visit the releases page for the latest version. Working on a different platform? No problem, building from source is easy with Cargo, Rust's default package manager. Use docker? We have docker images available too. See Installing for complete details.

For more information on getting started and how to use Orbit in your workflow, check out the Book of Orbit.

Orbit manages your project by turning it into a package (referred to as an ip) with the addition of a single file: "Orbit.toml."

cpu/
├─ Orbit.toml
├─ rtl/
│  ├─ ctrl.vhd
│  ├─ datapath.v
│  └─ top.vhd
└─ sim/
   └─ top_tb.sv

The "Orbit.toml" file is a simple file written in TOML syntax that requires only a couple fields, such as the ip's name and version, to get setup.

filename: Orbit.toml

[ip]
name = "cpu"
version = "1.0.0"

[dependencies]
gates = "2.0.0"

To encourage code reuse and faster development cycles, Orbit includes HDL-specific commands to integrate designs across ips. For example, Orbit can display HDL code snippets of other known design units to be instantiated within your local ip.

$ orbit get and_gate --ip gates:2.0.0 --library --signals --instance

library gates;

signal a : std_logic;
signal b : std_logic;
signal x : std_logic;

u_and_gate : entity gates.and_gate
  port map(
    a => a,
    b => b,
    x => x
  );

Since Orbit focuses on efficiently managing the HDL source code and minimizing its associated technical debt, users have the power to add their own execution targets to the build process. This is accomplished by Orbit performing the planning of a build process to generate a single file, called a blueprint, that lists the topologically-sorted order of source files. After planning the build, Orbit invokes the user's target to perform the execution process on the list of source files.

filename: blueprint.tsv

VHDL	gates	/users/chase/.orbit/cache/gates-2.0.0-7f4d8c7812/rtl/nand_gate.vhd
VHDL	gates	/users/chase/.orbit/cache/gates-2.0.0-7f4d8c7812/rtl/and_gate.vhd
VLOG	cpu	/users/chase/projects/cpu/rtl/datapath.v
VHDL	cpu	/users/chase/projects/cpu/rtl/ctrl.vhd
VHDL	cpu	/users/chase/projects/cpu/rtl/top.vhd
SYSV	cpu	/users/chase/projects/cpu/sim/top_tb.sv

Add a target by writing a script to accept Orbit's generated blueprint file for whatever EDA tools you prefer once, and use it across all future ips.

What makes Orbit an agile package manager for HDLs? Here are some of its key features:

• Orbit acts as the intermediary between your source code and back end EDA tools, automating the upkeep process to minimize technical debt as your codebase evolves over time

• Supports VHDL, Verilog, and SystemVerilog hardware description languages

• Reproduce results across any environment with Orbit through its automatic handling of lockfiles and checksums

• Overcome namespace collisions, a problem inherent to VHDL and Verilog, through a custom aglorithm that dynamically transforms conflicting design names called dynamic symbol transformation

• Because of dynamic symbol transformation, multiple versions of the same design unit (or more broadly, design units given the same identifier) are allowed in the same build under two simple constraints

• Quickly navigate through HDL source code to read its inline documentation and review a design unit's implementation with Orbit's ability to jump to and display HDL code segments

• Integrate existing design units across projects faster than ever with Orbit's ability to display valid HDL code snippets for design unit instantiation

• Explore your evolving codebase to identify the projects you need next with Orbit's ability to quickly search through known ip by filtering based on keywords, status, and name

• Keep your source code independent of vendor tools and avoid vendor lock-in with Orbit's vendor-agnostic interface to back end EDA tools

• Continue to use your preferred version control system (or none) due to Orbit's flexible approach to being version control system agnostic

• Review high-level design unit circuit tree hierarchies at the HDL level or ip level

• No longer worry about manually organizing a design unit's order of dependencies with Orbit's built-in ability to tokenize HDL source code and automatically identify valid references to other design units

• Linux, MacOS, and Windows are fully supported with zero dependencies

• Docker images and GitHub Actions are available to support CI/CD workflows

• Manifest files that mark a project as an ip only require a few user-defined fields to get setup

• Write a target for your preferred EDA tools once, and reuse across projects with Orbit's support for configuration files

And these are only a few of Orbit's features! Download Orbit and read its documentation today to discover everything Orbit provides as an agile package manager for HDLs.

Orbit has prebuilt binaries for MacOS, Windows, and Linux. See the releases page to download the latest version, or build from source using Cargo, Rust's default package manager. See Installing for more details on getting Orbit up and running.

A fictitious organization, "Hyperspace Labs", exists for the purpose of demonstrating and learning how to leverage Orbit in a real development setting. No identification with actual persons, places, buildings, and products is intended or should be inferred.

The projects and code for Hyperspace Labs are walked through in the tutorials section.

The final code repositories for Hyperspace Labs are found here.

Read the Book of Orbit for comprehensive documentation composed of tutorials, user guides, topic guides, references, and command manuals.

Orbit brings an agile approach to hardware development that minimizes technical debt through its available commands related to ip integration and build automation:

Orbit is an hdl package manager and build tool.

Usage:
    orbit [options] [command]

Commands:
    new             create a new ip
    init            initialize an ip from an existing project
    view            display metadata of an ip
    read            navigate hdl design unit source code
    get             fetch an entity
    tree            view the dependency graph
    lock            save the world state of the current ip
    test, t         run a test
    build, b        plan and execute a target
    publish         post an ip to a channel
    search          browse the ip catalog 
    download        request packages from the internet
    install         store an immutable reference to an ip
    env             print orbit environment information
    config          modify configuration values
    remove          uninstall an ip from the catalog

Options:
    --version       print version information and exit
    --upgrade       check for the latest orbit binary
    --force         bypass interactive prompts
    --color <when>  coloring: auto, always, never
    --help, -h      print help information

Use 'orbit help <command>' for more information about a command.

This program is free software distributed under the terms of the GNU General Public License version 3 or later. You may use, modify, and redistribute the program as you wish but if you distribute modifications you must preserve the license text and copyright notices, and also make the modified source code available to your users.

See LICENSE.

Orbit has yet to have its first sponsor! I initially got inspiration for this project during my first internship with NASA Glenn Research Center in 2021, and started working on this project in my free time throughout my undergraduate studies at the University of Florida. Since then, I have continued to work on this project whenever possible throughout my graduate studies without any direct funding. If you use Orbit, please consider sponsoring; any amount is very much appreciated.

Being a sponsor not only keeps this project going, but enables you or your organization to have additional perks, such as prioritized issues and feature requests, being advertised in our documentation, and direct support for configuring Orbit for your specialized use case. See SPONSORING.

See CONTRIBUTING.