From 23910b488d9ad24ea4f2f73245b588ffab733af1 Mon Sep 17 00:00:00 2001 From: Jost Schulte Date: Wed, 22 Feb 2023 09:29:40 -0600 Subject: [PATCH 01/11] replace nix installation instructions with setup script --- src/pages/quick-start/index.md | 30 +++++------------------------- 1 file changed, 5 insertions(+), 25 deletions(-) diff --git a/src/pages/quick-start/index.md b/src/pages/quick-start/index.md index 029a6eab7..5cc126a21 100644 --- a/src/pages/quick-start/index.md +++ b/src/pages/quick-start/index.md @@ -11,44 +11,24 @@ pageStyleId: install * 30GB+ available disk space * High Speed Internet connection -## Install Holochain on Linux, macOS and Windows +## Holochain on Linux, macOS and Windows !!! note Prerequisite for Windows: WSL2 -Holochain development uses the same tools across Mac, Windows, and Linux. However, the Nix toolkit, which we use to install and manage those tools, only works natively on Mac and Linux. Linux can be run under Windows with [WSL2 (Windows Subsystem for Linux)](https://learn.microsoft.com/en-us/windows/wsl/install){target=_blank}. +The Nix package manager, which we use to install and manage Holochain development tools, only supports Mac and Linux. Linux can be run under Windows with [WSL2 (Windows Subsystem for Linux)](https://learn.microsoft.com/en-us/windows/wsl/install){target=_blank}. _Holochain is supported for the Ubuntu distribution under WSL2._ !!! -### Install the Nix Package Manager +### Install the Nix Package Manager & set up Holochain binary cache At a command line: ```bash -sh <(curl -L https://nixos.org/nix/install) --daemon +bash <(curl https://holochain.github.io/holochain/setup.sh) ``` -After installing Nix, close the terminal and open a new one. - -Check that Nix is correctly installed: - -```bash -nix-shell --version -``` - -You should see something like: - -```bash -nix-shell (Nix) 2.13.2 -``` - -Run the following command to set up the cache for precompiled Holochain executables: - -```bash -sudo --preserve-env=PATH $(which nix) run nixpkgs/nixos-22.11#cachix --extra-experimental-features nix-command --extra-experimental-features flakes -- use holochain-ci -m root-nixconf && sudo pkill nix-daemon -``` - -## Scaffold Your First Holochain App +### Scaffold Your First Holochain App Type the following at the command line: From b7e2f6627ee95de3db1e50e992f2d7d8f1860726 Mon Sep 17 00:00:00 2001 From: Stefan Junker Date: Fri, 10 Feb 2023 18:05:39 +0100 Subject: [PATCH 02/11] quick-start: replace nix-shell with nix --- src/pages/quick-start/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/quick-start/index.md b/src/pages/quick-start/index.md index 5cc126a21..5774d27b8 100644 --- a/src/pages/quick-start/index.md +++ b/src/pages/quick-start/index.md @@ -33,7 +33,7 @@ bash <(curl https://holochain.github.io/holochain/setup.sh) Type the following at the command line: ```bash -nix-shell https://holochain.love --run "hc scaffold example forum" +nix run github:holochain/holochain#hc-scaffold -- example forum ``` When prompted, select the UI framework you prefer. From 0dd86c10a0cca6a67dfce533791bdf34290a1eb1 Mon Sep 17 00:00:00 2001 From: Stefan Junker Date: Sat, 11 Feb 2023 13:13:09 +0100 Subject: [PATCH 03/11] get-building: replace nix-shell -> nix run --- src/pages/get-building/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/get-building/index.md b/src/pages/get-building/index.md index 442878fc0..7525af0fd 100644 --- a/src/pages/get-building/index.md +++ b/src/pages/get-building/index.md @@ -14,7 +14,7 @@ For this example we will scaffold the canonical example, a To-do hApp. Run the holochain scaffolding tool by typing in your terminal: ```bash -nix-shell https://holochain.love --run "hc scaffold web-app" +nix run github:/holochain/holochain#hc-scaffold -- web-app" ``` You should then see: ```text From eccb54690af251943277b81a4fd7f4e71ac158dc Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 22 Feb 2023 11:26:25 -0800 Subject: [PATCH 04/11] dev tools setup guide: install script turns experimental features on --- src/pages/get-building/install-advanced.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/get-building/install-advanced.md b/src/pages/get-building/install-advanced.md index e67c589d4..98bc023fc 100644 --- a/src/pages/get-building/install-advanced.md +++ b/src/pages/get-building/install-advanced.md @@ -29,7 +29,7 @@ nix develop github:holochain/holochain#holonix 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](../install/), including the scaffolding example, then you'll likely already had the scaffolding configure it for you via the file at _~/.config/nix/nix.conf_. +If you've completed the [quick installation guide](../install/), then the install script will have already configured this for you via the file at _~/.config/nix/nix.conf_. To manually configure it via this file you can run the following commands: From 2a63a71b7d6d8a8775ac1f955d4cd83f373a93ae Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 22 Feb 2023 11:44:52 -0800 Subject: [PATCH 05/11] formatting fixes --- src/pages/get-building/install-advanced.md | 30 +++++++++++----------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/src/pages/get-building/install-advanced.md b/src/pages/get-building/install-advanced.md index 98bc023fc..c22a39355 100644 --- a/src/pages/get-building/install-advanced.md +++ b/src/pages/get-building/install-advanced.md @@ -5,31 +5,31 @@ hide: --- ::: coreconcepts-intro -This guide assumes that you've already followed the [quick installation guide](../install/) 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](../install/) and want to learn more about the setup. It describes how to manually recreate and maintain the development environment, use your default shell and preferred code editor with Nix, or install specific versions of Holochain, and explains why we use `nix develop` in the first place. ::: -## Holonix - the Holochain app development environment +## Holonix, the Holochain app development environment Each Holochain application repository will contain its own setup of the development environment. If you use the scaffolding to generate the project structure, this will already be taken care of in the scaffolded directory. 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](https://nixos.wiki/wiki/Flakes) features -### Holonix' usage of [Nix' Flakes](https://nixos.wiki/wiki/Flakes) features - -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/develop/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: ```shell nix develop github:holochain/holochain#holonix ``` + #### 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](../install/), then the install script will have already configured this for you via the file at _~/.config/nix/nix.conf_. +If you've completed the [quick installation guide](../install/), then the install script will have already configured this for you via the file at `~/.config/nix/nix.conf`. To manually configure it via this file you can run the following commands: @@ -78,12 +78,13 @@ In the root directory of your app's code, you will either find the scaffolded on 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. +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 devShell that inherits its inputs from the `holonix` devShell 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. @@ -94,9 +95,9 @@ The resulting `flake.lock` records pinned references to all the `inputs` at the ### 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. +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. -Specifically, if the `flake.nix` is not tracked in git, the command will fail altogether with a message that it cannot find a `flake.nix` file. Even though by design, this is a [known UX issue in Nix](https://github.com/NixOS/nix/issues/6642). +Specifically, if the `flake.nix` is not tracked in Git, the command will fail altogether with a message that it cannot find a `flake.nix` file. Even though by design, this is a [known UX issue in Nix](https://github.com/NixOS/nix/issues/6642). 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. @@ -114,8 +115,7 @@ If you want to only update a specific input, you can use the following command. $ 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._ - +_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 @@ -219,9 +219,9 @@ The full suite of Nix tooling is broad and deep. There’s even a dedicated prog ### `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. +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'](../install/) 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. +If you want to do more work, or create multiple terminals to work in, you'll need to re-enter the `nix develop` shell 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'](../install/) 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 From 739edcbf05c7a071799002b26233bcf1e5a25c6a Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 22 Feb 2023 11:45:45 -0800 Subject: [PATCH 06/11] update fave text editor example to be more realistic --- src/pages/get-building/install-advanced.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/get-building/install-advanced.md b/src/pages/get-building/install-advanced.md index c22a39355..0e1a44a43 100644 --- a/src/pages/get-building/install-advanced.md +++ b/src/pages/get-building/install-advanced.md @@ -194,7 +194,7 @@ To do this, just open your editor from the command line while you are in the `ni ```shell nix develop github:holochain/holochain#holonix cd my_project -vim my_file.rs +code my_file.rs ``` ## More info on Nix From dfe7dee27be71c5af6fe8f34613d1f971985fc71 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 22 Feb 2023 11:51:04 -0800 Subject: [PATCH 07/11] Change the bit about working offline --- src/pages/get-building/install-advanced.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/get-building/install-advanced.md b/src/pages/get-building/install-advanced.md index 0e1a44a43..3b7ba156a 100644 --- a/src/pages/get-building/install-advanced.md +++ b/src/pages/get-building/install-advanced.md @@ -221,7 +221,7 @@ The full suite of Nix tooling is broad and deep. There’s even a dedicated prog 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 do more work, or create multiple terminals to work in, you'll need to re-enter the `nix develop` shell 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'](../install/) 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. +If you want to do more work, or create multiple terminals to work in, you'll need to re-enter the `nix develop` shell in each new instance. The packages are cached locally on your machine, so they will be ready the next time you enter the shell. If you follow the practices above to create a per-project `flake.nix` file, you can work completely offline, but you need an internet connection in order to enter the [ad-hoc shell](#holonixs-usage-of-nixs-flakes-features). If you're going to be working offline, you can [download a snapshot of the holochain GitHub repository](https://github.com/holochain/holochain/archive/refs/heads/develop.zip) and enter the shell once using the contained `flake.nix`. After that, the packages will be cached and you can use that as an ad-hoc shell. ## Uninstalling Nix From 2a595f47ea0f7668be1db3540b0e9bd5e3684300 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 22 Feb 2023 11:53:47 -0800 Subject: [PATCH 08/11] fix broken quick-install links in advanced guide --- src/pages/get-building/install-advanced.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/get-building/install-advanced.md b/src/pages/get-building/install-advanced.md index 3b7ba156a..d4c594ff8 100644 --- a/src/pages/get-building/install-advanced.md +++ b/src/pages/get-building/install-advanced.md @@ -5,7 +5,7 @@ hide: --- ::: coreconcepts-intro -This guide assumes that you've already followed the [quick installation guide](../install/) and want to learn more about the setup. It describes how to manually recreate and maintain the development environment, use your default shell and preferred code editor with Nix, or install specific versions of Holochain, and explains why we use `nix develop` in the first place. +This guide assumes that you've already followed the [quick installation guide](../../install/) and want to learn more about the setup. It describes how to manually recreate and maintain the development environment, use your default shell and preferred code editor with Nix, or install specific versions of Holochain, and explains why we use `nix develop` in the first place. ::: ## Holonix, the Holochain app development environment @@ -29,7 +29,7 @@ nix develop github:holochain/holochain#holonix 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](../install/), then the install script will have already configured this for you via the file at `~/.config/nix/nix.conf`. +If you've completed the [quick installation guide](../../install/), then the install script will have already configured this for you via the file at `~/.config/nix/nix.conf`. To manually configure it via this file you can run the following commands: From d81979c5d90c26c7e738ba0cc30c7db294a8cf8c Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 22 Feb 2023 11:55:25 -0800 Subject: [PATCH 09/11] fix broken frag id links on advanced install guide --- src/pages/get-building/install-advanced.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/get-building/install-advanced.md b/src/pages/get-building/install-advanced.md index d4c594ff8..3c37dc69a 100644 --- a/src/pages/get-building/install-advanced.md +++ b/src/pages/get-building/install-advanced.md @@ -221,7 +221,7 @@ The full suite of Nix tooling is broad and deep. There’s even a dedicated prog 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 do more work, or create multiple terminals to work in, you'll need to re-enter the `nix develop` shell in each new instance. The packages are cached locally on your machine, so they will be ready the next time you enter the shell. If you follow the practices above to create a per-project `flake.nix` file, you can work completely offline, but you need an internet connection in order to enter the [ad-hoc shell](#holonixs-usage-of-nixs-flakes-features). If you're going to be working offline, you can [download a snapshot of the holochain GitHub repository](https://github.com/holochain/holochain/archive/refs/heads/develop.zip) and enter the shell once using the contained `flake.nix`. After that, the packages will be cached and you can use that as an ad-hoc shell. +If you want to do more work, or create multiple terminals to work in, you'll need to re-enter the `nix develop` shell in each new instance. The packages are cached locally on your machine, so they will be ready the next time you enter the shell. If you follow the practices above to create a per-project `flake.nix` file, you can work completely offline, but you need an internet connection in order to enter the [ad-hoc shell](#holonix%27s-usage-of-nix%27s-flakes-features). If you're going to be working offline, you can [download a snapshot of the holochain GitHub repository](https://github.com/holochain/holochain/archive/refs/heads/develop.zip) and enter the shell once using the contained `flake.nix`. After that, the packages will be cached and you can use that as an ad-hoc shell. ## Uninstalling Nix From e1e36e4e84e76a6ba9e24d02c4b269cb0d1ae080 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 22 Feb 2023 11:57:08 -0800 Subject: [PATCH 10/11] modify language a bit --- src/pages/get-building/install-advanced.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/get-building/install-advanced.md b/src/pages/get-building/install-advanced.md index 3c37dc69a..de5951b1d 100644 --- a/src/pages/get-building/install-advanced.md +++ b/src/pages/get-building/install-advanced.md @@ -221,7 +221,7 @@ The full suite of Nix tooling is broad and deep. There’s even a dedicated prog 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 do more work, or create multiple terminals to work in, you'll need to re-enter the `nix develop` shell in each new instance. The packages are cached locally on your machine, so they will be ready the next time you enter the shell. If you follow the practices above to create a per-project `flake.nix` file, you can work completely offline, but you need an internet connection in order to enter the [ad-hoc shell](#holonix%27s-usage-of-nix%27s-flakes-features). If you're going to be working offline, you can [download a snapshot of the holochain GitHub repository](https://github.com/holochain/holochain/archive/refs/heads/develop.zip) and enter the shell once using the contained `flake.nix`. After that, the packages will be cached and you can use that as an ad-hoc shell. +If you want to do more work, or create multiple terminals to work in, you'll need to re-enter the `nix develop` shell in each new instance. The packages are cached locally on your machine, so they will be ready the next time you enter the shell. If you follow the practices above to create a per-project `flake.nix` file, you can work completely offline, but you need an internet connection in order to enter the [ad-hoc shell](#holonix%27s-usage-of-nix%27s-flakes-features). If you're going to be working offline, you can [download a snapshot of the holochain GitHub repository](https://github.com/holochain/holochain/archive/refs/heads/develop.zip) and enter the shell once using the contained `flake.nix`. After that, the packages will be cached and you can continue to use this flake for ad-hoc shells. ## Uninstalling Nix From 8f1d7e479076a9c262d99be4f912dc29eb77445c Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 22 Feb 2023 12:01:55 -0800 Subject: [PATCH 11/11] change `code` example editor to `codium` Co-authored-by: Stefan Junker <1181362+steveeJ@users.noreply.github.com> --- src/pages/get-building/install-advanced.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/get-building/install-advanced.md b/src/pages/get-building/install-advanced.md index de5951b1d..545a10db1 100644 --- a/src/pages/get-building/install-advanced.md +++ b/src/pages/get-building/install-advanced.md @@ -194,7 +194,7 @@ To do this, just open your editor from the command line while you are in the `ni ```shell nix develop github:holochain/holochain#holonix cd my_project -code my_file.rs +codium my_file.rs ``` ## More info on Nix