Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

How Orbit Works

Orbit is a package manager and build system for VHDL, Verilog, and SystemVerilog.

Key concepts

  • Orbit manages your projects using a group of file system directories that together make up the Catalog. The catalog has 3 levels that store increasingly more information about a particular project: Channels, the Archive, and the Cache.

  • A project's manifest may be stored in a user-defined channel so that a user can find that project. Running orbit install will download the project from its defined source found in its channel and create a compressed snapshot of the project in the archive. Once the compressed snapshot is saved, Orbit will decompress the archived snapshot into an immutable reference of the project at the cache level. The usage of checksums prevents users from editing projects in the cache.

  • Every project requires a Manifest file, named Orbit.toml. This is a simple TOML file maintained by the user. The manifest file documents basic metadata about the project, like its name and version, as well as the project's list of direct dependencies.

  • A project saves its world state by storing a Lockfile, called Orbit.lock, alongside the manifest. A lockfile lists all of the resolved project dependencies required for the current project and how to retrieve those projects if necessary again. Running orbit lock will build an project-level graph to resolve the entire project-level dependency tree and store this information in the lockfile.

  • Users customize their experience with Orbit using Configurations, which are collections of Targets, Settings, and Protocols. All of these items are defined in an Orbit configuration file, called config.toml. Configurations allow users to reuse and share their workflows across teams and projects.

  • To build (or test) a design within a local project, Orbit runs a Build Process. The build process takes as input the local project's Lockfile, Source Files (hdl code), Auxiliary Files (any other file types needed), and a specified Target. Running orbit build (or orbit test) will enter the build process.

  • The build process occurs in 2 stages: the Planning Stage and the Execution Stage. During the planning stage, Orbit generates a Blueprint, which is a single file that lists all the files required to perform the build. During the execution stage, Orbit calls the specified Target's commmand, which typically reads the previously generated blueprint and processes the files using some user-defined EDA tool. The final output from the build process is typically one or more Artifacts, which are one or more files generated from the user-defined EDA tool.

  • Publish a new version of a project when it is ready by posting it to a user-defined channel. This method enables other users who also have that channel configured to seamlessly discover and access that new version of the project. Running orbit publish will run a series of checks and then copy the project's manifest to the proper location within the specified channel.

Other notes

  • Backend EDA tools and workflows (makefiles, TCL scripts, etc.) have the ability to be decoupled from projects and are able to be reused across projects by creating targets in the configuration file (config.toml).

  • Orbit does not require a version control system (VCS). Orbit is intended to work with any VCS (git, mercurial, svn, etc.).

  • Orbit solves the namespace collision problem by a variant of name mangling when primary design unit identifiers conflict in the dependency tree (dynamic symbol transformation).

  • Orbit generates a lockfile (Orbit.lock) during the planning stage of the build process. The lockfile saves the entire state such that Orbit can return to this state at a later time or on a different computing system. All necessary data that is required to reproduce the build is stored in the lockfile. The lockfile is maintained by Orbit and should be checked into versionc control.

  • Orbit generates a blueprint during the planning stage of the build process. The blueprint is a single file that lists the HDL source code files required for the particular build in topologically sorted order. Targets can also specify other file types to be collected into the blueprint. The blueprint is an artifact to be consumed by the target's process during the exection stage of the build process. Since it can frequently change with each build, it should not be checked into version control.