Project Layout

A standard Karkain project keeps sources, tests and metadata in predictable places:

my_project/
  karkain.toml          # project manifest
  .gitignore            # generated by `karkain init`
  src/
    main.kark           # application entry point
  tests/
    main_test.kark      # native tests (*_test.kark)
  lib/
    utils.kark          # shared modules (convention)
  conformance/          # language conformance tests (optional)
  stdlib/               # standard library (symlinked or vendored)

karkain init scaffolds the canonical subset: karkain.toml, .gitignore, src/main.kark, tests/main_test.kark and the .karkain/ cache directories. lib/, conformance/ and stdlib/ are conventions borrowed from the Karkain repository itself; empty directories are fine.

Directory roles

  • src/ — application source. karkain run src/main.kark finds it; a directory argument implicitly selects main.kark inside it.

  • lib/ — shared modules imported by the application (sibling modules in the same directory or project are assembled automatically).

  • tests/ — *_test.kark files discovered by karkain test.

  • conformance/ — the optional language conformance corpus (test_* functions, identical *_test.kark conventions).

  • stdlib/ — the standard library surface. Vendored or symlinked so import std.* resolves through the module loader.

The manifest

karkain.toml is a small TOML file. karkain init writes:

name = "my_project"
version = "0.1.0"
description = "A Karkain project"
license = "MIT"
targets = ["native"]

[dependencies]

Fields:

  • name / version — project identity, used by the package manager

  • description / license / author / repository — metadata

  • targets — default --target values

  • [dependencies] — resolved dependencies; see Dependencies

  • [dev-dependencies] — test-only dependencies

Entry point

There is no required ``main`` function. The top-level scope is the entry point: statements at file scope run when the program starts. A top-level func main() is just an ordinary function unless the top-level code calls it.

// src/main.kark — runs immediately, no main() needed
println("Hello from my_project!")

Dependencies and the table of contents live in Dependencies and Workflow.

See also

Modules — importing lib/ and std.* modules. Command-Line Interface — the full command reference.