Running protoc-gen-doc on Mac after Go-Compilation

[ghost]

Hi all,

I am having a mac and just compiled the proto-gen-doc locally. The Go-Compiler generates a compile inside my workspace within the bin-directory. This compile is named "main" - just as the "main.go"-file used to start compilation. The bin-directory is included in my $PATH environmental variable.

Protoc Compiler is fetched via brew and running successful, until I do not include any protoc-gen-doc-related options. As soon, as I include --doc_out in my call, I get an error from protoc.

Here is - step-by-step - what I did:

1. Starting Terminal

2. Via Terminal, go to examples-folder in protoc-gen-doc-folder from GitHub.

3. Generate a new folder "py_out" for the Python-compiled examples from you.

4. Calling: protoc -I=./proto/ --python_out=./py_out/ ./proto/Booking.proto

5. This works. protoc puts "Booking_pb2.py" to the py_out-folder.

6. Explicitly adding the bin-path of the compiled protoc-gen-doc to the $PATH variable of my system:

export PATH=$PATH:/Users/[MYNAME]/go/bin/

7. Explicitly checking, if the path is set:

   [MYNAME]-MacBook-Pro:examples [MYNAME]$ echo $PATH
   /usr/local/bin:/Library/Frameworks/Python.framework/Versions/3.4/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Library/TeX/texbin:/Users/[MYNAME]/go/bin/

8. Calling:

   [MYNAME]s-MacBook-Pro:examples [MYNAME]$ protoc --doc_out=./doc --doc_opt=html -I=./proto/ --python_out=./py_out/ ./proto/Booking.proto
   protoc-gen-doc: program not found or is not executable
   --doc_out: protoc-gen-doc: Plugin failed with status code 1.

   10. THIS DOES NOT WORK!

9. Calling (maybe, the clear call for the plugin is needed):

   Timms-MacBook-Pro:examples [MYNAME]$ protoc --plugin=protoc-gen-doc --doc_out=./doc --doc_opt=html -I=./proto/ --python_out=./py_out/ ./proto/Booking.proto
   protoc-gen-doc: program not found or is not executable

   12. THIS DOES NOT WORK!

10. Calling (maybe I need to directly name the main, instead of the protoc-gen-doc plugin name):

    [MYNAME]-MacBook-Pro:examples [MYNAME]$ protoc --plugin=main --doc_out=./doc --doc_opt=html -I=./proto/ --python_out=./py_out/ ./proto/Booking.proto
    protoc-gen-doc: program not found or is not executable
    --doc_out: protoc-gen-doc: Plugin failed with status code 1.

    14. THIS DOES NOT WORK!

Can you please help me, running the protoc-gen-doc on my Mac?

Thanks

[ghost]

protobuf_example.zip I add a simple example to illustrate what I mean ... Maybe its easier to understand my issue. Please look into run.sh to see my command line

Even I got it running now with a brew install, I am still struggling to get a proper documentation.

[pseudomuto]

Hey @TimmKayserHere!

I'm going to assume that when you clone this repo and run make build you get a new file (./protoc-gen-doc) created for you (if not, let me know, that's a problem).

At this point, the binary is not "installed" on your system but is compiled and ready to be run. You have two choices at this point:

Option 1

You can move the binary somewhere on your $PATH, like $GOPATH/bin, or /usr/local/bin since you've got brew.

The you should be able to run it with: protoc -Iproto --doc_out=doc --doc_opt=html --python_out=py_out proto/Booking.proto

Option 2

You can also specify which binary to use for a particular plugin. If you wanted to run protoc but not move the locally built binary, you can do this:

protoc --plugin=protoc-gen-doc=<PATH_TO_BIN> \
  -Iproto --doc_out=doc --doc_opt=html --python_out=py_out proto/Booking.proto

Please give one (or both) of these a try and let me know if you're still having issues.

[ghost]

Hi Stuart!

I essentially have two issues: #1 I do not get protoc-gen-doc compiled on my may. and #2 I cannot generate a documentation if I have packages defined in a proto-file.

I will now walk you through all my steps:

# Here are the steps related to #1 (getting protoc-gen-doc running on my Mac)

(1) I install the go-language support via brew. Therefore I do the following in the Terminal:

brew update
brew install gaoling
go version

This confirms the following:

go version go1.10 darwin/amd64

(2) Now I define some environmental variables on my system to tell GO where to put files

export GOPATH=$HOME/go
export GOROOT=/usr/local/opt/go/libexec
export PATH=$PATH:$GOPATH/bin
export PATH=$PATH:$GOROOT/bin
export GOBIN=$PATH:$GOROOT/bin
mkdir -p $GOPATH $GOPATH/src $GOPATH/pkg $GOPATH/bin

(3) Now I go get your code on my machine inside the src-folder just generated by the mkdir command above.

go get -u github.com/pseudomuto/protoc-gen-doc

(4) Now I browse to your GitHub folder structure as shown below. There I find the file main.go which is the main to compile.

src
- github.com
-- pseudomuto
--- protoc-gen-doc
---- cmd
----- protoc-gen-doc

(5) Now I run GO by typing the following in the console:

go build -buildmode=plugin main.go

The output is as follow:

# command-line-arguments
./main.go:26:14: undefined: ParseFlags
./main.go:36:21: undefined: Flags

Same happens, if I do not go for a plugin mode my typing:

go build main.go

Okay, I understand: The Plugin wants some arguments. But, how do I compile the plugin in GO without handing over some (fake?) arguments to just compile it? (I never worked with GO before.)

However, I tried to follow your comment by calling the makefile. Therefore, I do the following:

(6.1) I browse the GitHub folder structure just cloned on my Mac and go to:

src
- github.com
-- pseudomuto
--- protoc-gen-doc

Here I do have a Makefile checked out from your repository.

(6.2) From here I call:

make build

The output is:

Synching dev tools and dependencies...
make: retool: No such file or directory
make: *** [setup] Error 1

Interestingly, by calling the Makefile, other Github repositories have been checked out. These are:

src
- github.com
-- **MichaelTJones**
-- pseudomuto
-- **twitchtv**
-- **uudashr**

The retool error is somehow strange, as inside the twitchtv folder, there is a folder called retool which you requested.

## Here is the mitigation strategy for #1 - I do not build protoc-gen-doc on my own, but use a brew-based compile:

(1) I run the brew install command:

brew install protoc-gen-doc

The Mac Terminal tells me, that is is version 0.8 being installed (already installed, as I did that before I write these lines):

Warning: ebenoist/protoc-gen-doc/protoc-gen-doc 0.8 is already installed

But anyway, I do have protoc-gen-doc at least installed.

Now, I want to run through my example files (provided in the zip-file attached to the previous post) using the brew install version. This is #2

(1) I move to the folder protobuf_handling in my zip-file. There I do have a shell script, that will go through all the three proto-files (base.proto, special.proto, message.proto).

(2) I first compile the proto-files to generate Python files. This works for all the files by the following code:

echo Compile "base.proto"
protoc -I=./src/ --python_out=../protobuf_handling/protobuf_out/ ./src/project/protobuf/types/base.proto

echo Compile "special.proto"
protoc -I=./src/ --python_out=../protobuf_handling/protobuf_out/ ./src/project/protobuf/types/special.proto

echo Compile "message.proto"
protoc -I=./src/ --python_out=../protobuf_handling/protobuf_out/ ./src/project/protobuf/messages/message.proto

This works just fine.

(3) I now want to generate the documentation for the proto-files by calling protoc again, but without telling it to generate Python source, but generate the documentation by the following code:

echo Generate documentation for "base.proto"
protoc -I=./src/ --doc_out=./doc/ --doc_opt=html,base.html ./src/project/protobuf/types/base.proto

echo Generate documentation for "special.proto"
protoc -I=./src/ --doc_out=./doc/ --doc_opt=html,special.html ./src/project/protobuf/types/special.proto

echo Generate documentation for "message.proto"
protoc -I=./src/ --doc_out=./doc/ --doc_opt=html,message.html ./src/project/protobuf/types/message.proto

Interestingly, the base.proto is importing only Google proto-files and compiles just fine. special.proto and message.proto are referencing base.proto or special.proto. And this referencing makes the documentation generation to raise some errors, which might refer to a failure in importing the references.

Generate documentation for base.proto
--doc_out: project/protobuf/types/base.proto: project/protobuf/types/base.proto: No such file or directory
Generate documentation for special.proto
--doc_out: project/protobuf/types/special.proto: project/protobuf/types/special.proto: No such file or directory
Generate documentation for message.proto
./src/project/protobuf/types/message.proto: No such file or directory

This is the second issue I have with the protoc-gen-doc now.

Can you please help me resolving these two issues (#1 and #2)?

Thanks, Timm

[StefanWerder]

Hi Timm,

so I setup the project on a Linux based machine, but it should work alike on a Mac.

Problem 1:

I used another command to compile the code. I saw it in some recent commit ;)

cd ~/go/src/github.com/pseudomuto/protoc-gen-doc
go install ./cmd/...

This generates the executable go/bin/protoc-gen-doc.

Problem 2:

I copied the example files to ~/go/bin and therein they are at project/protobuf/types/base.proto and project/protobuf/types/special.proto.

Running e.g.

./protobuf/bin/protoc --plugin=./protoc-gen-doc --doc_out=./doc --doc_opt=templates/html.tmpl,project.html project/protobuf/types/base.proto project/protobuf/types/special.proto

with the protobuf 3.4 executable in ~/go/bin/protobuf/bin/protoc and the output folder set to ~/go/bin/doc I get a HTML file containing content from both files. Important is that you give both files in one call to the generator plugin, otherwise it cannot solve the dependencies.

project.html.zip

I hope this helps solving your problems.

Thanks again @pseudomuto for making this awesome and outstanding project!