{"id":13748870,"url":"https://github.com/OCamlPro/matla","last_synced_at":"2025-05-09T11:31:32.480Z","repository":{"id":59996412,"uuid":"499568104","full_name":"OCamlPro/matla","owner":"OCamlPro","description":"A manager for TLA+ projects, written in Rust.","archived":false,"fork":false,"pushed_at":"2022-09-30T15:52:36.000Z","size":2244,"stargazers_count":8,"open_issues_count":1,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-05-22T20:32:22.439Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OCamlPro.png","metadata":{"files":{"readme":"README.md","changelog":"changes.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-06-03T15:51:58.000Z","updated_at":"2022-12-09T09:32:50.000Z","dependencies_parsed_at":"2023-01-18T21:03:13.007Z","dependency_job_id":null,"html_url":"https://github.com/OCamlPro/matla","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCamlPro%2Fmatla","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCamlPro%2Fmatla/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCamlPro%2Fmatla/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCamlPro%2Fmatla/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OCamlPro","download_url":"https://codeload.github.com/OCamlPro/matla/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253240350,"owners_count":21876593,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T07:00:51.167Z","updated_at":"2025-05-09T11:31:30.055Z","avatar_url":"https://github.com/OCamlPro.png","language":"Rust","funding_links":[],"categories":["Projects"],"sub_categories":["Verification"],"readme":"# matla\n\nA manager for TLA+ projects by [OCamlPro][ocp].\n\nRead the user manual [here][user manual].\n\n## Features\n\n- [x] does not require the TLA+ toolbox to be installed;\n- [x] can use the toolbox from your environment;\n- [x] uses a config directory `~/.config/matla` by default, but can run in portable mode with\n  `--portable` (requires to have the TLA+ toobox jar in your path);\n- [x] builds/runs everything in a build directory `target/debug` or `target/release`, meaning\n  TLC's garbage files will not pollute your sources;\n- [x] runs TLC;\n- [x] partially processes TLC's output for readability;\n- [ ] fully processes TLC's output for readability;\n- [ ] reconstruct *\"errors\"* and pretty-present them\n    - [x] basic parse errors\n    - [x] assertion failures\n    - [x] property/invariant falsification\n    - [x] deadlocks\n    - [ ] things I missed\n- [x] provides a `Matla` module with assertions and checks, actually performed in `debug` mode but\n  ignored in `release` mode;\n- [ ] tla2tex-based *\"doc\"* generation;\n- [ ] other (better, usable) doc generation;\n- [ ] handles unit tests defined in your TLA+ modules;\n- [ ] and more.\n\nNon-features\n\n- actually package the TLA+ toolbox in the binary.\n\n\n## Install\n\nMatla is not on [crates.io], you can still install it with `cargo` which you get when [installing rust].\n\n- Install from git:\n\n    ```text\n    \u003e cargo install --git https://github.com/OCamlPro/matla#latest matla\n    ...\n    ```\n\n- Install from local clone:\n\n    ```text\n    \u003e git clone https://github.com/OCamlPro/matla\n    ...\n    \u003e cd matla\n    ...\n    \u003e cargo install --path matla\n    ...\n    ```\n\n- Retrieve the latest binary from [the release page][releases]\n\nMake sure everything works:\n\n```\nmatla 0.1.0-alpha1\n\nA project manager for TLA+ projects.\n\nUSAGE:\n    lmatla [OPTIONS] [SUBCOMMAND]\n\nOPTIONS:\n    -c, --color \u003ctrue|on|false|off\u003e    (De)activates colored output. [default: on]\n    -h, --help                         Print help information\n        --log \u003cLOG_LEVEL\u003e              Makes the internal logger more verbose, mostly for debugging.\n                                       [default: warn] [possible values: warn, info, debug, trace]\n    -p, --portable                     Infer toolchain from environment, load no user configuration.\n        --path \u003cDIR\u003e                   Path to a matla project directory [default: .]\n    -V, --version                      Print version information\n\nSUBCOMMANDS:\n    clean        Cleans the current project: deletes the `target` directory.\n    help         Print this message or the help of the given subcommand(s)\n    init         Initializes an existing directory as a matla project.\n    run          Runs TLC on a TLA module in a project directory.\n    setup        Performs this initial matla setup, required before running matla.\n    test         Run the tests of a project.\n    tlc          Calls TLC with some arguments.\n    uninstall    Deletes your matla user directory (cannot be undone).\n    update       Updates the `tla2tools` jar in the matla user directory.\n```\n\n\n## Configuration and Setup\n\nMatla's configuration deals mostly with knowing how to call the TLA+ toolbox. Matla needs to create\na configuration folder to store information (or not, see the [portable mode](#portable-mode) below).\nThe path to this folder is `$HOME/.config/matla/`.\n\n\u003e TL;DR: run `matla setup` and answer matla's questions.\n\nThere are two ways matla handle the TLA+ toolbox. In `standalone` mode, matla will retrieve the\nlatest version of the toolbox and put it in your configuration folder, and use that anytime you call\nit after setup. In this mode, `matla update` will make sure you have the latest version.\n\nIn `from_env` mode, matla retrieves the path to the toolbox from your path. If it fails to do so,\nit will ask you for help. Naturally, this only works if the TLA+ toolbox is actually in your path.\n\nWhile `matla setup` guides you towards setting up one of these modes, you can give it flags to tell\nit what you want right away:\n\n```text\n\u003e matla help setup\nmatla-setup\nPerforms this initial matla setup, required before running matla\n\nUSAGE:\n    matla setup [FLAGS]\n\nFLAGS:\n        --from_env      Retrieve TLA toolbox path from the environment\n    -o, --overwrite     Automatically overwrite config files when they exists\n    -s, --standalone    Download the latest TLA toolbox to user directory and automatically use it\n    -h, --help          Prints help information\n    -V, --version       Prints version information\n```\n\n### Portable Mode\n\nIf you feel strongly about matla managing this user configuration folder, use `--portable` (or `-p`)\nto let matla know: `matla --portable \u003cother_my_arguments\u003e`. Matla will not even look for a user\nconfiguration folder and retrieve the TLA+ toolbox from the environment. Again, this means the\ntoolbox jar must be in your path.\n\n\n## Init\n\n`matla init \u003cDIR\u003e` initializes an *existing* project directory `\u003cDIR\u003e` (`.` by default). Pass\n`--new` if you also want matla to create `\u003cDIR\u003e`. By default, `matla init \u003cDIR\u003e` will\n\n- update the/create a `.gitignore` file in `\u003cDIR\u003e` with a rule to ignore the `target` (build)\n  directory, and\n- write the `Matla` module to `\u003cDIR\u003e/Matla.tla`.\n\nThis behavior can be changed by passing flags to `matla init`, see `matla help init` for details.\n\nThe `Matla` module contains helpers for writing assertions. In particular, it has a `dbg` sub-module\nwith helpers such as `Matla!dbg!assert(predicate, message)`. Helpers in `dbg` do nothing if you run\nmatla in `release` mode with `matla run --release`, as discussed below.\n\n\n## Run\n\n`matla run \u003cMODULE_NAME\u003e` runs TLC on your project with the entry point `\u003cMODULE_NAME\u003e`. Note that\n`\u003cMODULE_NAME\u003e` must be *TLC-executable*, *i.e.* `\u003cMODULE_NAME\u003e.tla` and `\u003cMODULE_NAME\u003e.cfg` must\nexist in your project directory.\n\nIf your project only has one TLC-executable module, `matla run` will automatically run on this\nmodule.\n\nNotable `matla run` command-line arguments:\n\n- `--path`/`-p`: path to the project directory, `.` by default;\n- `--release`: runs your project in release mode, see [below](#debugrelease).\n\n\n### Debug/release\n\n`matla run --release \u003cMODULE_NAME\u003e` runs TLC in *release* mode. As discussed in [`matla\ninit`](#init), matla comes with a `Matla` module providing helpers for writing assertions.\nIt features a `dbg` sub-module which behaves differently in *debug* and *release*.\n\n\u003e The `Matla` module is optional, if you don't want it make sure you initialize your project with\n\u003e `matla init --no_matla_module`.\n\nIf the `Matla` module is present, and you run your project in *debug* mode, then all assertion\nhelpers (in `Matla` and `Matla!dbg`) behave as expected: check some predicate(s) and fail with a\nmessage if it is/they are not `TRUE`.\n\nIn *release* mode however, assertion helpers **in `Matla!dbg`** (**not** in `Matla`) are compiled\naway: their definition is just `TRUE`.\n\nIf the `Matla` module is not present, there is currently no difference at all between *debug* mode\nand *release* mode.\n\n\n\n[crates.io]: https://crates.io\n[installing rust]: https://www.rust-lang.org/tools/install\n[user manual]: https://ocamlpro.github.io/matla/manual\n[ocp]: https://ocamlpro.com\n[releases]: https://github.com/OCamlPro/matla/releases\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOCamlPro%2Fmatla","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FOCamlPro%2Fmatla","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOCamlPro%2Fmatla/lists"}