Skip to content

Commit

Permalink
Merge branch 'master' into kwxm/SCP-2176/cost-model-ledger-interface
Browse files Browse the repository at this point in the history
  • Loading branch information
@kwxm
kwxm committed May 13, 2021
2 parents 4b1e33e + a9423ee commit a6b68c3
Show file tree
Hide file tree
Showing 102 changed files with 2,583 additions and 1,451 deletions.
4 changes: 2 additions & 2 deletions .github/workflows/test.yml
View file
Expand Up @@ -8,7 +8,7 @@ jobs:
os: [ubuntu-latest]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v2
- uses: actions/checkout@v2.3.4
- uses: nixbuild/nix-quick-install-action@v5
- run: nix-instantiate release.nix --arg supportedSystems '[ builtins.currentSystem ]' --restrict-eval -I . --allowed-uris 'https://github.com/NixOS/nixpkgs https://github.com/input-output-hk https://github.com/NixOS/nixpkgs-channels' --option trusted-public-keys "hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= iohk.cachix.org-1:DpRUyj7h7V830dp/i6Nti+NEO2/nhblbov/8MW7Rqoo= cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=" --option substituters "https://hydra.iohk.io https://iohk.cachix.org https://cache.nixos.org/" --show-trace
nix-tests:
Expand All @@ -17,6 +17,6 @@ jobs:
os: [ubuntu-latest]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v2
- uses: actions/checkout@v2.3.4
- uses: nixbuild/nix-quick-install-action@v5
- run: nix-build -A tests.nixpkgsFmt -A tests.purty -A tests.shellcheck -A tests.stylishHaskell -A tests.terraform --arg supportedSystems '[ builtins.currentSystem ]' --restrict-eval -I . --allowed-uris 'https://github.com/NixOS/nixpkgs https://github.com/input-output-hk https://github.com/NixOS/nixpkgs-channels' --option trusted-public-keys "hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= iohk.cachix.org-1:DpRUyj7h7V830dp/i6Nti+NEO2/nhblbov/8MW7Rqoo= cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=" --option substituters "https://hydra.iohk.io https://iohk.cachix.org https://cache.nixos.org/"
180 changes: 91 additions & 89 deletions README.adoc
View file
@@ -1,19 +1,32 @@
= https://github.com/input-output-hk/plutus[Plutus Platform]
= https://github.com/input-output-hk/plutus[The Plutus Platform and Marlowe]
:email: plutus@iohk.io
:author: Input Output HK Limited
:toc: left
:reproducible:

The Plutus Platform enables you to:
The Plutus Platform is an application development platform for developing distributed applications using the Cardano blockchain; and Marlowe is a platform specifically for financial products, built on top of Plutus.
For more information about the projects, see the <<user-documentation>>.

* 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.
This repository contains:

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.
* Plutus Platform
* The implementation, specification, and mechanized metatheory of Plutus Core, the scripting language embedded in the Cardano ledger.
* Plutus Tx, the compiler from Haskell to Plutus Core.
* Libraries which implement the Plutus Application Framework, a framework for writing applications that work with Cardano.
* A selection of end-to-end usecases written with the Plutus Application Framework
* The Plutus Playground, a web-based playground for learning and writing basic Plutus Applications.
* Marlowe
* The implementation of the Marlowe domain-specific language.
* Tools for working with Marlowe, including static analysis.
* A selection of examples using Marlowe, including a number based on the ACTUS financial standard.
* The Marlowe Playground, a web-based playground for learning and writing Marlowe Applications.
[IMPORTANT]
====
The rest of this README is focussed on people who want to develop or contribute to the Platform.
For people who want to *use* the Platform, please consult the <<user-documentation>>.
====

[[cache-warning]]
[IMPORTANT]
Expand All @@ -25,115 +38,101 @@ If you do not do this, you will end up building GHC, which takes several hours.
If you find yourself building GHC, STOP and fix the cache.
====

== How to use the project
== Documentation

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

[[prerequisites]]
=== 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.

==== Nix

Install https://nixos.org/nix/[Nix] (recommended). following the instructions on the https://nixos.org/nix/[Nix website].
The main documentation is located https://docs.cardano.org/projects/plutus/en/latest/[here].

Make sure you have read and understood the xref:cache-warning[cache warning].
DO NOT IGNORE THIS.
=== Talks

See <<nix-advice>> for further advice on using Nix.
- https://www.youtube.com/watch?v=MpWeg6Fg0t8[Functional Smart Contracts on Cardano]
- https://www.youtube.com/watch?v=usMPt8KpBeI[The Plutus Platform]

==== Non-Nix
=== Specifications and design

If you use Nix, these tools are provided for you via `shell.nix`, and you do *not* need to install them yourself.

* If you want to build our Haskell packages with https://www.haskell.org/cabal/[`cabal`], then install it.
* If you want to build our Haskell packages with https://haskellstack.org/[`stack`], then install it.
* If you want to build our Agda code, then install https://github.com/agda/agda[Agda] and the https://github.com/agda/agda-stdlib[standard library].
- https://hydra.iohk.io/job/Cardano/plutus/linux.docs.plutus-report/latest/download-by-type/doc-pdf/plutus[Plutus Technical Report] (draft)
- https://hydra.iohk.io/job/Cardano/plutus/linux.docs.plutus-core-spec/latest/download-by-type/doc-pdf/plutus-core-specification[Plutus Core Specification]
- https://hydra.iohk.io/job/Cardano/plutus/linux.docs.extended-utxo-spec/latest/download-by-type/doc-pdf/extended-utxo-specification[Extended UTXO Model]

=== How to get started using the platform
=== Academic papers

The https://github.com/input-output-hk/plutus-starter[`plutus-starter`] repository contains a starter setup.
- https://hydra.iohk.io/job/Cardano/plutus/linux.docs.papers.unraveling-recursion/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/linux.docs.papers.system-f-in-agda/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/linux.docs.papers.eutxo/latest/download-by-type/doc-pdf/eutxo[The Extended UTXO Model] (in press)
- https://hydra.iohk.io/job/Cardano/plutus/linux.docs.papers.utxoma/latest/download-by-type/doc-pdf/utxoma[UTXOma: UTXO with Multi-Asset Support] (in press)
- https://hydra.iohk.io/job/Cardano/plutus/linux.docs.papers.eutxoma/latest/download-by-type/doc-pdf/eutxoma[Native Custom Tokens in the Extended UTXO Model] (in press)

=== How to build the Haskell packages and other artifacts
== Working with the project

[[building-with-nix]]
==== How to build Haskell packages and other artifacts with Nix
=== How to submit an issue

Run `nix build -f default.nix plutus.haskell.packages.plutus-core.components.library`
from the root to build the Plutus Core library.
Issues can be filed in the https://github.com/input-output-hk/plutus/issues[GitHub Issue tracker].

See <<nix-build-attributes>> to find out
what other attributes you can build.
However, note that this is pre-release software, so we will not usually be providing support.

==== How to build Haskell packages with `cabal`
[[how-to-develop]]
=== How to develop and contribute to the project

Run `cabal build plutus-core` from the root to build the
Plutus Core library.
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.

NOTE: you must have R installed for this to work. https://cran.r-project.org/[R Installation]
=== How to depend on the project from another Haskell project

See the link:./cabal.project[cabal project file] to see the other
projects that you can build with `cabal`.
None of our libraries are on Hackage, unfortunately (many of our dependencies aren't either).
So for the time being, you need to:

==== How to build the Haskell packages with `stack`
. Add `plutus` as a `source-repository-package` to your `cabal.project`.
. Copy the `source-repository-package` stanzas from our `cabal.project` to yours.
. Copy additional stanzas from our `cabal.project` as you need, e.g. you may need some of the `allow-newer` stanzas.

Run `stack build plutus-core` from the root to build the
Plutus Core library. The `stack` build is less well supported than the `cabal` build, we do not promise that it will work.
The https://github.com/input-output-hk/plutus-starter[plutus-starter] project provides an example.

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

=== How to get the most recent documentation PDFs from CI
This section contains information about how to build the project's artifacts for independent usage.
For development work see <<how-to-develop>> for more information.

==== Specifications and design
[[prerequisites]]
==== Prerequisites

- https://hydra.iohk.io/job/Cardano/plutus/linux.docs.plutus-report/latest/download-by-type/doc-pdf/plutus[Plutus Technical Report] (draft)
- https://hydra.iohk.io/job/Cardano/plutus/linux.docs.plutus-core-spec/latest/download-by-type/doc-pdf/plutus-core-specification[Plutus Core Specification]
- https://hydra.iohk.io/job/Cardano/plutus/linux.docs.extended-utxo-spec/latest/download-by-type/doc-pdf/extended-utxo-specification[Extended UTXO Model]
The Haskell libraries in the Plutus Platform are built with `cabal` and Nix.
The other artifacts (docs etc.) are also most easily built with Nix.

==== Academic papers
===== Nix

- https://hydra.iohk.io/job/Cardano/plutus/linux.docs.papers.unraveling-recursion/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/linux.docs.papers.system-f-in-agda/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/linux.docs.papers.eutxo/latest/download-by-type/doc-pdf/eutxo[The Extended UTXO Model] (in press)
- https://hydra.iohk.io/job/Cardano/plutus/linux.docs.papers.utxoma/latest/download-by-type/doc-pdf/utxoma[UTXOma: UTXO with Multi-Asset Support] (in press)
- https://hydra.iohk.io/job/Cardano/plutus/linux.docs.papers.eutxoma/latest/download-by-type/doc-pdf/eutxoma[Native Custom Tokens in the Extended UTXO Model] (in press)
Install https://nixos.org/nix/[Nix] (recommended). following the instructions on the https://nixos.org/nix/[Nix website].

== Where to go next
Make sure you have read and understood the xref:cache-warning[cache warning].
DO NOT IGNORE THIS.

=== Where to find tutorials
See <<nix-advice>> for further advice on using Nix.

The link:./doc[doc] folder contains the documentation site.
===== Non-Nix

To build a full HTML version of the site that you can view locally, build the `docs.site` attribute xref:building-with-nix[using Nix].
You can build some of the Haskell packages without Nix, but this is not recommended and we don't guarantee that these prerequisites are sufficient.
If you use Nix, these tools are provided for you via `shell.nix`, and you do *not* need to install them yourself.

The online version of the tutorial can be found https://docs.cardano.org/projects/plutus/en/latest/index.html[here]
* If you want to build our Haskell packages with https://www.haskell.org/cabal/[`cabal`], then install it.
* If you want to build our Haskell packages with https://haskellstack.org/[`stack`], then install it.
* If you want to build our Agda code, then install https://github.com/agda/agda[Agda] and the https://github.com/agda/agda-stdlib[standard library].

=== How to submit an issue
[[building-with-nix]]
==== How to build the Haskell packages and other artifacts with Nix

User issues can be filed in the
https://github.com/input-output-hk/plutus/issues[GitHub Issue tracker].
Run `nix build -f default.nix plutus.haskell.packages.plutus-core.components.library` from the root to build the Plutus Core library.

However, note that this is pre-release software, so we will not usually be providing support.
See <<nix-build-attributes>> to find out what other attributes you can build.

=== How to communicate with us
==== How to build the Haskell packages with `cabal`

We’re active on the https://forum.cardano.org/[Cardano
forum]. Tag your post with the `plutus` tag so we’ll see it.
The Haskell packages can be built directly with `cabal`.
We do this during development (see <<how-to-develop>>).
The best way is to do this is inside a `nix-shell`.

Use the Github issue tracker for bugs and feature requests, but keep
other discussions to the forum.
Run `cabal build plutus-core` from the root to build the Plutus Core library.

[[how-to-develop]]
=== How to develop and contribute to the project
See the link:./cabal.project[cabal project file] to see the other packages that you can build with `cabal`.

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-advice]]
== Nix
Expand Down Expand Up @@ -176,8 +175,7 @@ nix = {

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]:
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
Expand All @@ -188,20 +186,24 @@ extra-sandbox-paths = /System/Library/Frameworks /System/Library/PrivateFramewor
[[nix-build-attributes]]
=== 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:
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 plutus.haskell.packages.plutus-core
nix build -f default.nix docs.papers.eutxo
----

.Example attributes
* Project packages: defined inside `plutus.haskell.packages`
** e.g. `plutus.haskell.packages.plutus-core.components.library`
* 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`].

== Licensing

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.

0 comments on commit a6b68c3

Please sign in to comment.