Ip

Ips are the core component that Orbit operates on as a package manager. First, let's understand some key terms related to ip in the context of Orbit.

Anatomy of an ip

A developer's tasks often involve interfacing with a collection of closely related files (source code, scripts, text files). This collection of closely related files is typically stored under a single directory and is called a project.

The core operations of a package manager revolve around packages. A package is a project with additional information provided by the developer. This "additional information" is called metadata, and it is written to a special file called a manifest. The manifest must be placed at the project's root directory. Without manifests, a package manager would not know which projects it should manage and what each project's current state is in regards to being a package.

In the context of being a package manager for digital hardware, Orbit calls a package an ip. An ip's manifest file is "Orbit.toml", with case-sensitivity.

Working ip

Typically, developers work on one project at a given time (while we can work on projects concurrently, we unfortunately are not parallel processors...yet). The working ip is the ip that is currently being developed at a given moment. The working ip is found by Orbit by checking along the working directory and its parent directories. Some Orbit commands only work when they are called within the working ip (orbit lock, orbit build).

Types of files inside an ip

Since Orbit focuses on digital hardware projects, it automatically detects and manages files that store HDL source code. Files that store HDL source code are called source files. Any other files, such as scripts and test vectors, are considered auxiliary files.

Auxiliary files can be injected into the planning stage by specifying filesets for the given target. A fileset is glob-style pattern that collects matching files under a common name within the working ip. These matched files will appear in the target's generated blueprint file for future execution.

So, what files are inside an ip?

• Source files: Stores HDL source code (VHDL, Verilog)
• Auxiliary files: Any additional files that do not store source code
• Manifest file (Orbit.toml): Stores the ip's metadata provided by the user
• Lock file (Orbit.lock): Saves the ip's world state for reproducibility purposes

All files except the lock file are expected to be edited by the user. Orbit automatically maintains the lock file to ensure it can reproduce the ip's world state in the future.

Reserved names

File names that begin with ".orbit-" are reserved for internal use and are not allowed at the root directory of an ip. Files that are named with this pattern are used by Orbit in the ip catalog to store additional metadata about the ip.

Ip names

An ip's name is a human-readable name given to an ip so users can easily recall and locate relevant packages.

gates

An ip's specification, more commonly called a spec, is the full resolved name of an ip. As of now, the spec involves the ip's name and ip's version separated by a : character.

gates:1.0.0

When asking Orbit to operate on a particular ip outside of the working ip, Orbit will usually ask you to provide the ip's spec. Orbit uses the spec to lookup the ip in the catalog and then continues operation.