From fa16ae5c68fb4c9fe421ce5a18a79da4f0c3f8c6 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Thu, 3 Oct 2024 14:34:22 -0700 Subject: [PATCH 1/6] add Holonix upgrade guide to upgrades page nav --- src/pages/resources/upgrade/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/pages/resources/upgrade/index.md b/src/pages/resources/upgrade/index.md index edd51bc31..3b7457bdc 100644 --- a/src/pages/resources/upgrade/index.md +++ b/src/pages/resources/upgrade/index.md @@ -10,3 +10,4 @@ Upgrading between versions of Holochain can be a bit tricky! While Holochain is * [Holochain Upgrade 0.1 → 0.2](/resources/upgrade/upgrade-holochain-0.2/) * [Holochain Upgrade 0.2 → 0.3](/resources/upgrade/upgrade-holochain-0.3/) +* [Upgrading to the new Holonix](/resources/upgrade/upgrade-new-holonix/) (all Holochain versions) From 3844916d1caf1ac0138467d381378df75114e4da Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Thu, 3 Oct 2024 14:35:26 -0700 Subject: [PATCH 2/6] add Holonix upgrade guide --- .../resources/upgrade/upgrade-new-holonix.md | 120 ++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 src/pages/resources/upgrade/upgrade-new-holonix.md diff --git a/src/pages/resources/upgrade/upgrade-new-holonix.md b/src/pages/resources/upgrade/upgrade-new-holonix.md new file mode 100644 index 000000000..b9b2a5bf1 --- /dev/null +++ b/src/pages/resources/upgrade/upgrade-new-holonix.md @@ -0,0 +1,120 @@ +--- +title: Upgrade to the new Holonix +--- + +::: intro +In the third quarter of 2024, we released a new [Holonix](/get-started/install-advanced/#holonix-the-holochain-app-development-environment), our development environment based on [Nix](https://nixos.org) that gives you all the dependencies to build hApps and contribute to Holochain core development. + +The new Holonix is simpler and more modular, which means that it's easier to configure it for your needs and preferences. +::: + +## Upgrade an existing project + +The previous and the new Holonix distributions are both based on Nix's [flakes](https://wiki.nixos.org/wiki/Flakes) feature. Fortunately, this means it's easy to upgrade. First back up and remove your project's existing flake files: + +```bash +mv flake.nix flake.nix.backup +mv flake.lock flake.lock.backup +``` + +Then create new flake files: + +```bash +nix flake init -t github:holochain/holonix?ref=main-0.3 +``` + +For most projects, that's all you need! + +## Targeting a specific Holochain version + +If your project is not on the latest recommended Holochain version (0.3 at the time of writing), you'll need to change the `ref` query string in the URL. + +For Holochain 0.2: + +```bash +nix flake init -t github:holochain/holonix?ref=main-0.2 +``` + +For the latest, unstable Holochain 0.4: + +```bash +nix flake init -t github:holochain/holonix?ref=main +``` + +If you've already created flake files for the newest Holonix, you can edit the `flake.nix` file like this: + +```diff +... +inputs = { +- holonix.url = "github:holochain/holonix?ref=main-0.3"; ++ holonix.url = "github:holochain/holonix?ref=main-0.2"; + ... +}; +... +``` + +Next time you type `nix develop` to enter the shell, it'll update your `nix.lock` and download the requested packages for you. + +## Choosing a very specific Holochain release + +If you need to be more precise about the Holochain package version, you can do this in your `flake.nix` file too: + +```diff +... +inputs = { + holonix.url = "github:holochain/holonix?ref=main"; ++ holonix.inputs.holochain.url = "github:holochain/holochain?ref=branch-or-tag-name"; + ... +} +... +``` + +!!! info Old packages and long build times +We have a limited amount of cache space for our Nix packages, so if you target a Holochain version that's quite old, you may end up building it from source on your machine, which can take hours. +!!! + +## Adding and removing packages + +If you need extra Nix packages, or don't need some provided packages, you can edit `flake.nix` like this: + +```diff +... +packages = (with inputs'.holonix.packages; [ + holochain ++ # Remove a few Holochain-provided packages +- lair-keystore +- hc-launch +- hc-scaffold +- hn-introspect + rust # For Rust development, with the WASM target included for zome builds +]) ++ (with pkgs; [ + nodejs_20 # For UI development + binaryen # For WASM optimisation + # Add any other packages you need here ++ # Add my preferred Node package manager ++ yarn +]); +... +``` + +## Customizing Holochain + +If you want your build environment to include a version of Holochain with custom build flags, use this command to generate your flake files: + +```bash +nix flake init -t github:holochain/holonix#custom +``` + +(This can be used in combination with the `?ref=` query string to target a specific version.) Next, open up the generated `flake.nix` file and look for this section: + +``` +let + # Disable default features and enable wasmer_wamr for a wasm interpreter, + # as well as re-enabling tx5 and sqlite-encrypted. + cargoExtraArgs = "--no-default-features --features wasmer_wamr,sqlite-encrypted,tx5"; + # Override arguments passed in to Holochain build with above feature arguments. + customHolochain = inputs'.holonix.packages.holochain.override { inherit cargoExtraArgs; }; +in +``` + +Change the value of `cargoExtraArgs ` to your liking, then enter the development shell. _This will take a while the first time around,_ because Nix will have to build your custom Holochain binary. \ No newline at end of file From b1afa63763992b65bf92828890d08e8d698f5b05 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Thu, 3 Oct 2024 14:37:56 -0700 Subject: [PATCH 3/6] fix spelling errors --- .cspell/custom-words.txt | 4 ++++ src/pages/resources/upgrade/upgrade-new-holonix.md | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/.cspell/custom-words.txt b/.cspell/custom-words.txt index 8a95d2da8..c74c3fee3 100644 --- a/.cspell/custom-words.txt +++ b/.cspell/custom-words.txt @@ -5,6 +5,7 @@ agent-centricity Anwaar Automerge automerge +binaryen buildinputs builtins Brisebois @@ -39,6 +40,9 @@ subl Tauri Ulhaq Wahlstrom +wamr +Wasmer +wasmer WebRTC webview webviews diff --git a/src/pages/resources/upgrade/upgrade-new-holonix.md b/src/pages/resources/upgrade/upgrade-new-holonix.md index b9b2a5bf1..22b4bae3a 100644 --- a/src/pages/resources/upgrade/upgrade-new-holonix.md +++ b/src/pages/resources/upgrade/upgrade-new-holonix.md @@ -89,7 +89,7 @@ packages = (with inputs'.holonix.packages; [ rust # For Rust development, with the WASM target included for zome builds ]) ++ (with pkgs; [ nodejs_20 # For UI development - binaryen # For WASM optimisation + binaryen # For WASM optimization # Add any other packages you need here + # Add my preferred Node package manager + yarn From 0fe53c045f5ebd0751ae060997b0df36d6bc923c Mon Sep 17 00:00:00 2001 From: Jost Schulte Date: Tue, 8 Oct 2024 20:50:11 -0600 Subject: [PATCH 4/6] update dev tools setup page --- src/pages/get-started/install-advanced.md | 193 +--------------------- 1 file changed, 7 insertions(+), 186 deletions(-) diff --git a/src/pages/get-started/install-advanced.md b/src/pages/get-started/install-advanced.md index cd1f28158..5740e799d 100644 --- a/src/pages/get-started/install-advanced.md +++ b/src/pages/get-started/install-advanced.md @@ -1,11 +1,11 @@ --- -title: Dev Tools Setup +title: Setup with Nix flakes hide: - toc --- ::: intro -This guide assumes that you've already followed the [quick installation guide](/get-started/) and want to learn more about the set up. It describes how to manually recreate and maintain the development environment, use your default shell and preferred code editor with Nix, explains how to install specific versions of Holochain, and discusses why we use `nix develop` in the first place. +This guide assumes that you've already followed the [quick installation guide](/get-started/) and want to learn more about the development environment. ::: ## Holonix - the Holochain app development environment @@ -15,102 +15,22 @@ If you use the scaffolding to generate the project structure, this will already If you want to learn more about how this setup works and how to create it manually and how to maintain it, please find all the information below. -### Holonix's usage of Nix's Flakes features +### Holonix's usage of Nix's flake feature -[Flakes](https://wiki.nixos.org/wiki/Flakes) is an experimental but well-supported feature of the Nix package manager that makes it easier to manage dependencies consistently. - -As of [holochain#1863](https://github.com/holochain/holochain/pull/1863) Holonix is implemented as Holochain's [flake.nix](https://github.com/holochain/holochain/blob/develop/flake.nix) output named _#holonix_ a.k.a. _devShells.${system}.holonix_. +[Flakes](https://wiki.nixos.org/wiki/Flakes) is an experimental but well-supported feature of the Nix package manager that makes it easier to manage dependencies consistently. [Enable flakes on your system.](https://wiki.nixos.org/wiki/Flakes#Enable_flakes_temporarily) The flake-based one-liner to get you an ad-hoc Holonix shell looks like this: ```shell -nix develop github:holochain/holochain#holonix -``` - -By default, the above one-liner will give you the latest recommended release (currently from the 0.2.x series). To get an ad-hoc shell with a specific version of Holochain, use the flag `--override-input versions `. This example gives you the next release candidate in the 0.2.x series: - -```shell -nix develop --override-input versions "github:holochain/holochain?dir=versions/0_2_rc" "github:holochain/holochain#holonix" +nix develop github:holochain/holonix ``` -And this example gives you the newest weekly developer snapshot (currently from the 0.3.x series): +The above one-liner will give you the latest version of Holochain from branch `main`. To get an ad-hoc shell with a specific version of Holochain, use the flag `--override-input versions `. ```shell -nix develop --override-input versions "github:holochain/holochain?dir=versions/weekly" "github:holochain/holochain#holonix" +nix develop --override-input holochain "github:holochain/holochain?ref=main-0.4" github:holochain/holonix ``` -Take a look at the [`versions/` folder in the `holochain/holochain` repository](https://github.com/holochain/holochain/tree/develop/versions) to find out what versions you can target. Each subfolder is a valid version to use in the above command, and the `flake.nix` file inside the subfolder shows the specific release tags that will be used for Holochain and the Lair Keystore. The launcher and scaffolding tools live in separate repos, so you will get the latest release of those tools that are available on their respective release branches referenced in the version-specific `flake.nix` file. Note that you may temporarily see older versions than the current tip of the referenced release branch because our automation updates the `flake.lock` separately, so that file is the absolute source of truth for what versions you will get. - -#### Enabling Flake features on your system - -At the time of writing, flakes are still considered an experimental in the nix world and thus require being enabled. This happens either ad-hoc on the command itself or permanently via Nix's configuration. - -If you've completed the [quick installation guide](/get-started/), including the scaffolding example, then you'll likely already had the scaffolding configure it for you via the file at _~/.config/nix/nix.conf_. - -To manually configure it via this file you can run the following commands: - -```shell -mkdir -p ~/.config/nix -``` -```shell -echo "extra-experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf -``` - -To learn more, please see the [Enable flakes section on the NixOS Wiki](https://nixos.wiki/wiki/Flakes#Enable_flakes). - -### The anatomy of a `flake.nix` - -In the root directory of your app's code, you will either find the scaffolded one, or you can manually create the `flake.nix` file. Here's an example `flake.nix` that is inspired by the scaffolding template: - -```nix -{ - description = "Flake for Holochain app development"; - - inputs = { - versions.url = "github:holochain/holochain?dir=versions/0_1"; - holochain-flake = { - url = "github:holochain/holochain"; - inputs.versions.follows = "versions"; - }; - - nixpkgs.follows = "holochain-flake/nixpkgs"; - }; - - outputs = inputs @ { ... }: - inputs.holochain-flake.inputs.flake-parts.lib.mkFlake { inherit inputs; } - { - systems = builtins.attrNames inputs.holochain-flake.devShells; - perSystem = { config, pkgs, system, ... }: { - devShells.default = pkgs.mkShell { - inputsFrom = [ - inputs.holochain-flake.devShells.${system}.holonix - ]; - packages = [ - pkgs.nodejs-18_x - ]; - }; - }; - }; -} -``` - -In principle a flake implements a function that produces a set of _outputs_ from a given set of _inputs_, keeping the side-effects to an absolute minimum if not at zero. - -#### `inputs` - -This flake declares one input named `holochain-flake` that the Holochain Github repository. This input will look for a `flake.nix` in the default branch of the remote repository. -The `versions` input of the `holochain-flake` input is explicitly specified to track the _0_1_ series, which refers to Holochain's Beta 0.1 and its compatible tools. - -The flake follows (think inherits) the `nixpkgs` input of the `holochain-flake` input. This ensures that your development environment passes all the same buildinputs to the component packages, giving you very high chances to make use of our Cachix binary cache. - -#### `outputs` - -In the `outputs` set, this flake composes a dev shell that inherits its inputs from the `holonix` dev shell and adds the NodeJS package. To find the names of the packages you're interested in, the [nixos.org package search](https://search.nixos.org/packages?channel=unstable&) can be used. - -### `flake.lock` file - -Once the `flake.nix` is created (and added to the git repo), the lockfile can be initialized by running `nix flake update`. The resulting `flake.lock` records pinned references to all the `inputs` at the given point in time, in our case to the the `holochain-flake` and of all its inputs transitively; altogether keeping track of all the dependencies of your app's development environment. - ### A gotcha with Flakes and Git The behavior of `nix` commands that rely on a `flake.nix` as its input such as `nix develop` can be counterintuitive in a git repository. @@ -119,23 +39,6 @@ Specifically, if the `flake.nix` is not tracked in git, the command will fail al The simple solution to is to `git add flake.*` after your initial creation of your flake if you manually create a repository. In case of scaffolding a repository this is taken care of by the scaffolding process for you. -#### Updating the component versions - -Each time the following command is run, it looks up the most recent revisions of the inputs and locks them in the `flake.lock` file. - -```shell -nix flake update -``` - -If you want to only update a specific input, you can use the following command. Here it shows updating only the _holochain_ input: - -```shell -nix flake lock --update-input holochain -``` - -_Note that if your directory is a git repository it is recommended to `git commit flake.lock` to ensure consistency between the development environment and your app's source code._ - - ### Holonix inspection commands Built into Holochain and holonix are a few commands that give insight about versions of Holochain components. @@ -179,94 +82,12 @@ A sample output of this command looks like this (JSON formatted using `jq` i.e. } ``` -### Using a specific version of the development tools - -Here's an example of how to override the inputs of the flake to pick a different version of the `holochain` component, which includes the `holochain` conductor binary and the `hc` CLI tool: - -```nix -inputs = { - versions.url = "github:holochain/holochain?dir=versions/0_1"; - holochain-flake = { - url = "github:holochain/holochain"; - inputs.versions.follows = "versions"; - inputs.holochain.url = "github:holochain/holochain/"; - }; -... -``` - -You can override the versions of four different Holochain components: `holochain`, `lair`, `launcher`, and `scaffolding`. The `inputs.versions.url` field points to a file in the `holochain/holochain` GitHub repo containing versions of each of these, which are known to be mutually compatible. As you can see in the snippet above, the URLs of any of those components can be overridden. Take a look at the [versions file](https://github.com/holochain/holochain/blob/develop/versions/0_1/flake.nix) for an example of how we specify their URLs using Git tags. - -_Note that by specifying custom component URLs, you will probably get a binary cache miss when entering the shell, and it will have to compile the custom component versions ad-hoc._ - -### Using your default `$SHELL` - -Many developers have their shell set up just the way they like it, whether a custom-formatted prompt or a completely different shell such as `zsh` and `fish`. If you don't want Holonix to clobber your carefully-crafted environment, try adding `--command $SHELL` to the end of your `nix develop` command: - -```shell -nix develop github:holochain/holochain#holonix --command "$SHELL" -``` - -### Using your favorite text editor or IDE - -In most cases you can run your editor as you normally would. However, if you are using a text editor or integrated development environment (IDE) that needs to communicate with the Rust compiler for real-time syntax checks, then you should launch it from inside the `nix develop`. This is because Holonix comes with its own version of Rust that might be different from what you may already have installed. - -To do this, just open your editor from the command line while you are in the `nix develop` (this example uses Vim): - -```shell -nix develop github:holochain/holochain#holonix -``` -```shell -cd my_project -``` -```shell -vim my_file.rs -``` - ## More info on Nix -We use the Nix/NixOS toolkit to build consistent development, testing, and deployment environments for Holochain Core and apps. It consists of two systems: - -* NixOS, a tool for reliably building Linux-based systems from a set of configuration files (we use NixOS in our HoloPorts and automated testing VMs) -* Nix, a package manager that works on many OSes and uses the same configuration file format as NixOS - -The main components of the tooling for Holochain development are: - -* The [Rust](https://rust-lang.org) programming language -* [Node.JS](https://nodejs.org) and [npm](https://npmjs.com) -* Cryptographic libraries -* Common automations and scripts - -It is important that these remain consistent, so you can get your work done without fighting package and compiler issues. And when it comes time to compile and distribute your application, it's **very important to have a deterministic build system** so the same DNA source code always results in the same hash. - The main Nix tool used in Holochain development workflows is `nix develop`, a program that overlays a new Bash environment and set of tools on top of your existing shell environment. The full suite of Nix tooling is broad and deep. There's even a dedicated programming language, called [Nix expressions](https://nixos.org/manual/nix/stable/#functional-package-language). Learn more with the [NixOS Wiki](https://nixos.wiki) or the [Pills](https://nixos.org/nixos/nix-pills/) Tutorial. The [NixOS community chat on matrix.to](https://matrix.to/#/#community:nixos.org) is active and helpful. -### `nix develop` - -While working on Holochain, you will usually have an active `nix develop` to run commands. This shell overlays Holochain-specific configuration on top of your existing shell - environment variables, Rust toolchains, binaries, libraries, and development tools - giving you a consistent development environment to build Holochain apps. The shell environment is only set up in the current shell session, and will be reset automatically when you `exit` the shell. - -If you want to re-enter the shell to do more work, or create multiple terminals to work in, you'll need to re-enter the `nix develop` in each new instance. The packages are cached locally on your machine, so they will be ready the next time you enter the shell. You do need to get the package configuration files from somewhere, though. If you use the Holochain repo cloning method, they're cached on your machine too, but the ['quick install'](/get-started/) and ['using a specific version'](#using-a-specific-version-of-the-development-tools) methods require an internet connection every time you want to enter the shell. - -## Uninstalling Nix - -You usually don't need to uninstall anything, because `nix develop` leaves your familiar user environment alone and makes all of its own changes disappear once you exit the shell. But it does keep binaries and other packages on your device. On macOS it adds users and a user group too. If you want to free up some space, run these commands: - -```shell -nix-collect-garbage -d -``` - -If you want to uninstall Nix as well, run these commands (you might need root privileges for the first line): - -```shell -rm -rf /nix -``` -```shell -rm ~/.nix-profile -``` - -[Detailed uninstallation instructions for macOS](https://gist.github.com/chriselsner/3ebe962a4c4bd1f14d39897fc5619732#uninstalling-nix) - ## Fixing the SUID sandbox error in Ubuntu 24.04 Ubuntu 24.04 [introduced an AppArmor security policy](https://discourse.ubuntu.com/t/ubuntu-24-04-lts-noble-numbat-release-notes/39890#unprivileged-user-namespace-restrictions-15) that causes `hc spin`, which is used to test applications and their UIs, to fail with a fatal error. If you have a `package.json` that lists `@holochain/hc-spin` as a dev dependency, you may see this error message: From 248f5967373e66a02b71482f9e88bb033a75e1d5 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Fri, 11 Oct 2024 09:54:16 -0700 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: Jost Schulte --- src/pages/resources/upgrade/upgrade-new-holonix.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pages/resources/upgrade/upgrade-new-holonix.md b/src/pages/resources/upgrade/upgrade-new-holonix.md index 22b4bae3a..549f016a9 100644 --- a/src/pages/resources/upgrade/upgrade-new-holonix.md +++ b/src/pages/resources/upgrade/upgrade-new-holonix.md @@ -3,7 +3,7 @@ title: Upgrade to the new Holonix --- ::: intro -In the third quarter of 2024, we released a new [Holonix](/get-started/install-advanced/#holonix-the-holochain-app-development-environment), our development environment based on [Nix](https://nixos.org) that gives you all the dependencies to build hApps and contribute to Holochain core development. +In the third quarter of 2024, we released a new [Holonix](/get-started/install-advanced/#holonix-the-holochain-app-development-environment), our development environment based on [Nix](https://nixos.org) that gives you all the dependencies to build hApps. The new Holonix is simpler and more modular, which means that it's easier to configure it for your needs and preferences. ::: @@ -17,7 +17,7 @@ mv flake.nix flake.nix.backup mv flake.lock flake.lock.backup ``` -Then create new flake files: +Then create a new flake file: ```bash nix flake init -t github:holochain/holonix?ref=main-0.3 @@ -53,7 +53,7 @@ inputs = { ... ``` -Next time you type `nix develop` to enter the shell, it'll update your `nix.lock` and download the requested packages for you. +Next time you type `nix develop` to enter the shell, it'll update your `flake.lock` and download the requested packages for you. ## Choosing a very specific Holochain release From 68139fc919b2ac29360d0d13036d14a989dcbaa7 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Fri, 11 Oct 2024 10:01:59 -0700 Subject: [PATCH 6/6] link to Holonix readme --- src/pages/get-started/install-advanced.md | 2 +- .../resources/upgrade/upgrade-new-holonix.md | 96 +------------------ 2 files changed, 2 insertions(+), 96 deletions(-) diff --git a/src/pages/get-started/install-advanced.md b/src/pages/get-started/install-advanced.md index cd1f28158..78be80e23 100644 --- a/src/pages/get-started/install-advanced.md +++ b/src/pages/get-started/install-advanced.md @@ -19,7 +19,7 @@ If you want to learn more about how this setup works and how to create it manual [Flakes](https://wiki.nixos.org/wiki/Flakes) is an experimental but well-supported feature of the Nix package manager that makes it easier to manage dependencies consistently. -As of [holochain#1863](https://github.com/holochain/holochain/pull/1863) Holonix is implemented as Holochain's [flake.nix](https://github.com/holochain/holochain/blob/develop/flake.nix) output named _#holonix_ a.k.a. _devShells.${system}.holonix_. +As of [holochain#1863](https://github.com/holochain/holochain/pull/1863) Holonix is implemented as Holochain's [flake.nix](https://github.com/holochain/holochain/blob/main/flake.nix) output named _#holonix_ a.k.a. _devShells.${system}.holonix_. The flake-based one-liner to get you an ad-hoc Holonix shell looks like this: diff --git a/src/pages/resources/upgrade/upgrade-new-holonix.md b/src/pages/resources/upgrade/upgrade-new-holonix.md index 22b4bae3a..1bfa31bef 100644 --- a/src/pages/resources/upgrade/upgrade-new-holonix.md +++ b/src/pages/resources/upgrade/upgrade-new-holonix.md @@ -23,98 +23,4 @@ Then create new flake files: nix flake init -t github:holochain/holonix?ref=main-0.3 ``` -For most projects, that's all you need! - -## Targeting a specific Holochain version - -If your project is not on the latest recommended Holochain version (0.3 at the time of writing), you'll need to change the `ref` query string in the URL. - -For Holochain 0.2: - -```bash -nix flake init -t github:holochain/holonix?ref=main-0.2 -``` - -For the latest, unstable Holochain 0.4: - -```bash -nix flake init -t github:holochain/holonix?ref=main -``` - -If you've already created flake files for the newest Holonix, you can edit the `flake.nix` file like this: - -```diff -... -inputs = { -- holonix.url = "github:holochain/holonix?ref=main-0.3"; -+ holonix.url = "github:holochain/holonix?ref=main-0.2"; - ... -}; -... -``` - -Next time you type `nix develop` to enter the shell, it'll update your `nix.lock` and download the requested packages for you. - -## Choosing a very specific Holochain release - -If you need to be more precise about the Holochain package version, you can do this in your `flake.nix` file too: - -```diff -... -inputs = { - holonix.url = "github:holochain/holonix?ref=main"; -+ holonix.inputs.holochain.url = "github:holochain/holochain?ref=branch-or-tag-name"; - ... -} -... -``` - -!!! info Old packages and long build times -We have a limited amount of cache space for our Nix packages, so if you target a Holochain version that's quite old, you may end up building it from source on your machine, which can take hours. -!!! - -## Adding and removing packages - -If you need extra Nix packages, or don't need some provided packages, you can edit `flake.nix` like this: - -```diff -... -packages = (with inputs'.holonix.packages; [ - holochain -+ # Remove a few Holochain-provided packages -- lair-keystore -- hc-launch -- hc-scaffold -- hn-introspect - rust # For Rust development, with the WASM target included for zome builds -]) ++ (with pkgs; [ - nodejs_20 # For UI development - binaryen # For WASM optimization - # Add any other packages you need here -+ # Add my preferred Node package manager -+ yarn -]); -... -``` - -## Customizing Holochain - -If you want your build environment to include a version of Holochain with custom build flags, use this command to generate your flake files: - -```bash -nix flake init -t github:holochain/holonix#custom -``` - -(This can be used in combination with the `?ref=` query string to target a specific version.) Next, open up the generated `flake.nix` file and look for this section: - -``` -let - # Disable default features and enable wasmer_wamr for a wasm interpreter, - # as well as re-enabling tx5 and sqlite-encrypted. - cargoExtraArgs = "--no-default-features --features wasmer_wamr,sqlite-encrypted,tx5"; - # Override arguments passed in to Holochain build with above feature arguments. - customHolochain = inputs'.holonix.packages.holochain.override { inherit cargoExtraArgs; }; -in -``` - -Change the value of `cargoExtraArgs ` to your liking, then enter the development shell. _This will take a while the first time around,_ because Nix will have to build your custom Holochain binary. \ No newline at end of file +For most projects, that's all you need! If you have specific needs, such as targeting a specific Holochain version or release series, specifying build flags, or adding more Nix packages, read the [Holonix readme](https://github.com/holochain/holonix/tree/main/README.md). \ No newline at end of file