Skip to content

Commit

Permalink
docs(getting-started): local setup with gnodev (#1936)
Browse files Browse the repository at this point in the history
<!-- please provide a detailed description of the changes made in this
pull request. -->

## Description

This PR introduces a change to the Getting Started section in the docs.
As discussed with @moul, it makes sense to have `gnodev` take the
spotlight in the "Local setup" section.

With this PR, I've modified the "Local setup" section to reflect the use
of `gnodev`. I've moved the "Setting up a local chain" & "Premining
balances" out of this section, as they will belong better in a new
section which will contain new chain initialization flows.

~Dep. on #1949

Latest preview:
https://www.loom.com/share/a9d354b7234843fb8108f1698cc28b5c?sid=92850b75-5153-4f8b-aa0d-bb9d3aa0d6fd

<details><summary>Contributors' checklist...</summary>

- [x] Added new tests, or not needed, or not feasible
- [x] Provided an example (e.g. screenshot) to aid review or the PR is
self-explanatory
- [x] Updated the official documentation or not needed
- [x] No breaking changes were made, or a `BREAKING CHANGE: xxx` message
was included in the description
- [x] Added references to related issues and PRs
- [ ] Provided any useful hints for running manual tests
- [ ] Added new benchmarks to [generated
graphs](https://gnoland.github.io/benchmarks), if any. More info
[here](https://github.com/gnolang/gno/blob/master/.benchmarks/README.md).
</details>
  • Loading branch information
leohhhn authored May 13, 2024
1 parent 3ea1b47 commit 98c1d64
Show file tree
Hide file tree
Showing 21 changed files with 363 additions and 249 deletions.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
96 changes: 0 additions & 96 deletions docs/getting-started/local-setup/browsing-gno-source-code.md

This file was deleted.

104 changes: 104 additions & 0 deletions docs/getting-started/local-setup/browsing-gnoland.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
---
id: browsing-gnoland
---

# Browsing Gno.land

## Overview
In this tutorial, you will learn how to browse [realms](../../concepts/realms.md)
and [packages](../../concepts/packages.md) deployed to a Gno.land chain.
You will understand how the `Render` method is utilized to achieve realm state
visibility, and you will learn how to easily access realm APIs.

## Prerequisites
- **`gnodev` installed.** Reference the
[Local Setup](installation.md#3-installing-other-gno-tools) guide for steps

## 1. Start `gnodev`
To browse Gno source code, we need two components:
- a running `gno.land` node,
- a gno.land source code viewer, like `gnoweb`

Luckily, `gnodev` comes prepackaged with both. To start, simply run `gnodev` in
your terminal.

`gnodev` will start an in-memory node, as well as a `gnoweb` server:

![gnodev](../../assets/getting-started/local-setup/browsing-gno-source-code/gnodev.gif)

`gnodev` remembers the folder where it was installed, and loads the
[`examples/`](https://github.com/gnolang/gno/tree/master/examples) subfolder by default. By visiting
[`http://localhost:8888`](http://localhost:8888), you will be able to see the
gno.land home page:

![homepage](../../assets/getting-started/local-setup/browsing-gno-source-code/gnoland-homepage.png)

## 2. Browsing Gno.land

### Package source code
Packages in Gno.land usually have names resembling `gno.land/p/<name>`. Since
packages do not contain state, only their source code can be viewed on-chain. To
learn more about packages, check out the [Packages](../../concepts/packages.md)
concept page.

Let's take a specific example: the `avl` package, deployed at `gno.land/p/demo/avl`.
To access the source code of the `avl` package, we can append the `/p/demo/avl`
to our browser URL (from the homepage).

The final URL for the `avl` package source could be viewable at
[`http://127.0.0.1:8888/p/demo/avl`](http://127.0.0.1:8888/p/demo/avl),
if we followed default setup params, as we did in this guide.

![gnoweb avl](../../assets/getting-started/local-setup/browsing-gno-source-code/gnoweb-avl.png)

From here, we can open any source code file of the deployed on-chain package
and inspect its API.

### Realm source code & state
In contrast to Packages, Realms in Gno.land usually have names resembling
`gno.land/r/<name>`.

Realms _do_ contain state, and in addition to being able to view their source
code on-chain, users can also view their internal state representation in the
form of the `Render()` output. To learn more about realms, please check out the
[Realms](../../concepts/realms.md) concept page.

We can browse the realm `Render()` method output and source code in our browser.
For example, the `gnoland/blog` realm is deployed at `gno.land/r/gnoland/blog`.

To view the internal realm state of the `blog` realm, we can append the
`/r/gnoland/blog` to our browser URL (from the homepage).

The final URL for the `blog` realm internal state could be viewable at
[`http://127.0.0.1:8888/r/gnoland/blog`](http://127.0.0.1:8888/r/gnoland/blog),
if we followed default setup params, as we did in this guide.

![blog_render](../../assets/getting-started/local-setup/browsing-gno-source-code/blog_render.png)

:::info Render() is not required
Internal realm state does not have to be exposed through the `Render()` method
of the realm, as it is not a requirement for deploying a Realm.
:::

Additionally, to view the source code for the realm, we have two options:
- append `/` to the full realm path - [`http://127.0.0.1:8888/r/gnoland/blog/`](http://127.0.0.1:8888/r/gnoland/blog/)
- click on the `[source]` button in the top-right corner

![blog_source](../../assets/getting-started/local-setup/browsing-gno-source-code/blog_source.png)

Finally, the `[help]` button takes us to the realm help page, where you will
be able to see the user-facing API of the realm.

![blog_help](../../assets/getting-started/local-setup/browsing-gno-source-code/blog_help.png)

This page will allow you to easily generate `gnokey` commands for interacting
with the realm in question.

## Conclusion

That's it 🎉

You have successfully inspected the source code of a package and realm, and seen
the on-chain state of the blog app. You have also learned about the `[help]` page
that `gnoweb` provides.

110 changes: 110 additions & 0 deletions docs/getting-started/local-setup/installation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
---
id: installation
---

# Installation

## Overview
In this tutorial, you will learn how to set up the Gno development environment
locally, so you can get up and running writing Gno code. You will download and
install all the necessary tooling, and validate that it is correctly configured
to run on your machine.

## Prerequisites
- **Git**
- **`make` (for running Makefiles)**
- **Go 1.19+**
- **Go Environment Setup**:
- Make sure `$GOPATH` is well-defined, and `$GOPATH/bin` is added to your `$PATH` variable.
- To do this, you can add the following line to your `.bashrc`, `.zshrc` or other config file:
```
export GOPATH=$HOME/go
export PATH=$GOPATH/bin:$PATH
```

## 1. Cloning the repository
To get started with a local Gno.land development environment, you must clone the
GitHub repository somewhere on disk:

```bash
git clone https://github.com/gnolang/gno.git
```

## 2. Installing the required tools

There are three tools that should be used for getting started with Gno development:
- `gno` - the GnoVM binary
- `gnodev` - the Gno [development helper](../../gno-tooling/cli/gnodev.md)
- `gnokey` - the Gno [keypair manager](working-with-key-pairs.md)

To install all three tools, simply run the following in the root of the repo:
```bash
make install
```

## 3. Verifying installation

### `gno`
`gno` provides ample functionality to the user, among which is running,
transpiling, testing and building `.gno` files. Read more
about `gnokey` [here](../../gno-tooling/cli/gno.md).

To verify the `gno` binary is installed system-wide, you can run:

```bash
gno --help
```

You should get the help output from the command:

![gno help](../../assets/getting-started/local-setup/local-setup/gno-help.gif)

Alternatively, if you don't want to have the binary callable system-wide, you
can run the binary directly:

```bash
cd gnovm
go run ./cmd/gno --help
```

### `gnodev`
`gnodev` is the go-to Gno development helper tool - it comes with a built in
Gno.land node, a `gnoweb` server to display the state of your smart contracts
(realms), and a watcher system to actively track changes in your code. Read more
about `gnodev` [here](../../gno-tooling/cli/gnodev.md).

To verify that the `gnodev` binary is installed system-wide, you can run:

```bash
gnodev
```

You should get the following output:
![gnodev](../../assets/getting-started/local-setup/local-setup/gnodev.gif)


### `gnokey`

`gnokey` is the Gno.land keypair management CLI tool. It allows you to create
keypairs, sign transactions, and broadcast them to Gno.land chains. Read more
about `gnokey` [here](../../gno-tooling/cli/gnokey.md).

To verify that the `gnokey` binary is installed system-wide, you can run:

```bash
gnokey --help
```

You should get the help output from the command:

![gnokey help](../../assets/getting-started/local-setup/local-setup/gnokey-help.gif)

## Conclusion

That's it 🎉

You have successfully built out and installed the necessary tools for Gno
development!

In further documents, you will gain a better understanding on how they are used
to make Gno work.
Loading

0 comments on commit 98c1d64

Please sign in to comment.