`orbit`

orbit is a package manager for Hardware Description Languages (HDL).

Read the Book of Orbit for complete documentation.

orbit manages your projects, called IPs, by handling the overhead for referencing, maintaining, and integrating your hardware description files:

cpu/
├─ Orbit.toml
├─ rtl/
│  ├─ reg.vhd
│  └─ top.vhd
└─ sim/
   └─ top_tb.vhd

Adding a simple TOML file Orbit.toml to a directory denotes that directory as an IP to orbit:

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

[dependencies]
gates = "2.3.0"

orbit generates VHDL code snippets able to be directly inserted into a new VHDL design for rapid reuse:

$ orbit get and_gate --ip gates:2.3.0 --component --signals --instance

component and_gate
  port(
    a : in std_logic;
    b : in std_logic;
    x : out std_logic
  );
end component;

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

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

orbit plans your build by generating a file list, called a blueprint, that contains a list of the required files for your given design in topologically-sorted order to act as an input to any backend toolchain:

VHDL-RTL	gates	/users/chase/.orbit/cache/gates-2.3.0-7f4d8c7812/rtl/nand_gate.vhd
VHDL-RTL	gates	/users/chase/.orbit/cache/gates-2.3.0-7f4d8c7812/rtl/and_gate.vhd
VHDL-RTL	work	/users/chase/projects/cpu/rtl/reg.vhd
VHDL-RTL	work	/users/chase/projects/cpu/rtl/top.vhd
VHDL-SIM	work	/users/chase/projects/cpu/sim/top_tb.vhd

Features

orbit has a lot more useful features relating to HDL package management and development:

orbit is a frontend package manager, not a build system, so it allows users to define and automate their own workflows for building HDL designs.
Linux, MacOS, and Windows are supported with no additional dependencies.
Docker images of orbit are available for easy integration into new or existing CI/CD pipelines.
Reproducible builds are achieved with checksums and automatic handling of a lockfile Orbit.lock.
Namespace collisions, a problem inherent to VHDL and not resolved in many backend tools, is solved through a custom algorithm called dynamic symbol transformation.
Multiple versions of the same entity (or more broadly, entities given the same identifier) are allowed in the same build under two simple constraints.
Navigate HDL source code efficiently to read its inline documentation and visit its implementation through orbit's ability to locate HDL code segments
Produce VHDL code snippets with a single command to properly instantiate entities within a new design.
Quickly search through your IP catalog by filtering based on keywords, catalog status, and name.
Avoid being locked into a specific vendor's tooling through orbit's common interface with a flexible build command to adapt to any workflow.
orbit is version control system (VCS) agnostic through defining custom protocols for fetching IP. Continue to use your current VCS (or none).
Minimal user upkeep is required to maintain a manifest file Orbit.toml that identifies an IP, its metadata, and any dependencies from your catalog.
View the current design's tree hierarchy at an HDL entity level or at an IP level.
Implement custom scripted workflows through a plugin system.
Specify additional supportive files to be passed to your backend workflows with filesets.
Dependencies at the HDL level are automatically identified and resolved by tokenizing file contents for valid primary design unit references across IP. The user is only responsible for specifying direct dependencies at the IP level.

Examples

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.

Installing

orbit has pre-built binaries for MacOS, Windows, and Ubuntu. See the releases page to grab the latest release, or you can build from source with cargo. See the full installation instructions for complete details here.

Documentation

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

orbit provides commands for every stage of the development cycle, such as exploration, integration, and automation:

Orbit is a tool for hdl package management.

Usage:
    orbit [options] [command]

Commands:
    new             create a new ip
    init            initialize an ip from an existing project
    show            print information about an ip
    read            navigate hdl design unit source code
    get             fetch an entity
    tree            view the dependency graph
    plan, p         generate a blueprint file
    build, b        execute a backend workflow
    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.

Contributing

See CONTRIBUTING.

License

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.

cdotrus/orbit