============== Project Layout ============== A standard Karkain project keeps sources, tests and metadata in predictable places: .. code-block:: text 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: .. code-block:: toml 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 :doc:`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. .. code-block:: karkain // src/main.kark — runs immediately, no main() needed println("Hello from my_project!") Dependencies and the table of contents live in :doc:`dependencies` and :doc:`workflow`. .. seealso:: :doc:`modules` — importing ``lib/`` and ``std.*`` modules. :doc:`/tools/cli` — the full command reference.