= https://github.com/input-output-hk/plutus[Plutus Platform]
:email: plutus@iohk.io
:author: Input Output HK Limited
:toc: left
:reproducible:

The Plutus Platform enables you to:

• Work with Plutus Core, the smart contract language embedded in the Cardano ledger.
• Write Haskell programs that create and use embedded Plutus Core programs using Plutus Tx.
• Write smart contract executables which can be distributed for use with the Plutus
  Smart Contract Backend.

You are free to copy, modify, and distribute the Plutus Platform with
under the terms of the Apache 2.0 license. See the link:./LICENSE[LICENSE]
and link:./NOTICE[NOTICE] files for details.

== How to use the project

This section contains brief information about how to use this project. For development
work see <> for more information.

=== Prerequisites

The Haskell libraries in the Plutus Platform can be built in a number of ways. The prerequisites depend
on how you want to build the libraries. The other artifacts (docs etc.) are most easily built with Nix,
so we recommend installing it regardless.

• https://nixos.org/nix/[Nix] (recommended).
  ** Install Nix following the instructions on the https://nixos.org/nix/[Nix website].

[IMPORTANT]

Even if you already have Nix installed, make sure to set up the xref:iohk-binary-cache[IOHK binary cache].

** See <> for further advice on using Nix.

• https://www.haskell.org/cabal/[`cabal`] (if building Haskell packages with cabal).
• https://haskellstack.org/[`stack`] (if building Haskell packages with stack).

=== How to get started using the libraries

There is an example project in the example folder, see its link:./example/README.md[README]
for more details.

=== How to build the Haskell packages and other artifacts

==== How to build Haskell packages and other artifacts with Nix

Run nix build -f default.nix localPackages.language-plutus-core
from the root to build the Plutus Core library.

See <> to find out
what other attributes you can build.

==== How to build Haskell packages with cabal

Run cabal v2-build language-plutus-core from the root to build the
Plutus Core library.

See the link:./cabal.project[cabal project file] to see the other
projects that you can build with cabal.

==== How to build the Haskell packages with stack

Run stack build language-plutus-core from the root to build the
Plutus Core library.

See the link:./stack.yaml[stack project file] to see the other
projects that you can build with stack.

=== How to run a local Plutus Playground in a Docker container

1. Install Docker following the instructions on the https://docs.docker.com/[Docker website].
2. Run nix build -f default.nix docker.plutusPlaygroundImage, to build
3. Run docker load < docker-image-plutus-playgrounds.tar.gz - this will
   print out the image name at the end, e.g. Loaded image: plutus-playgrounds:yn7h7m5qdjnnj9rxv8cgkvvwjkkcdnvp
4. Run docker run --mount ‘type=bind,source=/tmp,target=/tmp’ -p 8080:8080 plutus-playgrounds:yn7h7m5qdjnnj9rxv8cgkvvwjkkcdnvp using the image name from the previous step.
5. Open http://localhost:8080/ in a web browser.

=== How to get the most recent documentation PDFs from CI

==== Specifications and design

• https://hydra.iohk.io/job/Cardano/plutus/docs.plutus-core-spec.x86_64-linux/latest/download-by-type/doc-pdf/plutus-core-specification[Plutus Core Specification]
• https://hydra.iohk.io/job/Cardano/plutus/docs.extended-utxo-spec.x86_64-linux/latest/download-by-type/doc-pdf/extended-utxo-specification[Extended UTXO Model]

==== Academic papers

• https://hydra.iohk.io/job/Cardano/plutus/papers.unraveling-recursion.x86_64-linux/latest/download-by-type/doc-pdf/unraveling-recursion[Unraveling Recursion] (https://doi.org/10.1007/978-3-030-33636-3_15[published version])
• https://hydra.iohk.io/job/Cardano/plutus/papers.system-f-in-agda.x86_64-linux/latest/download-by-type/doc-pdf/paper[System F in Agda] (https://doi.org/10.1007/978-3-030-33636-3_10[published version])
• https://hydra.iohk.io/job/Cardano/plutus/papers.eutxo.x86_64-linux/latest/download-by-type/doc-pdf/eutxo[The Extended UTXO Model] (in press)

== Where to go next

=== Where to find tutorials

The link:./plutus-tutorial/README{outfilesuffix}[plutus-tutorial] project contains a basic tutorial
for using the Plutus Platform to write smart contracts.

To build a full HTML version of the tutorial that you can view locally, build the docs.plutus-tutorial xref:building-with-nix[using Nix].

=== Where to find the changelog

The changelog is stored in link:./CHANGELOG.md[CHANGELOG].

=== How to submit an issue

We track our issues on the
https://github.com/input-output-hk/plutus/issues[GitHub Issue tracker].

=== How to communicate with us

We’re active on the https://forum.cardano.org/[Cardano
forum]. Tag your post with the plutus tag so we’ll see it.

Use the Github issue tracker for bugs and feature requests, but keep
other discussions to the forum.

=== How to develop and contribute to the project

See link:CONTRIBUTING{outfilesuffix}[CONTRIBUTING], which describes our processes in more
detail including development environments;
and link:ARCHITECTURE{outfilesuffix}[ARCHITECTURE], which describes the structure of the repository.

== Nix

=== How to set up the IOHK binary caches

Adding the IOHK binary cache to your Nix configuration will speed up
builds a lot, since many things will have been built already by our CI.

If you find you are building packages that are not defined in this
repository, or if the build seems to take a very long time then you may
not have this set up properly.

To set up the cache:

. On non-NixOS, edit /etc/nix/nix.conf and add the following lines:
+

substituters = https://hydra.iohk.io https://cache.nixos.org/
trusted-public-keys = hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=

. On NixOS, set the following NixOS options:
+

nix = {
binaryCaches = [ "https://hydra.iohk.io" ];
binaryCachePublicKeys = [ "hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ=" ];
};

NOTE: If you are a https://nixos.org/nix/manual/#ssec-multi-user[trusted user] you may add the
nix.conf lines to ~/.config/nix/nix.conf instead.

=== Nix on macOS

Nix on macOS can be a bit tricky. In particular, sandboxing is disabled by default, which can lead to strange failures.

These days it should be safe to turn on sandboxing on macOS with a few exceptions. Consider setting the following Nix settings,
in the same way as in xref:iohk-binary-cache[previous section]:

sandbox = true
extra-sandbox-paths = /System/Library/Frameworks /System/Library/PrivateFrameworks /usr/lib /private/tmp /private/var/tmp /usr/bin/env

=== Which attributes to use to build different artifacts

link:./default.nix[default.nix] defines a package set with attributes for all the
artifacts you can build from this repository. These can be built
using nix build. For example:

nix build -f default.nix localPackages.language-plutus-core

.Example attributes

• Local packages: defined inside localPackages
  ** e.g. localPackages.language-plutus-core
• Documents: defined inside docs
  ** e.g. docs.plutus-core-spec
• Development scripts: defined inside dev
  ** e.g. dev.scripts.fixStylishHaskell

There are other attributes defined in link:./default.nix[default.nix].