Getting Started

Try without installing

Want to try Celox before setting up a project? The Celox Playground runs entirely in the browser.

Prerequisites

• Node.js (v18+)
• A package manager (npm, pnpm, yarn, etc.)
• Rust toolchain -- required when a prebuilt native addon is not available for your platform

Starter Template

A ready-to-use project template is available at celox-template. Click Use this template on GitHub or clone the repository, then run npm install && npm test to get started immediately.

Project Setup

Create a new project directory and initialize it:

mkdir my-celox-project && cd my-celox-project
npm init -y
npm pkg set type=module

Install Celox and Vitest:

npm add -D @celox-sim/celox @celox-sim/vite-plugin vitest

After following the steps below, your project will look like this:

my-celox-project/
├── Veryl.toml            # Veryl project config
├── vitest.config.ts      # Vitest + Celox plugin
├── tsconfig.json
├── package.json
├── src/
│   └── Adder.veryl       # Veryl design files
└── test/
    └── adder.test.ts     # TypeScript testbenches

Veryl.toml

Create a Veryl.toml at the project root:

[project]
name    = "my_project"
version = "0.1.0"

[build]
clock_type = "posedge"
reset_type = "async_low"
sources    = ["src"]

vitest.config.ts

import { defineConfig } from "vitest/config";
import celox from "@celox-sim/vite-plugin";

export default defineConfig({
  plugins: [celox()],
});

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "allowArbitraryExtensions": true,
    "rootDirs": ["src", ".celox/src"]
  },
  "include": ["test", "src", ".celox/src"]
}

Write a Veryl Module

Create src/Adder.veryl:

module Adder (
    clk: input clock,
    rst: input reset,
    a: input logic<16>,
    b: input logic<16>,
    sum: output logic<17>,
) {
    always_comb {
        sum = a + b;
    }
}

Write a Test

Create test/adder.test.ts:

import { describe, test, expect } from "vitest";
import { Simulator } from "@celox-sim/celox";
import { Adder } from "../src/Adder.veryl";

describe("Adder", () => {
  test("adds two numbers", () => {
    const sim = Simulator.create(Adder);

    sim.dut.a = 100n;
    sim.dut.b = 200n;
    expect(sim.dut.sum).toBe(300n);

    sim.dispose();
  });
});

The Vite plugin automatically analyzes your .veryl files and generates TypeScript type definitions, so imports like import { Adder } from "../src/Adder.veryl" are fully typed.

Run Tests

Add a test script to package.json:

{
  "scripts": {
    "test": "vitest run"
  }
}

Then run:

npm test

Next Steps

• Playground -- Try Celox in the browser.
• Writing Tests -- Event-based and time-based simulation patterns.
• Introduction -- Architecture overview.