github.com/onflow/flow-go@v0.35.7-crescendo-preview.23-atree-inlining/README.md (about)

     1  # Flow [![GoDoc](https://godoc.org/github.com/onflow/flow-go?status.svg)](https://godoc.org/github.com/onflow/flow-go)
     2  
     3  Flow is a fast, secure, and developer-friendly blockchain built to support the next generation of games, apps and the
     4  digital assets that power them. Read more about it [here](https://github.com/onflow/flow).
     5  
     6  <!-- START doctoc generated TOC please keep comment here to allow auto update -->
     7  <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
     8  
     9  ## Table of Contents
    10  
    11  - [Getting started](#getting-started)
    12  - [Documentation](#documentation)
    13  - [Installation](#installation)
    14      - [Clone Repository](#clone-repository)
    15      - [Install Dependencies](#install-dependencies)
    16  - [Development Workflow](#development-workflow)
    17      - [Testing](#testing)
    18      - [Building](#building)
    19      - [Local Network](#local-network)
    20      - [Code Generation](#code-generation)
    21  
    22  <!-- END doctoc generated TOC please keep comment here to allow auto update -->
    23  
    24  ## Getting started
    25  
    26  - To install all dependencies and tools, see the [project setup](#installation) guide
    27  - To dig into more documentation about Flow, see the [documentation](#documentation)
    28  - To learn how to contribute, see the [contributing guide](/CONTRIBUTING.md)
    29  - To see information on developing Flow, see the [development workflow](#development-workflow)
    30  
    31  ## Documentation
    32  
    33  You can find an overview of the Flow architecture on the [documentation website](https://www.onflow.org/primer).
    34  
    35  Development on Flow is divided into work streams. Each work stream has a home directory containing high-level
    36  documentation for the stream, as well as links to documentation for relevant components used by that work stream.
    37  
    38  The following table lists all work streams and links to their home directory and documentation:
    39  
    40  | Work Stream        | Home directory                             |
    41  |--------------------|--------------------------------------------|
    42  | Access Node        | [/cmd/access](/cmd/access)                 |
    43  | Collection Node    | [/cmd/collection](/cmd/collection)         |
    44  | Consensus Node     | [/cmd/consensus](/cmd/consensus)           |
    45  | Execution Node     | [/cmd/execution](/cmd/execution)           |
    46  | Verification Node  | [/cmd/verification](/cmd/verification)     |
    47  | Observer Service   | [/cmd/observer](/cmd/observer)             |
    48  | HotStuff           | [/consensus/hotstuff](/consensus/hotstuff) |
    49  | Storage            | [/storage](/storage)                       |
    50  | Ledger             | [/ledger](/ledger)                         |
    51  | Networking         | [/network](/network/)                      |
    52  | Cryptography       | [/crypto](/crypto)                         |
    53  
    54  ## Installation
    55  
    56  - Clone this repository
    57  - Install [Go](https://golang.org/doc/install) (Flow supports Go 1.18 and later)
    58  - Install [Docker](https://docs.docker.com/get-docker/), which is used for running a local network and integration tests
    59  - Make sure the [`GOPATH`](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable) and `GOBIN` environment variables
    60    are set, and `GOBIN` is added to your path:
    61  
    62      ```bash
    63      export GOPATH=$(go env GOPATH)
    64      export GOBIN=$GOPATH/bin
    65      export PATH=$PATH:$GOBIN
    66      ```
    67  
    68    Add these to your shell profile to persist them for future runs.
    69  - Then, run the following command:
    70  
    71      ```bash
    72      make install-tools
    73      ```
    74  
    75  At this point, you should be ready to build, test, and run Flow! 🎉
    76  
    77  ## Development Workflow
    78  
    79  ### Testing
    80  
    81  Flow has a unit test suite and an integration test suite. Unit tests for a module live within the module they are
    82  testing. Integration tests live in `integration/tests`.
    83  
    84  Run the unit test suite:
    85  
    86  ```bash
    87  make test
    88  ```
    89  
    90  Run the integration test suite:
    91  
    92  ```bash
    93  make integration-test
    94  ```
    95  
    96  ### Building
    97  
    98  The recommended way to build and run Flow for local development is using Docker.
    99  
   100  Build a Docker image for all nodes:
   101  
   102  ```bash
   103  make docker-native-build-flow
   104  ```
   105  
   106  Build a Docker image for a particular node role (replace `$ROLE` with `collection`, `consensus`, etc.):
   107  
   108  ```bash
   109  make docker-native-build-$ROLE
   110  ```
   111  
   112  ### Importing the module
   113  
   114  When importing the `github.com/onflow/flow-go` module in your Go project, testing or building your project may require setting extra Go flags because the module requires [cgo](https://pkg.go.dev/cmd/cgo). In particular, `CGO_ENABLED` must be set to `1` if `cgo` isn't enabled by default. This constraint comes from the underlying cryptography library. Refer to the [crypto repository build](https://github.com/onflow/crypto?tab=readme-ov-file#build) for more details.
   115  
   116  ### Local Network
   117  
   118  A local version of the network can be run for manual testing and integration. See
   119  the [Local Network Guide](/integration/localnet/README.md) for instructions.
   120  
   121  ### Code Generation
   122  
   123  Generated code is kept up to date in the repository, so should be committed whenever it changes.
   124  
   125  Run all code generators:
   126  
   127  ```bash
   128  make generate
   129  ```
   130  
   131  Generate protobuf stubs:
   132  
   133  ```bash
   134  make generate-proto
   135  ```
   136  
   137  Generate OpenAPI schema models:
   138  
   139  ```bash
   140  make generate-openapi
   141  ```
   142  
   143  Generate mocks used for unit tests:
   144  
   145  ```bash
   146  make generate-mocks
   147  ```