From f366a4080f0db1338f1db2ad37045771c2b73bd9 Mon Sep 17 00:00:00 2001 From: Artur Troian Date: Mon, 7 Nov 2022 09:49:00 -0500 Subject: [PATCH] docs: document dev environment (#1712) refs ovrclk/engineering#361 Signed-off-by: Artur Troian --- .envrc | 40 +++++++++++-- Makefile | 4 +- README.md | 7 +-- _docs/development-environment.md | 98 ++++++++++++++++++++++++++++++++ _docs/img/logo-label-black.svg | 38 +++++++++++++ make/init.mk | 27 +++++---- 6 files changed, 193 insertions(+), 21 deletions(-) create mode 100644 _docs/development-environment.md create mode 100644 _docs/img/logo-label-black.svg diff --git a/.envrc b/.envrc index 3d5d10eb7c..3a257cb1f3 100644 --- a/.envrc +++ b/.envrc @@ -1,10 +1,42 @@ +if ! has make ; then + echo "make is not installed"; exit 1 +fi + +if ! has go ; then + echo "go is not installed"; exit 1 +fi + +if ! has unzip ; then + echo "unzip is not installed"; exit 1 +fi + +if ! has wget ; then + echo "wget is not installed"; exit 1 +fi + +if ! has curl ; then + echo "curl is not installed"; exit 1 +fi + +if ! has npm ; then + echo "npm is not installed"; exit 1 +fi + +if ! has jq ; then + echo "jq is not installed"; exit 1 +fi + +if ! has readlink ; then + echo "readlink is not installed"; exit 1 +fi + export AKASH_ROOT=$(pwd) dotenv -PATH_add $AKASH_DEVCACHE_NODE_BIN -PATH_add $AKASH_DEVCACHE_BIN - -make cache +PATH_add "$AKASH_DEVCACHE_NODE_BIN" +PATH_add "$AKASH_DEVCACHE_BIN" export AKASH=$AKASH_DEVCACHE_BIN/akash + +make cache diff --git a/Makefile b/Makefile index b555f50efa..b890dec7dd 100644 --- a/Makefile +++ b/Makefile @@ -11,7 +11,7 @@ UNAME_ARCH := $(shell uname -m) include make/init.mk -.DEFAULT_GOAL := $(AKASH) +.DEFAULT_GOAL := bins DOCKER_RUN := docker run --rm -v $(shell pwd):/workspace -w /workspace DOCKER_BUF := $(DOCKER_RUN) bufbuild/buf:$(BUF_VERSION) @@ -21,7 +21,7 @@ LINT = $(GOLANGCI_LINT_RUN) ./... --disable-all --deadline=5m TEST_DOCKER_REPO := ovrclk/akashtest -GORELEASER_CONFIG = .goreleaser.yaml +GORELEASER_CONFIG ?= .goreleaser.yaml GIT_HEAD_COMMIT_LONG := $(shell git log -1 --format='%H') GIT_HEAD_COMMIT_SHORT := $(shell git rev-parse --short HEAD) diff --git a/README.md b/README.md index e7c8b6e8ee..88b94c92c0 100644 --- a/README.md +++ b/README.md @@ -82,16 +82,13 @@ Akash is written in Golang and is Apache 2.0 licensed - contributions are welcom To become a contributor, please see the guide on [contributing](CONTRIBUTING.md) ## Development environment +[This doc](https://github.com/ovrclk/akash/blob/master/_docs/development-environment.md) guides through setting up local development environment + Akash is developed and tested with [golang 1.16.0+](https://golang.org/). Building requires a working [golang](https://golang.org/) installation, a properly set `GOPATH`, and `$GOPATH/bin` present in `$PATH`. It is also required to have C/C++ compiler installed (gcc/clang) as there are C dependencies in use (libusb/libhid) Akash build process and examples are heavily tied to Makefile. -Akash also uses [direnv](https://direnv.net) to setup and seamlessly update environment. List of variables exported in root dir are listed in [.env](./.env) -It sets local dir `.cache` to hold all temporary files and tools (except **kind** which installed ) required for development purposes. -It is possible to set custom path to `.cache` with `AKASH_DEVCACHE` environment variable. -All tools are referred as `makefile targets` and set as dependencies thus installed (to `.cache/bin`) only upon necessity. -For example `protoc` installed only when `proto-gen` target called. ## Building from Source Command below will compile akash executable and put it into `.cache/bin` diff --git a/_docs/development-environment.md b/_docs/development-environment.md new file mode 100644 index 0000000000..25b92bb60a --- /dev/null +++ b/_docs/development-environment.md @@ -0,0 +1,98 @@ +# Setting up development environment + +## Install dependencies +### macOS + +> **WARNING**: macOS uses ancient version of the `make`. Akash's environment uses some tricks available in `make 4`. +We recommend use homebrew to installs most up-to-date version of the `make`. Keep in mind `make` is keg-only, and you'll need manually add its location to the `PATH`. +Make sure homebrew's make path takes precedence of `/usr/bin` + + +```shell +brew install curl wget jq direnv coreutils make npm + +# Depending on your shell, it may go to .zshrc, .bashrc etc +export PATH="$(brew --prefix)/opt/make/libexec/gnubin:$PATH" +``` + +### Linux +#### Debian based +**TODO** validate +```shell +sudo apt update +sudo apt install -y jq curl wget build-essentials ca-certificates npm direnv gcc +``` + +## Direnv +Both [akash](https://github.com/ovrclk/akash) [provider-services](https://github.com/ovrclk/provider-services) are extensively using `direnv` to setup and seamlessly update environment +while traversing across various directories. It is especially handy for running `provider-services` examples. + +You may enable auto allow by whitelisting specific directories in `direnv.toml`. +To do so use following template to edit `${XDG_CONFIG_HOME:-$HOME/.config}/direnv/direnv.toml` +```toml +[whitelist] +prefix = [ + "", + "" +] +``` + +## Cache + +Build environment will create `.cache` directory in the root of source-tree. We use it to install specific versions of temporary build tools. Refer to `make/setup-cache.mk` for exact list. +It is possible to set custom path to `.cache` with `AKASH_DEVCACHE` environment variable. + +All tools are referred as `makefile targets` and set as dependencies thus installed (to `.cache/bin`) only upon necessity. +For example `protoc` installed only when `proto-gen` target called. + +The structure of the dir: +```shell +./cache + bin/ # build tools + run/ # work directories for _run examples (provider-services + versions/ # versions of installed build tools (make targets use them to detect change of version of build tool and install new version if changed) +``` + +### Add new tool + +We will use `modevendor` as an example. +All variables must be capital case. + +Following are added to `make/init.mk` +1. Add version variable as `_VERSION ?= ` to the "# ==== Build tools versions ====" section + ```makefile + MODVENDOR_VERSION ?= v0.3.0 + ``` +2. Add variable tracking version file `_VERSION_FILE := $(AKASH_DEVCACHE_VERSIONS)//$()` to the `# ==== Build tools version tracking ====` section + ```makefile + MODVENDOR_VERSION_FILE := $(AKASH_DEVCACHE_VERSIONS)/modvendor/$(MODVENDOR) + ``` +3. Add variable referencing executable to the `# ==== Build tools executables ====` section + ```makefile + MODVENDOR := $(AKASH_DEVCACHE_VERSIONS)/bin/modvendor + ``` + +4. Add installation rules. Following template is used followed by the example + ```makefile + $(_VERSION_FILE): $(AKASH_DEVCACHE) + @echo "installing $(_VERSION) ..." + rm -f $() # remove current binary if exists + # installation procedure depends on distribution type. Check make/setup-cache.mk for various examples + rm -rf "$(dir $@)" # remove current version file if exists + mkdir -p "$(dir $@)" # make new version directory + touch $@ # create new version file + $(): $(_VERSION_FILE) + ``` + + Following are added to `make/setup-cache.mk` + + ```makefile + $(MODVENDOR_VERSION_FILE): $(AKASH_DEVCACHE) + @echo "installing modvendor $(MODVENDOR_VERSION) ..." + rm -f $(MODVENDOR) + GOBIN=$(AKASH_DEVCACHE_BIN) $(GO) install github.com/goware/modvendor@$(MODVENDOR_VERSION) + rm -rf "$(dir $@)" + mkdir -p "$(dir $@)" + touch $@ + $(MODVENDOR): $(MODVENDOR_VERSION_FILE) + ``` diff --git a/_docs/img/logo-label-black.svg b/_docs/img/logo-label-black.svg new file mode 100644 index 0000000000..27a3a1e8d6 --- /dev/null +++ b/_docs/img/logo-label-black.svg @@ -0,0 +1,38 @@ + + + + + +]> + + + + + + + + + + + + + + + + diff --git a/make/init.mk b/make/init.mk index b6c6da4b6a..6718b35ab6 100644 --- a/make/init.mk +++ b/make/init.mk @@ -1,21 +1,26 @@ +ifeq (, $(shell which direnv)) +$(warning "No direnv in $(PATH), consider installing. https://direnv.net") +endif + # AKASH_ROOT may not be set if environment does not support/use direnv # in this case define it manually as well as all required env variables ifndef AKASH_ROOT -AKASH_ROOT := $(abspath $(dir $(lastword $(MAKEFILE_LIST)))/../) -include $(AKASH_ROOT)/.env -endif + AKASH_ROOT := $(abspath $(dir $(lastword $(MAKEFILE_LIST)))/../) + include $(AKASH_ROOT)/.env -AKASH = $(AKASH_DEVCACHE_BIN)/akash + AKASH := $(AKASH_DEVCACHE_BIN)/akash + # setup .cache bins first in paths to have precedence over already installed same tools for system wide use + PATH := "$(AKASH_DEVCACHE_BIN):$(AKASH_DEVCACHE_NODE_BIN):$(PATH)" + +endif BINS := $(AKASH) GO := GO111MODULE=$(GO111MODULE) go - GO_MOD_NAME := $(shell go list -m 2>/dev/null) -# setup .cache bins first in paths to have precedence over already installed same tools for system wide use -PATH := "$(PATH):$(AKASH_DEVCACHE_BIN):$(AKASH_DEVCACHE_NODE_BIN)" - +# ==== Build tools versions ==== +# Format _VERSION BUF_VERSION ?= 0.35.1 PROTOC_VERSION ?= 3.13.0 PROTOC_GEN_GOCOSMOS_VERSION ?= v0.3.1 @@ -28,6 +33,7 @@ GIT_CHGLOG_VERSION ?= v0.15.1 MODVENDOR_VERSION ?= v0.3.0 MOCKERY_VERSION ?= 2.12.1 +# ==== Build tools version tracking ==== # _VERSION_FILE points to the marker file for the installed version. # If _VERSION_FILE is changed, the binary will be re-downloaded. PROTOC_VERSION_FILE := $(AKASH_DEVCACHE_VERSIONS)/protoc/$(PROTOC_VERSION) @@ -39,8 +45,9 @@ GIT_CHGLOG_VERSION_FILE := $(AKASH_DEVCACHE_VERSIONS)/git-chglog/$(GIT_ MOCKERY_VERSION_FILE := $(AKASH_DEVCACHE_VERSIONS)/mockery/v$(MOCKERY_VERSION) GOLANGCI_LINT_VERSION_FILE := $(AKASH_DEVCACHE_VERSIONS)/golangci-lint/$(GOLANGCI_LINT_VERSION) -MODVENDOR = $(AKASH_DEVCACHE_BIN)/modvendor -SWAGGER_COMBINE = $(AKASH_DEVCACHE_NODE_BIN)/swagger-combine +# ==== Build tools executables ==== +MODVENDOR := $(AKASH_DEVCACHE_BIN)/modvendor +SWAGGER_COMBINE := $(AKASH_DEVCACHE_NODE_BIN)/swagger-combine PROTOC_SWAGGER_GEN := $(AKASH_DEVCACHE_BIN)/protoc-swagger-gen PROTOC := $(AKASH_DEVCACHE_BIN)/protoc STATIK := $(AKASH_DEVCACHE_BIN)/statik