How To: use nix-shell for Plutus Pioneer Program

Do NOT waste time building Cabal locally. It's provided in Nix.

Note: The setup assumes that you are running this from an already configured Nix-Shell, look at the other guides to set this up.

Working on the plutus-pioneers-program exercises

Let's say that I have done a git clone on 2 repositories.

  1. Plutus-Apps
  2. Plutus-Pioneer-Program

Both of them, I have decided to put in /opt/ for the example.

The Plutus Pioneer Program source is made to compile and run against Plutus for a specific commit hash which is listed in each week's cabal.project file.

For example, in plutus-pioneer-program/code/week02/cabal.project there's a block like this specifying the plutus-apps repo.

source-repository-package
  type: git
  location: https://github.com/input-output-hk/plutus-apps.git
  tag: 41149926c108c71831cfe8d244c83b0ee4bf5c8a

You'll want to cd to the plutus-apps directory and checkout the commit where the tag: line is pointing before building and starting the playground. Stop the client and server and then

git checkout 41149926c108c71831cfe8d244c83b0ee4bf5c8a

nix-shell
And then start the server and client back up again. For more details and environments other than Linux, see the other guides.

Doing some of the work in a shell with cabal

It may be desireable to edit and build outside the playground because

  1. You have a lot of code to write and prefer your real editor
  2. You'd like to compile as you work out there from the shell or your IDE to check it
  3. You may want to use the repl to exercise some types and/or functions
  4. You may have started using unit testing on some of the code
  5. You'd like to periodically commit changes to source control

First, we bring up a nix-shell which sets up the environment and has working versions of tools (like cabal)

cd /opt/plutus-apps
nix-shell

From here we can use this nix-shell to work on the source outside the playground

cd /opt/plutus-pioneer-program/code/week02/
cabal update  # DEFINITELY DO THIS the first time. Not needed every time after, similar to `apt update`
cabal build

What this cabal build is doing is compiling the week02 source code locally. These build artifacts are not used by the plutus playground and the copy/paste procedure described above is still needed to run it.