From e0c1ed5776c1090ce8a1e5ceaef6b7ae6e3d2e37 Mon Sep 17 00:00:00 2001
From: Michael McLoughlin <mmcloughlin@gmail.com>
Date: Thu, 3 Jan 2019 20:02:32 -0800
Subject: [PATCH] doc: add quick start to README

Updates #13
---
 README.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 77 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 0356cdc..46256a8 100644
--- a/README.md
+++ b/README.md
@@ -5,4 +5,80 @@
   <a href="http://godoc.org/github.com/mmcloughlin/avo"><img src="http://img.shields.io/badge/godoc-reference-5272B4.svg" alt="GoDoc" /></a>
 </p>
 
-Golang x86 assembly generator. Inspired by [PeachPy](https://github.com/Maratyszcza/PeachPy).
+High-level Golang x86 assembly generator. Inspired by [PeachPy](https://github.com/Maratyszcza/PeachPy).
+
+_Warning: `avo` is experimental. APIs are subject to change._
+
+## Install
+
+Install `avo` with `go get`:
+
+```
+$ go get -u github.com/mmcloughlin/avo
+```
+
+## Quick Start
+
+`avo` assembly generators are pure Go programs. Let's get started with a function that adds two `uint64` values.
+
+[embedmd]:# (examples/add/asm.go)
+```go
+// +build ignore
+
+package main
+
+import (
+	. "github.com/mmcloughlin/avo/build"
+)
+
+func main() {
+	TEXT("Add", "func(x, y uint64) uint64")
+	Doc("Add adds x and y.")
+	x := Load(Param("x"), GP64v())
+	y := Load(Param("y"), GP64v())
+	ADDQ(x, y)
+	Store(y, ReturnIndex(0))
+	RET()
+	Generate()
+}
+```
+
+You can `go run` this code to see the assembly output. To integrate this into the rest of your Go package we recommend a [`go:generate`](https://blog.golang.org/generate) line to produce the assembly and the corresponding Go stub file.
+
+[embedmd]:# (examples/add/add_test.go go /.*go:generate.*/)
+```go
+//go:generate go run asm.go -out add.s -stubs stub.go
+```
+
+After running `go generate` the [`add.s`](examples/add/add.s) file will contain the Go assembly.
+
+[embedmd]:# (examples/add/add.s)
+```s
+// Code generated by command: go run asm.go -out add.s -stubs stub.go. DO NOT EDIT.
+
+// func Add(x uint64, y uint64) uint64
+TEXT ·Add(SB), $0-24
+	MOVQ	x(FP), AX
+	MOVQ	y+8(FP), CX
+	ADDQ	AX, CX
+	MOVQ	CX, ret+16(FP)
+	RET
+```
+
+The same call will produce the stub file [`stub.go`](examples/add/stub.go) which will enable the function to be called from your Go code.
+
+[embedmd]:# (examples/add/stub.go)
+```go
+// Code generated by command: go run asm.go -out add.s -stubs stub.go. DO NOT EDIT.
+
+package add
+
+// Add adds x and y.
+func Add(x uint64, y uint64) uint64
+```
+
+See the [`examples/add`](examples/add) directory for the complete working example.
+
+## License
+
+`avo` is available under the [BSD 3-Clause License](LICENSE).