# miso.yml

> The project file of the miso CLI: programs, targets, a library, tests and dependencies.

Source: https://haskell-miso.org/docs/cli-miso-yml/

A project is a `miso.yml`. With one program:

```
name: counter
version: 0.1.0             # required: numbers separated by dots
synopsis: A counter        # optional: one line about the package
author: Ada <ada@example.org>
license: BSD-3-Clause      # optional: an SPDX id
main: Main                 # the main module (default Main)
source-dirs: [app]         # default [app]
target: browser            # browser (WebAssembly) or browser_js (JavaScript),
                           # which need emcc; or native (the default)
mhs-options: []            # passed to mhs
dependencies:
  - miso                   # the miso of the release
  - split                  # from Hackage (Stackage)
  - name: lens-family      # from git, at a revision, with cabal flags
    git: https://github.com/example/lens-family
    rev: v2.1.3
    flags: -foo +bar
  - name: my-lib           # a local checkout, relative to miso.yml
    path: ../my-lib
  - name: aeson            # a version from Hackage, not the package list's
    version: 2.2.3.0
```

miso reads a subset of YAML: mappings, block lists, `[a, b]` lists, scalars and comments.

## A library, and several programs

```
name: todo
version: 0.1.0
dependencies: [miso]       # for every component
library:                   # code the programs share
  source-dirs: [src]       # default [src]
  exposed-modules: [Todo]  # default: every module under source-dirs
executables:
  web:                     # miso build web, miso dev web, ...
    main: Main
    source-dirs: [app]
    target: browser
  cli:
    main: Cli
    source-dirs: [cli]
    dependencies: [containers]
```

- Every program can import the library's modules. The library and each program may also have `dependencies` and `mhs-options`, added to the project's.
- `miso build` type checks the library and builds every program: native ones to `dist/NAME`, a browser one to `public/`, or with several browser programs, each to `public/NAME/`.
- A project with just `library:` is a library, which another project can depend on with `git:` or `path:`.

## Tests

```
tests:
  spec:                    # miso test spec
    main: Spec
    source-dirs: [test]    # default [test]
    dependencies: [split]
```

Tests are programs that run on this machine, and pass when they exit with 0, as Cabal's `exitcode-stdio` tests.

## C and JavaScript

The library, each program, and a project with one program also take:

```
c-sources: [cbits/*.c]       # C files (globs)
js-sources: [jsbits/*.js]    # JavaScript for browser programs (emcc --pre-js)
include-dirs: [include]      # -I for the C files and for CPP
cpp-options: [-DDEBUG]       # for modules with {-# LANGUAGE CPP #-}
extra-libraries: [m]         # -lm for the linker
cc-options: [-DSCALE=2]      # for the C compiler
ld-options: []               # for the linker
static-dir: static           # programs only: copied next to a browser program
```

Without `c-sources`, `js-sources` or `include-dirs`, `cbits/*.c`, `jsbits/*.js` and `include/` are used when they are there.

## Targets

| Target |  |
| --- | --- |
| `native` | a program for this machine, in `dist/` |
| `browser` | WebAssembly, with emcc, in `public/` |
| `browser_js` | JavaScript, with emcc, in `public/` |
| `emscripten`, `emscripten_js`, `emscripten_web`, `browser_rts` | passed to mhs as `-tTARGET`; compiled with emcc |