Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update scaffolding and version nums when 0.4 is finally recommended #503

Merged
merged 9 commits into from
Dec 20, 2024
Merged

Update scaffolding and version nums when 0.4 is finally recommended #503

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
321d8cf
update for scaffolding 0.4000
pdaoust Dec 6, 2024
25ab4c9
update for scaffolding 0.4000.0-rc.4
pdaoust Dec 13, 2024
45dcfa6
bump version numbers in advanced install guide, plus new output from …
pdaoust Dec 20, 2024
feb4a04
Merge branch 'main' into 2024-12-06-updates-0.4
pdaoust Dec 20, 2024
f158c42
Merge branch 'main' into 2024-12-06-updates-0.4
pdaoust Dec 20, 2024
d2f4940
update ubuntu sandbox instructions to reflect that there's a new version
pdaoust Dec 20, 2024
e665745
Merge branch '2024-12-06-updates-0.4' of github.com:holochain/docs-pa…
pdaoust Dec 20, 2024
d5acdea
remove holo dev server from hn-introspect output
pdaoust Dec 20, 2024
504eabb
update holonix commands in getting started guide
pdaoust Dec 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/pages/get-started/2-hello-world.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Ubuntu Linux 24.04 [introduces security policy changes](https://discourse.ubuntu
sudo chown root:root node_modules/electron/dist/chrome-sandbox && sudo chmod 4755 node_modules/electron/dist/chrome-sandbox
```

You'll need to do this once (but only once) for every new project you scaffold. You can find out more [here](/get-started/install-advanced/#fixing-the-suid-sandbox-error-in-ubuntu-24-04).
You'll need to do this once (but only once) for every new project you scaffold. You can find out more [here](/get-started/install-advanced/#fixing-the-suid-sandbox-error-in-ubuntu-24-04-and-later).
!!!

```shell
Expand Down
85 changes: 50 additions & 35 deletions src/pages/get-started/3-forum-app-tutorial.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -396,6 +396,24 @@ You should then see:
```text
Which fields should the entry contain?

? Field name: ›
```
:::

The scaffolding tool is now prompting you to add fields to the `post` entry type.

Fields are the individual components or attributes within a Rust struct. They determine the specific pieces of information to be stored in an entry and their respective data types. The scaffolding tool supports a collection of native Rust types such as booleans, numbers, enums (a choice between several predetermined values), optional values, and vectors (lists of items of the same type), along with Holochain-specific types that refer to other pieces of data on the DHT.

For your `post` entry type, you're going to add `title` and `content` fields. Enter the name of the first field:

```text
title
```

Next, it asks you to choose a field type:

::: output-block
```text
? Choose field type: ›
❯ String
bool
Expand All @@ -406,24 +424,15 @@ Which fields should the entry contain?
ActionHash
EntryHash
DnaHash
ExternalHash
AgentPubKey
Enum
Option of...
Vector of...
```
:::

The scaffolding tool is now prompting you to add fields to the `post` entry type.

Fields are the individual components or attributes within a Rust struct. They determine the specific pieces of information to be stored in an entry and their respective data types. The scaffolding tool supports a collection of native Rust types such as booleans, numbers, enums (a choice between several predetermined values), optional values, and vectors (lists of items of the same type), along with Holochain-specific types that refer to other pieces of data on the DHT.

For your `post` entry type, you're going to add `title` and `content` fields. Select `String` as the first field's type, and enter:

```text
title
```

as the field name.
Choose `String` and press <kbd>Enter</kbd>.

Press <kbd>Y</kbd> for the field to be visible in the UI, and select `TextField` as the widget to render this field. (A `TextField` is a single-line input field designed for capturing shorter pieces of text.)

Expand All @@ -437,17 +446,24 @@ When you see:

press <kbd>Y</kbd>.

Select `String` for this field's type too. Then enter:
Then enter the name `content` for this field's name and choose `String` as its type. Press <kbd>Y</kbd> for the field to be visible in the UI, and select `TextArea` as the widget to render the field. (A `TextArea` is a multi-line input field that allows users to enter larger blocks of text. That'll work better for forum posts.)

```text
content
```
After adding the `title` and `content` fields, press <kbd>N</kbd> when asked if you want to add another field. Next, you should see:

as the field name.
::: output-block
```text
Chosen fields:
title: String
content: String

Press <kbd>Y</kbd> for the field to be visible in the UI, and select `TextArea` as the widget to render the field. (A `TextArea` is a multi-line input field that allows users to enter larger blocks of text. That'll work better for blog posts.)
? Do you want to proceed with the current entry type or restart from the beginning? ›
❯ Confirm
pdaoust marked this conversation as resolved.
Show resolved Hide resolved
Modify
Restart
```
:::

After adding the `title` and `content` fields, press <kbd>N</kbd> when asked if you want to add another field. Next, you should see:
If the summary of your fields looks like this, press <kbd>Enter</kbd> to confirm that it's correct. Next, you'll see:

::: output-block
```text
Expand Down Expand Up @@ -537,19 +553,13 @@ comment

for the entry type name.

You're going to add a `content` field, so select the `String` field type and enter:

```text
content
```

Then select the `TextArea` widget and press <kbd>Enter</kbd>. (Again, a `TextArea` is a multi-line input field that allows users to enter larger blocks of text. Perfect for a comment on a post.)
Next, create a `content` field and select `String` as its type. Choose <kbd>Y</kbd> to create UI for it, then select the `TextArea` widget and press <kbd>Enter</kbd>. (Again, a `TextArea` is a multi-line input field that allows users to enter larger blocks of text. Perfect for a comment on a post.)

Press <kbd>Y</kbd> to add another field.

For this next field you'll want to create a field that will help you associate each particular comment to the post that it's commenting on. To do this, the next field in the `comment` entry type will store a reference to a `post`.

Use the arrow keys to select `ActionHash` as the field type.
Enter `post_hash` as the field name, press <kbd>Enter</kbd>, and use the arrow keys to select `ActionHash` as the field type.

!!! dig-deeper Hashes and other identifiers

Expand Down Expand Up @@ -599,7 +609,7 @@ You can check out the Core Concepts to dive a bit deeper into [how the distribut

!!!

After press <kbd>Enter</kbd>, you should see:
After pressing <kbd>Enter</kbd>, you should see:

::: output-block
```text
Expand All @@ -614,20 +624,25 @@ Next you will see:
::: output-block
```text
✔ Which entry type is this field referring to?
❯ Post
```
:::

Press <kbd>Enter</kbd> to accept the suggested entry type `Post`.
Press <kbd>Enter</kbd> to accept the suggested entry type `Post`. Then press <kbd>N</kbd> to decline adding another field to the entry.

Next, you'll be asked to pick a field name. You can press <kbd>Enter</kbd> to accept the field name suggestion, which should be:
You should then see a similar confirmation to when you were creating a post:

::: output-block
```text
post_hash
Chosen fields:
content: String, post_hash: ActionHash
? Do you want to proceed with the current entry type or restart from the beginning? ›
❯ Confirm
Restart
```
:::

Press <kbd>N</kbd> to decline adding another field to the entry.

Then use the arrow keys to deselect `Update`, but leave `Delete` selected. It should look as follows:
If the summary looks like this, press <kbd>Enter</kbd>. Then at the next question, use the arrow keys to deselect `Update`, but leave `Delete` selected. It should look as follows:

::: output-block
```text
Expand All @@ -637,7 +652,7 @@ Which CRUD functions should be scaffolded (SPACE to select/unselect, ENTER to co
```
:::

Once that is done, press <kbd>Enter</kbd> to generate a delete function for the **`comment`** entry type.
Once that is done, press <kbd>Enter</kbd> to generate a delete function for the `comment` entry type.

You should then see:

Expand Down Expand Up @@ -778,7 +793,7 @@ Ubuntu Linux 24.04 [introduces security policy changes](https://discourse.ubuntu
sudo chown root:root node_modules/electron/dist/chrome-sandbox && sudo chmod 4755 node_modules/electron/dist/chrome-sandbox
```

You'll need to do this once (but only once) for every new project you scaffold. You can find out more [here](/get-started/install-advanced/#fixing-the-suid-sandbox-error-in-ubuntu-24-04).
You'll need to do this once (but only once) for every new project you scaffold. You can find out more [here](/get-started/install-advanced/#fixing-the-suid-sandbox-error-in-ubuntu-24-04-and-later).
!!!

At this stage, we'll incorporate some of the UI components that have been scaffolded by the scaffolding tool into our main application interface. Our aim here is to make all the functionality of our forum application accessible from a single, unified interface. We'll use Svelte to accomplish this, as it is the framework that we have chosen for the UI layer of our application.
Expand Down
37 changes: 26 additions & 11 deletions src/pages/get-started/install-advanced.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,26 +24,26 @@ If you want to learn more about how this setup works and how to create it manual
The flake-based one-liner to get you an ad-hoc Holonix shell (that is, not using a local flake file) looks like this:

```shell
nix develop github:holochain/holonix?ref=main-0.3
nix develop github:holochain/holonix?ref=main-0.4
```

#### Specifying a certain release

The above one-liner will give you the latest **recommended** version of Holochain from the 0.3 release branch. To get an ad-hoc shell with a different version of Holochain, change the `ref` parameter. For example, if you want to enter a Holochain 0.4 development shell, run:
The above one-liner will give you the latest **recommended** version of Holochain from the 0.4 release branch. To get an ad-hoc shell with a specific version of Holochain, change the `ref` parameter. For example, if you want to enter a Holochain 0.3 development shell, run:

```shell
nix develop github:holochain/holonix?ref=main-0.4
nix develop github:holochain/holonix?ref=main-0.3
```

The options you should know about are:

* `main` or no `ref` parameter: The development version of Holochain, released weekly with no guarantee of stability (currently 0.5)
* `main-0.4`: The latest version of Holochain, which has not yet had a 'recommended' release
* `main-0.3`: The recommended version of Holochain for everyday development, which still receives maintenance releases
* `main-0.4`: The current recommended version of Holochain for everyday development
* `main-0.3`: The previous version of Holochain, which still receives maintenance releases

### Customizing the Holochain binary

If you want to enable or disable certain Holochain features, such as unstable features, it's best to do this in a local flake file. [Read the 'Customized Holochain build'](https://github.com/holochain/holonix?tab=readme-ov-file#customized-holochain-build) on the Holonix readme to find out how. Keep in mind that, because you'll be creating a custom Holochain binary, you won't be able to take advantage of the package cache, so it'll take a while to compile Holochain on your machine. The same will be true on CI, where you should consider setting up your own caching.
If you want to enable or disable certain Holochain features, such as unstable features, it's best to do this in a local flake file. Read [Customized Holochain build](https://github.com/holochain/holonix?tab=readme-ov-file#customized-holochain-build) on the Holonix readme to find out how. Keep in mind that, because you'll be creating a custom Holochain binary, you won't be able to take advantage of the package cache, so it'll take a while to compile Holochain on your machine. The same will be true on CI, where you should consider setting up your own caching.

### A gotcha with Flakes and Git

Expand All @@ -65,10 +65,25 @@ This command displays versioning information about Holochain's main components.

::: output-block
```text
holochain (holochain 0.1.3): ed5b7bb461c2a8bfd4d2633bad604a20b8f2da03
lair-keystore (lair_keystore 0.2.3): cbfbefefe43073904a914c8181a450209a74167b
hc-launch (holochain_cli_launch 0.0.11): 3bcd14e81cda07e015071b070c2ef032aa1d1193
hc-scaffold (holochain_scaffolding_cli 0.1.6): 0d84d09a9a3f41d3b7d7330a0797a789c42fd57f
hc-scaffold : holochain_scaffolding_cli 0.4000.0 (cda8433)
hc-launch : holochain_cli_launch 0.400.0 (holochain 0.4.0) (ca59803)
Lair keystore : lair_keystore 0.5.3 (e829375)
Holochain : holochain 0.4.0 (f931190)

Holochain build info: {
"git_info": null,
"cargo_pkg_version": "0.4.0",
"hdk_version_req": "0.4.0",
"hdi_version_req": "0.5.0",
"lair_keystore_version_req": "0.5.3",
"timestamp": "2024-12-18T19:25:03.915833743Z",
"hostname": "localhost",
"host": "x86_64-unknown-linux-gnu",
"target": "x86_64-unknown-linux-gnu",
"rustc_version": "rustc 1.80.0 (051478957 2024-07-21)",
"rustflags": "",
"profile": "release"
}
```
:::

Expand Down Expand Up @@ -102,7 +117,7 @@ The main Nix tool used in Holochain development workflows is `nix develop`, a pr

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.

## Fixing the SUID sandbox error in Ubuntu 24.04
## Fixing the SUID sandbox error in Ubuntu 24.04 and later

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:

Expand Down
2 changes: 1 addition & 1 deletion src/pages/resources/upgrade/upgrade-holochain-0.3.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ npm install --save-dev @holochain/hc-spin@">=0.300.0 <0.400.0"
You can always check what versions of `@holochain/hc-spin` are available on the [NPM registry](https://www.npmjs.com/package/@holochain/hc-spin?activeTab=versions).

!!! note
If you happen to be running on a recent Linux version (e.g. Ubuntu 24.04+), you might encounter an error starting your hApp with `hc-spin`. There is a guide here you should check out in [the dev tools setup tips](/get-started/install-advanced#fixing-the-suid-sandbox-error-in-ubuntu-24-04).
If you happen to be running on a recent Linux version (e.g. Ubuntu 24.04+), you might encounter an error starting your hApp with `hc-spin`. There is a guide here you should check out in [the dev tools setup tips](/get-started/install-advanced#fixing-the-suid-sandbox-error-in-ubuntu-24-04-and-later).
!!!

### Update `@holochain/tryorama`
Expand Down
Loading