add doc for egbuilder

cmd/builder/build/config.go

@@ -95,6 +95,13 @@ func (config *Config) Init() error {
  }
  config.Output = output
  }
+ if strings.HasPrefix(config.Output, ".") {
+ output, err := filepath.Abs(config.Output)
+ if err != nil {
+ return fmt.Errorf("get absolute path of output file %s failed: %v", config.Output, err)
+ }
+ config.Output = output
+ }
 
  // check compile
  if config.Compile.OS == "" {

cmd/builder/build/env.go

@@ -74,6 +74,9 @@ func newEnvironment(ctx context.Context, config *Config) (*environment, error) {
  // specify module replacements before pinning versions
  replaced := make(map[string]string)
  for _, plugin := range config.Plugins {
+ if plugin.Replacement == "" {
+ continue
+ }
  cmd := env.newGoCmdWithModFlags(ctx, "mod", "edit", "-replace", fmt.Sprintf("%s=%s", plugin.Module, plugin.Replacement))
  err := cmd.Run()
  if err != nil {

doc/developer-guide.md

@@ -70,7 +70,7 @@ After modifying the code, run `make fmt` to format the code and `make test` to r
 
 # Extending Easegress
 
-Let's suppose that you have a requirement or a feature enhancement in your mind. The most common way to extend Easegress is to develop a new Object or Filter.
+Let's suppose that you have a requirement or a feature enhancement in your mind. The most common way to extend Easegress is to develop a new Object or Filter. [egbuilder](./egbuilder.md) provides tools to quickly create, build, and run Easegress with custom plugins.
 
 ## Developing an Object
 

doc/egbuilder.md

@@ -0,0 +1,139 @@
+# egbuilder
+`egbuilder` is a command-line tool that enables you to create, build, and run Easegress with custom plugins.
+
+## Init a custom plugin project
+The `egbuilder init` command helps initialize a custom plugin project, creating the necessary directories and files for users to get started.
+
+```
+egbuilder init --repo github.com/your/repo \
+ --filters=MyFilter1,MyFilter2 \
+ --controllers=MyController1,MyController2
+```
+
+The example above will create following directories and files.
+```
+.
+├── .egbuilderrc
+├── controllers
+│ ├── mycontroller1
+│ │ └── mycontroller1.go
+│ └── mycontroller2
+│ └── mycontroller2.go
+├── filters
+│ ├── myfilter1
+│ │ └── myfilter1.go
+│ └── myfilter2
+│ └── myfilter2.go
+├── go.mod
+├── go.sum
+└── registry
+ └── registry.go
+```
+The `.egbuilderrc` file is a configuration file that can be used by the `egbuilder add` and `egbuilder run` commands. The `registry/registry.go` file contains code generated to register custom filters and controllers with Easegress. The `controllers` and `filters` directories contain the necessary variables, structures, and methods to get started.
+
+## Add more plugins
+The `egbuilder add` command allows you to add more custom filters and controllers to an existing custom plugin project.
+
+```
+egbuilder add --filters=MyFilter3,MyFilter4 \ 
+ --controllers=MyController3,MyController4
+```
+
+The above example will add following directories and files.
+```
+.
+├── controllers
+ ...
+│ ├── mycontroller3
+│ │ └── mycontroller3.go
+│ └── mycontroller4
+│ └── mycontroller4.go
+├── filters
+ ...
+│ ├── myfilter3
+│ │ └── myfilter3.go
+│ └── myfilter4
+│ └── myfilter4.go
+...
+```
+The `.egbuilderrc` and `registry/registry.go` files will be updated based on changes.
+
+## Build Easegress with custom plugins
+The `egbuilder build` command is used to compile Easegress with custom plugins.
+
+```
+egbuilder build -f build.yaml
+```
+where `build.yaml` contains:
+```yaml
+# egVersion: the version of Easegress used for building. Supports versions v2.5.2 and later.
+# An empty egVersion value means using the latest version of Easegress.
+egVersion: v2.5.2
+
+# plugins: custom plugins.
+# It is recommended to use plugins created with "egbuilder init".
+# Generally, any plugin containing "registry/registry.go" can utilize the "egbuilder build" command.
+# You can initialize a project to see for yourself.
+plugins:
+- module: github.com/your/repo
+ version: ""
+ replacement: "."
+- module: github.com/other/repo
+
+# output: path of output file.
+output: "./easegress-server"
+
+# raceDetector: "-race" flag for go build
+raceDetector: false
+
+# skipBuild: if true, not build, just generate temp directory and files. 
+# still clean up if skipCleanUp is false. 
+skipBuild: false
+
+# skipCleanup: if true, not clean up the temp directory.
+skipCleanup: false
+
+# buildFlags: flags for "go build" command
+buildFlags: []
+
+# modFlags: flags for "go mod" command
+modFlags: []
+
+# compile: GOOS, GOARCH, GOARM env variable for "go build"
+compile:
+ os: ""
+ arch: ""
+ arm: ""
+ cgo: false
+```
+
+## Run Easegress in current directory
+The `egbuilder run` command is used to run Easegress with custom plugins in current working directory.
+
+```
+egbuilder run // run with default
+egbuilder run -f run.yaml // run with config
+```
+where `run.yaml` contains:
+
+```yaml
+egVersion: v2.5.2
+
+# egServerArgs: args for easegress-server
+# egServerArgs: ["--config-file", "easegress-server.yaml"] means
+# ./easegress-server --config-file easegress-server.yaml
+egServerArgs: []
+
+raceDetector: false
+skipBuild: false
+skipCleanup: false
+buildFlags: []
+modFlags: []
+compile:
+ os: ""
+ arch: ""
+ arm: ""
+ cgo: false
+```
+
+So, `egbuilder run` can be seen as executing `egbuilder build` first, followed by running `./easegress-server`.