Skip to content

Commit

Permalink
Updated docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@brunoffranca
brunoffranca committed Nov 15, 2024
1 parent 04f5d9a commit 457c4f2
Show file tree
Hide file tree
Showing 2 changed files with 80 additions and 102 deletions.
172 changes: 75 additions & 97 deletions docs/src/guides/setup-dev.md
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,21 @@
# Installing dependencies
# Installing development setup for ZKsync

## TL;DR

This is a shorter version of setup guide to make it easier subsequent initializations. If it's the first time you're
This is a shorter version of setup guide to make it easier for initializations. If it's the first time you're
initializing the workspace, it's recommended that you read the whole guide below, as it provides more context and tips.

If you run on 'clean' Ubuntu on GCP:
Just run the following command on Linux:

```bash

curl -L https://raw.githubusercontent.com/matter-labs/zksync-era/main/docs/src/guides/setup-dev.sh | bash
```

Don't forget to look at [tips](#tips).

## Supported operating systems
## Installation guide

### Supported operating systems

ZKsync currently can be launched on any \*nix operating system (e.g. any linux distribution or macOS).

Expand All @@ -28,84 +30,26 @@ Rosetta may cause problems that are hard to spot and debug, so make sure to chec

If you are a NixOS user or would like to have a reproducible environment, skip to the section about `nix`.

## Docker

Install `docker`. It is recommended to follow the instructions from the
[official site](https://docs.docker.com/install/).

Note: currently official site proposes using Docker Desktop for Linux, which is a GUI tool with plenty of quirks. If you
want to only have CLI tool, you need the `docker-ce` package and you can follow
[this guide](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-20-04) for Ubuntu.

Installing `docker` via `snap` or from the default repository can cause troubles.

You need to install both `docker` and `docker compose`.

**Note:** `docker compose` is installed automatically with `Docker Desktop`.

**Note:** On linux you may encounter the following error when you’ll try to work with `zksync`:

```
ERROR: Couldn't connect to Docker daemon - you might need to run `docker-machine start default`.
```

If so, you **do not need** to install `docker-machine`. Most probably, it means that your user is not added to
the`docker` group. You can check it as follows:

```bash
docker-compose up # Should raise the same error.
sudo docker-compose up # Should start doing things.
```

If the first command fails, but the second succeeds, then you need to add your user to the `docker` group:

```bash
sudo usermod -a -G docker your_user_name
```

After that, you should logout and login again (user groups are refreshed after the login). The problem should be solved
at this step.

If logging out does not resolve the issue, restarting the computer should.

## Node.js & Yarn

1. Install `Node` (requires version `v20`). The recommended way is via [nvm](https://github.com/nvm-sh/nvm).
2. Install `yarn`. Can be done via `npm install -g yarn`. Make sure to get version 1.22.19 - you can change the version
by running `yarn set version 1.22.19`.
### Basic packages

## clang

In order to compile RocksDB, you must have LLVM available. On debian-based linux it can be installed as follows:
Install the basic packages:

On debian-based linux:

```bash
sudo apt-get install build-essential pkg-config cmake clang lldb lld
sudo apt install git build-essential pkg-config cmake clang lldb lld libssl-dev libpq-dev apt-transport-https ca-certificates curl software-properties-common
```

On macOS:

You need to have an up-to-date `Xcode`. You can install it directly from `App Store`. With Xcode command line tools, you
get the Clang compiler installed by default. Thus, having XCode you don't need to install `clang`.

## OpenSSL

Install OpenSSL:

On mac:

```bash
brew install openssl
brew install git build-essential pkg-config cmake clang lldb lld libssl-dev libpq-dev apt-transport-https ca-certificates curl software-properties-common
```

On debian-based linux:
Note that in order to install `clang` on MacOS you need to have an up-to-date `Xcode`. You can install it directly from `App Store`.
With `Xcode` command line tools, you get the Clang compiler installed by default. Thus, having `Xcode` you don't need to install `clang`.

```bash
sudo apt-get install libssl-dev
```

## Rust
### Rust

Install `Rust`'s toolchain version reported in `/rust-toolchain.toml` (also a later stable version should work).

Expand Down Expand Up @@ -141,62 +85,84 @@ If you see `x86_64` mentioned in the output, probably you're running (or used to
that's the case, you should probably change the way you run terminal, and/or reinstall your IDE, and then reinstall the
Rust toolchain as well.

## PostgreSQL Client Library

For development purposes, you typically only need the PostgreSQL client library, not the full server installation.
Here's how to install it:
#### Cargo nextest

On macOS:
[cargo-nextest](https://nexte.st/) is the next-generation test runner for Rust projects. `zkstack dev test rust` uses
`cargo nextest` by default.

```bash
brew install libpq
cargo install cargo-nextest --locked
```

On Debian-based Linux:
#### SQLx CLI

SQLx is a Rust library we use to interact with Postgres, and its CLI is used to manage DB migrations and support several
features of the library.

```bash
sudo apt-get install libpq-dev
cargo install sqlx-cli --version 0.8.1
```

### Cargo nextest
### Docker

[cargo-nextest](https://nexte.st/) is the next-generation test runner for Rust projects. `zkstack dev test rust` uses
`cargo nextest` by default.
Install `docker`. It is recommended to follow the instructions from the
[official site](https://docs.docker.com/install/).

```bash
cargo install cargo-nextest
```
Note: currently official site proposes using Docker Desktop for Linux, which is a GUI tool with plenty of quirks. If you
want to only have CLI tool, you need the `docker-ce` package and you can follow
[this guide](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-20-04) for Ubuntu.

### SQLx CLI
Installing `docker` via `snap` or from the default repository can cause troubles.

SQLx is a Rust library we use to interact with Postgres, and its CLI is used to manage DB migrations and support several
features of the library.
You need to install both `docker` and `docker compose`.

**Note:** `docker compose` is installed automatically with `Docker Desktop`.

**Note:** On linux you may encounter the following error when you’ll try to work with `zksync`:

```
ERROR: Couldn't connect to Docker daemon - you might need to run `docker-machine start default`.
```

If so, you **do not need** to install `docker-machine`. Most probably, it means that your user is not added to
the`docker` group. You can check it as follows:

```bash
cargo install sqlx-cli --version 0.8.1
docker-compose up # Should raise the same error.
sudo docker-compose up # Should start doing things.
```

## Easier method using `nix`
If the first command fails, but the second succeeds, then you need to add your user to the `docker` group:

Nix is a tool that can fetch _exactly_ the right dependencies specified via hashes. The current config is Linux-only but
it is likely that it can be adapted to Mac.
```bash
sudo usermod -a -G docker your_user_name
```

Install `nix`. Enable the nix command and flakes.
After that, you should logout and login again (user groups are refreshed after the login). The problem should be solved
at this step.

Install docker, rustup and use rust to install SQLx CLI like described above. If you are on NixOS, you also need to
enable nix-ld.
If logging out does not resolve the issue, restarting the computer should.

Go to the zksync folder and run `nix develop`. After it finishes, you are in a shell that has all the dependencies.
### Node.js & Yarn

1. Install `Node` (requires version `v20`). The recommended way is via [nvm](https://github.com/nvm-sh/nvm).
2. Install `yarn`. Can be done via `npm install -g yarn`. Make sure to get version 1.22.19 - you can change the version
by running `yarn set version 1.22.19`.

## Foundry ZKsync
### Foundry ZKsync

ZKSync depends on Foundry ZKsync (which is is a specialized fork of Foundry, tailored for ZKsync). Please follow this
[installation guide](https://foundry-book.zksync.io/getting-started/installation) to get started with Foundry ZKsync.

Foundry ZKsync can also be used for deploying smart contracts. For commands related to deployment, you can pass flags
for Foundry integration.

## Non-GPU setup
### ZK Stack CLI

Toolkit for creating and managing ZK Stack chains. `ZK Stack CLI` facilitates the creation and management of ZK Stacks.
Commands are interactive but can also accept arguments via the command line. Follow the installation instructions [here](https://github.com/matter-labs/zksync-era/tree/main/zkstack_cli#installation).

### Non-GPU setup

Circuit Prover requires a CUDA bindings to run. If you still want to be able to build everything locally on non-CUDA
setup, you'll need use CUDA stubs.
Expand All @@ -221,6 +187,18 @@ RUSTFLAGS as env var, or pass it in `config.toml` (either project level or globa
rustflags = ["--cfg=no_cuda"]
```

## Easier method using `nix`

Nix is a tool that can fetch _exactly_ the right dependencies specified via hashes. The current config is Linux-only but
it is likely that it can be adapted to Mac.

Install `nix`. Enable the nix command and flakes.

Install docker, rustup and use rust to install SQLx CLI like described above. If you are on NixOS, you also need to
enable nix-ld.

Go to the zksync folder and run `nix develop`. After it finishes, you are in a shell that has all the dependencies.

## Tips

### Tip: `mold`
Expand Down
10 changes: 5 additions & 5 deletions docs/src/guides/setup-dev.sh
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#!/bin/bash
#!/usr/bin/env bash

main() {
say "Setting up the development environment for ZKSync"
Expand Down Expand Up @@ -51,15 +51,15 @@ main() {
curl -L https://raw.githubusercontent.com/matter-labs/zksync-era/main/zkstack_cli/zkstackup/install | bash
"$HOME/.local/bin/zkstackup"

# Clone the repo
say "Cloning the ZK Sync repository..."
git clone --recurse-submodules https://github.com/matter-labs/zksync-era.git

# Non CUDA (GPU) setup, can be skipped if the machine has a CUDA installed for provers
# Don't do that if you intend to run provers on your machine. Check the prover docs for a setup instead.
say "Setting up the non-CUDA setup..."
echo "export ZKSYNC_USE_CUDA_STUBS=true" >> "$HOME/.bashrc"

# Clone the repo
say "Cloning the ZK Sync repository..."
git clone --recurse-submodules https://github.com/matter-labs/zksync-era.git

say "Installation of the development environment for ZKSync complete!"
say "Please reload your shell configuration by running 'source ~/.bashrc'"
}
Expand Down

0 comments on commit 457c4f2

Please sign in to comment.