neo-go/pkg/vm/compiler/README.md

# NEO-GO Compiler

The neo-go compiler compiles Go programs to bytecode that the NEO virtual machine can understand.

> The neo-go compiler is under very active development and will be updated on a weekly basis.

## Usage

```
./bin/neo-go contract compile -i mycontract.go --out /Users/foo/bar/contract.avm
```

## Currently supported

### Go internals 
- type checker
- multiple assigns
- types int, string and booleans
- struct types + method receives
- functions
- composite literals `[]int, []string`
- basic if statements
- binary expressions.
- return statements
- imports 

### VM API (interop layer)
- storage

## Not yet implemented
- for loops
- ranges
- builtins (append, len, ..)
- large part of the interop layer (VM API)

## Not supported
Due to the limitations of the NEO virtual machine, features listed below will not be supported.
- channels 
- goroutines
- multiple returns 

## How to report compiler bugs 
1. Make a proper testcase (example testcases can be found in the tests folder)
2. Create an issue on Github 
3. Make a PR with a reference to the created issue, containing the testcase that proves the bug
4. Either you fix the bug yourself or wait for patch that solves the problem

## Quick start

### Compile a smart contract

```
./bin/neo-go contract compile mycontract.go
```

By default the filename will be the name of your .go file with the .avm extension, the file will be located in the same directory where you called the command from. If you want another location for your compiled contract:

```
./bin/neo-go contract compile mycontract.go --out /Users/foo/bar/contract.avm
```

### Debugging your smart contract
You can dump the opcodes generated by the compiler with the following command:

```
./bin/neo-go contract opdump mycontract.go
```

This will result in something like this:

```
INDEX    OPCODE    DESC
0        0x52      OpPush2
1        0xc5      OpNewArray
2        0x6b      OpToAltStack
3        0x 0      OpPush0
4        0x6c      OpFromAltStack
5        0x76      OpDup
6        0x6b      OpToAltStack
7        0x 0      OpPush0
8        0x52      OpPush2
9        0x7a      OpRoll
10       0xc4      OpSetItem
```
Update compiler (#22) * refactor to use ast.Walk for recursive converting * added lots of test cases * added a new way to handle jump labels * function calls with multiple arguments * binary expression (LOR LAND) * struct types + method receives * cleaner opcode dumps, side by side diff for debugging test cases 2018-02-19 09:24:28 +00:00			`# NEO-GO Compiler`

			`The neo-go compiler compiles Go programs to bytecode that the NEO virtual machine can understand.`

			`> The neo-go compiler is under very active development and will be updated on a weekly basis.`

Better error messages (#24) * Print proper error messages while using contract subcommands and also exit with status code 1. * Make -in a flag, also remove dot from avm extension. * Work on feedback by Anthony. * Update README and VERSION 2018-02-24 09:10:45 +00:00			`## Usage`

			```
			`./bin/neo-go contract compile -i mycontract.go --out /Users/foo/bar/contract.avm`
			```

Update compiler (#22) * refactor to use ast.Walk for recursive converting * added lots of test cases * added a new way to handle jump labels * function calls with multiple arguments * binary expression (LOR LAND) * struct types + method receives * cleaner opcode dumps, side by side diff for debugging test cases 2018-02-19 09:24:28 +00:00			`## Currently supported`
Compiler (#23) * implemented add, mul, div, sub assign for identifiers. * Implemented struct field initialization. * Implemented imports * Implemented storage VM API (interop layer) + additional bug fixes when encountered. * Bumped version 0.12.0 * fixed double point extension on compiled output file. * Fixed bug where callExpr in returns where added to voidCall * fixed binExpr compare equal * Check the env for the gopath first * removed travis.yml * custom types + implemented general declarations. * commented out the storage test to make the build pass 2018-02-24 09:06:48 +00:00
			`### Go internals`
Update compiler (#22) * refactor to use ast.Walk for recursive converting * added lots of test cases * added a new way to handle jump labels * function calls with multiple arguments * binary expression (LOR LAND) * struct types + method receives * cleaner opcode dumps, side by side diff for debugging test cases 2018-02-19 09:24:28 +00:00			`- type checker`
			`- multiple assigns`
Compiler (#23) * implemented add, mul, div, sub assign for identifiers. * Implemented struct field initialization. * Implemented imports * Implemented storage VM API (interop layer) + additional bug fixes when encountered. * Bumped version 0.12.0 * fixed double point extension on compiled output file. * Fixed bug where callExpr in returns where added to voidCall * fixed binExpr compare equal * Check the env for the gopath first * removed travis.yml * custom types + implemented general declarations. * commented out the storage test to make the build pass 2018-02-24 09:06:48 +00:00			`- types int, string and booleans`
Update compiler (#22) * refactor to use ast.Walk for recursive converting * added lots of test cases * added a new way to handle jump labels * function calls with multiple arguments * binary expression (LOR LAND) * struct types + method receives * cleaner opcode dumps, side by side diff for debugging test cases 2018-02-19 09:24:28 +00:00			`- struct types + method receives`
			`- functions`
			- composite literals `[]int, []string`
			`- basic if statements`
			`- binary expressions.`
			`- return statements`
Compiler (#23) * implemented add, mul, div, sub assign for identifiers. * Implemented struct field initialization. * Implemented imports * Implemented storage VM API (interop layer) + additional bug fixes when encountered. * Bumped version 0.12.0 * fixed double point extension on compiled output file. * Fixed bug where callExpr in returns where added to voidCall * fixed binExpr compare equal * Check the env for the gopath first * removed travis.yml * custom types + implemented general declarations. * commented out the storage test to make the build pass 2018-02-24 09:06:48 +00:00			`- imports`

			`### VM API (interop layer)`
			`- storage`
Update compiler (#22) * refactor to use ast.Walk for recursive converting * added lots of test cases * added a new way to handle jump labels * function calls with multiple arguments * binary expression (LOR LAND) * struct types + method receives * cleaner opcode dumps, side by side diff for debugging test cases 2018-02-19 09:24:28 +00:00
			`## Not yet implemented`
			`- for loops`
			`- ranges`
			`- builtins (append, len, ..)`
Compiler (#23) * implemented add, mul, div, sub assign for identifiers. * Implemented struct field initialization. * Implemented imports * Implemented storage VM API (interop layer) + additional bug fixes when encountered. * Bumped version 0.12.0 * fixed double point extension on compiled output file. * Fixed bug where callExpr in returns where added to voidCall * fixed binExpr compare equal * Check the env for the gopath first * removed travis.yml * custom types + implemented general declarations. * commented out the storage test to make the build pass 2018-02-24 09:06:48 +00:00			`- large part of the interop layer (VM API)`
Update compiler (#22) * refactor to use ast.Walk for recursive converting * added lots of test cases * added a new way to handle jump labels * function calls with multiple arguments * binary expression (LOR LAND) * struct types + method receives * cleaner opcode dumps, side by side diff for debugging test cases 2018-02-19 09:24:28 +00:00
			`## Not supported`
			`Due to the limitations of the NEO virtual machine, features listed below will not be supported.`
			`- channels`
			`- goroutines`
			`- multiple returns`

Compiler (#23) * implemented add, mul, div, sub assign for identifiers. * Implemented struct field initialization. * Implemented imports * Implemented storage VM API (interop layer) + additional bug fixes when encountered. * Bumped version 0.12.0 * fixed double point extension on compiled output file. * Fixed bug where callExpr in returns where added to voidCall * fixed binExpr compare equal * Check the env for the gopath first * removed travis.yml * custom types + implemented general declarations. * commented out the storage test to make the build pass 2018-02-24 09:06:48 +00:00			`## How to report compiler bugs`
Update compiler (#22) * refactor to use ast.Walk for recursive converting * added lots of test cases * added a new way to handle jump labels * function calls with multiple arguments * binary expression (LOR LAND) * struct types + method receives * cleaner opcode dumps, side by side diff for debugging test cases 2018-02-19 09:24:28 +00:00			`1. Make a proper testcase (example testcases can be found in the tests folder)`
			`2. Create an issue on Github`
			`3. Make a PR with a reference to the created issue, containing the testcase that proves the bug`
			`4. Either you fix the bug yourself or wait for patch that solves the problem`
Compiler (#23) * implemented add, mul, div, sub assign for identifiers. * Implemented struct field initialization. * Implemented imports * Implemented storage VM API (interop layer) + additional bug fixes when encountered. * Bumped version 0.12.0 * fixed double point extension on compiled output file. * Fixed bug where callExpr in returns where added to voidCall * fixed binExpr compare equal * Check the env for the gopath first * removed travis.yml * custom types + implemented general declarations. * commented out the storage test to make the build pass 2018-02-24 09:06:48 +00:00
			`## Quick start`

			`### Compile a smart contract`

			```
			`./bin/neo-go contract compile mycontract.go`
			```

			`By default the filename will be the name of your .go file with the .avm extension, the file will be located in the same directory where you called the command from. If you want another location for your compiled contract:`

			```
			`./bin/neo-go contract compile mycontract.go --out /Users/foo/bar/contract.avm`
			```

			`### Debugging your smart contract`
			`You can dump the opcodes generated by the compiler with the following command:`

			```
			`./bin/neo-go contract opdump mycontract.go`
			```

			`This will result in something like this:`

			```
			`INDEX OPCODE DESC`
			`0 0x52 OpPush2`
			`1 0xc5 OpNewArray`
			`2 0x6b OpToAltStack`
			`3 0x 0 OpPush0`
			`4 0x6c OpFromAltStack`
			`5 0x76 OpDup`
			`6 0x6b OpToAltStack`
			`7 0x 0 OpPush0`
			`8 0x52 OpPush2`
			`9 0x7a OpRoll`
			`10 0xc4 OpSetItem`
			```