{"id":22202880,"url":"https://github.com/logsem/iris-tutorial","last_synced_at":"2025-07-27T05:31:56.023Z","repository":{"id":195710630,"uuid":"604558436","full_name":"logsem/iris-tutorial","owner":"logsem","description":null,"archived":false,"fork":false,"pushed_at":"2024-10-20T18:38:27.000Z","size":431,"stargazers_count":12,"open_issues_count":1,"forks_count":8,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-10-20T23:05:31.435Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Coq","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/logsem.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-21T10:10:49.000Z","updated_at":"2024-10-20T18:38:30.000Z","dependencies_parsed_at":"2023-09-27T17:27:06.675Z","dependency_job_id":"460472a5-871c-45d7-b16c-2fdb3823aa1f","html_url":"https://github.com/logsem/iris-tutorial","commit_stats":null,"previous_names":["logsem/iris-tutorial"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logsem%2Firis-tutorial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logsem%2Firis-tutorial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logsem%2Firis-tutorial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logsem%2Firis-tutorial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/logsem","download_url":"https://codeload.github.com/logsem/iris-tutorial/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227763357,"owners_count":17816170,"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-12-02T16:38:39.769Z","updated_at":"2024-12-02T16:38:40.375Z","avatar_url":"https://github.com/logsem.png","language":"Coq","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Iris Tutorial\nThe Iris Tutorial is an introduction to the [Iris separation logic framework](https://iris-project.org/) and how to work with its [Coq formalization](https://gitlab.mpi-sws.org/iris/iris/).\n\nThe exposition is intended for a broad range of readers from advanced undergraduates to PhD students and researchers. We assume that readers are already motivated to learn Iris and thus present the material in a bottom-up fashion, rather than starting out with cool motivating examples. The tutorial material is intended to be self-contained. No specific background in logic or programming languages is assumed but some familiarity with basic programming languages theory and discrete mathematics will be beneficial, see e.g. [TAPL](https://www.cis.upenn.edu/~bcpierce/tapl/). Additionally, basic knowledge of the Coq proof assistant is assumed. Advanced Coq tactics have been purposefully kept to a minimum, and some proofs are longer than necessary to facilitate learning. We demonstrate more advanced tactics in chapter [ticket_lock_advanced](/theories/ticket_lock_advanced.v).\n\nThe tutorial comes in two versions:\n\n- The folder `exercises`: a skeleton development with exercises left admitted.\n- The folder `theories`: the full development with solutions.\n\nThe tutorial consists of several chapters, each corresponding to a Coq file. The graph in [Chapter Dependencies](README.md#chapter-dependencies) illustrates possible ways to go through the tutorial. However, the recommended order is specified in the [Recommended Learning Path](README.md#recommended-learning-path).\n\n## Setup\nThis version is known to compile with\n\n- Coq 8.19.2\n- Iris 4.2.0\n\nThe recommended way to install the dependencies is through [opam](https://opam.ocaml.org/doc/Install.html).\n\n1. Install [opam](https://opam.ocaml.org/doc/Install.html) if not already installed (a version greater than 2.0 is required).\n2. Install a new switch and link it to the project.\n```\nopam switch create iris_tutorial 5.2.0\nopam switch link iris_tutorial .\n```\n3. Add the Coq opam repository.\n```\nopam repo add coq-released https://coq.inria.fr/opam/released\nopam repo add iris-dev https://gitlab.mpi-sws.org/iris/opam.git\nopam update\n```\n4. Install the right version of the dependencies as specified in the `iris-tutorial.opam` file.\n```\nopam install . --deps-only\n```\n\n## Editor\nIris makes extensive use of Unicode characters. [This guide](https://gitlab.mpi-sws.org/iris/iris/-/blob/master/docs/editor.md) describes how to set up your favorite editor.\n\n## Chapter Overview\n- [basics](/exercises/basics.v) - Introduction to the separation\n  logic and the Iris Proof Mode\n- [pure](/exercises/pure.v) - Distinction between the Coq context and the Iris context\n- [lang](/exercises/lang.v) - Introduction to HeapLang\n- [specifications](/exercises/specifications.v) - Weakest precondition,\n  basic resources, Hoare triples, and basic concurrency\n- [persistently](/exercises/persistently.v) - The persistently modality\n- [linked_lists](/exercises/linked_lists.v) - Linked lists\n- [later](/exercises/later.v) - The later modality and recursive functions\n- [arrays](/exercises/arrays.v) - Arrays in HeapLang\n- [gr_predicates](/exercises/gr_predicates.v) - Guarded Recursive Predicates\n- [resource_algebra](/exercises/resource_algebra.v) - Introduction to resource algebras\n- [invariants](/exercises/invariants.v) - Invariants\n- [timeless](/exercises/timeless.v) - Timeless propositions\n- [structured_conc](/exercises/structured_conc.v) - Introducing the spawn and par constructs\n- [counter](/exercises/counter.v) - The authoritative camera\n- [spin_lock](/exercises/spin_lock.v) - Specification of a spin lock\n- [ticket_lock](/exercises/ticket_lock.v) - Specification of a ticket lock\n- [ticket_lock_advanced](/theories/ticket_lock_advanced.v) - Advanced Coq tactics\n- [adequacy](/exercises/adequacy.v) - Adequacy\n- [merge_sort](/exercises/merge_sort.v) - Merge sort\n- [custom_ra](/exercises/custom_ra.v) - Defining resource algebras from scratch\n- [ofe](/exercises/ofe.v) - Detailed introduction to OFEs\n\n## Chapter Dependencies\n```mermaid\ngraph TD;\n  basics --\u003e pure;\n  pure --\u003e specs[specifications];\n  lang --\u003e specs;\n  specs --\u003e pers[persistently];\n  pers --\u003e  ra[resource algebra];\n  pers --\u003e later;\n  pers --\u003e linklist[linked list];\n\n  ra --\u003e invariants;\n\n  later --\u003e invariants;\n  later --\u003e grp[gr_predicates];\n  later --\u003e arrays;\n\n  linklist --\u003e grp;\n  linklist --\u003e arrays;\n\n  invariants --\u003e timeless;\n\n  arrays --\u003e merge[merge sort];\n\n  timeless --\u003e cst_ra[custom resource algebra];\n  timeless --\u003e strconc[structured concurrency];\n  timeless --\u003e ccs;\n\n  subgraph ccs[Case Studies on Concurrency]\n  counter;\n  spinlock;\n  ticketlock;\n  merge;\n  spinlock --\u003e ticketlock;\n  end\n\n  spinlock --\u003e adequacy;\n  cst_ra --\u003e ofe;\n```\n\n## Recommended Learning Path\nTo get a good understanding of the fundamental concepts of Iris, it is recommended to study the following chapters in the given order.\n\n1. [basics](/exercises/basics.v)\n2. [pure](/exercises/pure.v)\n3. [lang](/exercises/lang.v)\n4. [specifications](/exercises/specifications.v)\n5. [persistently](/exercises/persistently.v)\n6. [linked_lists](/exercises/linked_lists.v)\n7. [later](/exercises/later.v)\n8. [arrays](/exercises/arrays.v)\n9. [resource_algebra](/exercises/resource_algebra.v)\n10. [invariants](/exercises/invariants.v)\n11. [timeless](/exercises/timeless.v)\n12. [structured_conc](/exercises/structured_conc.v)\n13. [counter](/exercises/counter.v)\n14. [spin_lock](/exercises/spin_lock.v)\n15. [ticket_lock](/exercises/ticket_lock.v)\n16. [adequacy](/exercises/adequacy.v)\n\n## Exercises\nTo work on the exercises, simply edit the files in the `exercises/` folder. Some proofs and definitions are admitted and marked as `(* exercise *)`---your task is to fill in those definitions and complete the proofs all the way to `Qed`.\n\nAfter you are done with a file, run `make` (with your working directory being the repository root, where the `Makefile` is located) to compile and check the exercises.\n\nIf you are stuck, you can find solutions in the corresponding file in the `theories/` folder.\n\n## Documentation\nThis [cheatsheet](/cheatsheet.md) contains a table of the most important tactics for each logical connective. A full description of the Iris Proof Mode tactics can be found in the files [proof_mode.md](https://gitlab.mpi-sws.org/iris/iris/-/blob/master/docs/proof_mode.md) and [heap_lang.md](https://gitlab.mpi-sws.org/iris/iris/-/blob/master/docs/heap_lang.md).\n\n## Optional Reading\n\nCurrently, the [Iris Lecture Notes](https://iris-project.org/tutorial-material.html) cover all the material presented in this tutorial and more. The lecture notes are not required to work through the tutorial, but readers may want to refer to the lecture notes for additional/alternative explanations of introduced concepts.\n\nIn its current state, this tutorial does not go over the underlying model of Iris. For readers who wish to learn about the underlying model of Iris, we refer to the [Iris from the ground up](https://people.mpi-sws.org/~dreyer/papers/iris-ground-up/paper.pdf) paper. Advanced readers may read this paper prior to going through the tutorial. However, it is generally recommended to study it afterwards, given its technical nature.\n\n## Contributing\n\nThe hope is that the maintenance and extension of this tutorial becomes a collaborative community effort. We warmly welcome all contributions—whether it's correcting a typo, improving clarity, or extending the tutorial with new chapters.\n\nIf you have suggestions for future topics or improvements for existing ones, please add them to [TODO.md](TODO.md).\n\n**Note**: by contributing to the Iris Tutorial you agree that your contributions will be released under the terms of Iris Tutorial's license — see [the LICENSE file](LICENSE).\n\n### How to Contribute\n\nTo contribute, we recommend following these steps:\n\n1. Fork the repository.\n2. Create a new branch on the forked repository.\n3. Make your changes in the branch.\n4. Commit and push your changes.\n5. Open a pull request to the main repository\n\nFor more detailed instructions, see [first-contributions](\nhttps://github.com/firstcontributions/first-contributions).\n\n### CoqdocJS\nThis tutorial uses [CoqdocJS](https://github.com/coq-community/coqdocjs), so please make sure to format your changes accordingly. To see what your changes will look like in the documentation, run\n```\ngit submodule update --init\nmake html\n```\nThen open `html/toc.html` in a browser, and navigate to the chapter(s) containing your changes.\n\n### Generating the Exercises\nNote that the files in `exercises/` are generated from the corresponding files in `theories/`. As such, if you wish to make changes to a chapter, please make those changes to the `theories`-version of the chapter. Afterwards, the `exercises`-version can be re-generated by running `make exercises`. This requires `gawk` to be installed (which should be available on Linux, and on macOS can be installed via `brew install gawk`).\n\nThe syntax for the solution files is as follows:\n\n    (* SOLUTION *) Proof.\n      solution here.\n    Qed.\n\nis replaced by\n\n    Proof.\n      (* exercise *)\n    Admitted.\n\nand the more powerful\n\n    (* BEGIN SOLUTION *)\n      solution here.\n    (* END SOLUTION BEGIN TEMPLATE\n      exercise template here.\n    END TEMPLATE *)\n\nis replaced by\n\n      exercise template here.\n\n### Contact\nIf you have specific requests or questions about the tutorial, please contact:\n\n**Amin Timany**\\\nAarhus University\\\n\u003ctimany@cs.au.dk\u003e\n\n### Contributors\nBelow is a list of people who have contributed to the tutorial, sorted by last name. If you have contributed to the project, please add yourself to the list.\n\n**Lars Birkedal**\\\nAarhus University\\\n\u003cbirkedal@cs.au.dk\u003e\n\n**Simon Gregersen**\\\nAarhus University\\\n\u003cgregersen@cs.au.dk\u003e\n\n**Mathias Adam Møller**\\\nAarhus University\\\n\u003cmathias.adam.moeller@gmail.com\u003e\n\n**Mathias Pedersen**\\\nAarhus University\\\n\u003cmathiasp9999@gmail.com\u003e\n\n**Amin Timany**\\\nAarhus University\\\n\u003ctimany@cs.au.dk\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flogsem%2Firis-tutorial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flogsem%2Firis-tutorial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flogsem%2Firis-tutorial/lists"}