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 process.
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.vhd
│ └─ top.vhd
└─ sim/
└─ top_tb.vhd
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.
[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 the current working 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 listing 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.
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
VHDL work /users/chase/projects/cpu/rtl/datapath.vhd
VHDL work /users/chase/projects/cpu/rtl/ctrl.vhd
VHDL work /users/chase/projects/cpu/rtl/top.vhd
VHDL work /users/chase/projects/cpu/sim/top_tb.vhd
Add a target by writing a script to accept Orbit's output 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
-
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
launch verify an upcoming release
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.
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.
This project, which refers to all of the files and source code created and stored in this repository, is currently licensed under the open-source copyleft GPL-3.0 license. See LICENSE.