-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
SpecOps CLI w/ template code and instructions for getting started (#21)
* feat: `specopsdev` package and `getting-started` template * refactor: rename `specopsdev.RunCLI()` to `specopscli.Run()` * doc: README for getting started * doc: short section on getting started in root README * doc: remove Go reference in high-level description as it's irrelevant * doc: top-level README re learning Go + include repo cloning in getting-started * doc: clean up "Hello world" example and reference equivalent CLI code * doc: information about first run of CLI * doc: varied
- Loading branch information
1 parent
6bb70ac
commit dccf452
Showing
11 changed files
with
299 additions
and
14 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| # This file can be ignored (and even deleted) when developing in SpecOps. It is | ||
| # a configuration file for a build system called Bazel (https://bazel.build/) | ||
| # that is used for the development of SpecOps itself. | ||
| # | ||
| # Should you happen to know what Bazel is, all `go run getting-started.spec.go` | ||
| # commands in the README can be replaced with `bazel run . --`. | ||
|
|
||
| load("@rules_go//go:def.bzl", "go_binary", "go_library") | ||
|
|
||
| go_library( | ||
| name = "getting-started_lib", | ||
| srcs = ["getting-started.spec.go"], | ||
| importpath = "github.com/solidifylabs/specops/getting-started", | ||
| visibility = ["//visibility:private"], | ||
| deps = [ | ||
| "//:specops", | ||
| "//specopscli", | ||
| "//stack", | ||
| "@com_github_ethereum_go_ethereum//common", | ||
| ], | ||
| ) | ||
|
|
||
| go_binary( | ||
| name = "getting-started", | ||
| embed = [":getting-started_lib"], | ||
| visibility = ["//visibility:public"], | ||
| ) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| # Getting started with SpecOps | ||
|
|
||
| 1. [Install Go](https://go.dev/doc/install) | ||
| 2. Clone the SpecOps repo: | ||
|
|
||
| ```shell | ||
| git clone https://github.com/solidifylabs/specops.git | ||
| ``` | ||
|
|
||
| 3. From the `getting-started` directory: | ||
|
|
||
| ```shell | ||
| go run getting-started.spec.go compile | ||
| ``` | ||
|
|
||
| This will print the compiled EVM bytecode to `stdout`. The first time you run it you may see some logs about fetching dependencies, but from then on it will only output the compiled contract. | ||
|
|
||
| ## Development | ||
|
|
||
| The `getting-started.spec.go` file contains everything you need to be productive. | ||
| If this is your first time using Go, stick between the `START/STOP EDITING HERE` comments and everything will work. | ||
|
|
||
| ### Do I have to learn Go? | ||
|
|
||
| > TL;DR You don't | ||
| SpecOps is a DSL built and run in Go, but designed so that it reads and is written like a standalone language. | ||
| The advantage of piggybacking on the Go toolchain is that we get all of the developer tooling out of the box: syntax highlighting, code completion, etc. | ||
| For more experienced Go developers, there is also support for native testing, interoperability with geth, etc. | ||
|
|
||
| A standalone language inside another? | ||
| In Go, all functions, types, etc. from external packages are *usually* referenced by their package name. | ||
| There is, however, the ability to "dot-import" a package, promoting these symbols such that the package-qualification is unnecessary. | ||
| `specops.Fn` becomes `Fn`, `specops.MSTORE` becomes `MSTORE`, etc. While this goes against the Go style guide, for a DSL it makes sense as it greatly improves developer experience. | ||
|
|
||
| ## Other CLI usage | ||
|
|
||
| ### Commands | ||
|
|
||
| The CLI has `compile`, `exec`, and `debug` commands. The `-h` or `--help` flag | ||
| will provide more information about each (for now, quite limited). | ||
|
|
||
| ### calldata | ||
|
|
||
| Both the `exec` and `debug` commands support the `--calldata` flag, which accepts hex-encoded calldata (*without* the `0x` prefix). For example: | ||
|
|
||
| ```shell | ||
| go run getting-started.spec.go debug --calldata decafc0ffeebad | ||
| ``` | ||
|
|
||
| ### Debugger | ||
|
|
||
| * `<space>` Step to next instruction | ||
| * `<end>` Fast-forward to the end of execution | ||
| * `<Esc>` or `q` Once execution has ended, quit | ||
| * `Ctrl+C` At any time, quit | ||
|
|
||
|  |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| package main | ||
|
|
||
| import ( | ||
| "github.com/ethereum/go-ethereum/common" | ||
|
|
||
| . "github.com/solidifylabs/specops" //lint:ignore ST1001 SpecOps DSL is designed to be dot-imported | ||
| "github.com/solidifylabs/specops/specopscli" | ||
| "github.com/solidifylabs/specops/stack" | ||
| ) | ||
|
|
||
| func code() Code { | ||
| // ---------------------------------------- | ||
| // ========== START EDITING HERE ========== | ||
| // vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv | ||
|
|
||
| hello := []byte("Hello, world!") | ||
|
|
||
| return Code{ | ||
| Fn(MSTORE, PUSH0, PUSH(hello)), | ||
| Fn(RETURN, PUSH(32-len(hello)), PUSH(len(hello))), | ||
| } | ||
|
|
||
| // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
| // ========== STOP EDITING HERE =========== | ||
| // ---------------------------------------- | ||
| } | ||
|
|
||
| func main() { | ||
| specopscli.Run(code()) | ||
| } | ||
|
|
||
| // Stop unused imports being removed. | ||
| var ( | ||
| _ = stack.ExpectDepth(0) | ||
| _ = common.Address{} | ||
| ) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.