From 0d72dac883ffb35824c2fddf1d81d6b3efbff923 Mon Sep 17 00:00:00 2001 From: zeme Date: Wed, 8 Nov 2023 19:01:12 +0100 Subject: [PATCH 1/2] Update nix documentation the README --- .envrc | 12 --- CONTRIBUTING.adoc | 4 +- README.adoc | 102 +++--------------------- doc/README.md | 24 +++--- doc/marlowe/tutorials/using-marlowe.rst | 4 +- flake.lock | 38 ++++----- marlowe-playground-client/README.md | 18 ++--- 7 files changed, 52 insertions(+), 150 deletions(-) delete mode 100644 .envrc diff --git a/.envrc b/.envrc deleted file mode 100644 index 5db09bae4b..0000000000 --- a/.envrc +++ /dev/null @@ -1,12 +0,0 @@ -#! /bin/sh - -source "$( - nix eval \ - --no-update-lock-file \ - --no-write-lock-file \ - --no-warn-dirty \ - --accept-flake-config \ - .#__std.direnv_lib 2>/dev/null \ - || nix eval .#__std.direnv_lib # show the errors -)" -use std nix/cells //marlowe-playground/devshells:default diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index cfa83f1f46..31c44e44ff 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -40,7 +40,7 @@ pre-commit run purs-tidy === How to build the code during development -The `nix-shell` environment has the correct GHC with all the external Haskell dependencies of the project. +The nix shell environment has the correct GHC with all the external Haskell dependencies of the project. From here you can build the project packages directly with `cabal`. NOTE: You may need to run `cabal update` so that `cabal` knows about the index state xref:update-index-state[we have pinned]. @@ -48,7 +48,7 @@ NOTE: You may need to run `cabal update` so that `cabal` knows about the index s [WARNING] ==== -You can also use `cabal` and `stack` outside the `nix-shell` environment to build the project. +You can also use `cabal` and `stack` outside the nix shell environment to build the project. _However_ there are two caveats: * You may get different versions of packages. diff --git a/README.adoc b/README.adoc index cd931d54bc..7cccb3f16e 100644 --- a/README.adoc +++ b/README.adoc @@ -18,18 +18,6 @@ Related projects: ==== The rest of this README is focussed on people who want to develop or contribute to Marlowe. -==== - -[[cache-warning]] -[IMPORTANT] -==== -DO NOT IGNORE THIS - -If you want to use Nix with this project, make sure to set up the xref:iohk-binary-cache[IOHK binary cache]. -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. -==== - == Documentation == Working with the project @@ -57,12 +45,17 @@ The other artifacts (docs etc.) are also most easily built with Nix. ===== Nix -Install https://nixos.org/nix/[Nix] (recommended). following the instructions on the https://nixos.org/nix/[Nix website]. +This repository uses nix to provide the development and build environment. -Make sure you have read and understood the xref:cache-warning[cache warning]. -DO NOT IGNORE THIS. +If you know nix, simply run `nix develop` to enter the shell; if prompted, trust +the flake config values to enable access to our binary caches. -See <> for further advice on using Nix. +The nix code is based on a template from the the +[IOGX flake](https://github.com/input-output-hk/iogx). +For instructions on how to install and configure nix (including how to enable +access to our binary caches), and how keep the flake inputs up to date, refer to +[this section](https://github.com/input-output-hk/iogx/blob/main/doc/api.md#flakenix) +of the IOGX manual. ===== Non-Nix @@ -72,19 +65,6 @@ If you use Nix, these tools are provided for you via `shell.nix`, and you do *no * 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. -[[building-with-nix]] -==== Using Nix - -Run `nix develop` to enter the shell. - -From there, you can type `info` to get a list of available commands. - -==== How to build the Haskell packages with `cabal` - -The Haskell packages can be built directly with `cabal`. -We do this during development (see <>). -The best way is to do this is inside a `nix-shell`. - [NOTE] ==== For fresh development setups, you also need to run `cabal update`. @@ -92,7 +72,6 @@ For fresh development setups, you also need to run `cabal update`. Run `cabal build all` from the root to build all artifacts. - === Deployment The Marlowe Playground is automatically deployed upon certain pushes to GitHub @@ -101,69 +80,6 @@ The Marlowe Playground is automatically deployed upon certain pushes to GitHub For more details, including instructions for setting up ad hoc testing deployments, see https://github.com/input-output-hk/plutus-ops[the plutus-ops repo]. - -[[nix-advice]] -== Nix - -[[iohk-binary-cache]] -=== 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: -+ ----- -experimental-features = nix-command flakes -substituters = "https://cache.nixos.org" "https://cache.iog.io "https://marlowe-playground.cachix.org" -trusted-public-keys = "hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= marlowe-playground.cachix.org-1:8TmdbVgcB4QzTmuzLxNdaCxdc8ZVI9S8eeeXsY9stxo=" ----- -+ -[NOTE] -==== -If you don't have an `/etc/nix/nix.conf` or don't want to edit it, you may add the `nix.conf` lines to `~/.config/nix/nix.conf` instead. -You must be a https://nixos.org/nix/manual/#ssec-multi-user[trusted user] to do this. -==== -. On NixOS, set the following NixOS options: -+ ----- -nix.settings = { - experimental-features = [ "nix-command" "flakes" ]; - substituters = [ - "https://cache.nixos.org" - "https://cache.iog.io" - ]; - trusted-public-keys = [ - "hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ=" - ]; -}; ----- - - -=== 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 ----- - -Changes to `/etc/nix/nix.conf` may require a restart of the nix daemon in order to take affect. Restart the nix daemon by running the following commands: - ----- -sudo launchctl stop org.nixos.nix-daemon -sudo launchctl start org.nixos.nix-daemon ----- - == Licensing You are free to copy, modify, and distribute Marlowe under the terms diff --git a/doc/README.md b/doc/README.md index 08c33da56d..874d874923 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,16 +1,18 @@ -# Plutus and Marlowe documentation site - -This is a sphinx site. You can build it with sphinx directly (assuming you're in a `nix-shell`): +# Plutus documentation site -``` -sphinx-build -j 4 -n . _build -``` +This is a sphinx site. -Or you can build it with Nix at the top level, which will also build the Haddock for the project and link it in: +Run `nix develop` to enter a development shell with `sphinx-build` and `sphinx-autobuild`. -``` -nix build -f default.nix docs.site -``` +The following commands are also available: + +- `develop-rtd-site` + Start a development server with live reload on `http://localhost:8000` +- `build-rtd-site` + Build the docs locally in `_build/index.html` +- `serve-rtd-site` + Build the full site with nix (including Haddock) and serve it on `http://localhost:8002` + +The doc site from main is built automatically and hosted [here](https://plutus.readthedocs.io/en/latest). -The doc site from master is built automatically and hosted [here](https://plutus.readthedocs.io/en/latest). Additionally, the site is built for all PRs, and a link to a preview can be found in the PR statuses. diff --git a/doc/marlowe/tutorials/using-marlowe.rst b/doc/marlowe/tutorials/using-marlowe.rst index 759d1354e9..f8dca5d372 100644 --- a/doc/marlowe/tutorials/using-marlowe.rst +++ b/doc/marlowe/tutorials/using-marlowe.rst @@ -12,13 +12,13 @@ Marlowe in Haskell This tutorial works in the version of Marlowe which can be found in the ``main`` branch of the `marlowe-cardano repository `_. -We can run ghci by using the `nix-shell` available in `marlowe-dependency-docs repository `_: +We can run ghci by using the shell available in `marlowe-dependency-docs repository `_: .. code:: bash git clone "https://github.com/input-output-hk/marlowe-dependency-docs.git" cd marlowe-dependency-docs - nix-shell + nix develop ghci A standalone version and formalisation of the semantics can also be found in diff --git a/flake.lock b/flake.lock index af14f2f1b6..a6d7f7f630 100644 --- a/flake.lock +++ b/flake.lock @@ -622,16 +622,16 @@ "nixpkgs": [ "nixpkgs" ], - "nixpkgs-with-working-prefetch-npm-deps": "nixpkgs-with-working-prefetch-npm-deps", + "nixpkgs-stable": "nixpkgs-stable", "pre-commit-hooks-nix": "pre-commit-hooks-nix", "sphinxcontrib-haddock": "sphinxcontrib-haddock" }, "locked": { - "lastModified": 1698409584, - "narHash": "sha256-zqY9WIjs6ELYbyRwDx2w0hAgsV27b6TiAlMkCAQzSJ4=", + "lastModified": 1699460731, + "narHash": "sha256-WhMr0HPj1T+2lvH3Yh+fJq79MXYPnXofQ805JnQmI3k=", "owner": "input-output-hk", "repo": "iogx", - "rev": "da8ab3dc6d1500d4fe0aefe8fb7331edb3d49231", + "rev": "63deb643d7dfac8bf06b0d357caca742bd53ae07", "type": "github" }, "original": { @@ -867,49 +867,49 @@ }, "nixpkgs-stable": { "locked": { - "lastModified": 1685801374, - "narHash": "sha256-otaSUoFEMM+LjBI1XL/xGB5ao6IwnZOXc47qhIgJe8U=", + "lastModified": 1690680713, + "narHash": "sha256-NXCWA8N+GfSQyoN7ZNiOgq/nDJKOp5/BHEpiZP8sUZw=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "c37ca420157f4abc31e26f436c1145f8951ff373", + "rev": "b81af66deb21f73a70c67e5ea189568af53b1e8c", "type": "github" }, "original": { "owner": "NixOS", - "ref": "nixos-23.05", "repo": "nixpkgs", + "rev": "b81af66deb21f73a70c67e5ea189568af53b1e8c", "type": "github" } }, - "nixpkgs-unstable": { + "nixpkgs-stable_2": { "locked": { - "lastModified": 1695318763, - "narHash": "sha256-FHVPDRP2AfvsxAdc+AsgFJevMz5VBmnZglFUMlxBkcY=", + "lastModified": 1685801374, + "narHash": "sha256-otaSUoFEMM+LjBI1XL/xGB5ao6IwnZOXc47qhIgJe8U=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "e12483116b3b51a185a33a272bf351e357ba9a99", + "rev": "c37ca420157f4abc31e26f436c1145f8951ff373", "type": "github" }, "original": { "owner": "NixOS", - "ref": "nixpkgs-unstable", + "ref": "nixos-23.05", "repo": "nixpkgs", "type": "github" } }, - "nixpkgs-with-working-prefetch-npm-deps": { + "nixpkgs-unstable": { "locked": { - "lastModified": 1690680713, - "narHash": "sha256-NXCWA8N+GfSQyoN7ZNiOgq/nDJKOp5/BHEpiZP8sUZw=", + "lastModified": 1695318763, + "narHash": "sha256-FHVPDRP2AfvsxAdc+AsgFJevMz5VBmnZglFUMlxBkcY=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "b81af66deb21f73a70c67e5ea189568af53b1e8c", + "rev": "e12483116b3b51a185a33a272bf351e357ba9a99", "type": "github" }, "original": { "owner": "NixOS", + "ref": "nixpkgs-unstable", "repo": "nixpkgs", - "rev": "b81af66deb21f73a70c67e5ea189568af53b1e8c", "type": "github" } }, @@ -1073,7 +1073,7 @@ "flake-utils": "flake-utils_3", "gitignore": "gitignore", "nixpkgs": "nixpkgs_2", - "nixpkgs-stable": "nixpkgs-stable" + "nixpkgs-stable": "nixpkgs-stable_2" }, "locked": { "lastModified": 1696846637, diff --git a/marlowe-playground-client/README.md b/marlowe-playground-client/README.md index 454c53a761..5f1d3cebfb 100644 --- a/marlowe-playground-client/README.md +++ b/marlowe-playground-client/README.md @@ -29,26 +29,22 @@ Now we will build and run the front end: ## Adding dependencies - Javascript dependencies are managed with npm, so add them to [package.json](./package.json) -- purescript uses package sets managed by spago so if the package set doesn't contain a dependency you can add it to [../packages.dhall](../packages.dhall) +- Purescript uses package sets managed by spago so if the package set doesn't contain a dependency you can add it to [../packages.dhall](../packages.dhall) -Whenever you change `packages.dhall` you need to make sure that all dependencies can still properly be resolved and built. -You can do so using the `update-client-deps` script: - -- Inside the nix-shell environment: `update-client-deps` -- Outside of the nix-shell environment (from the client directory): `$(nix-build -A plutus.updateClientDeps ../)/bin/update-client-deps` - -The `update-client-deps` script will generate/update `.nix` files which have to be committed and are required for a successful CI run. +Whenever you change `packages.dhall` or `packages.json` you must also run the following commands inside the nix shell: +```bash +gen-nix-lockfiles +generate-purescript +``` ## Code formatting The code is formatted using [purs-tidy](https://github.com/natefaubion/purescript-tidy), and there is a CI task that will fail if the code is not properly formatted. You can apply purs-tidy to the project by calling: ```bash -nix-shell shell.nix --run fix-purs-tidy +pre-commit run purs-tidy ``` -The code is formatted using [purs-tidy](https://github.com/natefaubion/purescript-tidy), and there is a CI task that will fail if the code is not properly formatted. You can apply purs-tidy to the project by calling: - ## VSCode notes In order to have the PureScript IDE working properly with this project you need to open this folder as the root folder. From b712dd18efa9f37c0edd327c6367ba20aede4f76 Mon Sep 17 00:00:00 2001 From: zeme Date: Thu, 9 Nov 2023 15:32:13 +0100 Subject: [PATCH 2/2] wip --- README.adoc | 12 +++--------- flake.lock | 6 +++--- 2 files changed, 6 insertions(+), 12 deletions(-) diff --git a/README.adoc b/README.adoc index 7cccb3f16e..93695f3c7a 100644 --- a/README.adoc +++ b/README.adoc @@ -45,17 +45,11 @@ The other artifacts (docs etc.) are also most easily built with Nix. ===== Nix -This repository uses nix to provide the development and build environment. +This repository uses nix to provide a development and build environment. -If you know nix, simply run `nix develop` to enter the shell; if prompted, trust -the flake config values to enable access to our binary caches. +For instructions on how to install and configure nix (including how to enable access to our binary caches), refer to link:https://github.com/input-output-hk/iogx/blob/main/doc/nix-setup-guide.md[this document]. -The nix code is based on a template from the the -[IOGX flake](https://github.com/input-output-hk/iogx). -For instructions on how to install and configure nix (including how to enable -access to our binary caches), and how keep the flake inputs up to date, refer to -[this section](https://github.com/input-output-hk/iogx/blob/main/doc/api.md#flakenix) -of the IOGX manual. +If you already have nix installed and configured, you may enter the development shell by running `nix develop`. ===== Non-Nix diff --git a/flake.lock b/flake.lock index a6d7f7f630..87e99ab2f7 100644 --- a/flake.lock +++ b/flake.lock @@ -627,11 +627,11 @@ "sphinxcontrib-haddock": "sphinxcontrib-haddock" }, "locked": { - "lastModified": 1699460731, - "narHash": "sha256-WhMr0HPj1T+2lvH3Yh+fJq79MXYPnXofQ805JnQmI3k=", + "lastModified": 1699537966, + "narHash": "sha256-MGGza+vZDRjKj31WhQJDt7CqVVdrFkgkXIcqr0gDiU8=", "owner": "input-output-hk", "repo": "iogx", - "rev": "63deb643d7dfac8bf06b0d357caca742bd53ae07", + "rev": "c6ce7f034717ed0c0e9c6dd8fa2f898a15439627", "type": "github" }, "original": {