nwaku/README.md

128 lines
4.3 KiB
Markdown
Raw Normal View History

2023-07-28 05:46:02 +00:00
# Nwaku
2020-05-08 20:39:16 +00:00
## Introduction
2020-05-08 20:39:16 +00:00
The nwaku repository implements Waku, and provides tools related to it.
2020-05-08 20:39:16 +00:00
- A Nim implementation of the [Waku (v2) protocol](https://specs.vac.dev/specs/waku/v2/waku-v2.html).
- CLI application `wakunode2` that allows you to run a Waku node.
- Examples of Waku usage.
- Various tests of above.
2020-05-08 20:39:16 +00:00
For more details see the [source code](waku/README.md)
2020-05-08 20:39:16 +00:00
## How to Build & Run
These instructions are generic. For more detailed instructions, see the Waku source code above.
### Prerequisites
2020-05-08 20:39:16 +00:00
2023-07-28 05:46:02 +00:00
The standard developer tools, including a C compiler, GNU Make, Bash, and Git. More information on these installations can be found [here](https://docs.waku.org/guides/nwaku/build-source#install-dependencies).
2020-05-08 20:39:16 +00:00
### Wakunode
2020-05-08 20:39:16 +00:00
```bash
# The first `make` invocation will update all Git submodules.
2023-07-28 05:46:02 +00:00
# You'll run `make update` after each `git pull` in the future to keep those submodules updated.
make wakunode2
2020-05-08 20:39:16 +00:00
# Build with custom compilation flags. Do not use NIM_PARAMS unless you know what you are doing.
# Replace with your own flags
make wakunode2 NIMFLAGS="-d:chronicles_colors:none -d:disableMarchNative"
# Run with DNS bootstrapping
./build/wakunode2 --dns-discovery --dns-discovery-url=DNS_BOOTSTRAP_NODE_URL
2020-05-08 20:39:16 +00:00
# See available command line options
./build/wakunode2 --help
2020-05-08 20:39:16 +00:00
```
To join the network, you need to know the address of at least one bootstrap node.
Please refer to the [Waku README](https://github.com/waku-org/nwaku/blob/master/waku/README.md) for more information.
2020-05-08 20:39:16 +00:00
For more on how to run `wakunode2`, refer to:
2024-02-20 17:07:26 +00:00
- [Run using binaries](https://docs.waku.org/guides/nwaku/build-source)
2023-07-28 05:46:02 +00:00
- [Run using docker](https://docs.waku.org/guides/nwaku/run-docker)
- [Run using docker-compose](https://docs.waku.org/guides/nwaku/run-docker-compose)
#### Issues
##### WSL
If you encounter difficulties building the project on WSL, consider placing the project within WSL's filesystem, avoiding the `/mnt/` directory.
### Developing
#### Nim Runtime
This repository is bundled with a Nim runtime that includes the necessary dependencies for the project.
Before you can utilise the runtime you'll need to build the project, as detailed in a previous section.
This will generate a `vendor` directory containing various dependencies, including the `nimbus-build-system` which has the bundled nim runtime.
After successfully building the project, you may bring the bundled runtime into scope by running:
```bash
source env.sh
```
2023-11-30 10:08:08 +00:00
If everything went well, you should see your prompt suffixed with `[Nimbus env]$`. Now you can run `nim` commands as usual.
### Waku Protocol Test Suite
2020-05-08 20:39:16 +00:00
```bash
# Run all the Waku tests
make test
2020-05-08 20:39:16 +00:00
```
### Building single test files
During development it is handful to build and run a single test file.
To support this make has a specific target:
targets:
- `build/<relative path to your test file.nim>`
- `test/<relative path to your test file.nim>`
Binary will be created as `<path to your test file.nim>.bin` under the `build` directory .
```bash
# Build and run your test file separately
make test/tests/common/test_enr_builder.nim
```
## Formatting
Nim files are expected to be formatted using the [`nph`](https://github.com/arnetheduck/nph) version present in `vendor/nph`.
You can easily format file with the `make nph/<relative path to nim> file` command.
For example:
```
make nph/waku/waku_core.nim
```
A convenient git hook is provided to automatically format file at commit time.
Run the following command to install it:
```shell
make install-nph
```
### Examples
2020-05-08 20:39:16 +00:00
Examples can be found in the examples folder.
This includes a fully featured chat example.
### Tools
Different tools and their corresponding how-to guides can be found in the `tools` folder.
### Bugs, Questions & Features
2023-07-28 05:46:02 +00:00
For an inquiry, or if you would like to propose new features, feel free to [open a general issue](https://github.com/waku-org/nwaku/issues/new).
2023-07-28 05:46:02 +00:00
For bug reports, please [tag your issue with the `bug` label](https://github.com/waku-org/nwaku/issues/new).
2023-07-28 05:46:02 +00:00
If you believe the reported issue requires critical attention, please [use the `critical` label](https://github.com/waku-org/nwaku/issues/new?labels=critical,bug) to assist with triaging.
2023-07-28 05:46:02 +00:00
To get help, or participate in the conversation, join the [Waku Discord](https://discord.waku.org/) server.
2023-11-07 09:56:22 +00:00
### Docs
* [REST API Documentation](https://waku-org.github.io/waku-rest-api/)