Development Guide for Mac and Windows (#121)

Development Guide for beginners.
Edgenesis · Jun 10, 2022 · cb1b060 · cb1b060
1 parent 41628c6
commit cb1b060
Show file tree

Hide file tree

Showing 11 changed files with 488 additions and 4 deletions.
diff --git a/docs/guide/development/build-shifu-zh.md b/docs/guide/development/build-shifu-zh.md
@@ -0,0 +1,53 @@
+# 构建 ***Shifu*** 组件:
+## 需求:
+根据我们 [Windows](develop-on-windows-zh.md)/[Mac OS](develop-on-mac-zh.md) 的配置指南来搭建本地环境。
+
+## 概览:
+我们提供了一个 `Docker` 开发镜像环境来简化配置步骤以及在不同平台提供一个一致的环境。
+
+## 构建
+### 1. 直接构建 ***deviceShifu*** 二进制文件:
+导航到 `Shifu` 的根目录, 使用以下命令来构建不同的 ***deviceShifu***:
+
+`HTTP 转 HTTP` ***deviceShifu***:
+```sh
+CGO_ENABLED=0 GOOS=$(go env GOOS) GOARCH=$(go env GOARCH) go build -a -o /output/deviceshifu-http-http deviceshifu/cmd/main.go
+```
+`HTTP 转 Socket` ***deviceShifu***:
+```sh
+CGO_ENABLED=0 GOOS=$(go env GOOS) GOARCH=$(go env GOARCH) go build -a -o /output/deviceshifu-http-socket deviceshifu/cmd/cmdSocket/main.go
+```
+`HTTP 转 MQTT` ***deviceShifu***:
+```sh
+CGO_ENABLED=0 GOOS=$(go env GOOS) GOARCH=$(go env GOARCH) go build -a -o /output/deviceshifu-http-mqtt deviceshifu/cmd/cmdMQTT/main.go
+```
+`HTTP 转 OPC UA` ***deviceShifu***:
+```sh
+CGO_ENABLED=0 GOOS=$(go env GOOS) GOARCH=$(go env GOARCH) go build -a -o /output/deviceshifu-http-opcua deviceshifu/cmd/cmdOPCUA/main.go
+```
+
+### 2. 构建 ***deviceShifu*** `Docker` 镜像:
+运行下面命令来构建以下不同的 ***deviceShifu*** 镜像, 标记为当前版本并载入到 `Docker` 镜像:
+```sh
+make buildx-load-image-deviceshifu
+```
+
+构建的镜像:
+```
+edgenesis/deviceshifu-http-http:{VERSION}
+edgenesis/deviceshifu-http-socket:{VERSION}
+edgenesis/deviceshifu-http-mqtt:{VERSION}
+edgenesis/deviceshifu-http-opcua:{VERSION}
+```
+
+### 3. 直接构建 ***shifuController*** 的二进制文件:
+导航到 `shifu/k8s/crd` 目录下, 用下面的命令来构建  ***shifuController*** 二进制文件:
+```sh
+make build
+```
+
+### 4. 构建 ***shifuController*** `Docker` 镜像:
+运行下面命令来构建 ***shifuController*** 镜像, 标记为当前版本并载入到 `Docker` images:
+```sh
+make docker-buildx-load IMG=edgehub/edgedevice-controller-multi:v0.0.1
+```
diff --git a/docs/guide/development/build-shifu.md b/docs/guide/development/build-shifu.md
@@ -0,0 +1,53 @@
+# Building ***Shifu*** components:
+## Requirement:
+Finish setting up using the setup guide: [Windows](develop-on-windows.md)/[Mac OS](develop-on-mac.md)
+
+## Overview:
+We have provided a `Docker` Dev Container environment that simplifies setup and provides consistent environment across all platforms.
+
+## Building
+### 1. Build ***deviceShifu*** binaries directly:
+Navigate to `Shifu`'s root directory, use the following commands to build different ***deviceShifu***:
+
+For `HTTP to HTTP` ***deviceShifu***:
+```sh
+CGO_ENABLED=0 GOOS=$(go env GOOS) GOARCH=$(go env GOARCH) go build -a -o /output/deviceshifu-http-http deviceshifu/cmd/main.go
+```
+For `HTTP to Socket` ***deviceShifu***:
+```sh
+CGO_ENABLED=0 GOOS=$(go env GOOS) GOARCH=$(go env GOARCH) go build -a -o /output/deviceshifu-http-socket deviceshifu/cmd/cmdSocket/main.go
+```
+For `HTTP to MQTT` ***deviceShifu***:
+```sh
+CGO_ENABLED=0 GOOS=$(go env GOOS) GOARCH=$(go env GOARCH) go build -a -o /output/deviceshifu-http-mqtt deviceshifu/cmd/cmdMQTT/main.go
+```
+For `HTTP to OPC UA` ***deviceShifu***:
+```sh
+CGO_ENABLED=0 GOOS=$(go env GOOS) GOARCH=$(go env GOARCH) go build -a -o /output/deviceshifu-http-opcua deviceshifu/cmd/cmdOPCUA/main.go
+```
+
+### 2. Build ***deviceShifu*** `Docker` images:
+Run the following command, this will build the following ***deviceShifu*** images with current tag and load it into `Docker` images:
+```sh
+make buildx-load-image-deviceshifu
+```
+
+Images built:
+```
+edgenesis/deviceshifu-http-http:{VERSION}
+edgenesis/deviceshifu-http-socket:{VERSION}
+edgenesis/deviceshifu-http-mqtt:{VERSION}
+edgenesis/deviceshifu-http-opcua:{VERSION}
+```
+
+### 3. Build ***shifuController*** binary directly:
+Navigate to `shifu/k8s/crd`, use the following command to build ***shifuController*** binary:
+```sh
+make build
+```
+
+### 4. Build ***shifuController*** `Docker` image:
+Run the following command, this will build the following ***shifuController*** image with current tag and load it into `Docker` images:
+```sh
+make docker-buildx-load IMG=edgehub/edgedevice-controller-multi:v0.0.1
+```
diff --git a/docs/guide/development/develop-on-mac-zh.md b/docs/guide/development/develop-on-mac-zh.md
@@ -0,0 +1,98 @@
+# 配置指南:
+
+开发者你好！ 本份指南会帮助你在本地搭建适用于 `Mac OS` 的 `Shifu` 开发环境。
+
+### 本指南的在以下平台中测试过:
+```
+MacBook Pro (14-inch, 2021)
+```
+
+如您在使用本指南中有任何的问题以及发现了任何错误请毫不犹豫的在GitHub中建立一个 [issue]
+
+# 步骤:
+## 1. 搭建环境
+
+### 1.1 安装 `homebrew`
+
+从 [brew.sh](https://brew.sh/), 用以下命令安装 ```homebrew```: 
+```
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+***(可选)*** 如果需要在命令行使用代理的话请用:
+```
+export http_proxy='http://[proxyServerAddr]:[port]'
+export https_proxy='http://[proxyServerAddr]:[port]'
+export ALL_PROXY='http://[proxyServerAddr]:[port]'
+```
+
+### 1.2 在本地克隆 ***Shifu*** 项目:
+使用以下命令克隆 ***Shifu***:
+```sh
+git clone https://github.com/Edgenesis/shifu.git
+```
+
+### 1.3 安装 `Docker`:
+从 Docker 官方的 [安装指南](https://docs.docker.com/desktop/mac/install/) 中安装 Docker。
+
+### 1.4 安装 `Visual Studio Code` (可选, 但是*强烈推荐*)
+
+[下载](https://code.visualstudio.com/download) dmg 并安装。
+
+按章完成后，使用 "File --> Open Folder" 来打开 ***Shifu*** 目录:
+
+![Open folder](img/develop-vscode-1.png)
+
+屏幕右下角会自动有一个弹窗来从 remote container 中打开项目:
+
+![Remote container prompt](img/develop-vscode-2.png)
+
+点击之后，VSCode会将项目挂载到容器中并打开。开发环境至此搭建完毕！
+
+
+***提示***: 如果您使用 `Visual Studio Code` 的 `Dev Container`, 您可以跳过下面所有的环境部署步骤。
+
+### 1.5 下载并安装 `Go`
+根据您的 Mac 的 CPU 架构，请在下面两个中选择一个安装包下载:
+
+运行 英特尔(amd64) 的 Mac:
+```
+https://go.dev/dl/go1.17.10.darwin-amd64.pkg
+```
+运行 M1(arm64) 的 Mac:
+```
+https://go.dev/dl/go1.17.10.darwin-arm64.pkg
+```
+
+### 1.6 安装 `kind`
+从 [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) 官网, 通过下面的命令安装:
+```sh
+brew install kind
+```
+
+### 1.7 安装 `kubectl`
+从 [kubernetes](https://kubernetes.io/docs/tasks/tools/install-kubectl-macos/) 官网, 通过下面的命令安装:
+```sh
+brew install kubectl
+```
+
+### 1.8 安装 `kubebuilder`
+从 [kubebuilder](https://book.kubebuilder.io/quick-start.html) 官网, 通过下面的命令安装:
+```sh
+curl -L -o kubebuilder https://go.kubebuilder.io/dl/latest/$(go env GOOS)/$(go env GOARCH)
+chmod +x kubebuilder && mv kubebuilder /usr/local/bin/
+
+```
+
+### 1.9 安装 `Go` 依赖
+切换到 `shifu` 的目录, 执行:
+```sh
+GO111MODULE=on go mod download
+```
+***(可选)*** 如果您在下载依赖过程中遇到问题, 通过下面命令来添加一个代理:
+```sh
+GOPROXY=https://goproxy.cn,direct GO111MODULE=on go mod download
+```
+
+# 接下来?
+跟着我们的 [创建指南](build-shifu-zh.md) 来搭建 `Shifu`
diff --git a/docs/guide/development/develop-on-mac.md b/docs/guide/development/develop-on-mac.md
@@ -1,15 +1,97 @@
-# Setting up the environment
+# Setup Guide:
 
-## Install homebrew
+Welcome developers! This guide will help you on setting up development environment for `Shifu` on `Mac OS`
+
+### This guide has been tested on the following platform:
+```
+MacBook Pro (14-inch, 2021)
+```
+
+Please submit an [issue] to GitHub if you are having issue following this guide/you have noticed anything wrong with this guide
+
+# Steps:
+## 1. Setting up the environment
+
+### 1.1 Install `homebrew`
 
 From [brew.sh](https://brew.sh/), install ```homebrew``` with the following command: 
 ```
 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
 ```
 
-### (Optional) If you need to proxy connections from your terminal:
+***(Optional)*** If you need to proxy connections from your terminal:
 ```
 export http_proxy='http://[proxyServerAddr]:[port]'
 export https_proxy='http://[proxyServerAddr]:[port]'
 export ALL_PROXY='http://[proxyServerAddr]:[port]'
-```
+```
+
+### 1.2 Clone ***Shifu*** repository:
+Use the following command to clone ***Shifu***:
+```sh
+git clone https://github.com/Edgenesis/shifu.git
+```
+
+### 1.3 Install `Docker`:
+Follow the official [installation guide](https://docs.docker.com/desktop/mac/install/) from Docker official website.
+
+### 1.4 Install `Visual Studio Code` (Optional, but *highly recommended*)
+
+[Download](https://code.visualstudio.com/download) the installation dmg and install.
+
+After installation, use "File --> Open Folder" to open ***Shifu*** directory:
+
+![Open folder](img/develop-vscode-1.png)
+
+A prompt should show up automatically to open this project in remote container:
+
+![Remote container prompt](img/develop-vscode-2.png)
+
+Click on that, VSCode should open your project in remote container. Your development environment is ready!
+
+***Note***: If you use `Visual Studio Code` with `Dev Container` you can skip all below environment setup steps.
+
+### 1.5 Download and install `Go`
+Depending on your Mac's CPU architecture, you can download one of the following packagaes:
+
+For Intel(amd64) Macs:
+```
+https://go.dev/dl/go1.17.10.darwin-amd64.pkg
+```
+For M1(arm64) Macs:
+```
+https://go.dev/dl/go1.17.10.darwin-arm64.pkg
+```
+
+### 1.6 Install `kind`
+from [kind](https://kind.sigs.k8s.io/docs/user/quick-start/), install with:
+```sh
+brew install kind
+```
+
+### 1.7 Install `kubectl`
+from [kubernetes](https://kubernetes.io/docs/tasks/tools/install-kubectl-macos/), install with:
+```sh
+brew install kubectl
+```
+
+### 1.8 Install `kubebuilder`
+from [kubebuilder](https://book.kubebuilder.io/quick-start.html), install with:
+```sh
+curl -L -o kubebuilder https://go.kubebuilder.io/dl/latest/$(go env GOOS)/$(go env GOARCH)
+chmod +x kubebuilder && mv kubebuilder /usr/local/bin/
+
+```
+
+### 1.9 Install `Go` dependencies
+Navigate to `shifu`'s directory, issue:
+```sh
+GO111MODULE=on go mod download
+```
+***(Optional)*** If you are having issue download dependencies, add a proxy by using:
+```sh
+GOPROXY=https://goproxy.cn,direct GO111MODULE=on go mod download
+```
+
+# What's next?
+Follow our [build guide](build-shifu.md) and start building `Shifu`