Reuse

Packages and Dependencies

Find reusable Livt packages, manage project dependencies, and share tested hardware capabilities across applications.

FPGA applications often rely on familiar building blocks: bus interfaces, buffers, protocol implementations, mathematical functions, and hardware controllers. Implementing and maintaining these capabilities independently in every project creates repetitive work and makes it harder to benefit from improvements made elsewhere.

Livt packages let teams develop such capabilities once and reuse them across applications. A package brings together reusable source code and project configuration under a defined public contract. Applications declare the packages they need in livt.toml, and Livt resolves and synchronises those dependencies. Packages can then evolve independently, with versioned releases allowing consumers to adopt changes deliberately.

For example, an application can depend on Livt.Bus to use shared bus-interface definitions. The package supplies reusable declarations; the application remains responsible for constructing components, connecting signals, and satisfying clock, reset, and timing requirements.

Packages, namespaces, components, and interfaces

These concepts serve different purposes:

Concept Purpose
Package Distributes and versions reusable capabilities across projects.
Namespace Organises declarations and prevents naming conflicts.
Component Describes a hardware structure, including its state and behaviour.
Interface Defines a contract for the behaviour or signals a component provides.

A package is not a hardware instance. Adding a package makes its accessible declarations available to a project; it does not automatically instantiate components, connect buses, or consume FPGA resources. Namespaces organise those declarations, while the components and interfaces that the application actually uses determine its hardware structure.

This page starts with package discovery and dependency management in Visual Studio Code, then explains how to develop, test, and publish reusable packages of your own.

Find and add a package

The Livt extension lets you discover registry packages without leaving your project. Begin with the application that will consume the package, because the dependency belongs to that project's configuration.

Open the application in Visual Studio Code and locate it in the Livt Project view. If the workspace contains several projects, expand the intended project. Right-click its Dependencies node and choose Add a Package….

Dependencies selected under PacketController, with Add a Package and Sync Dependencies in its context menu.
Start from the consuming project's Dependencies node.

The package picker searches the registry as you type. Enter a package name such as Livt.Bus, or use * to browse more broadly. Results show package names and versions together. Select the version you intend to use; a dependency already declared by the project is marked Already added.

Add a Package to PacketController picker, showing a search for Livt.Bus and the available package versions.
Choose a package and version from the search results. Available versions may differ from those shown.

After selection, Livt updates livt.toml and synchronises dependencies. When the operation finishes, expand Dependencies to inspect the installed package. You do not need separate manual lock-file or synchronisation steps for the normal add workflow.

Livt.Bus expanded in the PacketController Dependencies tree beside the updated dependencies table in livt.toml.
The manifest records the requested dependency; the Dependencies tree shows the synchronised package.

The declaration has this form; the picker writes the selected version for you:

toml
[dependencies]
"Livt.Bus" = "<selected-version>"

Replace <selected-version> with a version available in the registry if editing the manifest manually.

Use an installed package

Adding a package is only the first step. To use its capabilities, import the appropriate namespace, refer to the types it exposes, and integrate them into your design. For example, if you installed the Livt.Bus package and its documented namespace is Livt.Bus, a source file can begin with:

livt
using Livt.Bus

Then consult the package's documentation for an actual interface or component to use. A consumer might implement a supplied interface, instantiate a supplied component, or pass that interface to another component. The precise code depends on the package API; package installation alone does not establish hardware connections.

The workflow is therefore: add the dependency → import the namespace → use the documented contract → build and test. Run the consuming project's tests after integrating the package, especially when its interface includes timing, reset, or handshake requirements.

Package names and namespaces

A package name is used for dependency resolution, while a namespace is used by Livt source code. They may look similar, but they are not interchangeable. Check the package documentation for the namespaces and public declarations it provides.

Manage dependencies

A dependency can bring in other dependencies. For example, if an application uses package A and A depends on package B, Livt must resolve both packages even if the application never names B directly. This is the transitive dependency graph.

Three project artefacts have different responsibilities:

File or directory Role Version control
livt.toml Requested package versions or local dependency paths Commit
livt.lock Resolved dependency graph for reproducible builds Commit for reproducible applications
.livt/deps/ Downloaded package contents managed by the tools Keep local

The manifest describes what the project requests; the lock file records the dependency selection that was resolved. Keeping a lock file in version control helps developers and CI runners work with the same dependency graph.

Why keep livt.lock?

A dependency declaration may permit multiple compatible versions. A lock file records the selected graph so a later build does not unexpectedly choose different dependencies. Applications should generally commit it. Reusable libraries may use a different policy when testing a range of supported dependency versions.

After pulling dependency changes or editing livt.toml by hand, select Sync Dependencies to bring local packages into agreement with the manifest. Review manifest and lock-file changes before committing them, particularly after changing package versions, and rerun affected tests.

During synchronisation, Livt uses an existing lock file while it still satisfies the manifest. If dependency declarations have changed, Livt resolves the new requirements and refreshes the existing lock. To upgrade a package deliberately, change its declared version and review the resulting lock-file changes.

To remove a package, first replace or remove source references that depend on it. In the Livt Project view, expand Dependencies, right-click the package, and choose Remove Dependency. The command updates the configuration and synchronises the remaining dependencies. Deleting a directory below .livt/deps/ does not remove the dependency declaration.

Livt.Bus selected under PacketController’s Dependencies node, with Remove Dependency available in its context menu.
Right-click the installed package and choose Remove Dependency to remove it from the consuming project.

Treat downloaded sources as managed files. If you need to modify a package, work in its own project and connect it as a local dependency instead. For command-line dependency operations, see the CLI reference.

Resolve dependency problems

A valid dependency that has not yet been synchronised is reported as a warning. Run Sync Dependencies, wait for it to finish, and check the Dependencies tree and Problems panel again. The warning should disappear once local packages agree with the manifest and lock file.

A malformed declaration, an unavailable package version, or an invalid local project needs a configuration correction. Check the package name and version against registry search results, or verify that the local path points to a valid Livt project. If synchronisation fails, inspect the command output for the reported cause before retrying.

Warnings from dependency source code are separate from dependency-resolution problems. A package’s warning settings apply to its own source. See Configure warnings and understand errors for controls such as -W all when auditing warnings across dependencies.

Use a local package

Local dependencies allow an application and a library to evolve together without publishing every intermediate change. This is useful when extracting a reusable component, revising a shared interface, or working on several related packages.

Each package remains an independent Livt project with its own manifest, source files, and tests. Both projects can appear in the same VS Code workspace, making it easier to navigate between the consumer and the implementation while preserving an explicit dependency relationship.

For example, an application can refer to a sibling project:

toml
[dependencies]
"ByteTools" = { path = "../byte-tools" }

The path is relative to the consuming project's directory and must identify a valid Livt project. In this example, byte-tools sits beside the application. Share the intended directory layout with collaborators, then synchronise and validate the application after changing the dependency.

A local dependency uses the files currently on disk. A lock file alone therefore does not freeze its contents. Test both the library and its consumer while developing them. Before releasing a package for external users, replace private local paths with registry versions they can resolve.

So far, we have used packages as dependencies. A Livt project can also supply reusable capabilities to other projects. The same project manifest, source organisation, and testing workflow form the foundation for a package you maintain and publish yourself.

Create a reusable package

Not every component needs its own package. Extract a package when it provides a coherent capability with a useful, reasonably stable public contract that can be understood independently of its original application.

For example, ByteTools might contain a byte-stream interface, a stream buffer, and tests that describe their behaviour:

text
byte-tools/
├── livt.toml
├── README.md
├── src/
│   ├── IByteStream.lvt
│   └── StreamBuffer.lvt
└── tests/
    └── StreamBufferTest.lvt

The package manifest records its identity, version, and source and test locations:

toml
[project]
name = "ByteTools"
version = "<package-version>"
path = "src"
outdir = "out"

[tests]
path = "tests"
components = ["StreamBufferTest"]

Replace <package-version> with the intended release version.

Define the public contract

Reuse the contract, not the implementation details. Tell consumers which components and interfaces they should use, which constructor parameters configure them, and which public functions, fields, and constants are supported. Keep internal state and implementation helpers private whenever practical, so changing their implementation does not require changes across consuming applications.

Hardware contracts include more than source-level names. Document directions, clock and reset assumptions, handshakes, latency, throughput, and relevant configuration limits whenever consumers rely on them.

For shared bus interfaces, depend on the package that defines the contract rather than copying its declarations. For HxS-enabled components, also document register maps: addresses, reset values, parameter positions, and delegated ranges can affect compatibility. See Register Interfaces.

Packages versus vendor IP

A Livt source package provides reusable code and build configuration. Generated HDL or packaged vendor IP is a deliverable created for a particular integration. Keep generated output separate from authored source, and document any required vendor tools or external HDL files. See Hardware Integration.

Test and document a package

Reusable hardware is most valuable when consumers can rely on its documented behaviour. Package tests should exercise the public contract, not merely internal implementation details. That helps maintainers refactor safely and gives consumers executable examples of expected behaviour.

For a stream buffer, tests might cover accepting data, preserving order, responding to backpressure, and returning to the documented state after reset. A component that still produces the right data but changes its latency or handshake behaviour may nevertheless break a consumer: timing is part of the contract where applications depend on it.

Run the package's own tests and test it from a consuming application. Consumer tests can expose assumptions that isolated tests miss, such as how clocks and resets are supplied or how interfaces are connected. Distinguish simulation-only helpers from synthesizable components and describe simulator and vendor requirements.

Start the README with the package's purpose and its smallest complete usage example. Show the dependency declaration, the namespace to import, component construction, and essential connections. Then document timing, reset behaviour, supported parameters, and limitations. Keep the README with the source project and make change notes easy to find.

The documentation should describe the supported contract rather than require users to infer it from generated HDL.

Version and release a package

A package version communicates what consumers can expect when they upgrade. Semantic versioning can distinguish compatible fixes, compatible additions, and changes that require adaptation. In hardware, however, source compatibility alone is not enough.

Hardware compatibility

Imagine a FIFO whose output originally becomes available one cycle after a request. A new implementation returns the same value after two cycles. Even with unchanged function signatures and signal names, consumers that rely on the old latency may need modifications. Treat documented latency, throughput, handshake behaviour, reset values, and register maps as compatibility-sensitive properties.

Prepare releases from a known source revision, with a package name and version in livt.toml and dependencies that downstream projects can resolve. Before publishing:

  1. Run livt validate and livt test for the package, then test a consuming application.
  2. Review public APIs, interface directions, timing, reset behaviour, and register maps against the previous release.
  3. Update the package version, usage examples, and release notes.
  4. Check which source and test files will be uploaded, and arrange separate delivery for additional documentation or assets where needed.

Publish from the package project directory:

bash
livt publish

The command uploads the manifest and the files in the configured source and test directories to the package registry. A top-level README.md or another file outside those directories is not automatically included; make such documentation available through an appropriate accompanying location. Publishing is a distribution step, so perform validation and testing beforehand rather than assuming the upload does so for you.

After publication, add the released version to a clean consumer project. Verify that dependencies synchronise and the consumer's tests pass. This checks the package in the form other developers actually receive it, including its published files and resolved dependencies.

Build on reusable capabilities

Packages let Livt applications build on established capabilities instead of repeatedly implementing the same foundations. Explicit dependencies, stable contracts, tests, and versioned releases allow shared hardware code to evolve without forcing every consumer to change at once.

As libraries for communication, storage, mathematics, and other domains accumulate, development can begin increasingly at the application level. The hardware constraints remain important, but developers can spend more time composing the capabilities their application needs and less time rebuilding familiar blocks.

For automated package workflows, see the CLI reference.