Better getting started docs

[celer]

Hi,

I wanted to try gopium out on a repo I've been trying to optimize, but just getting started with it is a little confusing. Here is what I found confusing:

• What is a walker?
• What is a strategy?
• What do the struct tags do?
• When I took the example in the cmdline output 'gopium -r ^A json_std 1pkg/gopium filter_pads memory_pack separate_padding_cpu_l1_top separate_padding_cpu_l1_bottom' and tried to modify it to work on my package, I got 'can't build such walker "json_std" walker "json_std" wasn't found' - but it's unclear what a walker is so I'm not sure if this is something I provide or an issue with gopium

Essentially I'm asking for getting started docs that are aimed at someone who knows nothing about gopium.

Thanks,

I'm excited to try gopium, but need some more help getting started.

[1pkg]

Yeah, you highlighted fair points - gopium definitely lacks some beginner documentation. There is doc at https://github.com/1pkg/gopium/blob/master/cmd/gopium/README.MD which describes CLI part a bit better, but i guess it should be better access to this info in root README too. So I will copy/rework some data from there to root README.

On json_std, initially there were *_std walker pair for any walker from there https://github.com/1pkg/gopium/blob/master/cmd/gopium/README.MD#walkers-and-formatters, but i decided to remove them eventually to not overcomplicate the walkers list, and forgot to update example.

[1pkg]

Hey, i added some better examples to https://github.com/1pkg/gopium#requirements-installation-and-usage section and small intro to tags at https://github.com/1pkg/gopium#requirements-installation-and-usage. Please check it out and give me some feedback if something is still missing or awkward.

[bonedaddy]

Figured I'd comment here instead of open an issue as its related to getting started. The instructions for downloading and updating do not work:

<~>-> go get -u github.com/1pkg/gopium/cmd/gopium
# cd /home/solidity/go/src/github.com/1pkg/gopium; git submodule update --init --recursive
fatal: remote error: upload-pack: not our ref 5cf47dad5143b9c1a7802ba744a49936ddd08f6b
fatal: the remote end hung up unexpectedly
Fetched in submodule path 'cmd/vscode/src/vscode-go', but it did not contain 5cf47dad5143b9c1a7802ba744a49936ddd08f6b. Direct fetching of that commit failed.
package github.com/1pkg/gopium/cmd/gopium: exit status 1
<~>-1-> 

[1pkg]

@bonedaddy thank you for pointing, it's really weird one ...

So what is happening: initially I vendored vscode-go as git submodule to simplify development, then i created github release for v1.0.0 which created tag internally on gopium but not on submodule 😄. Now to the problem, it seems that -u flag for go get does not only pull last tagged commit on requested module/repo but also pulls latest tag on submodules too ... and lates tag on vscode-go is 0.14.2. So git is going crazy as it can't pull v1.0.0 consistently on all dependencies so go get is failing. Cool story!

I will create a separate issue for that, meanwhile just plain go get github.com/1pkg/gopium/cmd/gopium works as expected so I update doc to reflect that we should use just go get github.com/1pkg/gopium/cmd/gopium until I will figure out how to fix this submodule madness.

[1pkg]

go get -u issue was fixed in #8

[celer]

Thanks! this is a lot better, I did get it to run, still not sure I'm getting the results I should.

If you were really motivated you'd take a small go package and then do a screen recording of you using the tool to optimize it, assuming your audience knows nothing of gopium.

I realize this is a big ask, it really depends upon how much you want to evangelize your project. I'm terrible at evangelizing my open source work, and life usually gets in the way.

I think you've created an interesting tool, which has a high learning curve because of the complexity of the various optimization options that are available.

Thanks!