From 3675763b3ecd4a84f454cb0297854d13145c2ba1 Mon Sep 17 00:00:00 2001 From: Eduardo Bart Date: Mon, 16 Dec 2024 20:19:39 -0300 Subject: [PATCH] docs: refactor README --- LICENSES.md | 29 ++++ README.md | 419 ++++++++++++++++++++++------------------------------ 2 files changed, 208 insertions(+), 240 deletions(-) create mode 100644 LICENSES.md diff --git a/LICENSES.md b/LICENSES.md new file mode 100644 index 00000000..a6c9df24 --- /dev/null +++ b/LICENSES.md @@ -0,0 +1,29 @@ +# License + +This projects is licensed under the L[LGPL 3.0](https://www.gnu.org/licenses/lgpl-3.0.html) license. See the license terms in [COPYING](COPYING). + +## Submodules and Dependencies + +This project includes several submodules and dependencies, each with its own licensing: + +- `tests/machine`: Licensed under the Apache License 2.0. See the license terms in [tests/machine/LICENSE](tests/machine/LICENSE). +- `tests/uarch`: Licensed under the Apache License 2.0. Licensing details are available in [tests/uarch/LICENSE](tests/uarch/LICENSE). +- `third-party/llvm-flang-uint128`: Licensed under the Apache License 2.0 with LLVM exceptions. The license can be found at [third-party/llvm-flang-uint128/LICENSE](third-party/llvm-flang-uint128/LICENSE). +- `third-party/riscv-arch-test`: Source code licensed under the Apache 2.0 and BSD 3-Clause licenses. Documentation under `CC-BY-4.0`. License information is provided in README.md and other COPYING.* files like [third-party/riscv-arch-test/COPYING.APACHE](third-party/riscv-arch-test/COPYING.APACHE). +- `third-party/riscv-tests`: Licensed under the BSD 3-Clause "New" or "Revised" License. See [third-party/riscv-tests/LICENSE](third-party/riscv-tests/LICENSE) for license details. +- `third-party/riscv-tests/env`: Licensed under the BSD 3-Clause "New" or "Revised" License. License details are in [third-party/riscv-tests/env/LICENSE](third-party/riscv-tests/env/LICENSE). +- `third-party/tiny_sha3`: Licensed under the MIT License. The license can be found at [third-party/tiny_sha3/LICENSE](third-party/tiny_sha3/LICENSE). +- `third-party/nlohmann-json`: Licensed under the MIT License. The license can be found at [third-party/nlohmann-json/LICENSE.MIT](third-party/nlohmann-json/LICENSE.MIT). + +## Debian Packages + +The project releases several Debian packages, each subject to its specific licensing terms: + +- `cartesi-machine-[VERSION]_[ARCHITECTURE].deb` and `cartesi-machine-tests-[VERSION]_[ARCHITECTURE].deb` packages are licensed under LGPL v3.0 and may include or link to other software components with different licenses. +- `cartesi-machine-tests-data-[VERSION].deb`: This package contains files that are individually licensed under various terms, including but not limited to Apache-2.0, BSD-3-Clause-Regents, BSD-3-Clause, and GPL-2.0-only. For a comprehensive overview of the licenses applicable to specific files within this package, please refer to its copyright file, e.g., [tools/template/tests-data-copyright.template](tools/template/tests-data-copyright.template). + +For detailed licensing information of each Debian package, please refer to the copyright file included within the package. + +## Additional Notes + +This project may include or link to other software components with different licenses. Contributors and users are responsible for ensuring compliance with each component's licensing terms. For detailed information, please refer to the individual LICENSE files within each directory or submodule, and for the Debian packages, please review the respective copyright and licensing details as mentioned above. diff --git a/README.md b/README.md index 58e83ca6..c63d3396 100644 --- a/README.md +++ b/README.md @@ -1,324 +1,263 @@ # Cartesi Machine Emulator -The Cartesi Machine Emulator is the reference off-chain implementation of the Cartesi Machine Specification. It's written in C/C++ with POSIX dependencies restricted to the terminal, process, and memory-mapping facilities. It is distributed as a library and scriptable in the Lua programming language. - -The emulator implements RISC-V's RV64IMASU ISA. The letters after RV specify the extension set. This selection corresponds to a 64-bit machine, Integer arithmetic with Multiplication and division, Atomic operations, as well as the optional Supervisor and User privilege levels. In addition, Cartesi Machines support the Sv48 mode of address translation and memory protection. +[![Latest Release](https://img.shields.io/github/v/release/cartesi/machine-emulator?label=version)](https://github.com/cartesi/machine-emulator/releases) +[![Build Status](https://img.shields.io/github/actions/workflow/status/cartesi/machine-emulator/build.yml?branch=main)](https://github.com/cartesi/machine-emulator/actions) +[![License](https://img.shields.io/github/license/cartesi/machine-emulator)](LICENSE) + +The Cartesi Machine Emulator is the basis of Cartesi's verifiable computation framework. +It is a portable, deterministic, high-performance RISC-V emulator (a.k.a. a virtual machine) that can run complex computations off-chain but supports on-chain verification via fraud proofs. + +Under the hood, the emulator implements the RISC-V RV64GC ISA (including the unprivileged and privileged specifications). +This allows it to boot Linux, which in turn, gives creators access to traditional software development stacks when developing and running their applications. + +Written in C++, the Cartesi Machine Emulator is available as a standalone CLI application or as a library for embedding into other applications. +It can be controlled via a well-defined C API that can be easily accessed from multiple programming languages. +In particular, it can be scripted in Lua, for fast prototyping and testing. + +*TL;DR:* +> I can use the Cartesi Machine to disprove a dishonest result of a computation `M' = F(M)`, where `F` is a deterministic state transition function that corresponds to running an application on top of the Linux operating system to process some input, `M = (S, I)` is the initial state `S` of the machine and the input `I`, and `M' = (S', O')` is the final state `S'` of the machine and its output `O'`. + +## Features + +- **Powerful** + - **High-performance RISC-V emulation**, delivering high execution speed for demanding applications. + - **Complete RISC-V RV64GC ISA support**, covering both privileged and unprivileged specifications. + - **Linux kernel execution**, enabling running of standard Linux distributions (e.g., Ubuntu). + - **Full-featured Linux environment**, enabling applications to use traditional software stacks. + - **Large state address space**, enabling applications to utilize gigabytes of data. + - **Forking support**, enabling parallel execution and efficient rollback of state transitions. + - **State inspection capabilities**, enabling examination of the entire address space and processor. +- **Developer Friendly** + - **Simple C API**, facilitating integration with various languages (e.g., C++, Rust, Go, Python, JavaScript). + - **Lua scripting interface**, for rapid prototyping and testing. + - **JSON-RPC API endpoint**, enabling remote machine control. + - **Interactive CLI application**, for prototyping in the terminal. + - **VirtIO network and shared filesystem devices**, allowing access to host state during prototyping. + - **State serialization**, for storing and loading of machine snapshots. +- **Verifiable** + - **Deterministic execution**, ensuring every instruction is reproducible (including floating-point). + - **State Merkle tree computation**, for generating cryptographic proofs. + - **State transition access logging**, enabling on-chain verification of state transitions. + - **Cycle-level execution control**, for interactive fraud-proof bisection. + - **Microarchitecture-based emulation** of its interpreter for simplifying on-chain verification. + - **Generic I/O interface**, enabling handling of data input/output through state transitions. +- **Portable** + - **Cross-platform compatibility**, including Linux, macOS and Windows. + - **WebAssembly compatibility**, bringing all capabilities to browser environments. + - **Freestanding compilation**, suitable for embedding in other applications (e.g., in a zkVM). + - **Minimal runtime dependencies**, ensuring easy installation and integration. + +## Overview + +For a comprehensive technical overview of the Cartesi Machine emulator and its blockchain use cases, +you can watch this detailed presentation by Diego Nehab, +the principal architect of the Cartesi Machine, at the Ethereum Engineering Group: + +[![Cartesi Machine Overview](https://img.youtube.com/vi/ofb7MJ8dK0U/0.jpg)](https://www.youtube.com/watch?v=ofb7MJ8dK0U) + +In addition, you can watch an insightful interview with Diego Nehab about the Cartesi Machine on Cartesi's YouTube channel: + +[![Cartesi Machine Deep Dive](https://img.youtube.com/vi/uUzn_vdWyDM/0.jpg)](https://www.youtube.com/watch?v=uUzn_vdWyDM) ## Getting Started -Run `make help` for a list of target options. Here are some of them: - -``` -Main targets: -* all - Build the src/ code. To build from a clean clone, run: make submodules all - uarch - Build microarchitecture (requires riscv64-cartesi-linux-gnu-* toolchain) - uarch-with-toolchain - Build microarchitecture using the toolchain docker image - build-tests-all - Build all tests (machine, uarch and misc) - build-tests-machine - Build machine emulator tests (requires rv64gc-lp64d riscv64-cartesi-linux-gnu-* toolchain) - build-tests-machine-with-toolchain - Build machine emulator tests using the rv64gc-lp64d toolchain docker image - build-tests-uarch - Build microarchitecture rv64i instruction tests (requires rv64ima-lp64 riscv64-cartesi-linux-gnu-* toolchain) - build-tests-uarch-with-toolchain - Build microarchitecture rv64i instruction tests using the rv64ima-lp64 toolchain docker image - build-tests-misc - Build miscellaneous tests - build-tests-misc-with-builder-image - Build miscellaneous tests using the cartesi/machine-emulator:builder image - test-machine - Run machine emulator tests - test-uarch - Run uarch tests - test-misc - Run miscellaneous tests - test - Run all tests - doc - Build the doxygen documentation (requires doxygen) -Docker images targets: - build-emulator-image - Build the machine-emulator debian based docker image - build-debian-package - Build the cartesi-machine.deb package from image - build-toolchain - Build the emulator toolchain docker image - create-generated-files-patch - Create patch that adds generated files to source tree -Cleaning targets: - clean - Clean the src/ artifacts - depclean - Clean + dependencies - distclean - Depclean + profile information and downloads -``` - -### Requirements - -- C++ Compiler with support for C++20 (tested with GCC >= 8+ and Clang >= 8.x). -- GNU Make >= 3.81 -- Lua >= 5.4.4 -- Libslirp >= 4.6.0 -- Boost >= 1.81 +### Installation -Obs: Please note that Apple Clang Version number does not follow upstream LLVM/Clang. +We provide official packages for some distributions, but you can also build from source. -#### Debian Bookworm +#### Debian -```bash -sudo apt-get install build-essential wget git clang-tidy-16 clang-format-16 \ - libboost1.81-dev libssl-dev libslirp-dev \ - ca-certificates pkg-config lua5.4 liblua5.4-dev \ - luarocks +We maintain Debian Bookworm packages for amd64 and arm64, you can install with: -sudo luarocks install --lua-version=5.4 luasocket -sudo luarocks install --lua-version=5.4 luasec -sudo luarocks install --lua-version=5.4 luaposix +```sh +wget https://github.com/cartesi/machine-emulator/releases/download/latest/cartesi-machine_debian-bookworm-$(dpkg --print-architecture).deb +dpkg -i cartesi-machine_debian-bookworm-$(dpkg --print-architecture).deb ``` -For more information, see the [Configuring Lua 5.4](#configuring-lua-54) section. - -#### MacOS +#### Ubuntu -##### MacPorts +We maintain Ubuntu 24.04 packages for amd64 and arm64, you can install with: -```bash -sudo port install clang-16 boost181 wget pkgconfig lua54 lua-luarocks libslirp - -sudo luarocks install --lua-version=5.4 luasocket -sudo luarocks install --lua-version=5.4 luasec -sudo luarocks install --lua-version=5.4 luaposix +```sh +wget https://github.com/cartesi/machine-emulator/releases/download/latest/cartesi-machine_ubuntu-24.04-$(dpkg --print-architecture).deb +dpkg -i cartesi-machine_ubuntu-24.04-$(dpkg --print-architecture).deb ``` -For more information, see the [Configuring Lua 5.4](#configuring-lua-54) section. - -##### Homebrew +#### Arch Linux -```bash -brew install llvm@16 boost wget pkg-config openssl lua luarocks libslirp +We maintain an official Arch Linux package in [AUR](https://aur.archlinux.org/packages/cartesi-machine), you can install with: -luarocks --lua-dir=$(brew --prefix)/opt/lua install luasocket -luarocks --lua-dir=$(brew --prefix)/opt/lua install luasec -luarocks --lua-dir=$(brew --prefix)/opt/lua install luaposix +```sh +yay -S cartesi-machine ``` -For more information, see the [Configuring Lua 5.4](#configuring-lua-54) section. +#### Homebrew -##### Configuring Lua 5.4 +We maintain a Homebrew tap for macOS, you can install with: -For emulator scripts to function properly, it is necessary for the lua5.4 binary to be available in the system PATH. If your operating system or package manager provides a Lua binary under a different name (e.g., lua instead of lua5.4, which is common on Homebrew), you will need to create a symbolic link or an alias named lua5.4. This can be done as follows: - -```bash -ln -s $(which lua) /usr/local/bin/lua5.4 # Create a symbolic link (adjust as needed for your system) -# or -alias lua5.4='lua' # Create an alias (add this line to your shell profile file like .bashrc or .zshrc) +```sh +brew tap cartesi/tap +brew install cartesi-machine ``` -###### Setting Up LuaRocks Modules - -To use features that require LuaRocks modules, you must ensure your environment is configured to find these modules. Export the output of `luarocks path --lua-version=5.4` to your environment by executing them or adding it to your .bashrc or .zshrc file. E.g.: +#### From Sources -```bash -eval "$(luarocks path --lua-version=5.4)" -``` +##### System Requirements -This command adjusts the environment variables for your shell sessions, ensuring LuaRocks-installed modules are correctly discovered by Lua scripts. - -### Build - -```bash -git clone --recurse-submodules -j3 https://github.com/cartesi/machine-emulator.git -make -``` - -Cleaning: - -```bash -make clean -``` - -Microarchitecture: +- C++ Compiler with support for C++20 (tested with GCC >= 11.x and Clang >= 14.x). +- GNU Make >= 3.81 +- Boost >= 1.81 +- Lua >= 5.4.4 (optional, required for scripting support and interactive terminal) +- Libslirp >= 4.6.0 (optional, required for networking support) -If you want to use a pre-built uarch RAM image instead of building one, use the variable `UARCH_RAM_IMAGE` to specify the path to the desired image file. +###### Debian Requirements -```bash -$ make UARCH_RAM_IMAGE= +```sh +sudo apt-get install build-essential git wget libboost1.81-dev liblua5.4-dev libslirp-dev lua5.4 ``` -### Install +###### MacPorts Requirements -```bash -sudo make install PREFIX=/usr/local +```sh +sudo port install clang boost181 wget pkgconfig lua54 libslirp ``` -### Build C libraries in standalone +###### Homebrew Requirements -Both `libcartesi` and `libcartes_jsonrpc` C libraries can be compiled in standalone, either as static or shared library: - -```bash -make bundle-boost -make -C src libcartesi.a libcartesi_jsonrpc.a libcartesi.so libcartesi_jsonrpc.so +```sh +brew install llvm boost wget pkg-config lua libslirp ``` -The `.a` and `.so` files will be available in `src` directory, you can use any of them to link your application. - -You can even use other toolchains to cross compile targeting other platforms: - -```bash -# Target WASM with Emscripten toolchain -make -C src \ - CC=emcc CXX=em++ AR="emar rcs" \ - libcartesi.a +#### Build -# Target WASM with WASI SDK toolchain -make -C src \ - CC=/opt/wasi-sdk/bin/clang CXX=/opt/wasi-sdk/bin/clang++ AR="/opt/wasi-sdk/bin/llvm-ar rcs" \ - libcartesi.a +First, make sure to have all the system requirements, then run the following to build and install the latest release of the machine: -# Target Windows with mingw-w64 toolchain -make -C src \ - CC=x86_64-w64-mingw32-gcc \ - CXX=x86_64-w64-mingw32-g++ \ - AR="x86_64-w64-mingw32-ar rcs" \ - libcartesi.a -``` - -## Running Tests +```sh +# clone the latest release of the emulator +git clone --branch latest https://github.com/cartesi/machine-emulator.git +cd machine-emulator -To build and execute the all tests run: +# patch the sources with required generated files +wget https://github.com/cartesi/machine-emulator/releases/download/latest/add-generated-files.diff +git apply add-generated-files.diff -```bash -make build-tests-all -make test +# compile +make ``` -To execute the machine test suite run: +*Note*: We recommend running only the latest release. If you want to build the `main` development branch, you will need to regenerate files instead of patching the sources, which will require Docker on your system. For more details, please check our [development guide](https://github.com/cartesi/machine-emulator/wiki/Development-Guide). -```bash -make build-tests-machine-with-toolchain -make test-machine -``` +Finally, you can install it in your system in any path you would like with: -To execute the uarch test suite run: +```sh +# install the emulator +export INSTALL_PATH=/usr/local +sudo make install PREFIX=$INSTALL_PATH -```bash -make build-tests-uarch-with-toolchain -make test-uarch +# install latest guest Linux kernel and guest rootfs images +sudo mkdir -p $INSTALL_PATH/share/cartesi/images +sudo wget -O $INSTALL_PATH/share/cartesi/images/linux.bin https://github.com/cartesi/image-kernel/releases/download/latest/linux.bin +sudo wget -O $INSTALL_PATH/share/cartesi/images/rootfs.ext2 https://github.com/cartesi/machine-emulator-tools/releases/download/latest/rootfs.ext2 ``` -## Linter +Note that we also download guest Linux kernel and guest rootfs images to be used with the emulator. They are required to boot the default Ubuntu distribution with `cartesi-machine`. -We use clang-tidy 15 as the linter. +### Usage -### Install +Once you have the emulator, guest Linux kernel, and guest rootfs images installed, you can boot a Ubuntu distribution by running: -#### Debian Bookworm - -You need to install the package clang-tidy-16 and set it as the default executable with update-alternatives. - -```bash -apt install clang-tidy-16 -update-alternatives --install /usr/bin/clang-tidy clang-tidy /usr/bin/clang-tidy-16 120 +```sh +cartesi-machine ``` -### Running Lint - -```bash -make lint -j$(nproc) +It should output something similar to: ``` -## Code format + . + / \ + / \ +\---/---\ /----\ + \ X \ + \----/ \---/---\ + \ / CARTESI + \ / MACHINE + ' -We use clang-format to format the code base. +Nothing to do. -### Install - -#### Debian Bookworm - -You need to install the package clang-format-16 and set is as the default executable with update-alternatives. - -```bash -apt install clang-format-16 -update-alternatives --install /usr/bin/clang-format clang-format /usr/bin/clang-format-16 120 +Halted +Cycles: 48415113 ``` -### Formatting code +You can start an interactive terminal to play around with: -```bash -make format +```sh +cartesi-machine -it bash ``` -### Checking whether the code is formatted +And there you have a full Linux running in a RISC-V emulated CPU that you can interact with. +You can check the `cartesi-machine --help` for more information on how to use the CLI application. -```bash -make check-format -``` +### Library -## Coverage +You can use the emulator as library in other applications, its `libcartesi` library provides a [C API](https://github.com/cartesi/machine-emulator/blob/refactor/new-readme/src/machine-c-api.h) that is very simple to use. -### Dependencies +Check the following wiki guides on how to use with different languages: +- [C/C++](https://github.com/cartesi/machine-emulator/wiki/Using-the-C-API) +- [Rust](https://github.com/cartesi/machine-emulator/wiki/Using-the-C-API-with-Rust) +- [Go](https://github.com/cartesi/machine-emulator/wiki/Using-the-C-API-with-Go) +- [JavaScript](https://github.com/cartesi/machine-emulator/wiki/Using-the-C-API-with-JavaScript) +- [Python](https://github.com/cartesi/machine-emulator/wiki/Using-the-C-API-with-Python) +- [Lua](https://github.com/cartesi/machine-emulator/wiki/Using-the-Lua-API) +- [WebAssembly](https://github.com/cartesi/machine-emulator/wiki/Using-the-C-API-with-WebAssembly) -#### Debian Bookworm +## Use Cases -If you want to run the GCC-based coverage, you should install the lcov package with the following command. +The following projects have been using the emulator: +- [Cartesi Rollups Node](https://github.com/cartesi/rollups-node) - Uses the emulator's library in Go for Layer 2 rollups on Ethereum. +- [Cartesi Dave](https://github.com/cartesi/dave) - Uses the emulator's library in Rust for on-chain fraud-proofs validation. +- [Cartesi CLI](https://github.com/cartesi/machine-emulator/projects) - Uses the emulator's CLI in TypeScript for DApp development. -```bash -sudo apt install lcov -``` +## Benchmarks -If you want to run the clang-based coverage, you should install the clang package with the following command. +The emulator's RISC-V interpreter is optimized for high performance given the requirements of on-chain verification. +For detailed performance metrics comparing the emulator against bare-metal execution and other virtual machines, +please see our [benchmarks](https://github.com/cartesi/machine-emulator/wiki/Benchmarks) page. -```bash -sudo apt install clang llvm -``` +## Documentation -### Compilation +The Cartesi Machine emulator documentation is undergoing a comprehensive update. +While the full documentation is being refreshed, you can find guides and tutorials in our [wiki](https://github.com/cartesi/machine-emulator/wiki). -Before running the coverage, you should build the emulator with the flag coverage-toolchain=gcc or coverage-toolchain=clang. -Make sure you run `make clean` to clean up any previous compilation. -For GCC-based coverage run the following command. +## Change Log -```bash -make coverage=yes COVERAGE_TOOLCHAIN=gcc -j$(nproc) -make build-tests-all coverage=yes COVERAGE_TOOLCHAIN=gcc -j$(nproc) -``` +Changes between emulator releases are documented in [CHANGELOG](CHANGELOG). -For clang-based coverage run the following command. +## Roadmap -```bash -make coverage=yes COVERAGE_TOOLCHAIN=clang -j$(nproc) -make build-tests-all coverage=yes COVERAGE_TOOLCHAIN=clang -j$(nproc) -``` +We are continually improving the emulator with new features and enhancements. +Check out our roadmap at [GitHub Projects](https://github.com/cartesi/machine-emulator/projects) to see what's coming in the future. -### Running coverage +## Community & Support -After building the emulator with coverage enable, you should run the following command. -For instance: +- Join our [Discord](https://discord.gg/cartesi) `#cartesi-machine` channel to engage with the emulator users and developers. +- Report issues on our [GitHub Issues](https://github.com/cartesi/machine-emulator/issues). -```bash -make test coverage-report coverage=yes COVERAGE_TOOLCHAIN=gcc -``` +## Developing -This command will generate a coverage report in the src directory. -For clang coverage, repeat the same command but with the flag coverage-toolchain=clang. +For more detailed information about developing the emulator, including instructions for running tests, using the linter, and code formatting, please refer to our [development guide](https://github.com/cartesi/machine-emulator/wiki/Development-Guide) in the wiki. ## Contributing -Thank you for your interest in Cartesi! Head over to our [Contributing Guidelines](CONTRIBUTING.md) for instructions on how to sign our Contributors Agreement and get started with -Cartesi! - -Please note we have a [Code of Conduct](CODE_OF_CONDUCT.md), please follow it in all your interactions with the project. - -## License - -The `machine-emulator` repository and all contributions to it are licensed under the [LGPL 3.0](https://www.gnu.org/licenses/lgpl-3.0.html), unless otherwise specified below or in subdirectory LICENSE / COPYING files. Please review our [COPYING](COPYING) file for the LGPL 3.0 license. - -### Submodules and Dependencies +Please see our [contributing guidelines](CONTRIBUTING.md) for instructions on how to start contributing to the project. +Note we have a [code of conduct](CODE_OF_CONDUCT.md), please follow it in all your interactions with the project. -This project includes several submodules and dependencies, each with its own licensing: +## Authors -- `tests/machine`: Licensed under the Apache License 2.0. See the license terms in [tests/machine/LICENSE](tests/machine/LICENSE). -- `tests/uarch`: Licensed under the Apache License 2.0. Licensing details are available in [tests/uarch/LICENSE](tests/uarch/LICENSE). -- `third-party/llvm-flang-uint128`: Licensed under the Apache License 2.0 with LLVM exceptions. The license can be found at [third-party/llvm-flang-uint128/LICENSE](third-party/llvm-flang-uint128/LICENSE). -- `third-party/riscv-arch-test`: Source code licensed under the Apache 2.0 and BSD 3-Clause licenses. Documentation under `CC-BY-4.0`. License information is provided in README.md and other COPYING.* files like [third-party/riscv-arch-test/COPYING.APACHE](third-party/riscv-arch-test/COPYING.APACHE). -- `third-party/riscv-tests`: Licensed under the BSD 3-Clause "New" or "Revised" License. See [third-party/riscv-tests/LICENSE](third-party/riscv-tests/LICENSE) for license details. -- `third-party/riscv-tests/env`: Licensed under the BSD 3-Clause "New" or "Revised" License. License details are in [third-party/riscv-tests/env/LICENSE](third-party/riscv-tests/env/LICENSE). -- `third-party/tiny_sha3`: Licensed under the MIT License. The license can be found at [third-party/tiny_sha3/LICENSE](third-party/tiny_sha3/LICENSE). -- `third-party/nlohmann-json`: Licensed under the MIT License. The license can be found at [third-party/nlohmann-json/LICENSE.MIT](third-party/nlohmann-json/LICENSE.MIT). +The Cartesi Machine emulator is actively developed by [Cartesi](https://cartesi.io/)'s Machine Reference Unit, with significant contributions from many open-source developers. +For a complete list of authors, see the [AUTHORS](AUTHORS) file. -### Debian Packages - -The project releases several Debian packages, each subject to its specific licensing terms: - -- `cartesi-machine-[VERSION]_[ARCHITECTURE].deb` and `cartesi-machine-tests-[VERSION]_[ARCHITECTURE].deb` packages are licensed under LGPL v3.0 and may include or link to other software components with different licenses. -- `cartesi-machine-tests-data-[VERSION].deb`: This package contains files that are individually licensed under various terms, including but not limited to Apache-2.0, BSD-3-Clause-Regents, BSD-3-Clause, and GPL-2.0-only. For a comprehensive overview of the licenses applicable to specific files within this package, please refer to its copyright file, e.g., [tools/template/tests-data-copyright.template](tools/template/tests-data-copyright.template). - -For detailed licensing information of each Debian package, please refer to the copyright file included within the package. - -### Additional Notes - -This project may include or link to other software components with different licenses. Contributors and users are responsible for ensuring compliance with each component's licensing terms. For detailed information, please refer to the individual LICENSE files within each directory or submodule, and for the Debian packages, please review the respective copyright and licensing details as mentioned above. +## License +The repository and all contributions to it are licensed under the [LGPL 3.0](https://www.gnu.org/licenses/lgpl-3.0.html), unless otherwise specified below or in subdirectory LICENSE / COPYING files. +Please review our [COPYING](COPYING) file for the LGPL 3.0 license and also [LICENSES](LICENSES.md) file for additional information on third-party software licenses.