From 248e448c397543bbd4fb35519ecb1188ee015840 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 | 414 ++++++++++++++++++++++------------------------------ 2 files changed, 203 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..6b778fde 100644 --- a/README.md +++ b/README.md @@ -1,324 +1,258 @@ # 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 core component of Cartesi's verifiable computation stack, providing a deterministic and high-performance RISC-V virtual machine that can be used to run complex computations off-chain, with the results being verifiable on-chain. + +At its core, the emulator allows developers to perform intensive and complex computations outside of the blockchain using traditional Linux software stack while maintaining cryptographic guarantees that these computations were performed correctly. +This enables complex applications that would be impractical to run directly on-chain due to gas costs or computational limitations. + +The emulator implements the RISC-V RV64GC ISA, including both the unprivileged and privileged specifications, making it capable of running full Linux operating systems. +It is written in C++, is scriptable in Lua, and provides a C API. +It is available both as a CLI application and as a library that is easy to integrate into other applications. + +*TLDR.* +> I can use the Cartesi Machine to generate cryptographic proofs demonstrating `sha(F(S, I)) = H`, where `F` is a deterministic state transition function executing a full Linux operating system, `S` represents the rolling machine state, `I` denotes input data, and `H` is the resultant output Merkle root hash verifiable on-chain. + +## Features + +- **Complete RISC-V RV64GC ISA support** (both privileged and unprivileged) +- **High-performance and deterministic** RISC-V interpreter +- **Lua scripting interface** for rapid prototyping +- **Simple C API**, facilitating integration with various languages (e.g., C++, Rust, Go, Python, and JavaScript) +- **JSON-RPC API endpoint** for remote machine control +- **Linux kernel execution**, enabling the running of standard Linux distributions (e.g., Ubuntu) +- **Full-featured Linux environment** for user-space applications using traditional software stacks +- **Interactive CLI application** for prototyping +- **Cross-platform compatibility** (Linux, macOS, Windows, and WebAssembly) +- **Freestanding compilation** suitable for embedding in other applications (e.g., in a zkVM) +- **State Merkle tree computation** for generating proofs +- **State transition access logging** for on-chain verification +- **State transition bisection** through CPU cycle-level execution control +- **State inspection capabilities** of the entire machine CPU and address space +- **State serialization** for storing and loading machine snapshots +- **Microarchitecture-based emulation** of the primary RISC-V interpreter for simplified on-chain verification +- **Generic I/O interface** for handling data input/output through state transitions +- **Large state address space** enabling applications to utilize gigabytes of data +- **Deterministic floating-point** support +- **VirtIO network and shared filesystem** devices for accessing host state while prototyping +- **Forking support** enabling parallel execution and efficient rollback of state transitions +- **Minimal runtime** dependencies +- **WebAssembly compatibility**, enabling deterministic computations directly in browser frontends + +## 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 - -Obs: Please note that Apple Clang Version number does not follow upstream LLVM/Clang. - -#### Debian Bookworm - -```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 - -sudo luarocks install --lua-version=5.4 luasocket -sudo luarocks install --lua-version=5.4 luasec -sudo luarocks install --lua-version=5.4 luaposix -``` - -For more information, see the [Configuring Lua 5.4](#configuring-lua-54) section. +### Installation -#### MacOS +We provide official packages for some distributions, but you can also build from source. -##### MacPorts +#### Debian -```bash -sudo port install clang-16 boost181 wget pkgconfig lua54 lua-luarocks libslirp +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. - -##### Homebrew - -```bash -brew install llvm@16 boost wget pkg-config openssl lua luarocks libslirp - -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 -``` - -For more information, see the [Configuring Lua 5.4](#configuring-lua-54) section. - -##### Configuring Lua 5.4 +#### Ubuntu -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: +We maintain Ubuntu 24.04 packages for amd64 and arm64, you can install with: -```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 +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 ``` -###### Setting Up LuaRocks Modules +#### Arch Linux -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.: +We maintain an official Arch Linux package in [AUR](https://aur.archlinux.org/packages/cartesi-machine), you can install with: -```bash -eval "$(luarocks path --lua-version=5.4)" +```sh +yay -S cartesi-machine ``` -This command adjusts the environment variables for your shell sessions, ensuring LuaRocks-installed modules are correctly discovered by Lua scripts. +#### Homebrew -### Build +We maintain a Homebrew tap for macOS, you can install with: -```bash -git clone --recurse-submodules -j3 https://github.com/cartesi/machine-emulator.git -make +```sh +brew tap cartesi/tap +brew install cartesi-machine ``` -Cleaning: +#### From Sources -```bash -make clean -``` +##### System Requirements -Microarchitecture: +- C++ Compiler with support for C++20 (tested with GCC >= 8+ and Clang >= 8.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 - -Both `libcartesi` and `libcartes_jsonrpc` C libraries can be compiled in standalone, either as static or shared library: +###### Homebrew Requirements -```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 openssl 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: +#### Build -```bash -# Target WASM with Emscripten toolchain -make -C src \ - CC=emcc CXX=em++ AR="emar rcs" \ - libcartesi.a +First make sure to have all the [requirements](#system-requirements) in your system, then run the following to build and install the latest release of the machine: -# 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 +```sh +# clone the latest release of the emulator +git clone --branch latest https://github.com/cartesi/machine-emulator.git +cd machine-emulator -# 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 +# 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 -To build and execute the all tests run: - -```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 - -We use clang-tidy 15 as the linter. - -### Install +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`. -#### Debian Bookworm +### Usage -You need to install the package clang-tidy-16 and set it as the default executable with update-alternatives. +Once you have the emulator, guest Linux kernel and guest rootfs images installed, you can boot a Ubuntu distribution by running: -```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 - -We use clang-format to format the code base. - -### Install - -#### Debian Bookworm + . + / \ + / \ +\---/---\ /----\ + \ X \ + \----/ \---/---\ + \ / CARTESI + \ / MACHINE + ' -You need to install the package clang-format-16 and set is as the default executable with update-alternatives. +Nothing to do. -```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 emulators, +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 currently 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. +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. -### Submodules and Dependencies +## Authors -This project includes several submodules and dependencies, each with its own licensing: +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. -- `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. +## 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.