NeosynNeosyn
C⏚ v2.0.0Updated 2026-05-12·Getting started

Project layout

This page defines the file-system rules the C⏚ toolchain expects. If package names, file names, and folders do not agree, imports, entity discovery, and generated output paths become unreliable.

Minimum layout

Most projects should start with a src/ root:

my-project/
  src/
    com/
      example/
        Counter.cg
        Counter_test.cg

This corresponds to:

package com.example;

Rules

  • The declared package must match the folder path under the source root.
  • The file base name should match the top-level entity defined in the file.
  • Imports use the fully-qualified entity name.
  • Generated outputs preserve the package structure.

Example:

src/com/example/Counter.cg
package com.example;
 
task Counter {
  // ...
}

Then another file can import it as:

import com.example.Counter;

Recommended file organization

  • Put one top-level task, network, or bundle in each file.
  • Keep test networks next to the design they exercise.
  • Use _test suffixes consistently for test-oriented files.
  • Keep generated output directories such as verilog-gen/, vhdl-gen/, .ir/, and simulation artifacts out of src/.

Recommended shape:

my-project/
  src/
    com/example/
      Counter.cg
      Counter_test.cg
      fifo/
        AsyncFifo.cg
        AsyncFifo_test.cg
  verilog-gen/
  vhdl-gen/
  .ir/

What breaks when layout is wrong

Common symptoms:

  • import ... could not be resolved
  • the wrong top-level entity is selected for simulation
  • generated HDL appears under an unexpected folder
  • multiple entities in one file become harder to target reliably

Multi-package projects

Larger projects can define several packages under the same src/ root:

src/
  com/example/core/
  com/example/peripherals/
  com/example/tests/

That is fine as long as each file's package matches its location.

Generated output conventions

Typical defaults:

  • IR: .ir/
  • Verilog: verilog-gen/
  • VHDL: vhdl-gen/
  • waveform files: next to the simulated source, unless the tool writes them elsewhere for that client integration

The CLI can override some of these with explicit output flags. See CLI reference.

Checklist

Before debugging imports or entity selection, verify:

  • the folder path matches the declared package
  • the file name matches the top-level entity
  • the importing file uses the fully-qualified entity name
  • generated output directories are not being mistaken for source roots

Where next