-
Notifications
You must be signed in to change notification settings - Fork 382
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs(getting-started): local setup with gnodev (#1936)
<!-- 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
Showing
21 changed files
with
363 additions
and
249 deletions.
There are no files selected for viewing
Binary file added
BIN
+309 KB
docs/assets/getting-started/local-setup/browsing-gno-source-code/blog_help.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+90 KB
docs/assets/getting-started/local-setup/browsing-gno-source-code/blog_render.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+91.7 KB
docs/assets/getting-started/local-setup/browsing-gno-source-code/blog_source.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+264 KB
docs/assets/getting-started/local-setup/browsing-gno-source-code/gnodev.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+363 KB
...ssets/getting-started/local-setup/browsing-gno-source-code/gnoland-homepage.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified
BIN
-17.6 KB
(89%)
docs/assets/getting-started/local-setup/browsing-gno-source-code/gnoweb-avl.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed
BIN
-217 KB
...s/getting-started/local-setup/browsing-gno-source-code/gnoweb-boards-source.png
Binary file not shown.
Binary file removed
BIN
-153 KB
docs/assets/getting-started/local-setup/browsing-gno-source-code/gnoweb-boards.png
Binary file not shown.
Binary file removed
BIN
-218 KB
docs/assets/getting-started/local-setup/browsing-gno-source-code/gnoweb.png
Binary file not shown.
Binary file added
BIN
+108 KB
...getting-started/local-setup/interacting-with-gnoland/faucet-hub-portal-loop.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+114 KB
docs/assets/getting-started/local-setup/interacting-with-gnoland/faucet-hub.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+150 KB
...ssets/getting-started/local-setup/interacting-with-gnoland/userbook-default.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+239 KB
docs/assets/getting-started/local-setup/interacting-with-gnoland/userbook-help.png
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
96
docs/getting-started/local-setup/browsing-gno-source-code.md
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. |
Oops, something went wrong.