Merge pull request #15273 from MinaProtocol/dev-readme

Fixup formatting of README-dev
MinaProtocol · Mar 5, 2024 · 0d1394d · 0d1394d
2 parents 0894c3d + f2e3478
commit 0d1394d
Showing 1 changed file with 95 additions and 87 deletions.
diff --git a/README-dev.md b/README-dev.md
@@ -26,13 +26,13 @@ Quick start instructions:
     git clone [email protected]:MinaProtocol/mina.git
     ```
 
-If you have already done that, remember that the MinaProtocol and o1-labs repositories do not accept the password authentication used by the https URLs. You must set GitHub repos to pull and push over ssh: 
+    If you have already done that, remember that the MinaProtocol and o1-labs repositories do not accept the password authentication used by the https URLs. You must set GitHub repos to pull and push over ssh:
 
     ```sh
     git config --global url.ssh://[email protected]/.insteadOf https://github.com/
     ```
 
-3.  Pull in the submodules: 
+3.  Pull in the submodules:
 
     ```sh
     git submodule update --init --recursive
@@ -53,70 +53,80 @@ You can build Mina using Docker. Using Docker works in any dev environment. See
 ### Developer Setup (MacOS)
 
 1. Upgrade to the latest version of macOS.
-2. Install Xcode Command Line Tools: 
+2. Install Xcode Command Line Tools:
 
     ```sh
     xcode-select --install
     ```
 
 3. Invoke `make macos-setup`.
-  - When prompted, confirm that you want to add a number of exports in your shell config file.
-  - Make sure to `source` your shell config file or create a new terminal.
-  - If this is your first time using OCaml, be sure to run: 
-
+
+   - When prompted, confirm that you want to add a number of exports in your shell config file.
+   - Make sure to `source` your shell config file or create a new terminal.
+   - If this is your first time using OCaml, be sure to run:
+
+        ```sh
+        eval $(opam config env)
+        ```
+
+1. Install [rustup](https://rustup.rs/).
+2. Create your switch with deps `opam switch import --switch mina opam.export`
+
+    M1- and M2- operating systems experience issues because Homebrew does not link include files automatically.
+
+    If you get an error about failing to find `gmp.h`, update your `~/.zshrc` or `~/.bashrc` with:
+
     ```sh
-    eval $(opam config env)
+    export CFLAGS="-I/opt/homebrew/Cellar/gmp/6.2.1_1/include/"
     ```
 
-4. Install [rustup](https://rustup.rs/).
-5. Create your switch with deps `opam switch import --switch mina opam.export`
+    or run:
 
-  M1- and M-2 operating systems experience issues because Homebrew does not link include files automatically. 
-
-  If you get an error about failing to find `gmp.h`, update your `~/.zshrc` or `~/.bashrc` with:
-
-  `export CFLAGS="-I/opt/homebrew/Cellar/gmp/6.2.1_1/include/"`
-
-  or run:
-
-  `env CFLAGS="/opt/homebrew/Cellar/gmp/6.2.1_1/include/" opam install conf-gmp.2`
-
-  If you get an error about failing to find `lmdb.h`, update your `~/.zshrc` or `~/.bashrc` with:
-
-  ```text
-  export CPATH="$HOMEBREW_PREFIX/include:$CPATH"
-  export LIBRARY_PATH="$HOMEBREW_PREFIX/lib:$LIBRARY_PATH"
-  export PATH="$(brew --prefix lmdb)/bin:$PATH"
-  export PKG_CONFIG_PATH=$(brew --prefix lmdb)/lib/pkgconfig:$PKG_CONFIG_PATH
-  ```
-
-- Note: If you get conf-openssl install errors, try running `export PKG_CONFIG_PATH=$(brew --prefix [email protected])/lib/pkgconfig` and try `opam switch import opam.export` again.
-- If prompted, run `opam user-setup install` to enable opam-user-setup support for Merlin.
-6. Pin dependencies that override opam versions:
-
-  ```sh
-  scripts/pin-external-packages.sh
-  ```
+    ```sh
+    env CFLAGS="/opt/homebrew/Cellar/gmp/6.2.1_1/include/" opam install conf-gmp.2
+    ```
+
+    If you get an error about failing to find `lmdb.h`, update your `~/.zshrc` or `~/.bashrc` with:
+
+    ```text
+    export CPATH="$HOMEBREW_PREFIX/include:$CPATH"
+    export LIBRARY_PATH="$HOMEBREW_PREFIX/lib:$LIBRARY_PATH"
+    export PATH="$(brew --prefix lmdb)/bin:$PATH"
+    export PKG_CONFIG_PATH=$(brew --prefix lmdb)/lib/pkgconfig:$PKG_CONFIG_PATH
+    ```
+
+   - Note:If you get conf-openssl install errors, try running `export PKG_CONFIG_PATH=$(brew --prefix [email protected])/lib/pkgconfig` and try `opam switch import opam.export` again.
+   - If prompted, run `opam user-setup install` to enable opam-user-setup support for Merlin.
+
+3. Pin dependencies that override opam versions:
+
+    ```sh
+    scripts/pin-external-packages.sh
+    ```
 
 7. Install the correct version of golang:
+
    - `goenv init`
    - To make sure the right `goenv` is used, update your shell env script with:
 
-    ```text
-     eval "$(goenv init -)"
-     export PATH="/Users/$USER/.goenv/shims:$PATH"
-     ```
+        ```text
+        eval "$(goenv init -)"
+        export PATH="/Users/$USER/.goenv/shims:$PATH"
+        ```
+
    - `goenv install 1.18.10`
    - `goenv global 1.18.10`
-   - Check that the `go version` returns the right version, otherwise you see the message `compile: version "go1.18.10" does not match go tool version "go1.20.2"`. If so, run `brew remove go` or get the matching version.
-8. Invoke `make build`.
+   - Check that the `go version` returns the right version, otherwise you see the message `compile:version "go1.18.10" does not match go tool version "go1.20.2"`. If so, run `brew remove go` or get the matching version.
 
-  If you get errors about `libp2p` and `capnp`, try with `brew install capnp`.
-9.  For better IDE support, install the OCaml-LSP language server for OCaml: 
+9.  Invoke `make build`.
 
-  ```sh
-  opam install ocaml-lsp-server
-  ```
+    If you get errors about `libp2p` and `capnp`, try with `brew install capnp`.
+
+9.  For better IDE support, install the OCaml-LSP language server for OCaml:
+
+    ```sh
+    opam install ocaml-lsp-server
+    ```
 
 10. Set up your IDE. See [Customizing your dev environment for autocomplete/merlin](https://github.com/MinaProtocol/mina/blob/develop/README-dev.md#customizing-your-dev-environment-for-autocompletemerlin).
 
@@ -132,7 +142,7 @@ To get all of the required opam dependencies, run:
 opam switch import opam.export
 ```
 
-*_NOTE:_*  The `switch` command provides a `dune_wrapper` binary that you can use instead of dune and fails early if your switch becomes out of sync with the `opam.export` file.
+**NOTE**: The `switch` command provides a `dune_wrapper` binary that you can use instead of dune and fails early if your switch becomes out of sync with the `opam.export` file.
 
 Some dependencies that are not taken from `opam` or integrated with `dune` must be added manually. Run the `scripts/pin-external-packages.sh` script.
 
@@ -143,9 +153,8 @@ A number of C libraries are expected to be available in the system and are also
 - [Ubuntu Setup Instructions](https://docs.docker.com/install/linux/docker-ce/ubuntu/)
 
 #### Customizing your dev environment for autocomplete/merlin
-[dev-env]: #dev-env
 
-If you use vim, add this snippet in your `.vimrc` file to use Merlin. (Note: Be sure to change the HOME directory to match yours.)
+If you use vim, add this snippet in your `.vimrc` file to use Merlin. (Note:Be sure to change the HOME directory to match yours.)
 
 ```bash
 let s:ocamlmerlin="/Users/USERNAME/.opam/4.14.0/share/merlin"
@@ -162,27 +171,27 @@ let g:syntastic_ocaml_checkers=['merlin']
 
 - If you use emacs, install the `opam` packages mentioned above and also install `tuareg`. Add the following to your `.emacs` file:
 
-```lisp
-(let ((opam-share (ignore-errors (car (process-lines "opam" "var" "share")))))
-  (when (and opam-share (file-directory-p opam-share))
-    ;; Register Merlin
-    (add-to-list 'load-path (expand-file-name "emacs/site-lisp" opam-share))
-    (load "tuareg-site-file")
-    (autoload 'merlin-mode "merlin" nil t nil)
-    ;; Automatically start it in OCaml buffers
-    (add-hook 'tuareg-mode-hook 'merlin-mode t)
-    (add-hook 'caml-mode-hook 'merlin-mode t)))
-```
+    ```lisp
+    (let ((opam-share (ignore-errors (car (process-lines "opam" "var" "share")))))
+      (when (and opam-share (file-directory-p opam-share))
+        ;; Register Merlin
+        (add-to-list 'load-path (expand-file-name "emacs/site-lisp" opam-share))
+        (load "tuareg-site-file")
+        (autoload 'merlin-mode "merlin" nil t nil)
+        ;; Automatically start it in OCaml buffers
+        (add-hook 'tuareg-mode-hook 'merlin-mode t)
+        (add-hook 'caml-mode-hook 'merlin-mode t)))
+    ```
 
-To use the Emacs built-in autocomplete, use `M-x completion-at-point` or `M-tab`. There are other
-Emacs autocompletion packages; see [Emacs from scratch](https://github.com/ocaml/merlin/wiki/emacs-from-scratch).
+    To use the Emacs built-in autocomplete, use `M-x completion-at-point` or `M-tab`. There are other
+    Emacs autocompletion packages; see [Emacs from scratch](https://github.com/ocaml/merlin/wiki/emacs-from-scratch).
 
 - If you use VSCode, set up Merlin to work inside VSCode:
   - Make sure to be in the right switch (mina)
   - Add the [OCaml Platform](https://marketplace.visualstudio.com/items?itemName=ocamllabs.ocaml-platform) extension
   - You might get a prompt to install `ocaml-lsp-server` as well in the Sandbox
   - You might get a prompt to install `ocamlformat-rpc` as well in the Sandbox
-  - Type "shell command: install code command in PATH"
+  - Type "shell command:install code command in PATH"
   - Close all windows and instances of VSCode
   - From terminal, in your mina directory, run `code .`
   - Run `dune build` in the terminal inside VSCode
@@ -192,31 +201,30 @@ Emacs autocompletion packages; see [Emacs from scratch](https://github.com/ocaml
 The source code for the Mina node is located in `src/app/cli/`. After it is compiled, you can run the compiled binary like this:
 
 ```shell
-$ dune exec src/app/cli/src/mina.exe -- daemon --libp2p-keypair /path/to/key
+dune exec src/app/cli/src/mina.exe -- daemon --libp2p-keypair /path/to/key
 ```
 
-
 The results of a successful build appear in `_build/default/src/app/cli/src/mina.exe`.
 
 The default configuration of the node depends on the build profile that is used during compilation. To connect to some networks, you need to compile the daemon with a specific profile.
 
-Some setup is required:
+*Some setup is required*:
 
-1. Generate a key pair so that the daemon can create an account to issue blocks from using the same `mina.exe` binary:
+Generate a key pair so that the daemon can create an account to issue blocks from using the same `mina.exe` binary:
 
-  ```shell
-  $ dune exec src/app/cli/src/mina.exe -- libp2p generate-keypair --privkey-path /path/to/key
-  ```
+```shell
+dune exec src/app/cli/src/mina.exe -- libp2p generate-keypair --privkey-path /path/to/key
+```
 
-When prompted, enter a passphrase. During development, you can leave it blank for convenience, but using a passphrase is strongly encouraged when running a real node! 
+When prompted, enter a passphrase. During development, you can leave it blank for convenience, but using a passphrase is strongly encouraged when running a real node!
 
 The running daemon expects to find this passphrase in
 an environment variable `MINA_LIBP2P_PASS`, which must be defined even if the passphrase is empty.
 The `/path/to/key` must belong to the user running the daemon. Set these filesystem permissions:
 
 ```shell
-$ chmod 0600 /path/to/key
-$ chmod 0700 /path/to
+chmod 0600 /path/to/key
+chmod 0700 /path/to
 ```
 
 Additionally, you must provide a list of peers to connect to bootstrap the node.
@@ -231,27 +239,27 @@ The aforementioned bootstrap data includes the genesis ledger, i.e. the initial
 When all of this setup is complete, you can launch the daemon. The following command assumes the key passphrase is set to `pass`:
 
 ```shell
-$ MINA_LIBP2P_PASS=pass dune exec src/app/cli/src/mina.exe -- daemon --libp2p-keypair /path/to/key --peer-list-url https://example.peer.list --config-file /custom/path/to/daemon.json
+MINA_LIBP2P_PASS=pass dune exec src/app/cli/src/mina.exe -- daemon --libp2p-keypair /path/to/key --peer-list-url https://example.peer.list --config-file /custom/path/to/daemon.json
 ```
 
 The `--seed` flag tells the daemon to run a fresh network of its own. When this flag is used, specifying a peer list is not required, but is still possible. With `--seed` option the node does not crash, even if it does not manage to connect to any peers. To learn more, see the command line help:
 
 ```shell
-$ dune exec src/app/cli/src/mina.exe -- -help
+dune exec src/app/cli/src/mina.exe -- -help
 ```
 
 The command line help is the place to learn about other options to the Mina CLI and how to connect to an existing network, such as Mainnet.
 
 ## Using the Makefile
 
-The Makefile contains placeholder targets for all the common tasks that need to be done and automatically knows how to use Docker. 
+The Makefile contains placeholder targets for all the common tasks that need to be done and automatically knows how to use Docker.
 
 The most important `make` targets are:
 
-- `build`: build everything
-- `libp2p_helper`: build the libp2p helper
-- `reformat`: automatically use `ocamlformat` to reformat the source files (use
-    it if the hook fails during a commit)
+- `build`: build the Mina binary
+- `build_intgtest`: build the [`test_executive`](./src/app/test_executive/README.md#using-lucy) for running integration tests
+- `libp2p_helper`: build the [`libp2p_helper`](./src/app/libp2p_helper/README.md)
+- `reformat`: automatically use `ocamlformat` to reformat the source files (use it if the hook fails during a commit)
 
 We use the [Dune](https://github.com/ocaml/dune/) build system for OCaml code.
 
@@ -262,20 +270,20 @@ OCaml dependencies live in the [`opam.export`](./opam.export) file. This file is
 To add a new dependency, you most likely will need to create a new fresh switch to avoid pushing in any local dependency (like `ocaml-lsp`). The following commands assume that the version of the OCaml compiler used in the codebase is 4.14.0:
 
 ```shell
-$ opam switch create mina_fresh 4.14.0
-$ opam switch import opam.export
+opam switch create mina_fresh 4.14.0
+opam switch import opam.export
 ```
 
 After that, install your dependency. You might have to specify versions of current dependencies to avoid having to upgrade  dependencies. For example:
 
-```console
-$ opam install alcotest cmdliner=1.0.3 fmt=0.8.6
+```sh
+opam install alcotest cmdliner=1.0.3 fmt=0.8.6
 ```
 
 Then, run the following command to update the `ocaml.export` file:
 
-```console
-$ opam switch export opam.export
+```sh
+opam switch export opam.export
 ```
 
 ## Steps for adding a new OCaml pinned dependency