Every Livt project has a livt.toml file in its project directory. This manifest defines the project's name, source and test locations, entry component, and build configuration. It provides a common foundation for developing, building, and testing the project consistently across different environments.
When you open a project folder in Visual Studio Code, the Livt extension automatically discovers livt.toml and displays the project in the Livt Project view. From there, you can explore source files and tests, edit the project configuration, and run build and test commands.
A Visual Studio Code workspace can contain multiple Livt projects, each with its own manifest and configuration. Select the appropriate project in the Livt Project view to ensure that commands operate on the intended project.
This page introduces the most important livt.toml settings and explains how to configure and validate your project using Visual Studio Code.
Configure sources and tests
Start with the project's name, source location, entry component, and tests. These settings describe what belongs to the project.
[project]
name = "PacketController"
component = "Livt.Packet.ControllerTop"
path = "src"
outdir = "out"
profile = "debug"
[tests]
path = "tests"
components = ["PacketControllerTest"]
The name identifies the project and package. The component setting selects the default Livt entry component; it may be omitted when it matches the project name. path selects the source directory, outdir sets the generated-output location, and profile selects the default output profile; see debug and release builds for the compilation options. Under [tests], path identifies the test directory and components lists the test components to execute.
Paths are resolved relative to the project directory, so the manifest can travel with the source. Keep the manifest and the source and test files in version control.
Multiple projects in VS Code
A workspace can contain several independent Livt projects. Select the intended project in the Livt Project view and run commands from its context menu. The extension uses that project's
livt.tomlrather than assuming the workspace root is the project.
Configure build behaviour
Choose a build profile for development or release, decide which warnings to report, and enable optimisations when you want to compare generated implementations. Keep settings that belong to the project in livt.toml; use command-line options for individual builds.
Choose debug or release builds
Use debug builds during development to retain application assertions and simulation diagnostics. Use release builds when preparing the application for delivery, and test that configuration before relying on its output.
In the existing [project] table, keep profile = "debug" for the normal development output profile. With outdir = "out", this places output under out/debug/. Select release behaviour for an individual build with --release; the release output goes under out/release/.
livt build
livt build --release
livt test --release
The manifest's profile setting selects the output profile. Use --release to explicitly enable release compilation behaviour; changing the manifest output profile alone does not enable assertion stripping.
| Check or diagnostic | Debug build | Release build |
|---|---|---|
| Ordinary application assertions | Retained | Stripped by default |
| Assertions in test components and test functions | Retained | Retained |
Compile-time static assert checks | Always checked | Always checked |
Release compilation also removes application Simulation.Report and Simulation.Wait calls outside test code. To retain application assertions while testing a release build, override assertion stripping explicitly:
livt test --release --strip-assertions=false
Configure warnings and understand errors
Errors prevent a successful build and must be corrected. Warnings identify code or configuration that deserves review, but do not normally stop the build. In Visual Studio Code, inspect diagnostics in the Problems panel and select an entry to navigate to its source. Inspect the build output for messages from the command you ran.
Configure warning selection for each build profile in the manifest. Start with all warnings enabled:
[build.debug]
warnings = ["all"]
[build.release]
warnings = ["all"]
A warning setting belongs to the source package that defines it. If you have reviewed a particular warning and intentionally accept it, add no-<code> to that profile's list. For example, warnings = ["all", "no-variable-divisor"] suppresses the warning about division or remainder with a non-constant divisor, which can require costly hardware.
Use -W to change warning handling for one invocation. The following commands respectively include warnings suppressed by manifests, treat reported warnings as errors, and combine both for a stricter audit:
livt build -W all
livt build -W error
livt build -W all,error
For a deliberate one-off suppression, use livt build -W no-variable-divisor. Explicit command-line suppressions still apply when combined with all. These options do not rewrite the manifest or turn compiler errors into warnings.
Choose optimisation settings
Livt selects optimisations by name with -O or --optimize, rather than numeric levels such as -O1 or -O2. Optimisation selection is independent of debug and release behaviour: --release does not automatically enable every optimisation.
Without -O, the generator enables indexed-write-lowering by default. Use all to enable the available optimisations, or none to disable them when comparing generated output:
livt build -O all
livt build -O none
Combine flags in a comma-separated list. They are applied from left to right: all enables the available set, none clears it, a name adds an optimisation, and no-<name> removes one. For example:
livt build --release -O all,no-loop-unrolling
livt build -O none,statement-fusion,getter-optimization
The first command enables all optimisations except loop unrolling. The second enables only statement fusion and getter optimisation. Other available choices include type-narrowing, multiplier-sharing, signal-copy-elimination, constant-divisor, and parallel-inference. Run livt build --help for the command's optimisation list.
Optimisations can change the generated hardware structure and the amount of compiler work. Sharing arithmetic resources, simplifying constant arithmetic, and expanding loops involve different trade-offs in area, scheduling, and timing. Enabling more optimisations does not guarantee a smaller or faster implementation. Run the tests with the selected flags, then compare synthesis and timing reports for the target device.
livt test --release -O all,no-loop-unrolling
Compilation profiling measures compiler work on the host, not FPGA clock-cycle latency or timing closure. See the CLI reference for profiling and further build options.
Customise the generated VHDL header
Set your company name in [vhdl] to include it in the header of generated VHDL files:
[vhdl]
file_header = true
company = "Example Engineering GmbH"
The opening line of the generated header uses the current year and the configured company name. In the following excerpt, <year> represents the generation year:
-- Copyright (C) <year> Example Engineering GmbH
--
-- This code was generated by:
Headers are enabled by default. If company is omitted or blank, the default is Eccelerators GmbH. Set file_header = false to omit the generated header. These settings change generated-file metadata; they do not change hardware behaviour. Edit the manifest and regenerate the output instead of editing generated headers by hand.
Separate project and local files
Not everything in a project directory belongs in source control. Distinguish authored project settings and dependency decisions from files that tools can recreate:
| File or directory | Purpose | Commit to version control? |
|---|---|---|
livt.toml |
Authored project configuration | Yes |
livt.lock |
Resolved dependency graph | Yes, for reproducible applications |
.livt/ |
Downloaded dependencies and local tool state | No |
Output directory (for example, out/) |
Generated HDL, reports, and metadata | No, ordinarily |
The managed Visual Studio Code installation supplies Java and GHDL locations directly. For manual or CI environments, make ghdl available on PATH or set LIVT_GHDL_PATH instead of recording a local simulator path in the project manifest. Do not add a [simulator] table for installation paths.
Vendor integration may need target-specific settings that belong to the project, such as the FPGA part:
[vendor.vivado]
part = "your-selected-part"
Executable locations are different: keep machine-specific paths local unless your team intentionally standardises an installation location.
Reproducible CI builds
Commit
livt.tomland, for applications,livt.lock. Configure the required tools on the CI runner and keep compiler and tool versions consistent. See Use commands in automation for running builds and tests from scripts.
Validate changes
After editing livt.toml, save it and run Validate Livt Project from Visual Studio Code.
Open the Command Palette with Ctrl + Shift + P and search for Validate Livt Project. Inspect configuration diagnostics in the Problems panel; filter by livt.toml to focus on the manifest.
Validation also identifies unsupported settings, malformed dependency values, and test components that cannot be found. Select a diagnostic in the Problems panel to review the affected setting, correct it, and validate again before building or testing.
For details about individual settings, including additional vendor and remote-generation options, consult the livt.toml reference.
Once the configuration is valid, continue with the CLI reference for build and test commands and for using them in automation.
Build results
Livt writes generated HDL, reports, and metadata to the output directory configured by outdir. With the settings shown above, development output is stored in out/debug/ and release output in out/release/. Browse these files under Generated Outputs in the Livt Project view. See Hello, Livt! for a first look at the generated hardware.
Subsequent builds can reuse existing results when the relevant inputs and settings are unchanged. Livt checks for changes automatically and rebuilds when needed, so you can normally run build and test commands without clearing the output directory.
To regenerate build output even when it is up to date, add --force:
livt build --force
To rebuild before running the tests, use:
livt test --force
Add --verbose to see why Livt decides a rebuild is needed. Use --force when you deliberately want fresh output; there is no need to delete downloaded dependencies for a normal rebuild. Make changes in the source files or manifest, since regeneration replaces generated files.
Configure reset behaviour
Livt uses synchronous reset by default. Most projects can leave this setting unchanged. Set default_reset_style when contexts without an explicit or inherited reset style need a different default:
[build]
default_reset_style = "sync"
Supported values are "sync" and "async". Omitting the setting selects synchronous reset. An explicit context reset style, or the reset style of a context to which a component is bound, takes precedence over the project default. Conflicting explicit requirements cause an error rather than silently changing a connected context.
For an individual invocation, you can override the project default with --default-reset-style async on livt build, livt test, or livt vendor. This does not override explicit context requirements.
Reset behaviour is independent of optimisation
Switching between debug and release builds, or changing
-Ooptimisation settings, does not change reset semantics. Treat the reset style as a hardware design choice, not a performance preset.