- [III. Compiling Proto files](#iii-compiling-proto-files)
- [Examples](#examples)
- [Config File](#config-file)
- [Definition](#definition)
- [Matching patterns and working directory](#matching-patterns-and-working-directory)
- [Multi-config](#multi-config)
- [PostAction](#postaction)
- [1. copy](#1-copy)
- [2. move](#2-move)
- [3. remove](#3-remove)
- [4. replace](#4-replace)
## Features
1. realize one-click installation and multi-version management of protoc.
2. realize one-click installation and multi-version management of protoc related plugins (such as protoc-gen-go).
3. manage the compilation of proto through config file instead of shell script to improve readability and compatibility.
4. bootstrap generation of config files, cross-platform compatibility, a config can be compiled in multiple platforms with one click.
5. support batch and recursive compilation of proto files to improve efficiency.
6. cross-platform support PostAction, you can perform some routine operations (such as replacing "omitempty" in all generated files) after the compilation.
7. support PostShell, execute specific shell scripts after the compilation.
1. The current version of `PowerProto` relies on `go` and `git` (in the future it may use CDN to pull built binaries directly), please make sure the runtime environment contains these two commands.
2.`protoc` download source is Github, `PowerProto` respects `HTTP_PROXY`, `HTTPS_PROXY` environment variables when downloading `protoc`, if you encounter network problems, please configure your own proxy.
3. When querying the version list of `protoc`, `git ls-remote` is used for `github.com`, if you encounter network problems, please configure the proxy for `git` by yourself.
4. In the current version, downloading and querying plugin versions rely on the `go` command, so if you encounter network problems, please configure the `GOPROXY` environment variable yourself.
5. By default, `user directory/.powerproto` is used as the installation directory, which is used to place the downloaded plug-ins and global config.
6. If you think the name `powerproto` is too long, you can `alias` it into a simpler name to improve the input efficiency, for example, no one will mind if you call it `pp`.
### I. Installation via Go
Installation can be performed by executing the following command directly:
```
go install github.com/storyicon/powerproto/cmd/powerproto
```
### II. out-of-the-box version
You can download the out-of-the-box version via the `Github Release Page`.
## Command Introduction
You can view help with `powerproto -h`, e.g.
```
powerproto -h
powerproto init -h
powerproto tidy -h
powerproto build -h
```
It has the advantage that the documentation on the command line is always consistent with your binary version.
### I. Initial Config
The config can be initialized with the following command.
```
powerproto init
```
### II. Tidy Config
The config can be tidied with the following command.
```
powerproto tidy
```
It will search for a config file named `powerproto.yaml` from the current directory to the parent directory, and will read and tidy the config.
You can also specify which config file to tidy.
```
powerproto tidy [the path of proto file]
```
Tidy the config consists of two main operations:
1. replacing the latest in the version with the real latest version number by querying.
2. install all dependencies defined in the config file.
The Proto file can be compiled with the following command.
```
// Compile the specified proto file
powerproto build xxxx.proto
// Compile all the proto files in the current directory
powerproto build .
// Compile all proto files in the current directory recursively, including subfolders.
powerproto build -r .
```
The execution logic is that for each proto file, the `powerproto.yaml` config file will be searched from the directory where the proto file is located to the ancestor directory:
1. For the found config file, match it with the `scope` in it and use it if it matches.
2. Check and install the dependencies declared in the config file.
3. Compile the proto file according to the `plugins`, `protoc`, `options`, `importPaths` and other configs in the config file。 After all the proto files are compiled, if you specify the `-p` argument, `PostAction` and `PostShell` will also be executed.
Note: The default `working directory` of `PowerProto` is the directory where the `proto file` matches to the config file, it is equivalent to the directory where you execute the `protoc` command. You can change it via `protocWorkDir` in the config file.
Supports entering `debug mode` by appending the `-d` argument to see more detailed logs.
Supports entering `dryRun mode` by appending the `-y` argument, in this mode the commands are not actually executed, but just printed out, which is very useful for debugging.
### IV. View environment variables
If your command keeps getting stuck in a certain state, there is a high probability that there is a network problem.
You can check if the environment variables are configured successfully with the following command:
# optional. The operation is executed after compilation.
# its working directory is the directory where the config file is located.
# postActions is cross-platform compatible.
# Note that the "-p" parameter must be appended to the "powerproto build" to allow execution of the postActions in the config file
postActions: []
# optional. The shell script that is executed after compilation.
# its working directory is the directory where the config file is located.
# postShell is not cross-platform compatible.
# Note that the "-p" parameter must be appended to the "powerproto build" to allow execution of the postShell in the config file
postShell: |
// do something
```
#### Matching patterns and working directory
When building the proto file, the `powerproto.yaml` config file will be searched from the directory where the proto file is located to the ancestor directory, match with the `scope` in.
The first matched config item will be used for the compilation of this proto file.
When PowerProto executes protoc (and also when it executes postActions and postShell), the default is to use the directory where the config file is located as the working directory. (working directory is equivalent to the directory where you execute the protoc command.)
#### Multi-config
A config file can be filled with multiple configs, which are separated by "---".
In the example below, the apis1 directory uses protoc-gen-go with v1.25.0, while the apis2 directory uses protoc-gen-go with v1.27.0.
PostAction allows to perform specific actions after all proto files have been compiled. In contrast to `PostShell`, it is cross-platform supported.
For security reasons, the `PostAction` and `PostShell` defined in the config file will only be executed if the `-p` argument is appended to the execution of `powerproto build`.
Currently, PostAction supports the following commands:
